📘 Technical Design 022 — Unified Runtime Marker System¶

from typing import Any


class Marker:
    """Base class for all runtime metadata markers.

    A marker is a typed container for runtime metadata that can be attached to
    functions, classes, methods, or class attributes. Subclasses should define
    domain-specific metadata fields relevant to their use case.

    :param name: Human-readable name for this marker type.
    :type name: str

    Example::

        class ServiceMarker(Marker):
            def __init__(self, lifecycle: ServiceLifecycle) -> None:
                super().__init__(name="service")
                self.lifecycle = lifecycle
    """

    _name: str

    def __init__(self, name: str) -> None:
        """Initialize marker with a name.

        :param name: Identifier for the marker type.
        :type name: str
        :raises ValueError: If name is empty or whitespace-only.
        """
        if not name or not name.strip():
            msg = "Marker name cannot be empty."
            raise ValueError(msg)
        self._name = name.strip()

    @property
    def name(self) -> str:
        """Return the marker name.

        :return: Name assigned during initialization.
        :rtype: str
        """
        return self._name

    def __repr__(self) -> str:
        """Return a debug representation of the marker."""
        return f"{self.__class__.__name__}(name='{self._name}')"

from typing import Any
from typing import Callable

# Any callable: function, method, class
CallableTarget = type | Callable[..., Any]

# Attribute target: tuple of (Class, attribute_name)
AttributeTarget = tuple[type, str]

# Union of all supported targets
MarkerTarget = CallableTarget | AttributeTarget

from abc import ABC
from abc import abstractmethod
from collections.abc import Iterator
from typing import Protocol


class CallableMarkerHandler(ABC):
    """Abstract handler for attaching/retrieving markers on callables.

    Implementations handle specific callable types: functions, methods, classes.
    """

    @abstractmethod
    def supports(self, target: CallableTarget) -> bool:
        """Check if this handler supports the target.

        :param target: The callable to check.
        :type target: CallableTarget
        :return: True if handler can manage this target.
        :rtype: bool
        """
        ...

    @abstractmethod
    def attach(self, target: CallableTarget, marker: Marker) -> None:
        """Attach a marker to the target.

        :param target: The callable to mark.
        :type target: CallableTarget
        :param marker: The marker to attach.
        :type marker: Marker
        """
        ...

    @abstractmethod
    def retrieve(self, target: CallableTarget) -> Iterator[Marker]:
        """Retrieve all markers from the target.

        :param target: The callable to inspect.
        :type target: CallableTarget
        :return: Iterator of markers attached to the target.
        :rtype: Iterator[Marker]
        """
        ...

    def has_marker(
        self, target: CallableTarget, marker_type: type[Marker]
    ) -> bool:
        """Check if target has a marker of the given type.

        :param target: The callable to check.
        :type target: CallableTarget
        :param marker_type: The marker class to search for.
        :type marker_type: type[Marker]
        :return: True if a marker of this type is attached.
        :rtype: bool
        """
        return any(
            isinstance(marker, marker_type) for marker in self.retrieve(target)
        )

    def find_marker[T: Marker](
        self, target: CallableTarget, marker_type: type[T]
    ) -> T | None:
        """Find the first marker of the given type.

        :param target: The callable to inspect.
        :type target: CallableTarget
        :param marker_type: The marker class to find.
        :type marker_type: type[T]
        :return: The first matching marker, or None.
        :rtype: T | None
        """
        for marker in self.retrieve(target):
            if isinstance(marker, marker_type):
                return marker
        return None

    def find_markers[T: Marker](
        self, target: CallableTarget, marker_type: type[T]
    ) -> Iterator[T]:
        """Find all markers of the given type.

        :param target: The callable to inspect.
        :type target: CallableTarget
        :param marker_type: The marker class to find.
        :type marker_type: type[T]
        :return: Iterator of matching markers.
        :rtype: Iterator[T]
        """
        for marker in self.retrieve(target):
            if isinstance(marker, marker_type):
                yield marker


