forging-blocks 0.3.6

Composable toolkit for clean, testable, and maintainable Python applications

ForgingBlocks

Composable abstractions and interfaces for writing clean, testable, and maintainable Python code.

---

🌱 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

poetry add forging-blocks
# or
pip install forging-blocks

---

⚡ Quick Example

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
• 🚀 Getting Started Guide
• 🏗️ Architecture Overview
• 🧱 Packages & Layers
• 🧩 Release Process

---

🧠 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:

   poetry run poe ci:simulate
   

4. Submit a pull request with a clear description of your improvement

See CONTRIBUTING.md for more details.

---

⚖️ License

MIT — see LICENSE

---

ForgingBlocks — foundations for clean, testable, and maintainable Python architectures.