Metadata-Version: 2.4
Name: taskchampion3-py-dev
Version: 3.0.1.1.1a1
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Dist: pytest>=8.2.0 ; extra == 'test'
Requires-Dist: mypy>=1.10.0 ; extra == 'test'
Provides-Extra: test
License-File: LICENSE
Summary: Python bindings for TaskChampion 3.x (fork, updated for taskchampion=3.0.1)
Keywords: taskwarrior,taskchampion,tasks,productivity
Author-email: Illya Laifu <illyalaifu@gmail.com>, "Dustin J. Mitchell" <dustin@v.igoro.us>, sznicolas <sznicolas+@users.noreply.github.com>
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: changelog, https://github.com/sznicolas/taskchampion-py-dev/releases
Project-URL: homepage, https://gothenburgbitfactory.org/taskchampion
Project-URL: repository, https://github.com/sznicolas/taskchampion-py-dev

# Python Taskchampion Bindings

This package contains Python bindings for [TaskChampion](https://github.com/GothenburgBitFactory/taskchampion).
It follows the TaskChampion API closely, with minimal adaptation for Python.

## Versioning

The `taskchampion-py` package version generally follows the Rust crate version. This fork publishes as `taskchampion3-py-fork` with Python package version 3.0.1.1.dev1 corresponding to TaskChampion crate 3.0.1. When an additional package-only release is required for the same Rust crate, a fourth version component is used (e.g., `1.2.0.1`).

## Usage

```py
def main():
    r = Replica.new_on_disk("/home/username/.task/", False) 
    tasks = r.all_tasks()
    print(tasks)
    for uuid in tasks.keys():
        task = r.get_task(uuid)
        print(f"Description: {task.get_description()}")
        print(f"UUID: {task.get_uuid()}")
        print(f"Status: {task.get_status()}")


if __name__ == "__main__":
    main()
```
For the Replica.new_on_disk(path), the argument is directory to your sqlite database (to match the Rust implementation). For a thorough understanding of the Rust implementation, which this Python package emulates, see the Rust documentation at: https://docs.rs/taskchampion/3.0.1/taskchampion/

The output of r.all_tasks() is a dictionary. The keys are the UUIDs of the tasks. Here is an example based on a couple test tasks:

```json
{'8655d0fe-3627-43b2-933a-7703609b101e': Task { data: TaskData { uuid: 8655d0fe-3627-43b2-933a-7703609b101e, taskmap: {"modified": "1775169728", "description": "test task 2", "entry": "1775169728", "due": "1775188800", "status": "pending"} }, depmap: DependencyMap { edges: [] }, updated_modified: false },
'f5bc3f9d-d97d-4165-863d-2e08d6b53dc9': Task { data: TaskData { uuid: f5bc3f9d-d97d-4165-863d-2e08d6b53dc9, taskmap: {"status": "pending", "entry": "1775007191", "description": "test1", "modified": "1775007191", "due": "1775016000"} }, depmap: DependencyMap { edges: [] }, updated_modified: false }}
```
Using the keys method on the dictionary allows for accessing the tasks by UUID. Below is the output from the Task API commands:

```bash
Description: test task 2
UUID: 8655d0fe-3627-43b2-933a-7703609b101e
Status: Status.Pending
Description: test1
UUID: f5bc3f9d-d97d-4165-863d-2e08d6b53dc9
Status: Status.Pending
```
Referring back to the dictionary, notice the strange numbers under entry, modified, and due. When the Task API is used to fetch the data, it is converted into a user-friendly date/time. For example, on test 1 the task.get_entry() results in: 2026-04-01 01:33:11+00:00

See the [API
documentation](https://gothenburgbitfactory.org/taskchampion-py/taskchampion.html)
for more information.

## Development

This project is built using [maturin](https://github.com/PyO3/maturin).

To install:

```shell
pipx install maturin
```

To build wheels:
```shell
maturin build
```
This stores wheels in the `target/wheels` folder by default.

### Testing

Extra testing dependencies can be installed with pip. To run tests locally:

```bash
python3.12 -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip
pip install maturin pytest mypy
# Build and install extension in editable mode
maturin develop --release
# Run tests
pytest
```

To reproduce the CI environment (ubuntu-latest) use the Docker recipe in the CONTRIBUTING or CI docs.

