Metadata-Version: 2.1
Name: toggl_python
Version: 0.3.0
Summary: Typed `Toggl API` Python wrapper with pre-validation to avoid extra network usage.
Home-page: https://github.com/evrone/toggl_python
Author: Evrone
Author-email: mail@evrone.com
Maintainer: Nifadev Vadim
Maintainer-email: vnifadev@evrone.com
Requires-Python: >=3.8.18,<4.0.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Typing :: Typed
Requires-Dist: backports-zoneinfo (>=0.2.1,<0.3.0) ; python_version == "3.8"
Requires-Dist: httpx[http2] (>=0.27.2,<0.28.0)
Requires-Dist: pydantic[email] (>=2.9.2,<3.0.0)
Project-URL: Documentation, https://toggl-python.readthedocs.io
Project-URL: Repository, https://github.com/evrone/toggl_python
Description-Content-Type: text/markdown

# toggl-python

![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 [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 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 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)

