forging-blocks 0.3.6__tar.gz

forging_blocks-0.3.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Glauber Brennon
+
+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.

forging_blocks-0.3.6/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.1
+Name: forging-blocks
+Version: 0.3.6
+Summary: Composable toolkit for clean, testable, and maintainable Python applications
+Home-page: https://forging-blocks-org.github.io/forging-blocks/
+License: MIT
+Keywords: python library,clean architecture,hexagonal architecture,domain-driven design,ddd,framework-agnostic,software architecture,software design,software engineering,ports and adapters,adapter pattern,application service,repository pattern,message bus,notifier pattern,data mapper,result pattern,result monad,ok,err,either type,debuggable,use case,domain layer,application layer,presentation layer,foundation,forging blocks
+Author: ForgingBlocks Org
+Author-email: forgingblocksorganization91@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Project-URL: Repository, https://github.com/forging-blocks-org/forging-blocks
+Description-Content-Type: text/markdown
+
+# ForgingBlocks
+
+Composable **abstractions and interfaces** for writing clean, testable, and maintainable Python code.
+
+[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Poetry](https://img.shields.io/badge/packaging-poetry-blue.svg)](https://python-poetry.org/)
+[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](https://mypy-lang.org/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+
+---
+
+## 🌱 Overview
+
+> Not a framework — a **toolkit** of composable contracts and abstractions.
+
+**ForgingBlocks** helps you create codebases that are:
+- **Clean** — with clear boundaries and intent
+- **Testable** — by design, through explicit interfaces
+- **Maintainable** — by isolating concerns and dependencies
+
+It doesn’t dictate your architecture.
+Instead, it provides **foundations and reusable** abstractions for **forging** your own **blocks**.
+
+Isolate external concerns from your core logic you will achieve systems that are adaptable and resilient. 
+If you **forge** your own **block** you will achieve software with intent and clarity
+If you use **blocks** you will achieve consistency and reusability.
+**ForgingBlocks** helps you build systems that last.
+
+You can use it to:
+- Learn and apply **architecture and design principles**
+- Build **decoupled applications** that scale safely
+- Model systems with **type safety and explicit intent**
+- Experiment with **Clean**, **Hexagonal**, **DDD**, or **Message-Driven** styles
+
+---
+
+## 🧩 Core Concepts
+
+> Foundations, not frameworks — ForgingBlocks provides the *language* for clean architecture.
+
+This toolkit defines **layer-agnostic foundations** that compose into any design:
+
+- `Result`, `Ok`, `Err` → explicit success/failure handling
+- `Port`, `InboundPort`, `OutboundPort` → communication boundaries
+- `Entity`, `ValueObject`, `AggregateRoot` → domain modeling
+- `Repository`, `UnitOfWork` → persistence contracts
+- `Event`, `EventBus`, `CommandHandler` → messaging and orchestration
+
+---
+
+## 🚀 Installation
+
+```bash
+poetry add forging-blocks
+# or
+pip install forging-blocks
+```
+
+---
+
+## ⚡ Quick Example
+
+```python
+from forging_blocks.foundation import Result, Ok, Err
+
+def divide(a: int, b: int) -> Result[int, str]:
+    if b == 0:
+        return Err("division by zero")
+    return Ok(a // b)
+
+result = divide(10, 2)
+if result.is_ok():
+    print(result.value)  # → 5
+```
+
+---
+
+## 📚 Learn More
+
+- [📘 Documentation](https://forging-blocks-org.github.io/forging-blocks/)
+- [🚀 Getting Started Guide](docs/guide/getting-started.md)
+- [🏗️ Architecture Overview](docs/guide/architecture.md)
+- [🧱 Packages & Layers](docs/guide/packages_and_layers.md)
+- [🧩 Release Process](docs/guide/release_guide.md)
+
+---
+
+## 🧠 Why It Matters
+
+Most systems fail not because of missing features,
+but because of **tight coupling**, **implicit dependencies**, and **unclear responsibilities**.
+
+**ForgingBlocks** helps you *design code intentionally* —
+so your system remains testable, extensible, and adaptable as it grows.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! 🎉
+
+1. Fork the repository
+2. Install dependencies with Poetry
+3. Run tests and lint checks:
+   ```bash
+   poetry run poe ci:simulate
+   ```
+4. Submit a pull request with a clear description of your improvement
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
+
+---
+
+## ⚖️ License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+_**ForgingBlocks** — foundations for clean, testable, and maintainable Python architectures._
+

forging_blocks-0.3.6/README.md

@@ -0,0 +1,121 @@
+# ForgingBlocks
+
+Composable **abstractions and interfaces** for writing clean, testable, and maintainable Python code.
+
+[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Poetry](https://img.shields.io/badge/packaging-poetry-blue.svg)](https://python-poetry.org/)
+[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](https://mypy-lang.org/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+
+---
+
+## 🌱 Overview
+
+> Not a framework — a **toolkit** of composable contracts and abstractions.
+
+**ForgingBlocks** helps you create codebases that are:
+- **Clean** — with clear boundaries and intent
+- **Testable** — by design, through explicit interfaces
+- **Maintainable** — by isolating concerns and dependencies
+
+It doesn’t dictate your architecture.
+Instead, it provides **foundations and reusable** abstractions for **forging** your own **blocks**.
+
+Isolate external concerns from your core logic you will achieve systems that are adaptable and resilient. 
+If you **forge** your own **block** you will achieve software with intent and clarity
+If you use **blocks** you will achieve consistency and reusability.
+**ForgingBlocks** helps you build systems that last.
+
+You can use it to:
+- Learn and apply **architecture and design principles**
+- Build **decoupled applications** that scale safely
+- Model systems with **type safety and explicit intent**
+- Experiment with **Clean**, **Hexagonal**, **DDD**, or **Message-Driven** styles
+
+---
+
+## 🧩 Core Concepts
+
+> Foundations, not frameworks — ForgingBlocks provides the *language* for clean architecture.
+
+This toolkit defines **layer-agnostic foundations** that compose into any design:
+
+- `Result`, `Ok`, `Err` → explicit success/failure handling
+- `Port`, `InboundPort`, `OutboundPort` → communication boundaries
+- `Entity`, `ValueObject`, `AggregateRoot` → domain modeling
+- `Repository`, `UnitOfWork` → persistence contracts
+- `Event`, `EventBus`, `CommandHandler` → messaging and orchestration
+
+---
+
+## 🚀 Installation
+
+```bash
+poetry add forging-blocks
+# or
+pip install forging-blocks
+```
+
+---
+
+## ⚡ Quick Example
+
+```python
+from forging_blocks.foundation import Result, Ok, Err
+
+def divide(a: int, b: int) -> Result[int, str]:
+    if b == 0:
+        return Err("division by zero")
+    return Ok(a // b)
+
+result = divide(10, 2)
+if result.is_ok():
+    print(result.value)  # → 5
+```
+
+---
+
+## 📚 Learn More
+
+- [📘 Documentation](https://forging-blocks-org.github.io/forging-blocks/)
+- [🚀 Getting Started Guide](docs/guide/getting-started.md)
+- [🏗️ Architecture Overview](docs/guide/architecture.md)
+- [🧱 Packages & Layers](docs/guide/packages_and_layers.md)
+- [🧩 Release Process](docs/guide/release_guide.md)
+
+---
+
+## 🧠 Why It Matters
+
+Most systems fail not because of missing features,
+but because of **tight coupling**, **implicit dependencies**, and **unclear responsibilities**.
+
+**ForgingBlocks** helps you *design code intentionally* —
+so your system remains testable, extensible, and adaptable as it grows.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! 🎉
+
+1. Fork the repository
+2. Install dependencies with Poetry
+3. Run tests and lint checks:
+   ```bash
+   poetry run poe ci:simulate
+   ```
+4. Submit a pull request with a clear description of your improvement
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
+
+---
+
+## ⚖️ License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+_**ForgingBlocks** — foundations for clean, testable, and maintainable Python architectures._

forging_blocks-0.3.6/pyproject.toml

@@ -0,0 +1,245 @@
+[tool.poetry]
+name = "forging-blocks"
+version = "0.3.6"
+description = "Composable toolkit for clean, testable, and maintainable Python applications"
+authors = ["ForgingBlocks Org <forgingblocksorganization91@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+repository = "https://github.com/forging-blocks-org/forging-blocks"
+homepage = "https://forging-blocks-org.github.io/forging-blocks/"
+packages = [{ include = "forging_blocks", from = "src" }]
+keywords = [
+  "python library",
+  "clean architecture",
+  "hexagonal architecture",
+  "domain-driven design",
+  "ddd",
+  "framework-agnostic",
+  "software architecture",
+  "software design",
+  "software engineering",
+  "ports and adapters",
+  "adapter pattern",
+  "application service",
+  "repository pattern",
+  "message bus",
+  "notifier pattern",
+  "data mapper",
+  "result pattern",
+  "result monad",
+  "ok",
+  "err",
+  "either type",
+  "debuggable",
+  "use case",
+  "domain layer",
+  "application layer",
+  "presentation layer",
+  "foundation",
+  "forging blocks",
+]
+
+[tool.poetry.dependencies]
+python = "^3.12"
+
+[tool.poetry.group.dev.dependencies]
+mypy = "^1.16.1"
+ruff = "^0.14.3"
+black = "^25.1.0"
+pytest = "^8.3.3"
+pytest-cov = "^5.0.0"
+pytest-asyncio = "^0.25.0"
+bandit = "^1.7.10"
+pre-commit = "^4.2.0"
+pyright = "^1.1.404"
+poethepoet = "^0.37.0"
+libcst = "^1.8.6"
+
+[tool.poetry.group.docs.dependencies]
+mkdocs = "^1.6.1"
+mkdocs-material = "^9.6.23"
+mkdocstrings = {extras = ["python"], version = "^0.30.1"}
+mkdocs-gen-files = "^0.5.0"
+mkdocs-literate-nav = "^0.6.2"
+mkdocs-autorefs = "^1.4.3"
+mkdocs-mermaid2-plugin = "^1.2.3"
+mkdocs-section-index = "^0.3.10"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+src = ["src", "tests", "scripts"]
+fix = true
+extend-exclude = ["site"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "D"]
+ignore = [
+    "B008",
+    "D105",
+    "D106",
+    "D107",
+    "D203",
+    "D213",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+known-first-party = ["forging_blocks"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*" = ["D"]
+"scripts/*.py" = ["D100", "D101", "D102", "D103", "D104", "D105", "D106", "D107"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+
+# ---------------------------------------------------------------------------
+# Mypy Configuration
+# ---------------------------------------------------------------------------
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = false
+allow_untyped_globals = true
+check_untyped_defs = false
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+strict_equality = true
+show_error_codes = true
+mypy_path = "src"
+exclude = ["^tests/"]
+
+[[tool.mypy.overrides]]
+module = "src.*"
+disallow_incomplete_defs = true
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = true
+disallow_incomplete_defs = false
+check_untyped_defs = false
+allow_untyped_globals = true
+
+# ---------------------------------------------------------------------------
+# Pytest Configuration
+# ---------------------------------------------------------------------------
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+asyncio_mode = "auto"
+addopts = [
+  "--strict-markers",
+  "--strict-config",
+  "--cov=forging_blocks",
+  "--cov-report=term-missing",
+]
+
+# ---------------------------------------------------------------------------
+# Coverage Configuration
+# ---------------------------------------------------------------------------
+[tool.coverage.report]
+exclude_lines = [
+    "@abstractmethod"
+]
+
+[tool.coverage.run]
+omit = [
+    "src/forging_blocks/application/ports/inbound/*.py",
+    "src/forging_blocks/application/ports/outbound/*.py",
+    "src/forging_blocks/foundation/mapper.py",
+    "src/forging_blocks/foundation/result_mapper.py",
+    "src/forging_blocks/foundation/ports.py",
+    "src/forging_blocks/foundation/debuggable.py"
+]
+
+[tool.black]
+line-length = 100
+target-version = ["py312"]
+
+[tool.flake8]
+max-line-length = 100
+extend-ignore = "E203,W503"
+class-order-style = "google"
+
+[tool.flake8-class-attributes-order]
+order = [
+  "__new__",
+  "__init__",
+  "classmethod",
+  "staticmethod",
+  "property",
+  "method",
+  "dunder"
+]
+
+class_attributes_order_style = "custom"
+
+[tool.poe.tasks]
+lint = { cmd = "ruff check ." }
+
+"lint:docs" = { cmd = "ruff check --select D100,D101,D102,D103,D104 src" }
+
+"lint:fix" = { cmd = "ruff check . --fix" }
+
+format.sequence = [
+  { cmd = "ruff check . --fix" },
+  { cmd = "ruff check --fix --unsafe-fixes src" },
+]
+"format:docs" = { cmd = "ruff check --select D --fix --unsafe-fixes src" }
+"type:mypy" = { cmd = "mypy --config-file pyproject.toml src" }
+"type:pyright" = { cmd = "pyright" }
+bandit = { cmd = "bandit -r src -x tests" }
+pre-commit = { cmd = "pre-commit run --all-files" }
+test = { cmd = "pytest -q" }
+"test:quick" = { cmd = "pytest -x -q" }
+"test:strict" = { cmd = "pytest -x --strict-markers" }
+"test:nocov" = { cmd = "pytest -q --no-cov" }
+"test:pipeline" = { cmd = "pytest --cov=src --cov-report=xml --cov-fail-under=80" }
+"mkdocs:serve" = { cmd = "mkdocs serve" }
+"mkdocs:build" = { cmd = "mkdocs build" }
+"mkdocs:clean" = { cmd = "mkdocs build --clean" }
+"mkdocs:deploy" = { cmd = "mkdocs gh-deploy --clean" }
+"docs:generate" = { cmd = "python scripts/generate_autodoc_pages.py" }
+"docs:serve".sequence = [
+    { cmd = "mkdocs build --clean" },
+    { cmd = "mkdocs serve" },
+]
+"docs:check".sequence = [
+  { cmd = "ruff check --select D" },
+  { cmd = "mkdocs build --strict" },
+]
+"docs:clean" = { cmd = "git restore mkdocs.yml" }
+"ci:simulate".sequence = [
+  { cmd = "poetry install --with dev,docs" },
+  { cmd = "poetry run poe lint" },
+  { cmd = "poetry run poe type:mypy" },
+  { cmd = "poetry run poe test:pipeline" },
+  { cmd = "poetry run python scripts/generate_autodoc_pages.py" },
+  { shell = "poetry run mkdocs build --strict || echo '❌ MkDocs build failed (warnings treated as errors). See log above.'" },
+  { cmd = "git restore mkdocs.yml" }  # revert autogenerated changes
+]
+"ci:clean".sequence = [
+  { cmd = "rm -rf .venv ~/.cache/pypoetry" },
+  { cmd = "poetry env use 3.12" },
+  { cmd = "poetry lock --no-update" },
+  { cmd = "poetry install --with dev,docs" },
+  { cmd = "poetry run poe lint" },
+  { cmd = "poetry run poe type:mypy" },
+  { cmd = "poetry run poe test:pipeline" },
+  { cmd = "poetry run python scripts/generate_autodoc_pages.py" },
+  { cmd = "poetry run mkdocs build --strict" },
+  { cmd = "git restore mkdocs.yml" }  # clean after run
+]

forging_blocks-0.3.6/src/forging_blocks/__init__.py

@@ -0,0 +1 @@
+"""ForgingBlocks package initialization."""

forging_blocks-0.3.6/src/forging_blocks/application/README.md

@@ -0,0 +1,136 @@
+# Application Layer ⚙️
+
+The **application layer** orchestrates use cases, coordinates domain logic, and manages cross-cutting concerns such as transactions and notifications.
+It acts as a bridge between the domain layer (business logic) and the outside world (presentation, infrastructure, external services).
+
+---
+
+## 📁 Directory Structure
+
+```
+application/
+├── ports/
+│   ├── inbound/
+│   │   └── use_case.py         # Abstract base for use cases/handlers
+│   └── outbound/
+│       ├── event_publisher.py  # Contract for publishing integration events
+│       ├── notifier.py         # Contract for sending notifications
+│       └── unit_of_work.py     # Contract for transaction management
+└── services/                   # Implementations of application use cases
+```
+
+---
+
+## ✨ Core Concepts
+
+### 1. **Application Inbound Ports**
+- **Purpose:** Define the entry points for your application's business workflows (use cases).
+- **What goes here:** Abstract base classes/interfaces for commands, queries, and use cases.
+- **Example:** `AsyncUseCase` and `SyncUseCase` ABCs in `ports/inbound/use_case.py`.
+
+### 2. **Application Services**
+- **Purpose:** Implement the business workflows and coordinate domain objects, repositories, and outbound ports.
+- **What goes here:** Concrete classes that implement inbound port interfaces and orchestrate use cases.
+- **Example:** `services/CreateUserService` (you provide your own implementations).
+
+### 3. **Application Outbound Ports**
+- **Purpose:** Abstract external systems or cross-cutting concerns that the application interacts with.
+- **What goes here:** Interfaces for things like event publishing, notifications, and transaction management.
+- **Examples:**
+  - `event_publisher.py`: Publish integration/application events
+  - `notifier.py`: Send notifications (email, SMS, etc.)
+  - `unit_of_work.py`: Coordinate transactional boundaries for use cases
+
+---
+
+## 🧩 How to Use
+
+> **Best Practice:**
+> Application services (use cases) should use DTOs (Data Transfer Objects) as their input and output types, not domain entities.
+> This keeps your application layer decoupled from domain and presentation concerns, and ensures a stable contract between layers.
+
+### 1. Define Use Case, Request, and Response (with type hints, using AsyncUseCase or SyncUseCase)
+
+```python
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from forging_blocks.application.ports.inbound.use_case import AsyncUseCase
+
+@dataclass(frozen=True)
+class CreateUserRequest:
+    email: str
+    name: str
+
+@dataclass(frozen=True)
+class CreateUserResponse:
+    user_id: str
+
+class CreateUserUseCase(AsyncUseCase[CreateUserRequest, CreateUserResponse], ABC):
+    @abstractmethod
+    async def execute(self, request: CreateUserRequest) -> CreateUserResponse:
+        """
+        Execute the use case to create a user.
+
+        Args:
+            request: The CreateUserRequest DTO with input data.
+
+        Returns:
+            CreateUserResponse DTO with the result user_id.
+        """
+```
+
+> You can use either `AsyncUseCase` or `SyncUseCase` for your interfaces, depending on your application's needs.
+> Keeping request and response DTOs close to the use case interface helps with discoverability and cohesion.
+
+### 2. Implement the Use Case
+
+```python
+from forging_blocks.application.ports.outbound.notifier import AsyncNotifier
+from forging_blocks.application.ports.outbound.unit_of_work import (
+    AsyncUnitOfWork
+)
+from forging_blocks.domain.ports.outbound.repository import AsyncRepository
+
+class CreateUserService(CreateUserUseCase):
+    def __init__(
+        self,
+        user_repo: AsyncRepository,
+        notifier: AsyncNotifier,
+        uow: AsyncUnitOfWork
+    ) -> None:
+        self._user_repo = user_repo
+        self._notifier = notifier
+        self._uow = uow
+
+    async def execute(self, request: CreateUserRequest) -> CreateUserResponse:
+        async with self._uow:
+            user = User(...)
+            # Create a new User entity, possibly using a factory method
+            await self._user_repo.save(user)
+            await self._notifier.notify(...)
+            # Send a notification (e.g., welcome email)
+            return CreateUserResponse(user_id=user.id)
+```
+
+---
+
+## 🏗️ Why This Matters
+
+- **Separation of Concerns:** Keeps business workflows free from technical details.
+- **Testability:** Use cases can be tested by mocking outbound ports.
+- **Flexibility:** Infrastructure can be swapped (e.g., different notification services) without changing application logic.
+- **Explicit Boundaries:** Makes dependencies and orchestration visible and intentional.
+- **Decoupling:** Using DTOs for input/output prevents leaking domain details to the outside world.
+
+---
+
+## 🧑‍💻 Extending the Application Layer
+
+- **Add new inbound ports** for new use cases.
+- **Add new outbound ports** for new integrations (e.g., background jobs, analytics, etc.).
+- **Implement services** for each use case, orchestrating domain and infrastructure as needed.
+
+---
+
+**For more examples and usage, see the project root [README](../../README.md) and the `/examples` directory.**

forging_blocks-0.3.6/src/forging_blocks/application/__init__.py

@@ -0,0 +1 @@
+"""ForgingBlocks for application-specific modules."""