Skip to content

Composable

composable

Composable specification abstraction.

Adds fluent logical composition to the core Specification contract.
Operators are defined ONCE here and delegate to logical classes.
Subclasses inherit them automatically—no reimplementation needed.

The logical operator classes (AndSpecification, OrSpecification,
NotSpecification) themselves inherit from ComposableSpecification so
that the result of a composition is itself composable. Because the operators
depend on this class for their base while this class delegates back to the
operators, importing the operators at module level would create a circular
import. The operator imports are therefore deferred into the methods that
construct them, keeping the static import graph acyclic:
composable -> base and logical_operators -> composable -> base.

ComposableSpecification

Bases: Specification[T]

Specification supporting fluent logical composition.

Provides a single definition of composition operators:
- and_() / and() → delegates to AndSpecification
- or_() / or() → delegates to OrSpecification
- not_() / invert() → delegates to NotSpecification

Subclasses inherit these automatically. Do NOT reimplement in subclasses.

Source code in src/forging_blocks/foundation/specification/composable.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
class ComposableSpecification[T](Specification[T]):
    """Specification supporting fluent logical composition.

    Provides a single definition of composition operators:
    - and_() / __and__()  → delegates to AndSpecification
    - or_()  / __or__()   → delegates to OrSpecification
    - not_() / __invert__() → delegates to NotSpecification

    Subclasses inherit these automatically. Do NOT reimplement in subclasses.
    """

    def and_(self, other: Specification[T]) -> Specification[T]:
        """Combine two specifications using logical conjunction.

        Args:
            other: The specification to AND with this one.

        Returns:
            A new AndSpecification combining both.
        """
        from .logical_operators import AndSpecification

        return AndSpecification(self, other)

    def or_(self, other: Specification[T]) -> Specification[T]:
        """Combine two specifications using logical disjunction.

        Args:
            other: The specification to OR with this one.

        Returns:
            A new OrSpecification combining both.
        """
        from .logical_operators import OrSpecification

        return OrSpecification(self, other)

    def not_(self) -> Specification[T]:
        """Create the logical negation of this specification.

        Returns:
            A new NotSpecification wrapping this one.
        """
        from .logical_operators import NotSpecification

        return NotSpecification(self)

    def __and__(self, other: Specification[T]) -> Specification[T]:
        """Operator overload for & (bitwise AND).

        Args:
            other: The specification to AND with this one.

        Returns:
            A new AndSpecification combining both.
        """
        return self.and_(other)

    def __or__(self, other: Specification[T]) -> Specification[T]:
        """Operator overload for | (bitwise OR).

        Args:
            other: The specification to OR with this one.

        Returns:
            A new OrSpecification combining both.
        """
        return self.or_(other)

    def __invert__(self) -> Specification[T]:
        """Operator overload for ~ (bitwise NOT).

        Returns:
            A new NotSpecification wrapping this one.
        """
        return self.not_()

and_(other: Specification[T]) -> Specification[T]

Combine two specifications using logical conjunction.

Parameters:

Name Type Description Default
other Specification[T]

The specification to AND with this one.

 required

Returns:

Type Description
Specification[T]

A new AndSpecification combining both.
Source code in src/forging_blocks/foundation/specification/composable.py 
31
32
33
34
35
36
37
38
39
40
41
42
def and_(self, other: Specification[T]) -> Specification[T]:
    """Combine two specifications using logical conjunction.

    Args:
        other: The specification to AND with this one.

    Returns:
        A new AndSpecification combining both.
    """
    from .logical_operators import AndSpecification

    return AndSpecification(self, other)

or_(other: Specification[T]) -> Specification[T]

Combine two specifications using logical disjunction.

Parameters:

Name Type Description Default
other Specification[T]

The specification to OR with this one.

 required

Returns:

Type Description
Specification[T]

A new OrSpecification combining both.
Source code in src/forging_blocks/foundation/specification/composable.py 
44
45
46
47
48
49
50
51
52
53
54
55
def or_(self, other: Specification[T]) -> Specification[T]:
    """Combine two specifications using logical disjunction.

    Args:
        other: The specification to OR with this one.

    Returns:
        A new OrSpecification combining both.
    """
    from .logical_operators import OrSpecification

    return OrSpecification(self, other)

not_() -> Specification[T]

Create the logical negation of this specification.

Returns:

Type Description
Specification[T]

A new NotSpecification wrapping this one.
Source code in src/forging_blocks/foundation/specification/composable.py 
57
58
59
60
61
62
63
64
65
def not_(self) -> Specification[T]:
    """Create the logical negation of this specification.

    Returns:
        A new NotSpecification wrapping this one.
    """
    from .logical_operators import NotSpecification

    return NotSpecification(self)

__and__(other: Specification[T]) -> Specification[T]

Operator overload for & (bitwise AND).

Parameters:

Name Type Description Default
other Specification[T]

The specification to AND with this one.

 required

Returns:

Type Description
Specification[T]

A new AndSpecification combining both.
Source code in src/forging_blocks/foundation/specification/composable.py 
67
68
69
70
71
72
73
74
75
76
def __and__(self, other: Specification[T]) -> Specification[T]:
    """Operator overload for & (bitwise AND).

    Args:
        other: The specification to AND with this one.

    Returns:
        A new AndSpecification combining both.
    """
    return self.and_(other)

__or__(other: Specification[T]) -> Specification[T]

Operator overload for | (bitwise OR).

Parameters:

Name Type Description Default
other Specification[T]

The specification to OR with this one.

 required

Returns:

Type Description
Specification[T]

A new OrSpecification combining both.
Source code in src/forging_blocks/foundation/specification/composable.py 
78
79
80
81
82
83
84
85
86
87
def __or__(self, other: Specification[T]) -> Specification[T]:
    """Operator overload for | (bitwise OR).

    Args:
        other: The specification to OR with this one.

    Returns:
        A new OrSpecification combining both.
    """
    return self.or_(other)

__invert__() -> Specification[T]

Operator overload for ~ (bitwise NOT).

Returns:

Type Description
Specification[T]

A new NotSpecification wrapping this one.
Source code in src/forging_blocks/foundation/specification/composable.py 
89
90
91
92
93
94
95
def __invert__(self) -> Specification[T]:
    """Operator overload for ~ (bitwise NOT).

    Returns:
        A new NotSpecification wrapping this one.
    """
    return self.not_()