Metadata-Version: 2.4
Name: invoke-toolkit
Version: 0.0.58
Summary: A set of extended APIs for PyInvoke for composable scripts, plugins and richer output
Project-URL: Documentation, https://github.com/D3f0/invoke-toolkit#readme
Project-URL: Issues, https://github.com/D3f0/invoke-toolkit/issues
Project-URL: Source, https://github.com/D3f0/invoke-toolkit
Author-email: Nahuel Defossé <D3f0@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Software Distribution
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: appdirs
Requires-Dist: attrs>=24.1.0
Requires-Dist: cattrs>=24.1.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: invoke>=2.2.1
Requires-Dist: pdbpp>=0.11.7
Requires-Dist: platformdirs>=4.5.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=13
Requires-Dist: setproctitle>=1.3.7
Requires-Dist: tomlkit>=0.13.3
Requires-Dist: typing-extensions>=4.13.2
Provides-Extra: cache
Requires-Dist: diskcache>=5.6.0; extra == 'cache'
Provides-Extra: copier
Requires-Dist: copier>=9.10.3; extra == 'copier'
Provides-Extra: debug
Requires-Dist: hunter>=3.7.0; extra == 'debug'
Requires-Dist: pdbpp>=0.11.7; extra == 'debug'
Provides-Extra: full
Requires-Dist: copier>=9.10.3; extra == 'full'
Requires-Dist: diskcache>=5.6.0; extra == 'full'
Requires-Dist: hunter>=3.7.0; extra == 'full'
Requires-Dist: pdbpp>=0.11.7; extra == 'full'
Provides-Extra: templating
Requires-Dist: copier>=9.10.3; extra == 'templating'
Description-Content-Type: text/markdown

# invoke-toolkit

A set of extensions for rich output, more options in collection/config discovery through `entry-points`.

This extends the Collection from Invoke so it can create automatically collections.

[![PyPI - Version](https://img.shields.io/pypi/v/invoke-toolkit.svg)](https://pypi.org/project/invoke-toolkit)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/invoke-toolkit.svg)](https://pypi.org/project/invoke-toolkit)

-----

## Table of Contents

- [invoke-toolkit](#invoke-toolkit)
  - [Table of Contents](#table-of-contents)
  - [Features](#features)
  - [Do I need this package](#do-i-need-this-package)
  - [Installation](#installation)
  - [Development](#development)
  - [License](#license)

## Features

- Task discovery by namespace for extendable/composable CLIs
- Discovery to *plain old* tasks.py (or any other name)
- Local tasks discovery from `local_tasks.py` in the current directory
- Integration with stand alone binaries for specific tasks
- **Task result caching** with TTL support via `diskcache` (optional)
- **Future** Download binaries

## Do I need this package

If you have...

- Used `invoke` for a while and...
- Have a large `tasks.py` that needs to be modularized
- Have a lot of copy/pasted code in multiple `tasks.py` across multiple repos.
- Have exceeded the approach of a repository cloned as `~/tasks/` with more .py files that you want to manage.
- Or you want to combine various tasks defined in multiple directories
- You want to create a zipped (shiv) redistribute script for container environments
  like Kubernetes based CI environments with only requiring the Python interpreter.

## Installation

```console
pip install invoke-toolkit
```

## Quick Start

### Using Local Tasks

Create a `local_tasks.py` file in your project directory with your tasks:

```python
from invoke_toolkit import task

@task()
def my_task(ctx):
    """Do something useful"""
    print("Hello from local tasks!")
```

Then run it with:

```console
intk local.my-task
```

Local tasks are automatically discovered and added to the `local` namespace, allowing you to keep project-specific tasks separate from your main task collection.

### Using Task Caching

Cache expensive task results with the `cache` parameter:

```python
from invoke_toolkit import task

# Simple caching (no expiration)
@task(cache=True)
def expensive_task(ctx, param: str) -> str:
    """Results are cached across invocations."""
    return do_expensive_computation(param)

# Caching with TTL (1 hour)
@task(cache={"ttl": 3600})
def cached_task(ctx, name: str) -> dict:
    """Results cached for 1 hour."""
    return fetch_data(name)

# Caching with ignored arguments
@task(cache={"ttl": 600, "ignore_args": ["verbose"]})
def cached_with_options(ctx, query: str, verbose: bool = False) -> list:
    """Cache key ignores verbose flag."""
    return search(query, verbose=verbose)
```

Cache features:
- Cache location is computed from git repository root + platformdirs
- Debug logging (`-d` flag) shows cache hits/misses
- Graceful degradation when `diskcache` is not installed

To enable caching, install with the cache extra:

```console
pip install invoke-toolkit[cache]
```

## Development

This project utilizes the `pre-commit` framework, make sure you run:

`pre-commit install`

With `uvx`:

`uvx --with pre-commit-uv pre-commit install`

## License

`invoke-toolkit` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
