Final Meta

final_meta

FinalMeta and runtime_final decorators.

This module provides runtime enforcement for methods marked as @runtime_final.
It complements the static @final decorator from typing by preventing
subclasses from overriding these methods at runtime.

FinalMeta

Bases: type

Metaclass that enforces runtime immutability of methods marked as @runtime_final.

Any attempt to override a @runtime_final method in a subclass raises TypeError
at class creation time.

Source code in src/forging_blocks/foundation/meta/final_meta.py

class FinalMeta(type):
    """Metaclass that enforces runtime immutability of methods marked as `@runtime_final`.

    Any attempt to override a `@runtime_final` method in a subclass raises `TypeError`
    at class creation time.
    """

    def __new__(
        mcls: type,
        name: str,
        bases: tuple[type, ...],
        namespace: dict[str, Any],
        **kwargs: Any,
    ) -> type:
        """Prevent overriding of runtime-final methods in subclasses."""
        validate_no_runtime_final_override(name, bases, namespace)
        return type.__new__(mcls, name, bases, namespace, **kwargs)  # type: ignore[no-any-return]

__new__(mcls: type, name: str, bases: tuple[type, ...], namespace: dict[str, Any], **kwargs: Any) -> type

Prevent overriding of runtime-final methods in subclasses.

Source code in src/forging_blocks/foundation/meta/final_meta.py

def __new__(
    mcls: type,
    name: str,
    bases: tuple[type, ...],
    namespace: dict[str, Any],
    **kwargs: Any,
) -> type:
    """Prevent overriding of runtime-final methods in subclasses."""
    validate_no_runtime_final_override(name, bases, namespace)
    return type.__new__(mcls, name, bases, namespace, **kwargs)  # type: ignore[no-any-return]

validate_no_runtime_final_override(name: str, bases: tuple[type, ...], namespace: dict[str, Any]) -> None

Check that no subclass overrides a @runtime_final method.

Raised at class creation time (inside metaclass __new__) so the
violation is caught immediately, before any instance is created.

Source code in src/forging_blocks/foundation/meta/final_meta.py

def validate_no_runtime_final_override(
    name: str,
    bases: tuple[type, ...],
    namespace: dict[str, Any],
) -> None:
    """Check that no subclass overrides a @runtime_final method.

    Raised at class creation time (inside metaclass ``__new__``) so the
    violation is caught immediately, before any instance is created.
    """
    final_methods: set[str] = {
        attr_name
        for base in bases
        for cls in base.__mro__
        for attr_name, attr_value in cls.__dict__.items()
        if getattr(attr_value, "__is_runtime_final__", False)
    }

    for method_name in final_methods:
        if method_name in namespace:
            raise TypeError(
                f"Cannot override runtime-final method '{method_name}' in subclass '{name}'."
            )

runtime_final(func: F) -> F

Decorator that marks a method as runtime-final and type-hint final.

Adds both static (__final__) and runtime (__is_runtime_final__) flags.

Source code in src/forging_blocks/foundation/meta/final_meta.py

def runtime_final[F: AnyCallable](func: F) -> F:
    """Decorator that marks a method as runtime-final and type-hint final.

    Adds both static (`__final__`) and runtime (`__is_runtime_final__`) flags.
    """
    func.__final__ = True  # type: ignore[attr-defined]
    func.__is_runtime_final__ = True  # type: ignore[attr-defined]
    return func