| Name | castlecraft-engineer JSON |
| Version |
0.9.0
JSON |
| download |
| home_page | None |
| Summary | Python framework for building robust, scalable applications with DDD, CQRS, and Event Sourcing. |
| upload_time | 2025-07-12 00:33:39 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2025 Castlecraft Ecommerce Pvt. Ltd.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
cqrs
ddd
event sourcing
architecture
domain-driven design
framework
python
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Castlecraft Engineer
[](https://gitlab.com/castlecraft/framework/engineer/-/commits/main)
[](https://gitlab.com/castlecraft/framework/engineer/-/pipelines)
[](https://opensource.org/licenses/MIT)
[](https://engineer.castlecraft.in/)
[](https://pypi.org/project/castlecraft-engineer/)
[](https://pypi.org/project/castlecraft-engineer/)
**Castlecraft Engineer** is a Python framework designed to help developers build robust, scalable, and maintainable applications by leveraging established software design patterns like Domain-Driven Design (DDD), Command Query Responsibility Segregation (CQRS), and Event Sourcing.
It provides a collection of abstractions, base classes, and utilities to streamline the development of complex business logic while promoting clean architecture principles.
## Guiding Principles & Target Audience
Castlecraft Engineer is built upon established software design principles, primarily:
* **Domain-Driven Design (DDD)**: Tools to model complex business domains effectively.
* **Command Query Responsibility Segregation (CQRS)**: Encouraging separation of write and read operations.
* **Event-Driven Architecture (EDA)**: Support for Domain Events for decoupled communication.
This library is ideal for Python developers building applications with these principles, aiming for highly testable, maintainable, and scalable systems.
It may be less suitable for very simple CRUD applications or for teams seeking a fully opinionated, all-in-one web framework.
For a more detailed breakdown, see ["Who Is This Library For?"](https://engineer.castlecraft.in/#who-is-this-library-for) in our main documentation.
## Accelerate Development with Castlecraft Architect
While Castlecraft Engineer provides the foundational building blocks for DDD, we recognize that starting a new project can still involve significant boilerplate. To address this, we developed **[Castlecraft Architect](https://architect.castlecraft.in)**—an intelligent scaffolding and development acceleration tool.
Architect leverages the principles of Engineer to:
* **Generate DDD-aligned boilerplate**: Quickly scaffold your application with a well-structured foundation.
* **Facilitate Domain Exploration**: Generate context for LLMs to assist in discussions with domain experts.
* **Provide AI-Powered Guidance**: Suggest contextually relevant code additions while respecting architectural integrity.
Engineer is the open-source framework that provides the building blocks, and Architect is our open-source tool to help you get started faster and streamline development on top of it.
## Key Features
* **Domain-Driven Design (DDD) Primitives**: Base classes for `Aggregate` and `AggregateRepository` to model your domain and manage persistence with optimistic concurrency.
* **Command Query Responsibility Segregation (CQRS)**: Clear separation of write operations (Commands) and read operations (Queries) with dedicated buses (`CommandBus`, `QueryBus`) and handlers.
* **Event System**: Support for domain events (`Event`), in-process `EventBus`, and abstractions for `ExternalEventPublisher` and `EventStreamConsumer` for integrating with message brokers.
* **Event Store**: An `EventStore` abstraction for persisting event streams, crucial for implementing Event Sourcing. Includes an `InMemoryEventStore` for testing.
* **Sagas**: Support for managing distributed transactions and long-running processes through sagas (newly documented).
* **Dependency Injection**: Built-in DI container (`ContainerBuilder` based on `punq`) for managing dependencies and promoting loosely coupled components.
* **SQLModel-based Persistence**: Easy integration with SQL databases using `SQLModel`, with generic repositories (`ModelRepository`, `AsyncModelRepository`) for data access.
* **Authorization Framework**: A flexible authorization service (`AuthorizationService`, `Permission` objects, `@ctx` decorator) to secure your application's features.
* **Caching Utilities**: Helpers for integrating with Redis (`RedisCacheClient`, `AsyncRedisCacheClient`) for both synchronous and asynchronous caching needs.
* **OIDC Authentication**: Utilities for OpenID Connect (OIDC) token verification and JWKS caching (`AuthenticationService`).
* **Cryptography**: Simple encryption/decryption utilities (`encrypt_data`, `decrypt_data`) using AES-GCM (via the `cryptography` library).
* **Testing Utilities**: A suite of test helpers and base classes to facilitate unit and integration testing of components built with the framework.
* **CLI Support**: Basic CLI structure for bootstrapping tasks (e.g., database schema creation).
## Installation
You can install `castlecraft-engineer` using `uv` (recommended) or `pip`:
```bash
uv pip install castlecraft-engineer
```
Or:
```bash
pip install castlecraft-engineer
```
## Quickstart
To give you a taste of how Engineer structures operations, here's a brief example of defining a business command and its handler (a core concept in CQRS):
```python
from dataclasses import dataclass
from castlecraft_engineer.abstractions.command import Command
from castlecraft_engineer.abstractions.command_handler import CommandHandler
from castlecraft_engineer.common.di import ContainerBuilder
from castlecraft_engineer.abstractions.command_bus import CommandBus
import asyncio
# 1. Define a Command
@dataclass(frozen=True)
class CreateItemCommand(Command[str]): # Returns a string (e.g., item ID)
name: str
# 2. Define a Command Handler
class CreateItemHandler(CommandHandler[CreateItemCommand, str]):
async def execute(self, command: CreateItemCommand) -> str:
print(f"Creating item: {command.name}")
# ... actual logic to create and persist item ...
item_id = f"item_{command.name.lower().replace(' ', '_')}"
print(f"Item created with ID: {item_id}")
return item_id
async def main():
# 3. Setup DI Container and Buses
builder = ContainerBuilder()
builder.with_command_bus()
# Register with DI
builder.register(CreateItemHandler)
# Register with Command Bus
builder.command_bus.register(CreateItemHandler)
container = builder.build()
# 4. Get the Command Bus and execute the command
command_bus = container.resolve(CommandBus)
item_id = await command_bus.execute(CreateItemCommand(name="My New Item"))
print(f"Command executed, returned ID: {item_id}")
if __name__ == "__main__":
asyncio.run(main())
```
For more detailed examples and usage, please refer to the Full Documentation.
## Documentation
Comprehensive documentation, including conceptual guides, tutorials, and API references, is available at:
https://engineer.castlecraft.in
The documentation is built using MkDocs with the Material theme and includes:
* Installation Guide
* Quickstart Guide
* In-depth Conceptual Explanations
* Step-by-step Tutorials
* API Reference
* Guides on Error Handling, Testing, and CLI usage.
To build the documentation locally:
```bash
uv pip install mkdocs mkdocs-material pymdown-extensions mike mkdocs-awesome-pages-plugin
mkdocs serve
```
## Contributing
Contributions are welcome! If you'd like to contribute, please:
1. Fork the repository on GitLab.
2. Create a new branch for your feature or bug fix.
3. Make your changes and ensure tests pass.
4. Add or update documentation as necessary.
5. Submit a Merge Request with a clear description of your changes.
Please refer to the `CONTRIBUTING.md` file for more detailed guidelines.
We use `python-semantic-release` for versioning and releases, and `pre-commit` for code quality checks.
## Development Setup
To set up the project for development:
```bash
# 1. Clone the repository
git clone https://gitlab.com/castlecraft/framework/engineer.git
cd castlecraft-engineer
# 2. Create a virtual environment and install dependencies (using uv)
python -m venv .venv
source .venv/bin/activate
uv pip install -e ".[dev]"
# 3. Install pre-commit hooks
pre-commit install
```
## Running Tests
To run the test suite:
```bash
pytest
```
## License
This project is licensed under the MIT License - see the LICENSE file for details.
---
Built with passion by the Castlecraft Engineering team.
Raw data
{
"_id": null,
"home_page": null,
"name": "castlecraft-engineer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "CQRS, DDD, Event Sourcing, architecture, domain-driven design, framework, python",
"author": null,
"author_email": "\"Castlecraft Ecommerce Pvt. Ltd.\" <support@castlecraft.in>",
"download_url": "https://files.pythonhosted.org/packages/e1/e2/130252cc82f39c0d37626a431209ba34f6afb69741c299f21cc37dd8e1a0/castlecraft_engineer-0.9.0.tar.gz",
"platform": null,
"description": "# Castlecraft Engineer\n\n[](https://gitlab.com/castlecraft/framework/engineer/-/commits/main)\n[](https://gitlab.com/castlecraft/framework/engineer/-/pipelines)\n[](https://opensource.org/licenses/MIT)\n[](https://engineer.castlecraft.in/)\n[](https://pypi.org/project/castlecraft-engineer/)\n[](https://pypi.org/project/castlecraft-engineer/)\n\n**Castlecraft Engineer** is a Python framework designed to help developers build robust, scalable, and maintainable applications by leveraging established software design patterns like Domain-Driven Design (DDD), Command Query Responsibility Segregation (CQRS), and Event Sourcing.\n\nIt provides a collection of abstractions, base classes, and utilities to streamline the development of complex business logic while promoting clean architecture principles.\n\n## Guiding Principles & Target Audience\n\nCastlecraft Engineer is built upon established software design principles, primarily:\n\n* **Domain-Driven Design (DDD)**: Tools to model complex business domains effectively.\n* **Command Query Responsibility Segregation (CQRS)**: Encouraging separation of write and read operations.\n* **Event-Driven Architecture (EDA)**: Support for Domain Events for decoupled communication.\n\nThis library is ideal for Python developers building applications with these principles, aiming for highly testable, maintainable, and scalable systems.\nIt may be less suitable for very simple CRUD applications or for teams seeking a fully opinionated, all-in-one web framework.\n\nFor a more detailed breakdown, see [\"Who Is This Library For?\"](https://engineer.castlecraft.in/#who-is-this-library-for) in our main documentation.\n\n## Accelerate Development with Castlecraft Architect\n\nWhile Castlecraft Engineer provides the foundational building blocks for DDD, we recognize that starting a new project can still involve significant boilerplate. To address this, we developed **[Castlecraft Architect](https://architect.castlecraft.in)**\u2014an intelligent scaffolding and development acceleration tool.\n\nArchitect leverages the principles of Engineer to:\n* **Generate DDD-aligned boilerplate**: Quickly scaffold your application with a well-structured foundation.\n* **Facilitate Domain Exploration**: Generate context for LLMs to assist in discussions with domain experts.\n* **Provide AI-Powered Guidance**: Suggest contextually relevant code additions while respecting architectural integrity.\n\nEngineer is the open-source framework that provides the building blocks, and Architect is our open-source tool to help you get started faster and streamline development on top of it.\n\n## Key Features\n\n* **Domain-Driven Design (DDD) Primitives**: Base classes for `Aggregate` and `AggregateRepository` to model your domain and manage persistence with optimistic concurrency.\n* **Command Query Responsibility Segregation (CQRS)**: Clear separation of write operations (Commands) and read operations (Queries) with dedicated buses (`CommandBus`, `QueryBus`) and handlers.\n* **Event System**: Support for domain events (`Event`), in-process `EventBus`, and abstractions for `ExternalEventPublisher` and `EventStreamConsumer` for integrating with message brokers.\n* **Event Store**: An `EventStore` abstraction for persisting event streams, crucial for implementing Event Sourcing. Includes an `InMemoryEventStore` for testing.\n* **Sagas**: Support for managing distributed transactions and long-running processes through sagas (newly documented).\n* **Dependency Injection**: Built-in DI container (`ContainerBuilder` based on `punq`) for managing dependencies and promoting loosely coupled components.\n* **SQLModel-based Persistence**: Easy integration with SQL databases using `SQLModel`, with generic repositories (`ModelRepository`, `AsyncModelRepository`) for data access.\n* **Authorization Framework**: A flexible authorization service (`AuthorizationService`, `Permission` objects, `@ctx` decorator) to secure your application's features.\n* **Caching Utilities**: Helpers for integrating with Redis (`RedisCacheClient`, `AsyncRedisCacheClient`) for both synchronous and asynchronous caching needs.\n* **OIDC Authentication**: Utilities for OpenID Connect (OIDC) token verification and JWKS caching (`AuthenticationService`).\n* **Cryptography**: Simple encryption/decryption utilities (`encrypt_data`, `decrypt_data`) using AES-GCM (via the `cryptography` library).\n* **Testing Utilities**: A suite of test helpers and base classes to facilitate unit and integration testing of components built with the framework.\n* **CLI Support**: Basic CLI structure for bootstrapping tasks (e.g., database schema creation).\n\n## Installation\n\nYou can install `castlecraft-engineer` using `uv` (recommended) or `pip`:\n\n```bash\nuv pip install castlecraft-engineer\n```\nOr:\n```bash\npip install castlecraft-engineer\n```\n\n## Quickstart\n\nTo give you a taste of how Engineer structures operations, here's a brief example of defining a business command and its handler (a core concept in CQRS):\n\n```python\nfrom dataclasses import dataclass\nfrom castlecraft_engineer.abstractions.command import Command\nfrom castlecraft_engineer.abstractions.command_handler import CommandHandler\nfrom castlecraft_engineer.common.di import ContainerBuilder\nfrom castlecraft_engineer.abstractions.command_bus import CommandBus\nimport asyncio\n\n# 1. Define a Command\n@dataclass(frozen=True)\nclass CreateItemCommand(Command[str]): # Returns a string (e.g., item ID)\n name: str\n\n# 2. Define a Command Handler\nclass CreateItemHandler(CommandHandler[CreateItemCommand, str]):\n async def execute(self, command: CreateItemCommand) -> str:\n print(f\"Creating item: {command.name}\")\n # ... actual logic to create and persist item ...\n item_id = f\"item_{command.name.lower().replace(' ', '_')}\"\n print(f\"Item created with ID: {item_id}\")\n return item_id\n\nasync def main():\n # 3. Setup DI Container and Buses\n builder = ContainerBuilder()\n builder.with_command_bus()\n # Register with DI\n builder.register(CreateItemHandler)\n # Register with Command Bus\n builder.command_bus.register(CreateItemHandler)\n container = builder.build()\n\n # 4. Get the Command Bus and execute the command\n command_bus = container.resolve(CommandBus)\n item_id = await command_bus.execute(CreateItemCommand(name=\"My New Item\"))\n print(f\"Command executed, returned ID: {item_id}\")\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\nFor more detailed examples and usage, please refer to the Full Documentation.\n\n## Documentation\n\nComprehensive documentation, including conceptual guides, tutorials, and API references, is available at:\nhttps://engineer.castlecraft.in\n\nThe documentation is built using MkDocs with the Material theme and includes:\n* Installation Guide\n* Quickstart Guide\n* In-depth Conceptual Explanations\n* Step-by-step Tutorials\n* API Reference\n* Guides on Error Handling, Testing, and CLI usage.\n\nTo build the documentation locally:\n```bash\nuv pip install mkdocs mkdocs-material pymdown-extensions mike mkdocs-awesome-pages-plugin\nmkdocs serve\n```\n\n## Contributing\n\nContributions are welcome! If you'd like to contribute, please:\n1. Fork the repository on GitLab.\n2. Create a new branch for your feature or bug fix.\n3. Make your changes and ensure tests pass.\n4. Add or update documentation as necessary.\n5. Submit a Merge Request with a clear description of your changes.\n\nPlease refer to the `CONTRIBUTING.md` file for more detailed guidelines.\nWe use `python-semantic-release` for versioning and releases, and `pre-commit` for code quality checks.\n\n## Development Setup\n\nTo set up the project for development:\n```bash\n# 1. Clone the repository\ngit clone https://gitlab.com/castlecraft/framework/engineer.git\ncd castlecraft-engineer\n\n# 2. Create a virtual environment and install dependencies (using uv)\npython -m venv .venv\nsource .venv/bin/activate\nuv pip install -e \".[dev]\"\n\n# 3. Install pre-commit hooks\npre-commit install\n```\n\n## Running Tests\n\nTo run the test suite:\n```bash\npytest\n```\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n---\n\nBuilt with passion by the Castlecraft Engineering team.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Castlecraft Ecommerce Pvt. Ltd.\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Python framework for building robust, scalable applications with DDD, CQRS, and Event Sourcing.",
"version": "0.9.0",
"project_urls": {
"Bug Tracker": "https://gitlab.com/castlecraft/framework/engineer/-/issues",
"Documentation": "https://engineer.castlecraft.in/",
"Homepage": "https://gitlab.com/castlecraft/framework/engineer",
"Repository": "https://gitlab.com/castlecraft/framework/engineer"
},
"split_keywords": [
"cqrs",
" ddd",
" event sourcing",
" architecture",
" domain-driven design",
" framework",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4670a1e0c5d7837725a08d0fee12f782dd0630cb00262ea3b3126a2f4d65dcd3",
"md5": "df68908841c5ee372c80f4c60d9a9176",
"sha256": "a0df3df967eb9e0784ca7ef6671e8846e160ecb5b3e43838356462486593f39b"
},
"downloads": -1,
"filename": "castlecraft_engineer-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "df68908841c5ee372c80f4c60d9a9176",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 95979,
"upload_time": "2025-07-12T00:33:38",
"upload_time_iso_8601": "2025-07-12T00:33:38.430303Z",
"url": "https://files.pythonhosted.org/packages/46/70/a1e0c5d7837725a08d0fee12f782dd0630cb00262ea3b3126a2f4d65dcd3/castlecraft_engineer-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e1e2130252cc82f39c0d37626a431209ba34f6afb69741c299f21cc37dd8e1a0",
"md5": "3c7b06cc6f28bee2f04ac806c6ce4efc",
"sha256": "f3d51ef5a6d09782be5d5bde0086c3e694e20d75fd0b2752cc7ce4e736b84c71"
},
"downloads": -1,
"filename": "castlecraft_engineer-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "3c7b06cc6f28bee2f04ac806c6ce4efc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 65495,
"upload_time": "2025-07-12T00:33:39",
"upload_time_iso_8601": "2025-07-12T00:33:39.842569Z",
"url": "https://files.pythonhosted.org/packages/e1/e2/130252cc82f39c0d37626a431209ba34f6afb69741c299f21cc37dd8e1a0/castlecraft_engineer-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 00:33:39",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "castlecraft",
"gitlab_project": "framework",
"lcname": "castlecraft-engineer"
}
