Metadata-Version: 2.1
Name: tamahagane
Version: 0.4.0
Summary: Forge your application registries.
Author-Email: Guillaume Gauvrit <guillaume@gauvr.it>
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Project-URL: Homepage, https://mardiros.github.io/tamahagane
Project-URL: Documentation, https://mardiros.github.io/tamahagane
Project-URL: Repository, https://github.com/mardiros/tamahagane.git
Project-URL: Issues, https://github.com/mardiros/tamahagane/issues
Project-URL: Changelog, https://mardiros.github.io/tamahagane/user/changelog.html
Requires-Python: >=3.10
Provides-Extra: docs
Requires-Dist: furo>=2024.5.6; extra == "docs"
Requires-Dist: linkify-it-py<3,>=2.0.3; extra == "docs"
Requires-Dist: myst-parser<5,>=4.0.0; extra == "docs"
Requires-Dist: sphinx<9,>=8.0.0; extra == "docs"
Requires-Dist: sphinx-autodoc2<1,>=0.5.0; extra == "docs"
Description-Content-Type: text/markdown

# Tamahagane


[![Documentation](https://github.com/mardiros/tamahagane/actions/workflows/publish-doc.yml/badge.svg)](https://mardiros.github.io/tamahagane/)
[![Continuous Integration](https://github.com/mardiros/tamahagane/actions/workflows/tests.yml/badge.svg)](https://github.com/mardiros/tamahagane/actions/workflows/tests.yml)
[![Coverage Report](https://codecov.io/gh/mardiros/tamahagane/graph/badge.svg?token=DTpi73d7mf)](https://codecov.io/gh/mardiros/tamahagane)


Forge your application registries.

Tamahagane is a library designed for constructing application registries,
the essential foundation for building decoupled software architectures
and enabling unit testing on application handlers.

## Motivation

Tamahagane essentially serves as a modern alternative to Venusian,
fulfilling the same core functionality.

The decision to create a new library stems from Venusian's limitations:
it was originally built for Python 2, relies heavily on dynamic behavior,
and lacks type support.

Tamahagane reuse the same vocabular, a Scanner and an attach function,
but the API is not fully compatible, in order to get a simpler version.

## Usage

To use Tamahagane you need to create a registries class that hold
all registries your app may load. The definition of the registry
is free and depends of the usage.

```python
from dataclasses import dataclass

@dataclass
class Registries:
    app_registry: ...
```

After what, the registries is filled out using the scan of the application code.

```python
import tamahagane as th

scanner = th.Scanner[Registries](Registries(app_registry=...))
scanner.scan("app.service_handlers")
```

At this time, the `app.service_handlers` is a module, or a package containing
submodules, that will be recursibely loaded. It contains decorated function,
where the decorator has been created in the application code to create the
callback.

```python
from collections.abc import Callable
from typing import Any

import tamahagane as th


CommandHandler = Callable[..., Any]

def command_handler(wrapped: CommandHandler) -> CommandHandler:

    def callback(registries: Registries) -> None:
        registries.app_registry.do_something_with(wrapped, ...)

    th.attach(callback, category="app_registry")
    return wrapped

```

Now, you have a command_handler decorator that can be used an be filled out an
application registry with the decorated method.

```python
@command_handler
def handle_stuff(...):
    ...
```

handle_stuff is **unmodified** by its decorator and is purely unit testable.
No overhead.

## Installation

Tamahagane is available on [PyPI](https://pypi.org/project/tamahagane/)

So you can installing using your favorite packaging tool, mine is uv:

```bash
uv add tamahagane
```

## See also

- Documentation - https://mardiros.github.io/tamahagane/
- Venusian - https://docs.pylonsproject.org/projects/venusian/en/