class AttributeMarkerHandler(ABC):
    """Abstract handler for retrieving markers on class attributes.

    Attribute markers are attached via Annotated[Type, Marker()]. This handler
    inspects __annotations__ and extracts Marker instances from Annotated metadata.
    """

    @abstractmethod
    def supports(self, target: AttributeTarget) -> bool:
        """Check if this handler supports the attribute target.

        :param target: Tuple of (Class, attribute_name).
        :type target: AttributeTarget
        :return: True if handler can manage this target.
        :rtype: bool
        """
        ...

    @abstractmethod
    def retrieve(self, target: AttributeTarget) -> Iterator[Marker]:
        """Retrieve all markers from the attribute.

        :param target: Tuple of (Class, attribute_name).
        :type target: AttributeTarget
        :return: Iterator of markers attached to the attribute.
        :rtype: Iterator[Marker]
        """
        ...

    def has_marker(
        self, target: AttributeTarget, marker_type: type[Marker]
    ) -> bool:
        """Check if attribute has a marker of the given type.

        :param target: Tuple of (Class, attribute_name).
        :type target: AttributeTarget
        :param marker_type: The marker class to search for.
        :type marker_type: type[Marker]
        :return: True if a marker of this type is attached.
        :rtype: bool
        """
        return any(
            isinstance(marker, marker_type) for marker in self.retrieve(target)
        )

    def find_marker[T: Marker](
        self, target: AttributeTarget, marker_type: type[T]
    ) -> T | None:
        """Find the first marker of the given type on the attribute.

        :param target: Tuple of (Class, attribute_name).
        :type target: AttributeTarget
        :param marker_type: The marker class to find.
        :type marker_type: type[T]
        :return: The first matching marker, or None.
        :rtype: T | None
        """
        for marker in self.retrieve(target):
            if isinstance(marker, marker_type):
                return marker
        return None

    def find_markers[T: Marker](
        self, target: AttributeTarget, marker_type: type[T]
    ) -> Iterator[T]:
        """Find all markers of the given type on the attribute.

        :param target: Tuple of (Class, attribute_name).
        :type target: AttributeTarget
        :param marker_type: The marker class to find.
        :type marker_type: type[T]
        :return: Iterator of matching markers.
        :rtype: Iterator[T]
        """
        for marker in self.retrieve(target):
            if isinstance(marker, marker_type):
                yield marker

from typing import Any


