twat-hatch 1.7.0

Plugin for twat that provides package initialization functionality

twat-hatch

(work in progress)

A powerful Python package initializer that supports both standalone packages and plugin-based architectures. Built with modern Python practices and robust configuration management.

Features

• 🎯 Flexible package creation: Create standalone packages or plugin-based architectures
• 🔧 Modern configuration: Type-safe configuration using Pydantic
• 📦 Multiple package types: Support for core packages and plugins
• 🎨 Templating system: Jinja2-based templating with multiple themes
• 📚 Documentation support: Optional MkDocs integration
• 🔄 Version control: Git integration and semantic versioning support
• ✨ Best practices: Enforces Python packaging best practices

Why twat-hatch?

twat-hatch helps you create modern Python packages with a focus on plugin systems. It implements best practices for:

Modern python packaging

• PEP 621-style configuration via pyproject.toml
• src/ layout pattern for better packaging practices
• Type hints and runtime type checking with Pydantic
• Automated dependency management

Plugin system architecture

• Namespace packages: Create plugin host packages that dynamically expose plugins
• Dynamic discovery: Automatic plugin registration via entry points
• Flexible usage: Support both direct imports and namespace-based imports
• Clean dependencies: Proper handling of optional plugin dependencies

Best practices implementation

• Code organization: Enforced src/ layout and modern project structure
• Error handling: Built-in validation and error checking
• Documentation: Automated documentation setup with MkDocs
• Testing: Pre-configured test structure with pytest
• Type safety: MyPy configuration and Pydantic validation

Installation

uv pip install twat-hatch

Or with pip:

pip install twat-hatch

Quick start

1. Create a configuration file twat-hatch.toml:

[project]
packages = ["my-package"]
output_dir = "packages"

[author]
name = "Your Name"
email = "[e-mail]"
github_username = "yourusername"

[package]
min_python = "3.8"
license = "MIT"
development_status = "4 - Beta"

1. Run the package initializer:

twat-hatch --config twat-hatch.toml

Creating plugin-based packages

Plugin system overview

When creating a plugin-based architecture, twat-hatch generates:

1. Plugin host package: The core package that provides plugin discovery and management
2. Plugin packages: Individual plugins that integrate with the host package

Example configuration:

[project]
packages = ["my-plugin-a", "my-plugin-b"]
plugin_host = "my-core-package"
output_dir = "packages"

# ... other configuration ...

Plugin system usage

Once packages are created, they can be used in several ways:

# Direct import of a plugin
import my_plugin_a
instance = my_plugin_a.SomeClass()

# Via namespace package (if configured)
from my_core_package import plugin_a
instance = plugin_a.SomeClass()

Installation options:

# Install a plugin directly
pip install my-plugin-a

# Install via the host package with extras
pip install my-core-package[plugin-a]

# Install multiple plugins
pip install my-core-package[plugin-a,plugin-b]

# Install all available plugins
pip install my-core-package[all]

Configuration reference

The configuration file ( twat-hatch.toml ) supports the following sections:

Project configuration

[project]
packages = ["package-name"]        # List of packages to create
plugin_host = "host-package"       # Optional plugin host package
output_dir = "path/to/output"      # Output directory (optional)

Author information

[author]
name = "Author Name"
email = "[e-mail]"
github_username = "username"

Package settings

[package]
min_python = "3.8"                 # Minimum Python version
license = "MIT"                    # Package license
development_status = "4 - Beta"    # PyPI development status

Dependencies

[dependencies]
dependencies = [                   # Regular dependencies
    "package>=1.0.0"
]
plugin_dependencies = [            # Plugin-specific dependencies
    "plugin-package>=1.0.0"
]
dev_dependencies = [               # Development dependencies
    "pytest>=7.0.0"
]

Features

[features]
mkdocs = false                     # Enable MkDocs documentation
semver = true                      # Use semantic versioning
vcs = true                        # Initialize Git repository

Generated package structure

Standalone package

my-package/
├── README.md
├── pyproject.toml                 # Project configuration
├── src/
│   └── my_package/               # Package source
│       ├── __init__.py
│       └── core.py
└── tests/                        # Test directory
    ├── conftest.py
    └── test_my_package.py

Plugin host package

my-core-package/
├── README.md
├── pyproject.toml
├── src/
│   └── my_core_package/
│       ├── __init__.py           # Plugin discovery logic
│       └── core.py               # Core functionality
└── tests/
    ├── conftest.py
    └── test_my_core_package.py

Plugin package

my-plugin/
├── README.md
├── pyproject.toml                # Includes plugin entry points
├── src/
│   └── my_plugin/
│       ├── __init__.py
│       └── plugin.py             # Plugin implementation
└── tests/
    ├── conftest.py
    └── test_my_plugin.py

Development

To set up the development environment:

git clone https://github.com/twardoch/twat-hatch.git
cd twat-hatch
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Run tests:

pytest

Run linting:

ruff check .
mypy src/

Technical details

Package naming convention

• Distribution names use hyphens: my-plugin
• Import names use underscores: my_plugin
• Plugin host packages follow the same convention

Plugin discovery

• Plugins register via entry points under {host}.plugins
• Plugin host packages support both direct imports and entry point discovery
• Dynamic loading ensures plugins are only imported when needed

Dependencies management

• Plugin packages can depend on their host package
• Host packages define optional dependencies via extras
• Version compatibility is managed through dependency specifications

Building and publishing

1. Build and publish the plugin host package first
2. Build and publish plugin packages separately
3. Use consistent versioning across packages

License

MIT License, see for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.