Skip to content

Commit 174ac4f

Browse files
nifadyevnifadyev
authored
Update README and ReadTheDocs documentation (#69)
* Add Usage, Installation, and Development sections to README * Add Downloads per month badge
1 parent ce7c6ab commit 174ac4f

File tree

2 files changed

+265
-37
lines changed

2 files changed

+265
-37
lines changed

‎README.md

+121-7
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,140 @@
1-
# Toggl Python API
1+
# toggl-python
22

3-
![https://pypi.python.org/pypi/toggl_python](https://img.shields.io/pypi/v/toggl_python.svg) [![Supported python versions](https://img.shields.io/pypi/pyversions/toggl_python.svg?style=flat-square)](https://pypi.python.org/pypi/toggl_python) [![MIT License](https://img.shields.io/pypi/l/aiogram.svg?style=flat-square)](https://opensource.org/licenses/MIT)
3+
![https://pypi.python.org/pypi/toggl_python](https://img.shields.io/pypi/v/toggl_python.svg) ![Downloads](https://img.shields.io/pypi/dm/toggl-python) [![Supported python versions](https://img.shields.io/pypi/pyversions/toggl_python.svg?style=flat-square)](https://pypi.python.org/pypi/toggl_python) [![MIT License](https://img.shields.io/pypi/l/aiogram.svg?style=flat-square)](https://opensource.org/licenses/MIT)
44

5+
Typed `Toggl API` Python wrapper with pre-validation to avoid extra network usage.
56

6-
* Based on open [Toggl API documentation](https://engineering.toggl.com/docs/)
7+
* Based on [Toggl API](https://engineering.toggl.com/docs/)
78
* [Documentation](https://toggl-python.readthedocs.io)
89

9-
## Warning
1010

11-
The package is currently broken because it uses **deprecated** Toggl API V8. Migration to V9 is currently in progress.
11+
## Important Note
12+
13+
Migration to API V9 is currently in progress. Many methods are not implemented yet. Feel free to open an issue to escalate their development.
14+
15+
## Install
16+
17+
`pip install toggl-python`
18+
19+
## Usage
20+
21+
Fetch information about current user via `TokenAuth` (`TOGGL_TOKEN` is required):
22+
23+
```python
24+
from toggl_python.auth import TokenAuth
25+
from toggl_python.entities.user import CurrentUser
26+
27+
28+
if __name__ == "__main__":
29+
auth = TokenAuth(token="TOGGL_TOKEN")
30+
CurrentUser(auth=auth).me()
31+
```
32+
33+
`Basic Auth` is also supported:
34+
35+
36+
```python
37+
from toggl_python.auth import BasicAuth
38+
from toggl_python.entities.user import CurrentUser
39+
40+
41+
if __name__ == "__main__":
42+
auth = BasicAuth(username="username", password="password")
43+
CurrentUser(auth=auth).me()
44+
45+
```
46+
47+
Package supports different input formats for `datetime` arguments:
48+
49+
* `str`:
50+
51+
```python
52+
from toggl_python.auth import TokenAuth
53+
from toggl_python.entities.user import CurrentUser
54+
55+
56+
if __name__ == "__main__":
57+
auth = TokenAuth(token="TOGGL_TOKEN")
58+
CurrentUser(auth=auth).get_time_entries(
59+
start_date="2024-01-01",
60+
end_date="2024-02-01T15:00:00-02:00",
61+
)
62+
```
63+
64+
- `datetime`:
65+
66+
```python
67+
from datetime import datetime, timezone
68+
69+
from toggl_python.auth import TokenAuth
70+
from toggl_python.entities.user import CurrentUser
71+
72+
73+
if __name__ == "__main__":
74+
auth = TokenAuth(token="TOGGL_TOKEN")
75+
CurrentUser(auth=auth).get_time_entries(
76+
start_date=datetime(2024, 1, 1, tzinfo=timezone.utc),
77+
end_date=datetime(2024, 2, 1, 15, tzinfo=timezone.utc),
78+
)
79+
```
80+
81+
Query params are available as well:
82+
83+
```python
84+
from toggl_python.auth import TokenAuth
85+
from toggl_python.entities.workspace import Workspace
86+
87+
88+
if __name__ == "__main__":
89+
auth = TokenAuth(token="TOGGL_TOKEN")
90+
workspace_id = "WORKSPACE_ID"
91+
Workspace(auth=auth).get_projects(active=True)
92+
```
93+
94+
Pre-validation to avoid extra network usage:
95+
96+
```python
97+
from datetime import datetime, timezone
98+
99+
from toggl_python.auth import TokenAuth
100+
from toggl_python.entities.workspace import Workspace
101+
102+
103+
if __name__ == "__main__":
104+
auth = TokenAuth(token="TOGGL_TOKEN")
105+
workspace_id = "WORKSPACE_ID"
106+
since = datetime(2024, 1, 20, tzinfo=timezone.utc)
107+
# Assume that datetime.now is 2024-05-01
108+
Workspace(auth=auth).list(since=since)
109+
110+
# ValidationError: Since cannot be older than 3 months
111+
```
12112

13113
## Development
14114

115+
`poetry` is required during local setup.
116+
117+
Run `poetry install --no-root` to setup local environment. `pre-commit install` is also advisable.
118+
119+
120+
### Unit Testing
121+
15122
In order to run tests using different Python versions, please follow these steps:
16123
* Install `pyenv`
17124
* Install all supported Python versions - `pyenv install 3.8.* 3.9.* ...`
18125
* Run `pyenv local 3.8.* 3.9.* ...`
19126
* Run `poetry run nox`
20127

128+
To run classic unit tests, execute `pytest -m "not integration"`
129+
130+
### Integration Testing
131+
132+
Pre-defined `Workspace` and `Project` are required to have in `Toggl` system.
133+
134+
Command `TOGGL_TOKEN=... WORKSPACE_ID=... PROJECT_ID=... USER_ID=... TOGGL_PASSWORD=... pytest -m integration`
135+
21136
## Credits
22-
-------
23137

24-
This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage) project template.
138+
This package follows [evrone-python-guidelines](https://github.com/evrone/evrone-python-guidelines) and uses configs from [evrone-django-template](https://github.com/evrone/evrone-django-template).
25139

26140
[<img src="https://evrone.com/logo/evrone-sponsored-logo.png" width=231>](https://evrone.com/?utm_source=github.com)

‎docs/index.rst

100644100755
+144-30
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,160 @@
1-
Toggl Python API
2-
================
1+
toggl-python
2+
============
33

4-
.. image:: https://evrone.com/logo/evrone-sponsored-logo.png
5-
:width: 231
6-
:alt: Sponsored by evrone.com
7-
:target: https://evrone.com/?utm_source=github.com
4+
|https://pypi.python.org/pypi/toggl_python| |Supported python versions|
5+
|MIT License|
86

9-
Based on open `Toggl API documentation <https://github.com/toggl/toggl_api_docs/blob/master/toggl_api.md>`_
7+
Typed python wrapper for ``Toggl API`` with pre-validation to avoid
8+
extra network usage.
109

11-
Installation
12-
============
13-
`pip install toggl-python` or use `poetry <https://python-poetry.org>`_ `poetry add toggl-python`
10+
- Based on `Toggl API <https://engineering.toggl.com/docs/>`__
11+
- `Documentation <https://toggl-python.readthedocs.io>`__
12+
13+
Important Note
14+
--------------
15+
16+
Migration to API V9 is currently in progress. Many methods are not
17+
implemented yet. Feel free to open an issue to escalate their
18+
implementation.
19+
20+
Install
21+
-------
22+
23+
``pip install toggl-python``
24+
25+
Usage
26+
-----
27+
28+
Fetch information about current user via ``TokenAuth`` (``TOGGL_TOKEN``
29+
is required):
30+
31+
.. code:: python
32+
33+
from toggl_python.auth import TokenAuth
34+
from toggl_python.entities.user import CurrentUser
35+
36+
37+
if __name__ == "__main__":
38+
auth = TokenAuth(token="TOGGL_TOKEN")
39+
CurrentUser(auth=auth).me()
40+
41+
``Basic Auth`` is also supported.
42+
43+
.. code:: python
44+
45+
from toggl_python.auth import BasicAuth
46+
from toggl_python.entities.user import CurrentUser
47+
48+
49+
if __name__ == "__main__":
50+
auth = BasicAuth(username="username", password="password")
51+
CurrentUser(auth=auth).me()
52+
53+
Package supports different input formats for ``datetime`` arguments:
54+
55+
- ``str``:
56+
57+
.. code:: python
58+
59+
from toggl_python.auth import TokenAuth
60+
from toggl_python.entities.user import CurrentUser
61+
62+
63+
if __name__ == "__main__":
64+
auth = TokenAuth(token="TOGGL_TOKEN")
65+
CurrentUser(auth=auth).get_time_entries(
66+
start_date="2024-01-01",
67+
end_date="2024-02-01T15:00:00-02:00",
68+
)
69+
70+
- ``datetime``:
71+
72+
.. code:: python
73+
74+
from datetime import datetime, timezone
75+
76+
from toggl_python.auth import TokenAuth
77+
from toggl_python.entities.user import CurrentUser
78+
79+
80+
if __name__ == "__main__":
81+
auth = TokenAuth(token="TOGGL_TOKEN")
82+
CurrentUser(auth=auth).get_time_entries(
83+
start_date=datetime(2024, 1, 1, tzinfo=timezone.utc),
84+
end_date=datetime(2024, 2, 1, 15, tzinfo=timezone.utc),
85+
)
86+
87+
Query params are available as well:
88+
89+
.. code:: python
90+
91+
from toggl_python.auth import TokenAuth
92+
from toggl_python.entities.workspace import Workspace
93+
94+
95+
if __name__ == "__main__":
96+
auth = TokenAuth(token="TOGGL_TOKEN")
97+
workspace_id = "WORKSPACE_ID"
98+
Workspace(auth=auth).get_projects(active=True)
99+
100+
Pre-validation to avoid extra network usage:
101+
102+
.. code:: python
103+
104+
from datetime import datetime, timezone
105+
106+
from toggl_python.auth import TokenAuth
107+
from toggl_python.entities.workspace import Workspace
108+
109+
110+
if __name__ == "__main__":
111+
auth = TokenAuth(token="TOGGL_TOKEN")
112+
workspace_id = "WORKSPACE_ID"
113+
since = datetime(2024, 1, 20, tzinfo=timezone.utc)
114+
# Assume that datetime.now is 2024-05-01
115+
Workspace(auth=auth).list(since=since)
116+
117+
# ValidationError: Since cannot be older than 3 months
14118
15-
Usage example
16-
=============
119+
Development
120+
-----------
17121

18-
Get authenticated user time entries:
122+
``poetry`` is required during local setup.
19123

20-
.. code-block:: python
124+
Run ``poetry install --no-root`` to setup local environment.
125+
``pre-commit install`` is also advisable.
21126

22-
from toggl_python import TokenAuth, TimeEntries
127+
Unit Testing
128+
~~~~~~~~~~~~
23129

24-
if __name__ == "__main__":
25-
auth = TokenAuth('AUTH_TOKEN')
26-
print(TimeEntries(auth=auth).list())
130+
In order to run tests using different Python versions, please follow
131+
these steps: \* Install ``pyenv`` \* Install all supported Python
132+
versions - ``pyenv install 3.8.* 3.9.* ...`` \* Run
133+
``pyenv local 3.8.* 3.9.* ...`` \* Run ``poetry run nox``
27134

28-
Get information about authenticated user:
135+
To run classic unit tests, execute ``pytest -m "not integration"``
29136

30-
.. code-block:: python
137+
Integration Testing
138+
~~~~~~~~~~~~~~~~~~~
31139

32-
from toggl_python import TokenAuth, Users
140+
Pre-defined ``Workspace`` and ``Project`` are required to have in
141+
``Toggl`` system.
33142

34-
if __name__ == "__main__":
35-
auth = TokenAuth('AUTH_TOKEN')
36-
print(Users(auth=auth).me())
143+
Command
144+
``TOGGL_TOKEN=... WORKSPACE_ID=... PROJECT_ID=... USER_ID=... TOGGL_PASSWORD=... pytest -m integration``
37145

38-
Get information about authenticated user workspaces:
146+
Credits
147+
-------
39148

40-
.. code-block:: python
149+
This package follows
150+
`evrone-python-guidelines <https://github.com/evrone/evrone-python-guidelines>`__
151+
and uses configs from
152+
`evrone-django-template <https://github.com/evrone/evrone-django-template>`__.
41153

42-
from toggl_python import TokenAuth, Workspaces
154+
` <https://evrone.com/?utm_source=github.com>`__
43155

44-
if __name__ == "__main__":
45-
auth = TokenAuth('AUTH_TOKEN')
46-
print(Workspaces(auth=auth).list())
156+
.. |https://pypi.python.org/pypi/toggl_python| image:: https://img.shields.io/pypi/v/toggl_python.svg
157+
.. |Supported python versions| image:: https://img.shields.io/pypi/pyversions/toggl_python.svg?style=flat-square
158+
:target: https://pypi.python.org/pypi/toggl_python
159+
.. |MIT License| image:: https://img.shields.io/pypi/l/aiogram.svg?style=flat-square
160+
:target: https://opensource.org/licenses/MIT

0 commit comments

Comments
 (0)