class MarkerContext:
    """Central registry managing all marker handlers.

    Provides a unified API for attaching and discovering markers on both
    callable targets (classes, functions, methods) and attribute targets
    (class attributes via Annotated[]).
    """

    __slots__ = ("_callable_handlers", "_attribute_handlers")

    def __init__(self) -> None:
        """Initialize with empty handler registries."""
        self._callable_handlers: list[CallableMarkerHandler] = []
        self._attribute_handlers: list[AttributeMarkerHandler] = []

    def register_callable_handler(
        self, handler: CallableMarkerHandler
    ) -> "MarkerContext":
        """Register a handler for callable targets.

        :param handler: Handler to register.
        :type handler: CallableMarkerHandler
        :return: Self for method chaining.
        :rtype: MarkerContext
        """
        self._callable_handlers.append(handler)
        return self

    def register_attribute_handler(
        self, handler: AttributeMarkerHandler
    ) -> "MarkerContext":
        """Register a handler for attribute targets.

        :param handler: Handler to register.
        :type handler: AttributeMarkerHandler
        :return: Self for method chaining.
        :rtype: MarkerContext
        """
        self._attribute_handlers.append(handler)
        return self

    def attach(self, target: MarkerTarget, marker: Marker) -> None:
        """Attach a marker to a target.

        :param target: Callable or (Class, attribute_name) tuple.
        :type target: MarkerTarget
        :param marker: The marker to attach.
        :type marker: Marker
        :raises TypeError: If target type is not supported.
        """
        if isinstance(target, tuple):
            handler = self._find_attribute_handler(target)
            # Attribute handler retrieve only; attach is implicit via type annotation
            msg = "Attribute markers are attached via Annotated[]; use type hints to define."
            raise TypeError(msg)
        else:
            handler = self._find_callable_handler(target)
            handler.attach(target, marker)

    def has_marker(
        self, target: MarkerTarget, marker_type: type[Marker]
    ) -> bool:
        """Check if target has a marker of the given type.

        :param target: Callable or (Class, attribute_name) tuple.
        :type target: MarkerTarget
        :param marker_type: The marker class to search for.
        :type marker_type: type[Marker]
        :return: True if target has the marker.
        :rtype: bool
        """
        if isinstance(target, tuple):
            handler = self._find_attribute_handler(target)
            return handler.has_marker(target, marker_type)
        else:
            handler = self._find_callable_handler(target)
            return handler.has_marker(target, marker_type)

    def find_marker[T: Marker](
        self, target: MarkerTarget, marker_type: type[T]
    ) -> T | None:
        """Find the first marker of the given type on target.

        Works for both callables and attributes::

            # Callable target
            service = find_marker(MyService, ServiceMarker)

            # Attribute target
            autowired = find_marker((MyService, 'database'), Autowired)

        :param target: Callable or (Class, attribute_name) tuple.
        :type target: MarkerTarget
        :param marker_type: The marker class to find.
        :type marker_type: type[T]
        :return: The first matching marker, or None.
        :rtype: T | None
        """
        if isinstance(target, tuple):
            handler = self._find_attribute_handler(target)
            return handler.find_marker(target, marker_type)
        else:
            handler = self._find_callable_handler(target)
            return handler.find_marker(target, marker_type)

    def find_markers[T: Marker](
        self, target: MarkerTarget, marker_type: type[T]
    ) -> Iterator[T]:
        """Find all markers of the given type on target.

        :param target: Callable or (Class, attribute_name) tuple.
        :type target: MarkerTarget
        :param marker_type: The marker class to find.
        :type marker_type: type[T]
        :return: Iterator of matching markers.
        :rtype: Iterator[T]
        """
        if isinstance(target, tuple):
            handler = self._find_attribute_handler(target)
            return handler.find_markers(target, marker_type)
        else:
            handler = self._find_callable_handler(target)
            return handler.find_markers(target, marker_type)

    def _find_callable_handler(
        self, target: CallableTarget
    ) -> CallableMarkerHandler:
        """Find a handler supporting the callable target.

        :param target: Callable to find handler for.
        :type target: CallableTarget
        :return: Supporting handler.
        :rtype: CallableMarkerHandler
        :raises TypeError: If no handler supports target.
        """
        for handler in self._callable_handlers:
            if handler.supports(target):
                return handler
        msg = f"No marker handler for callable type: {type(target)}"
        raise TypeError(msg)

    def _find_attribute_handler(
        self, target: AttributeTarget
    ) -> AttributeMarkerHandler:
        """Find a handler supporting the attribute target.

        :param target: Attribute tuple (Class, name) to find handler for.
        :type target: AttributeTarget
        :return: Supporting handler.
        :rtype: AttributeMarkerHandler
        :raises TypeError: If no handler supports target.
        """
        for handler in self._attribute_handlers:
            if handler.supports(target):
                return handler
        msg = f"No marker handler for attribute: {target}"
        raise TypeError(msg)

from types import FunctionType
from types import MethodType


class FunctionMarkerHandler(CallableMarkerHandler):
    """Handler for attaching/retrieving markers on functions."""

    def supports(self, target: CallableTarget) -> bool:
        """Check if target is a function."""
        return isinstance(target, FunctionType)

    def attach(self, target: CallableTarget, marker: Marker) -> None:
        """Attach marker to function via __loryth_markers__ attribute."""
        assert isinstance(target, FunctionType)
        markers = getattr(target, "__loryth_markers__", None)
        if markers is None:
            markers = []
            setattr(target, "__loryth_markers__", markers)
        assert isinstance(markers, list)
        markers.append(marker)

    def retrieve(self, target: CallableTarget) -> Iterator[Marker]:
        """Retrieve markers from function, including from wrapped functions."""
        current: CallableTarget | None = target
        while current is not None:
            markers = getattr(current, "__loryth_markers__", None)
            if markers is not None:
                yield from markers
            current = getattr(current, "__wrapped__", None)


class ClassMarkerHandler(CallableMarkerHandler):
    """Handler for attaching/retrieving markers on classes."""

    def supports(self, target: CallableTarget) -> bool:
        """Check if target is a class."""
        return isinstance(target, type)

    def attach(self, target: CallableTarget, marker: Marker) -> None:
        """Attach marker to class via __loryth_markers__ attribute."""
        markers = getattr(target, "__loryth_markers__", None)
        if markers is None:
            markers = []
            setattr(target, "__loryth_markers__", markers)
        assert isinstance(markers, list)
        markers.append(marker)

    def retrieve(self, target: CallableTarget) -> Iterator[Marker]:
        """Retrieve markers from class."""
        markers = getattr(target, "__loryth_markers__", None)
        if markers is not None:
            yield from markers


