Skip to content

ForgingBlocks

ForgingBlocks provides a set of small, composable foundational contracts that help you design software with clarity, intent, and expressiveness.

It doesn’t enforce any framework, library, or organizational approach.

Instead, it gives you a vocabulary and building blocks for shaping ideas in a way that fits your project and your style.

ForgingBlocks relies only on standard features available in Python 3.14+ (such as Protocols, Generics, and Type Hints), keeping it lightweight and broadly compatible.

Quick summary

ForgingBlocks provides foundational contracts for designing software with clarity, intent, and expressiveness.

It is not a framework — it gives you a vocabulary and building blocks to shape your own architecture using standard Python 3.14+ features (Protocols, Generics, Type Hints).

Key points:
- Small, composable abstractions (Result, Port, Entity, ValueObject, UseCase, etc.)
- Architecture-neutral — works with your preferred style
- Focus on explicit outcomes, clear boundaries, and testability
- Zero dependencies, lightweight

Architecture-agnostic — no DDD required

ForgingBlocks does not require Domain-Driven Design (DDD). You can use only the Foundation block for utilities like Result, ValueObject, Port, Specification, and structured errors — without adopting entities, aggregates, or domain layers. The Domain, Application, and other blocks are optional. Pick what fits your project.

Getting Started

Install using Poetry, pip or uv:

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

Quick example:

from forging_blocks.foundation import Result, Ok, Err

def divide_quotient_only(dividend: int, divisor: int) -> Result[int, str]:
    if divisor == 0:
        return Err("Division by zero")

    quotient = dividend // divisor

    return Ok(quotient)

Or that operation with a remainder:

def divide_with_remainder(dividend: int, divisor: int) -> Result[tuple[int, int], str]:
    if divisor == 0:
        return Err("Division by zero")

    quotient = dividend // divisor
    remainder = dividend % divisor

    return Ok((quotient, remainder))

How can ForgingBlocks help me?

ForgingBlocks helps you keep your project's structure clear, intentional, and easy to reason about.

It provides small, composable abstractions that support writing clean, testable, and maintainable Python code — without tying you to any framework or architectural pattern.

Not a framework. Not an architecture. A toolkit for forging your own building blocks.

ForgingBlocks doesn't prescribe how your system must be structured.
Instead, it works alongside your preferred style and supports practices like:

  • Making success and failure explicit
  • Creating clear boundaries between components
  • Modeling domain concepts that express intent
  • Keeping core logic independent of infrastructure concerns

You remain in control.

You define the guidelines and conventions that fit your project.

ForgingBlocks simply provides the building blocks that help you write decoupled, testable, high-quality code — free from framework lock-in.

Core Concepts

Concept Purpose
Result / Ok / Err Represents success or failure explicitly.
Mapper Transforms values from one type into another in an observable way.
Identified Protocol for any object that carries an identifier.
Debuggable Protocol ensuring an object exposes a clear, consistent debug representation.
Port / InboundPort / OutboundPort Define explicit communication boundaries.
ValueObject Base class for immutable concepts defined entirely by their values.
Error / ValidationError / RuleViolationError / FieldErrors / CombinedErrors Structured, composable error model.
Message / Command / Event / Query Express intent, facts, and queries within the problem space.
FinalMeta / FinalABCMeta / runtime_final Optional runtime enforcement of method finality.

Organizational Blocks

Each block represents a boundary of responsibility.

ForgingBlocks provides small abstractions that help you keep these boundaries intentional and easy to understand.

  • The Foundation block offers the core building blocks reused throughout the system.
  • The Domain block defines the concepts and rules that model your problem space.
  • The Application block expresses use cases and coordinates domain behavior.
  • The Infrastructure block supplies adapters to external systems.
  • The Presentation block handles incoming interactions with your application.

Block vs Layer

In ForgingBlocks, the term block is intentionally architecture-neutral.
You may interpret a block as a layer if that mental model helps, but this toolkit does not require or enforce any structural pattern.

Why It Matters

Many systems become difficult to evolve not because of missing features, but due to coupling, implicit assumptions, and unclear responsibilities.

ForgingBlocks helps you shape software that is clear, testable, and maintainable by encouraging intentional structure — block by block.

Learn More

Project Resources