forging-blocks-org/forging-blocks: Not a framework, a toolkit!

Not a framework, a toolkit!

Summary

ForgingBlocks is a Python toolkit that provides composable abstractions and interfaces for writing clean, testable code, including Result, ValueObject, and ports-and-adapters primitives for dependency inversion. It is explicitly positioned as a toolkit rather than a framework, so engineers can adopt individual pieces without committing to a whole architecture. The package is published under the MIT license and targets Python 3.14+.

What it is useful for

ForgingBlocks is useful when a Python codebase needs explicit error handling without exceptions, immutable domain values, or a clean separation between domain logic and external dependencies. The README describes it as "layer-agnostic foundations for clean architecture," making it relevant for teams adopting clean or hexagonal architecture patterns in Python. It fits scenarios where:

• Functions should return success and failure outcomes that callers must handle explicitly, instead of raising exceptions.
• Domain concepts such as identifiers, ranges, or quantities should be modeled as value objects that prevent invalid state.
• Code needs stable ports (interfaces) and swappable adapters for databases, message brokers, or external APIs, supporting testability through dependency inversion.
• A team wants a shared vocabulary across services without forcing a particular framework on each one.

How engineers can use it

Installation is documented in the README and supports common Python package managers:

pip install forging-blocks
poetry add forging-blocks
uv add forging-blocks

The README's quick example demonstrates the Result type for error handling:

from forging_blocks.foundation import Result, Ok, Err

def divide(a: float, b: float) -> Result[float, str]:
    if b == 0:
        return Err("Don't divide by zero")
    return Ok(a / b)

result = divide(10, 2).map(lambda n: f"Result: {n}")
print(result.value)  # "Result: 5.0"

This pattern forces callers to handle the failure case explicitly. Beyond Result, the toolkit ships ValueObject for domain modeling and ports-and-adapters interfaces, but the README does not include inline snippets for those pieces — for full usage, the project links to a Getting Started guide, a Blocks Overview, an Architecture Overview, a Testing Guide, and an API Reference.

Documented limitations and notes:

• Requires Python 3.14 or newer, which is a notable constraint for teams still on 3.12 or 3.13.
• The README does not enumerate every block in the current release beyond the foundations shown; readers should consult the API Reference for the full surface area.
• Because it is not a framework, there is no scaffold or runner — engineers wire its pieces into their own application code, which is by design.