class MethodMarkerHandler(CallableMarkerHandler):
    """Handler for attaching/retrieving markers on methods."""

    def supports(self, target: CallableTarget) -> bool:
        """Check if target is a method."""
        return isinstance(target, MethodType)

    def attach(self, target: CallableTarget, marker: Marker) -> None:
        """Attach marker to method via __loryth_markers__ attribute."""
        assert isinstance(target, MethodType)
        markers = getattr(target, "__loryth_markers__", None)
        if markers is None:
            markers = []
            setattr(target, "__loryth_markers__", markers)
        assert isinstance(markers, list)
        markers.append(marker)

    def retrieve(self, target: CallableTarget) -> Iterator[Marker]:
        """Retrieve markers from method."""
        markers = getattr(target, "__loryth_markers__", None)
        if markers is not None:
            yield from markers

from typing import Any
from typing import Annotated
from typing import get_args
from typing import get_origin


class AnnotatedAttributeMarkerHandler(AttributeMarkerHandler):
    """Handler for retrieving markers from class attributes via Annotated[]."""

    def supports(self, target: AttributeTarget) -> bool:
        """Check if target is a valid (Class, attribute_name) tuple."""
        if not isinstance(target, tuple) or len(target) != 2:
            return False
        cls, attr_name = target
        return isinstance(cls, type) and isinstance(attr_name, str)

    def retrieve(self, target: AttributeTarget) -> Iterator[Marker]:
        """Extract Marker instances from Annotated[] metadata.

        If the attribute is Annotated[Type, Meta1, Meta2, ...], yields all Meta
        entries that are Marker instances.
        """
        cls, attr_name = target
        annotations = getattr(cls, "__annotations__", {})

        annotation = annotations.get(attr_name)
        if annotation is None:
            return

        if get_origin(annotation) is not Annotated:
            return

        args = get_args(annotation)
        if not args:
            return

        # First arg is the type; rest are metadata
        for meta in args[1:]:
            if isinstance(meta, Marker):
                yield meta

# Create and configure global context with default handlers
_default_context = MarkerContext()
_default_context.register_callable_handler(FunctionMarkerHandler())
_default_context.register_callable_handler(ClassMarkerHandler())
_default_context.register_callable_handler(MethodMarkerHandler())
_default_context.register_attribute_handler(AnnotatedAttributeMarkerHandler())

# Public API
def attach(target: MarkerTarget, marker: Marker) -> None:
    """Attach a marker to a target."""
    _default_context.attach(target, marker)


def has_marker(
    target: MarkerTarget, marker_type: type[Marker]
) -> bool:
    """Check if target has a marker of the given type."""
    return _default_context.has_marker(target, marker_type)


def find_marker[T: Marker](
    target: MarkerTarget, marker_type: type[T]
) -> T | None:
    """Find the first marker of the given type on target."""
    return _default_context.find_marker(target, marker_type)


def find_markers[T: Marker](
    target: MarkerTarget, marker_type: type[T]
) -> Iterator[T]:
    """Find all markers of the given type on target."""
    return _default_context.find_markers(target, marker_type)

from typing import Callable
from typing import TypeVar

T = TypeVar("T")


class MarkerFactory[**Params]:
    """Protocol for factories that create markers from decorator arguments."""

    def __call__(self, *args: Params.args, **kwargs: Params.kwargs) -> Marker:
        """Create a marker instance from decorator parameters."""
        ...


def marker[T: Callable[..., Any], **Params](
    marker_factory: MarkerFactory[Params],
) -> Callable[Params, Callable[[T], T]]:
    """Create a decorator that attaches a marker to a callable.

    :param marker_factory: Callable that creates a Marker from decorator params.
    :type marker_factory: MarkerFactory[Params]
    :return: Decorator factory accepting marker parameters.
    :rtype: Callable[Params, Callable[[T], T]]

    Example::

        def service_marker(*, lifecycle: ServiceLifecycle = SINGLETON) -> Marker:
            return ServiceMarker(lifecycle)

        @marker(service_marker)
        def service(*, lifecycle: ServiceLifecycle = SINGLETON):
            def decorator(cls: type[T]) -> type[T]:
                # Apply decorator logic
                return cls
            return decorator
    """
    def decorator(*args: Params.args, **kwargs: Params.kwargs) -> Callable[[T], T]:
        marker_instance = marker_factory(*args, **kwargs)

        def wrapper(target: T) -> T:
            attach(target, marker_instance)
            return target

        return wrapper

    return decorator

