| Name | twat-hatch JSON |
| Version |
1.8.1
JSON |
| download |
| home_page | None |
| Summary | Plugin for twat that provides package initialization functionality |
| upload_time | 2025-02-15 05:50:25 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
package-template
twat
twat-plugin
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# `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
```bash
uv pip install twat-hatch
```
Or with `pip`:
```bash
pip install twat-hatch
```
## Quick start
1. Create a configuration file `twat-hatch.toml`:
```toml
[project]
packages = ["my-package"]
output_dir = "packages"
[author]
name = "Your Name"
email = "your.email@example.com"
github_username = "yourusername"
[package]
min_python = "3.8"
license = "MIT"
development_status = "4 - Beta"
```
1. Run the package initializer:
```bash
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:
```toml
[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:
```python
# 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:
```bash
# 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
```toml
[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
```toml
[author]
name = "Author Name"
email = "author@example.com"
github_username = "username"
```
### Package settings
```toml
[package]
min_python = "3.8" # Minimum Python version
license = "MIT" # Package license
development_status = "4 - Beta" # PyPI development status
```
### Dependencies
```toml
[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
```toml
[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:
```bash
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:
```bash
pytest
```
Run linting:
```bash
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 <LICENSE> for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
.
Raw data
{
"_id": null,
"home_page": null,
"name": "twat-hatch",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "package-template, twat, twat-plugin",
"author": null,
"author_email": "Adam Twardoch <adam+github@twardoch.com>",
"download_url": "https://files.pythonhosted.org/packages/70/ba/98773525516f94882ed09aaea29d8dda6bbbfec2522fd290e697951aee87/twat_hatch-1.8.1.tar.gz",
"platform": null,
"description": "# `twat-hatch`\n\n(work in progress)\n\nA powerful Python package initializer that supports both standalone packages and plugin-based architectures. Built with modern Python practices and robust configuration management.\n\n## Features\n\n- \ud83c\udfaf **Flexible package creation**: Create standalone packages or plugin-based architectures\n- \ud83d\udd27 **Modern configuration**: Type-safe configuration using Pydantic\n- \ud83d\udce6 **Multiple package types**: Support for core packages and plugins\n- \ud83c\udfa8 **Templating system**: Jinja2-based templating with multiple themes\n- \ud83d\udcda **Documentation support**: Optional MkDocs integration\n- \ud83d\udd04 **Version control**: Git integration and semantic versioning support\n- \u2728 **Best practices**: Enforces Python packaging best practices\n\n## Why `twat-hatch`?\n\n`twat-hatch` helps you create modern Python packages with a focus on plugin systems. It implements best practices for:\n\n### Modern python packaging\n\n- PEP 621-style configuration via `pyproject.toml`\n- `src/` layout pattern for better packaging practices\n- Type hints and runtime type checking with Pydantic\n- Automated dependency management\n\n### Plugin system architecture\n\n- **Namespace packages**: Create plugin host packages that dynamically expose plugins\n- **Dynamic discovery**: Automatic plugin registration via entry points\n- **Flexible usage**: Support both direct imports and namespace-based imports\n- **Clean dependencies**: Proper handling of optional plugin dependencies\n\n### Best practices implementation\n\n- **Code organization**: Enforced `src/` layout and modern project structure\n- **Error handling**: Built-in validation and error checking\n- **Documentation**: Automated documentation setup with MkDocs\n- **Testing**: Pre-configured test structure with pytest\n- **Type safety**: MyPy configuration and Pydantic validation\n\n## Installation\n\n```bash\nuv pip install twat-hatch\n```\n\nOr with `pip`:\n\n```bash\npip install twat-hatch\n```\n\n\n## Quick start\n\n1. Create a configuration file `twat-hatch.toml`:\n\n```toml\n[project]\npackages = [\"my-package\"]\noutput_dir = \"packages\"\n\n[author]\nname = \"Your Name\"\nemail = \"your.email@example.com\"\ngithub_username = \"yourusername\"\n\n[package]\nmin_python = \"3.8\"\nlicense = \"MIT\"\ndevelopment_status = \"4 - Beta\"\n```\n\n1. Run the package initializer:\n\n```bash\ntwat-hatch --config twat-hatch.toml\n```\n\n## Creating plugin-based packages\n\n### Plugin system overview\n\nWhen creating a plugin-based architecture, `twat-hatch` generates:\n\n1. **Plugin host package**: The core package that provides plugin discovery and management\n2. **Plugin packages**: Individual plugins that integrate with the host package\n\nExample configuration:\n\n```toml\n[project]\npackages = [\"my-plugin-a\", \"my-plugin-b\"]\nplugin_host = \"my-core-package\"\noutput_dir = \"packages\"\n\n# ... other configuration ...\n```\n\n### Plugin system usage\n\nOnce packages are created, they can be used in several ways:\n\n```python\n# Direct import of a plugin\nimport my_plugin_a\ninstance = my_plugin_a.SomeClass()\n\n# Via namespace package (if configured)\nfrom my_core_package import plugin_a\ninstance = plugin_a.SomeClass()\n```\n\nInstallation options:\n\n```bash\n# Install a plugin directly\npip install my-plugin-a\n\n# Install via the host package with extras\npip install my-core-package[plugin-a]\n\n# Install multiple plugins\npip install my-core-package[plugin-a,plugin-b]\n\n# Install all available plugins\npip install my-core-package[all]\n```\n\n## Configuration reference\n\nThe configuration file ( `twat-hatch.toml` ) supports the following sections:\n\n### Project configuration\n\n```toml\n[project]\npackages = [\"package-name\"] # List of packages to create\nplugin_host = \"host-package\" # Optional plugin host package\noutput_dir = \"path/to/output\" # Output directory (optional)\n```\n\n### Author information\n\n```toml\n[author]\nname = \"Author Name\"\nemail = \"author@example.com\"\ngithub_username = \"username\"\n```\n\n### Package settings\n\n```toml\n[package]\nmin_python = \"3.8\" # Minimum Python version\nlicense = \"MIT\" # Package license\ndevelopment_status = \"4 - Beta\" # PyPI development status\n```\n\n### Dependencies\n\n```toml\n[dependencies]\ndependencies = [ # Regular dependencies\n \"package>=1.0.0\"\n]\nplugin_dependencies = [ # Plugin-specific dependencies\n \"plugin-package>=1.0.0\"\n]\ndev_dependencies = [ # Development dependencies\n \"pytest>=7.0.0\"\n]\n```\n\n### Features\n\n```toml\n[features]\nmkdocs = false # Enable MkDocs documentation\nsemver = true # Use semantic versioning\nvcs = true # Initialize Git repository\n```\n\n## Generated package structure\n\n### Standalone package\n\n```\nmy-package/\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 my_package/ # Package source\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 core.py\n\u2514\u2500\u2500 tests/ # Test directory\n \u251c\u2500\u2500 conftest.py\n \u2514\u2500\u2500 test_my_package.py\n```\n\n### Plugin host package\n\n```\nmy-core-package/\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 pyproject.toml\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 my_core_package/\n\u2502 \u251c\u2500\u2500 __init__.py # Plugin discovery logic\n\u2502 \u2514\u2500\u2500 core.py # Core functionality\n\u2514\u2500\u2500 tests/\n \u251c\u2500\u2500 conftest.py\n \u2514\u2500\u2500 test_my_core_package.py\n```\n\n### Plugin package\n\n```\nmy-plugin/\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 pyproject.toml # Includes plugin entry points\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 my_plugin/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 plugin.py # Plugin implementation\n\u2514\u2500\u2500 tests/\n \u251c\u2500\u2500 conftest.py\n \u2514\u2500\u2500 test_my_plugin.py\n```\n\n## Development\n\nTo set up the development environment:\n\n```bash\ngit clone https://github.com/twardoch/twat-hatch.git\ncd twat-hatch\nuv venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\nuv pip install -e \".[dev]\"\n```\n\nRun tests:\n\n```bash\npytest\n```\n\nRun linting:\n\n```bash\nruff check .\nmypy src/\n```\n\n## Technical details\n\n### Package naming convention\n\n- Distribution names use hyphens: `my-plugin`\n- Import names use underscores: `my_plugin`\n- Plugin host packages follow the same convention\n\n### Plugin discovery\n\n- Plugins register via entry points under `{host}.plugins`\n- Plugin host packages support both direct imports and entry point discovery\n- Dynamic loading ensures plugins are only imported when needed\n\n### Dependencies management\n\n- Plugin packages can depend on their host package\n- Host packages define optional dependencies via extras\n- Version compatibility is managed through dependency specifications\n\n### Building and publishing\n\n1. Build and publish the plugin host package first\n2. Build and publish plugin packages separately\n3. Use consistent versioning across packages\n\n## License\n\nMIT License, see <LICENSE> for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n \n.\n",
"bugtrack_url": null,
"license": null,
"summary": "Plugin for twat that provides package initialization functionality",
"version": "1.8.1",
"project_urls": {
"Documentation": "https://github.com/twardoch/twat-hatch#readme",
"Issues": "https://github.com/twardoch/twat-hatch/issues",
"Source": "https://github.com/twardoch/twat-hatch"
},
"split_keywords": [
"package-template",
" twat",
" twat-plugin"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "73568b3edc3c9128073954e52dbae5ab84a871a672e8d1aff88b8b2a6367c90f",
"md5": "b4d1845e8d28311a960e5f1b2a0bac4a",
"sha256": "d16c768fb809e52318652d79644aa7c698966dc5a3b3c91587ab128677ae8a6f"
},
"downloads": -1,
"filename": "twat_hatch-1.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b4d1845e8d28311a960e5f1b2a0bac4a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 35031,
"upload_time": "2025-02-15T05:50:21",
"upload_time_iso_8601": "2025-02-15T05:50:21.283524Z",
"url": "https://files.pythonhosted.org/packages/73/56/8b3edc3c9128073954e52dbae5ab84a871a672e8d1aff88b8b2a6367c90f/twat_hatch-1.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "70ba98773525516f94882ed09aaea29d8dda6bbbfec2522fd290e697951aee87",
"md5": "02a5be88afe2e10303dd6f39adb10611",
"sha256": "b63ea27906745cdf8a8562eff86b500e7abd93eb3f6424a0e69e2db9d88f3bcb"
},
"downloads": -1,
"filename": "twat_hatch-1.8.1.tar.gz",
"has_sig": false,
"md5_digest": "02a5be88afe2e10303dd6f39adb10611",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 27999,
"upload_time": "2025-02-15T05:50:25",
"upload_time_iso_8601": "2025-02-15T05:50:25.119324Z",
"url": "https://files.pythonhosted.org/packages/70/ba/98773525516f94882ed09aaea29d8dda6bbbfec2522fd290e697951aee87/twat_hatch-1.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-15 05:50:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "twardoch",
"github_project": "twat-hatch#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "twat-hatch"
}
