Update README and ReadTheDocs documentation (#69)

* Add Usage, Installation, and Development sections to README * Add Downloads per month badge
evrone · Sep 19, 2024 · 174ac4f · 174ac4f
1 parent ce7c6ab
commit 174ac4f
Show file tree

Hide file tree

Showing 2 changed files with 265 additions and 37 deletions.
diff --git a/README.md b/README.md
@@ -1,26 +1,140 @@
-# Toggl Python API
+# toggl-python
 
-![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)
+![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)
 
+Typed `Toggl API` Python wrapper with pre-validation to avoid extra network usage.
 
-* Based on open [Toggl API documentation](https://engineering.toggl.com/docs/)
+* Based on [Toggl API](https://engineering.toggl.com/docs/)
 * [Documentation](https://toggl-python.readthedocs.io)
 
-## Warning
 
-The package is currently broken because it uses **deprecated** Toggl API V8. Migration to V9 is currently in progress.
+## Important Note
+
+Migration to API V9 is currently in progress. Many methods are not implemented yet. Feel free to open an issue to escalate their development.
+
+## Install
+
+`pip install toggl-python`
+
+## Usage
+
+Fetch information about current user via `TokenAuth` (`TOGGL_TOKEN` is required):
+
+```python
+from toggl_python.auth import TokenAuth
+from toggl_python.entities.user import CurrentUser
+
+
+if __name__ == "__main__":
+    auth = TokenAuth(token="TOGGL_TOKEN")
+    CurrentUser(auth=auth).me()
+```
+
+`Basic Auth` is also supported:
+
+
+```python
+from toggl_python.auth import BasicAuth
+from toggl_python.entities.user import CurrentUser
+
+
+if __name__ == "__main__":
+    auth = BasicAuth(username="username", password="password")
+    CurrentUser(auth=auth).me()
+
+```
+
+Package supports different input formats for `datetime` arguments:
+
+* `str`:
+
+```python
+from toggl_python.auth import TokenAuth
+from toggl_python.entities.user import CurrentUser
+
+
+if __name__ == "__main__":
+    auth = TokenAuth(token="TOGGL_TOKEN")
+    CurrentUser(auth=auth).get_time_entries(
+        start_date="2024-01-01",
+        end_date="2024-02-01T15:00:00-02:00",
+    )
+```
+
+- `datetime`:
+
+```python
+from datetime import datetime, timezone
+
+from toggl_python.auth import TokenAuth
+from toggl_python.entities.user import CurrentUser
+
+
+if __name__ == "__main__":
+    auth = TokenAuth(token="TOGGL_TOKEN")
+    CurrentUser(auth=auth).get_time_entries(
+        start_date=datetime(2024, 1, 1, tzinfo=timezone.utc),
+        end_date=datetime(2024, 2, 1, 15, tzinfo=timezone.utc),
+    )
+```
+
+Query params are available as well:
+
+```python
+from toggl_python.auth import TokenAuth
+from toggl_python.entities.workspace import Workspace
+
+
+if __name__ == "__main__":
+    auth = TokenAuth(token="TOGGL_TOKEN")
+    workspace_id = "WORKSPACE_ID"
+    Workspace(auth=auth).get_projects(active=True)
+```
+
+Pre-validation to avoid extra network usage:
+
+```python
+from datetime import datetime, timezone
+
+from toggl_python.auth import TokenAuth
+from toggl_python.entities.workspace import Workspace
+
+
+if __name__ == "__main__":
+    auth = TokenAuth(token="TOGGL_TOKEN")
+    workspace_id = "WORKSPACE_ID"
+    since = datetime(2024, 1, 20, tzinfo=timezone.utc)
+    # Assume that datetime.now is 2024-05-01
+    Workspace(auth=auth).list(since=since)
+
+    # ValidationError: Since cannot be older than 3 months
+```
 
 ## Development
 
+`poetry` is required during local setup.
+
+Run `poetry install --no-root` to setup local environment. `pre-commit install` is also advisable.
+
+
+### Unit Testing
+
 In order to run tests using different Python versions, please follow these steps:
 * Install `pyenv`
 * Install all supported Python versions - `pyenv install 3.8.* 3.9.* ...`
 * Run `pyenv local 3.8.* 3.9.* ...`
 * Run `poetry run nox`
 
+To run classic unit tests, execute `pytest -m "not integration"`
+
+### Integration Testing
+
+Pre-defined `Workspace` and `Project` are required to have in `Toggl` system.
+
+Command `TOGGL_TOKEN=... WORKSPACE_ID=... PROJECT_ID=... USER_ID=... TOGGL_PASSWORD=... pytest -m integration`
+
 ## Credits
--------
 
-This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [cookiecutter-pypackage](https://github.com/audreyr/cookiecutter-pypackage) project template.
+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).
 
 [<img src="https://evrone.com/logo/evrone-sponsored-logo.png" width=231>](https://evrone.com/?utm_source=github.com)
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,46 +1,160 @@
-Toggl Python API
-================
+toggl-python
+============
 
-.. image:: https://evrone.com/logo/evrone-sponsored-logo.png
-  :width: 231
-  :alt: Sponsored by evrone.com
-  :target: https://evrone.com/?utm_source=github.com
+|https://pypi.python.org/pypi/toggl_python| |Supported python versions|
+|MIT License|
 
-Based on open `Toggl API documentation <https://github.com/toggl/toggl_api_docs/blob/master/toggl_api.md>`_
+Typed python wrapper for ``Toggl API`` with pre-validation to avoid
+extra network usage.
 
-Installation
-============
-`pip install toggl-python` or use `poetry <https://python-poetry.org>`_ `poetry add toggl-python`
+-  Based on `Toggl API <https://engineering.toggl.com/docs/>`__
+-  `Documentation <https://toggl-python.readthedocs.io>`__
+
+Important Note
+--------------
+
+Migration to API V9 is currently in progress. Many methods are not
+implemented yet. Feel free to open an issue to escalate their
+implementation.
+
+Install
+-------
+
+``pip install toggl-python``
+
+Usage
+-----
+
+Fetch information about current user via ``TokenAuth`` (``TOGGL_TOKEN``
+is required):
+
+.. code:: python
+
+   from toggl_python.auth import TokenAuth
+   from toggl_python.entities.user import CurrentUser
+
+
+   if __name__ == "__main__":
+       auth = TokenAuth(token="TOGGL_TOKEN")
+       CurrentUser(auth=auth).me()
+
+``Basic Auth`` is also supported.
+
+.. code:: python
+
+   from toggl_python.auth import BasicAuth
+   from toggl_python.entities.user import CurrentUser
+
+
+   if __name__ == "__main__":
+       auth = BasicAuth(username="username", password="password")
+       CurrentUser(auth=auth).me()
+
+Package supports different input formats for ``datetime`` arguments:
+
+-  ``str``:
+
+.. code:: python
+
+   from toggl_python.auth import TokenAuth
+   from toggl_python.entities.user import CurrentUser
+
+
+   if __name__ == "__main__":
+       auth = TokenAuth(token="TOGGL_TOKEN")
+       CurrentUser(auth=auth).get_time_entries(
+           start_date="2024-01-01",
+           end_date="2024-02-01T15:00:00-02:00",
+       )
+
+-  ``datetime``:
+
+.. code:: python
+
+   from datetime import datetime, timezone
+
+   from toggl_python.auth import TokenAuth
+   from toggl_python.entities.user import CurrentUser
+
+
+   if __name__ == "__main__":
+       auth = TokenAuth(token="TOGGL_TOKEN")
+       CurrentUser(auth=auth).get_time_entries(
+           start_date=datetime(2024, 1, 1, tzinfo=timezone.utc),
+           end_date=datetime(2024, 2, 1, 15, tzinfo=timezone.utc),
+       )
+
+Query params are available as well:
+
+.. code:: python
+
+   from toggl_python.auth import TokenAuth
+   from toggl_python.entities.workspace import Workspace
+
+
+   if __name__ == "__main__":
+       auth = TokenAuth(token="TOGGL_TOKEN")
+       workspace_id = "WORKSPACE_ID"
+       Workspace(auth=auth).get_projects(active=True)
+
+Pre-validation to avoid extra network usage:
+
+.. code:: python
+
+   from datetime import datetime, timezone
+
+   from toggl_python.auth import TokenAuth
+   from toggl_python.entities.workspace import Workspace
+
+
+   if __name__ == "__main__":
+       auth = TokenAuth(token="TOGGL_TOKEN")
+       workspace_id = "WORKSPACE_ID"
+       since = datetime(2024, 1, 20, tzinfo=timezone.utc)
+       # Assume that datetime.now is 2024-05-01
+       Workspace(auth=auth).list(since=since)
+
+       # ValidationError: Since cannot be older than 3 months
 
-Usage example
-=============
+Development
+-----------
 
-Get authenticated user time entries:
+``poetry`` is required during local setup.
 
-.. code-block:: python
+Run ``poetry install --no-root`` to setup local environment.
+``pre-commit install`` is also advisable.
 
-  from toggl_python import TokenAuth, TimeEntries
+Unit Testing
+~~~~~~~~~~~~
 
-  if __name__ == "__main__":
-      auth = TokenAuth('AUTH_TOKEN')
-      print(TimeEntries(auth=auth).list())
+In order to run tests using different Python versions, please follow
+these steps: \* Install ``pyenv`` \* Install all supported Python
+versions - ``pyenv install 3.8.* 3.9.* ...`` \* Run
+``pyenv local 3.8.* 3.9.* ...`` \* Run ``poetry run nox``
 
-Get information about authenticated user:
+To run classic unit tests, execute ``pytest -m "not integration"``
 
-.. code-block:: python
+Integration Testing
+~~~~~~~~~~~~~~~~~~~
 
-  from toggl_python import TokenAuth, Users
+Pre-defined ``Workspace`` and ``Project`` are required to have in
+``Toggl`` system.
 
-  if __name__ == "__main__":
-      auth = TokenAuth('AUTH_TOKEN')
-      print(Users(auth=auth).me())
+Command
+``TOGGL_TOKEN=... WORKSPACE_ID=... PROJECT_ID=... USER_ID=... TOGGL_PASSWORD=... pytest -m integration``
 
-Get information about authenticated user workspaces:
+Credits
+-------
 
-.. code-block:: python
+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>`__.
 
-  from toggl_python import TokenAuth, Workspaces
+` <https://evrone.com/?utm_source=github.com>`__
 
-  if __name__ == "__main__":
-      auth = TokenAuth('AUTH_TOKEN')
-      print(Workspaces(auth=auth).list())
+.. |https://pypi.python.org/pypi/toggl_python| image:: https://img.shields.io/pypi/v/toggl_python.svg
+.. |Supported python versions| image:: https://img.shields.io/pypi/pyversions/toggl_python.svg?style=flat-square
+   :target: https://pypi.python.org/pypi/toggl_python
+.. |MIT License| image:: https://img.shields.io/pypi/l/aiogram.svg?style=flat-square
+   :target: https://opensource.org/licenses/MIT