from loryth.common.markers import Marker
from loryth.common.markers import attach
from loryth.common.markers import find_marker


class ServiceMarker(Marker):
    """Marks a class as a service."""

    def __init__(self, lifecycle: str = "singleton") -> None:
        super().__init__(name="service")
        self.lifecycle = lifecycle


# Attach marker manually
class UserRepository:
    pass


attach(UserRepository, ServiceMarker())

# Discover marker
marker = find_marker(UserRepository, ServiceMarker)
assert marker is not None
assert marker.lifecycle == "singleton"

from typing import Callable
from typing import TypeVar

from loryth.common.markers import Marker
from loryth.common.markers import attach

T = TypeVar("T")


class ComponentMarker(Marker):
    """Marks a class as a component."""

    def __init__(self, scope: str = "prototype") -> None:
        super().__init__(name="component")
        self.scope = scope


def component(*, scope: str = "prototype") -> Callable[[type[T]], type[T]]:
    """Decorator to mark a class as a component."""

    def decorator(cls: type[T]) -> type[T]:
        attach(cls, ComponentMarker(scope=scope))
        return cls

    return decorator


@component(scope="singleton")
class EmailService:
    pass


marker = find_marker(EmailService, ComponentMarker)
assert marker.scope == "singleton"

from typing import Annotated

from loryth.common.markers import Marker
from loryth.common.markers import find_marker


class InjectedMarker(Marker):
    """Marks an attribute as requiring injection."""

    def __init__(self, qualifier: str | None = None) -> None:
        super().__init__(name="injected")
        self.qualifier = qualifier


class DatabaseService:
    """Database service to be injected."""
    pass


class UserService:
    """Service with injected dependency."""

    # Mark dependency with marker via Annotated
    db: Annotated[DatabaseService, InjectedMarker()]
    cache: Annotated[DatabaseService, InjectedMarker(qualifier="redis")]


# Discover attribute markers
db_marker = find_marker((UserService, "db"), InjectedMarker)
assert db_marker is not None
assert db_marker.qualifier is None

cache_marker = find_marker((UserService, "cache"), InjectedMarker)
assert cache_marker is not None
assert cache_marker.qualifier == "redis"

from typing import Annotated

from loryth.common.markers import Marker
from loryth.common.markers import attach
from loryth.common.markers import find_marker


class ServiceMarker(Marker):
    """DI service marker with lifecycle."""

    def __init__(self, lifecycle: str = "singleton") -> None:
        super().__init__(name="service")
        self.lifecycle = lifecycle


class AutowiredMarker(Marker):
    """Marks an attribute for property injection."""

    def __init__(self, qualifier: str | None = None) -> None:
        super().__init__(name="autowired")
        self.qualifier = qualifier


# Define services with markers
class Logger:
    pass


class Database:
    pass


attach(Logger, ServiceMarker())
attach(Database, ServiceMarker())


class UserService:
    """Service with injected dependencies."""

    logger: Annotated[Logger, AutowiredMarker()]
    db: Annotated[Database, AutowiredMarker()]

    def __init__(self) -> None:
        self.initialized = True


# Mark as service
attach(UserService, ServiceMarker(lifecycle="singleton"))

# DI framework can now discover both class-level and attribute-level markers
service_marker = find_marker(UserService, ServiceMarker)
assert service_marker.lifecycle == "singleton"

logger_marker = find_marker((UserService, "logger"), AutowiredMarker)
assert logger_marker is not None

tests/unit/markers/
├── test_marker_base.py              # Marker class behavior
├── test_callable_handlers.py        # Function/Class/Method handlers
├── test_attribute_handler.py        # Annotated attribute handling
├── test_marker_context.py           # Registry and discovery API
└── test_marker_decorator.py         # @marker() decorator helper

tests/integration/markers/
├── test_callable_and_attribute_markers.py  # Mixed usage
├── test_marker_discovery_workflows.py      # End-to-end discovery
└── test_di_marker_integration.py           # DI system exercising new module imports

# BEFORE (old way)
from loryth.common.annotations import Annotation, AnnotationContext

class MyAnnotation(Annotation):
    pass

# AFTER (new way)
from loryth.common.markers import Marker, attach, find_marker

class MyMarker(Marker):
    pass

# Updated DI decorators now rely on the markers module
from loryth.common.di.annotations import service
from loryth.common.di.annotations import Autowired

# Internally, these use the new marker system exclusively
@service()
class MyService:
    pass