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.
from dataclasses import dataclass
@dataclass
class Registries:
app_registry: ...
After what, the registries is filled out using the scan of the application code.
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.
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(wrapped, callback, category="app_registry")
return wrapped
You now have a command_handler decorator that can be applied to functions,
which will register them in the application registry.
@command_handler
def handle_stuff(...):
...
The original handle_stuff function remains unchanged by the decorator,
making it fully unit-testable with no added overhead.
Note
Tamahagane differs from Venusian in its callback method design. Rather than receiving the scanner as a parameter, the callback is provided with the registries object, which is shared across all scanned decorators.
This design choice ensures type safety and better integration with modern Python practices.
Additionally, the callback must be defined within the decorator itself to ensure access to the wrapped method. This eliminates unnecessary parameters and maintains a consistent, localized scope for the callback logic.
Difference from Venusian¶
Tamahagene is fully typed.
Tamahagane supports absolute and relative name of module on scanner method scan.
Tamahagane
ignoredoes not accept a callable method.Tamahagane does not have a
onerroron the scan method, it raises.Tamahagane does not have a category on the scan method, categories are declared as attributes of the registry, nothing less, nothing more.
Tamagane does not support class/method decorator, does not provide
liftdecorators.
Installation¶
Tamahagane is available on PyPI
So you can installing using your favorite packaging tool, mine is uv:
uv add tamahagane
List of libraries using Tamahagane¶
Here is a curative list of projects using tamahagane:
Library |
Description |
Repository |
|---|---|---|
fastlife |
A web framework that register routes, templates and more using th. |
|
messagebus |
A message bus implementation for Python applications. |
|
whitesmith |
A testing library for blacksmith rest client. It scan routes, like a read web framework. |
See also¶
Documentation - https://mardiros.github.io/tamahagane/
Venusian - https://docs.pylonsproject.org/projects/venusian/en/
API:
Developper doc: