code-is-magic-markers 0.1.0__py3-none-any.whl

code_is_magic_markers-0.1.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: code-is-magic-markers
+Version: 0.1.0
+Summary: Lightweight class introspection toolkit — define typed markers, annotate fields and methods, collect metadata via MRO-walking descriptors.
+Project-URL: Homepage, https://github.com/Richard-Lynch/markers
+Project-URL: Repository, https://github.com/Richard-Lynch/markers
+Project-URL: Changelog, https://github.com/Richard-Lynch/markers/blob/main/CHANGELOG.md
+Author: Richie
+License-Expression: MIT
+License-File: LICENSE
+Keywords: annotations,descriptors,introspection,markers,metadata,pydantic,registry,typing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: tox>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# markers
+
+Lightweight class introspection toolkit for Python. Define typed markers, annotate fields and methods, collect metadata via MRO-walking descriptors.
+
+## Install
+
+```bash
+pip install code-is-magic-markers
+```
+
+## Quick start
+
+```python
+from typing import Annotated
+from markers import Marker, MarkerGroup, Registry
+
+# 1. Define markers — the class body IS the schema
+class Required(Marker): pass
+
+class MaxLen(Marker):
+    mark = "max_length"
+    limit: int
+
+class Searchable(Marker):
+    boost: float = 1.0
+    analyzer: str = "standard"
+
+class OnSave(Marker):
+    mark = "on_save"
+    priority: int = 0
+
+
+# 2. Bundle into groups
+class Validation(MarkerGroup):
+    Required = Required
+    MaxLen = MaxLen
+
+class Lifecycle(MarkerGroup):
+    OnSave = OnSave
+
+
+# 3. Annotate your classes
+class User(Validation.mixin, Lifecycle.mixin):
+    name: Annotated[str, Validation.Required(), Validation.MaxLen(limit=100)]
+    email: Annotated[str, Validation.Required()]
+    bio: Annotated[str, Searchable()] = ""
+
+    @Lifecycle.OnSave(priority=10)
+    def validate(self) -> list[str]:
+        errors = []
+        for name, info in type(self).required.items():
+            if info.is_field and not getattr(self, name, None):
+                errors.append(f"{name} is required")
+        return errors
+
+
+# 4. Query metadata — same dict[str, MemberInfo] everywhere
+User.fields          # all fields
+User.methods         # all methods
+User.members         # both
+User.required        # only members marked 'required'
+User.on_save         # only members marked 'on_save'
+
+# Introspect
+User.fields["name"].get("max_length").limit  # 100
+User.methods["validate"].get("on_save").priority  # 10
+```
+
+## Core concepts
+
+### Marker
+
+Subclass `Marker` to define a marker. The class body is the pydantic schema — typed fields become validated parameters:
+
+```python
+class ForeignKey(Marker):
+    mark = "foreign_key"  # explicit name (default: lowercased class name)
+    table: str            # required parameter
+    column: str = "id"    # optional with default
+    on_delete: str = "CASCADE"
+```
+
+Markers work as both `Annotated[]` metadata and method decorators:
+
+```python
+# As annotation
+author_id: Annotated[int, ForeignKey(table="users")]
+
+# As decorator
+@OnSave(priority=10)
+def validate(self): ...
+```
+
+Schema-less markers accept no parameters:
+
+```python
+class Required(Marker): pass
+Required()        # ok
+Required(x=1)     # TypeError
+```
+
+Intermediate bases share schema fields:
+
+```python
+class LifecycleMarker(Marker):
+    priority: int = 0
+
+class OnSave(LifecycleMarker):
+    mark = "on_save"
+
+class OnDelete(LifecycleMarker):
+    mark = "on_delete"
+
+# Both have 'priority'
+```
+
+### MarkerGroup
+
+Bundle related markers and produce a `.mixin`:
+
+```python
+class DB(MarkerGroup):
+    PrimaryKey = PrimaryKey
+    Indexed = Indexed
+    ForeignKey = ForeignKey
+
+class User(DB.mixin):
+    id: Annotated[int, DB.PrimaryKey()]
+    email: Annotated[str, DB.Indexed(unique=True)]
+
+User.primary_key  # {'id': MemberInfo(...)}
+User.indexed      # {'email': MemberInfo(...)}
+User.fields       # all fields (from BaseMixin)
+```
+
+Groups compose via inheritance:
+
+```python
+class ExtendedDB(DB):
+    Unique = Unique
+```
+
+### Registry
+
+Track subclasses for cross-class queries:
+
+```python
+class Entity(DB.mixin, Registry):
+    id: Annotated[int, DB.PrimaryKey()]
+
+class User(Entity):
+    name: Annotated[str, Required()]
+
+class Post(Entity):
+    title: Annotated[str, Required()]
+
+# List all subclasses
+Entity.subclasses()  # [User, Post]
+
+# Iterate with the same per-class API
+for cls in Entity.subclasses():
+    print(cls.__name__, list(cls.required.keys()))
+
+# Or gather across all subclasses
+Entity.all.required  # {'name': [MemberInfo(owner=User)], 'title': [MemberInfo(owner=Post)]}
+Entity.all.fields    # {'id': [MemberInfo(owner=User), MemberInfo(owner=Post)], ...}
+```
+
+### MemberInfo
+
+Every collected member (field or method) is a `MemberInfo`:
+
+```python
+info = User.fields["name"]
+info.name          # 'name'
+info.kind          # MemberKind.FIELD
+info.type          # <class 'str'>
+info.owner         # <class 'User'>
+info.default       # MISSING (no default)
+info.has_default   # False
+info.is_field      # True
+info.is_method     # False
+info.markers       # [MarkerInstance('required', ...), MarkerInstance('max_length', ...)]
+info.has("required")              # True
+info.get("max_length").limit      # 100
+info.get_all("required")          # [MarkerInstance(...)]
+```
+
+## API reference
+
+| Class | Purpose |
+|-------|---------|
+| `Marker` | Subclass to define markers with optional typed schema |
+| `MarkerGroup` | Subclass to bundle markers into a `.mixin` |
+| `Registry` | Subclass to track all subclasses, provides `.subclasses()` and `.all` |
+| `MarkerInstance` | A specific usage of a marker with validated params |
+| `MemberInfo` | Metadata about a field or method |
+| `MemberKind` | Enum: `FIELD` or `METHOD` |
+| `MISSING` | Sentinel for fields with no default |
+
+### Marker class methods
+
+| Method | Description |
+|--------|-------------|
+| `MyMarker.collect(cls)` | Collect members carrying this marker from `cls` |
+| `Marker.invalidate(cls)` | Clear cached collection for `cls` |
+
+## License
+
+MIT

code_is_magic_markers-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+markers/__init__.py,sha256=9m_dO-j8ebqL3U3ACgM8fGb3Wbrn8ZpSdvzAi4e4x6s,881
+markers/_types.py,sha256=PApctFsFKX0I-pbrz2DACrGR5XLJsXBXytqZZlWQi7E,4345
+markers/core.py,sha256=wPopCUY-vU-vnTF2Ald8NeWNdK5NMB-XvEgrSTDAjW8,4292
+markers/descriptors.py,sha256=_c8hNK0INxPyuFTkoZQlRnsLWV4ciWlL3cnYeOV4bFI,1677
+markers/groups.py,sha256=ao2bh3cXeB4s5gd90AMS4ZvLKBe_pWHLQUwyvqzafa8,2774
+markers/marker.py,sha256=1k97hD71DkZsBc6gVtMMImMIBpOkfnNkUoAARQNQsxY,6223
+markers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+markers/registry.py,sha256=1-of8GtyrQpZMDNelli0yPSNx10OibOZFeX24puf4g4,4324
+code_is_magic_markers-0.1.0.dist-info/METADATA,sha256=QsAgQnJ4X6jiu3Q9VE9GHwXkvr0BxDcHESzkLWF9aFc,6617
+code_is_magic_markers-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+code_is_magic_markers-0.1.0.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
+code_is_magic_markers-0.1.0.dist-info/RECORD,,

code_is_magic_markers-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

code_is_magic_markers-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

markers/__init__.py

@@ -0,0 +1,29 @@
+"""
+markers - Lightweight class introspection toolkit.
+
+Public API:
+    Marker      — Subclass to define markers (with optional pydantic schema).
+    MarkerGroup — Subclass to bundle related markers into a .mixin.
+    Registry    — Subclass to track and query across all subclasses.
+
+Supporting types (for type hints):
+    MarkerInstance — A specific usage of a marker with params.
+    MemberInfo     — Metadata about a field or method.
+    MemberKind     — Enum: FIELD or METHOD.
+    MISSING        — Sentinel for fields with no default.
+"""
+
+from markers._types import MISSING, MarkerInstance, MemberInfo, MemberKind
+from markers.groups import MarkerGroup
+from markers.marker import Marker
+from markers.registry import Registry
+
+__all__ = [
+    "MISSING",
+    "Marker",
+    "MarkerGroup",
+    "MarkerInstance",
+    "MemberInfo",
+    "MemberKind",
+    "Registry",
+]

markers/_types.py

@@ -0,0 +1,141 @@
+"""
+markers._types - Core data types.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from enum import Enum, auto
+from typing import Any
+
+__all__ = ["MISSING", "MarkerInstance", "MemberInfo", "MemberKind"]
+
+MISSING = object()
+
+
+class MemberKind(Enum):
+    FIELD = auto()
+    METHOD = auto()
+
+
+class MarkerInstance:
+    """A specific usage of a Marker with validated parameters.
+
+    Internal state is stored in underscore-prefixed slots to avoid
+    collisions with schema field names on ``__getattr__`` lookup.
+
+    Access the marker type name via ``.marker_name``.
+    Access schema fields directly as attributes: ``inst.boost``, ``inst.limit``.
+
+    Also callable as a decorator::
+
+        @OnSave(priority=1)
+        def validate(self): ...
+    """
+
+    __slots__ = ("_kwargs", "_marker_name", "_params")
+
+    def __init__(
+        self,
+        marker_name: str,
+        kwargs: dict[str, Any],
+        params: Any = None,
+    ) -> None:
+        self._marker_name = marker_name
+        self._kwargs = kwargs
+        self._params = params
+
+    @property
+    def marker_name(self) -> str:
+        """The marker type name (e.g. 'required', 'on_save')."""
+        return self._marker_name
+
+    def __call__(self, fn: Callable[..., Any]) -> Callable[..., Any]:
+        """Decorate a function, attaching this MarkerInstance."""
+        if not callable(fn):
+            raise TypeError(f"MarkerInstance '{self._marker_name}' expected a callable, got {type(fn).__name__}")
+        markers: list[MarkerInstance] = list(getattr(fn, "_markers", []))
+        markers.append(self)
+        fn._markers = markers  # type: ignore[attr-defined]
+        return fn
+
+    def __getattr__(self, key: str) -> Any:
+        """Access schema fields as attributes.
+
+        Checks the pydantic params model first, then raw kwargs.
+        Since internal state uses underscore-prefixed slots, schema
+        fields like 'name', 'params', 'kwargs' work without collision.
+        """
+        params = self._params
+        if params is not None:
+            try:
+                return getattr(params, key)
+            except AttributeError:
+                pass
+        kwargs = self._kwargs
+        if key in kwargs:
+            return kwargs[key]
+        raise AttributeError(f"MarkerInstance '{self._marker_name}' has no parameter '{key}'")
+
+    def __repr__(self) -> str:
+        if self._params is not None:
+            data = self._params.model_dump()
+        else:
+            data = self._kwargs
+        parts = [f"{k}={v!r}" for k, v in data.items()]
+        return f"{self._marker_name}({', '.join(parts)})"
+
+
+class MemberInfo:
+    """Metadata about a single class member (field or method)."""
+
+    __slots__ = ("default", "kind", "markers", "name", "owner", "type")
+
+    def __init__(
+        self,
+        name: str,
+        kind: MemberKind,
+        markers: list[MarkerInstance],
+        type_: Any = None,
+        default: Any = MISSING,
+        owner: type | None = None,
+    ) -> None:
+        self.name = name
+        self.kind = kind
+        self.type = type_
+        self.markers = markers
+        self.default = default
+        self.owner = owner
+
+    @property
+    def is_field(self) -> bool:
+        return self.kind == MemberKind.FIELD
+
+    @property
+    def is_method(self) -> bool:
+        return self.kind == MemberKind.METHOD
+
+    @property
+    def has_default(self) -> bool:
+        return self.default is not MISSING
+
+    def has(self, marker_name: str) -> bool:
+        return any(m._marker_name == marker_name for m in self.markers)
+
+    def get(self, marker_name: str) -> MarkerInstance | None:
+        return next((m for m in self.markers if m._marker_name == marker_name), None)
+
+    def get_all(self, marker_name: str) -> list[MarkerInstance]:
+        return [m for m in self.markers if m._marker_name == marker_name]
+
+    def __repr__(self) -> str:
+        parts = [f"name={self.name!r}", f"kind={self.kind.name}"]
+        if self.type is not None:
+            parts.append(f"type={self.type!r}")
+        if self.markers:
+            parts.append(f"markers={self.markers!r}")
+        if self.has_default:
+            parts.append(f"default={self.default!r}")
+        if self.owner is not None:
+            parts.append(f"owner={self.owner.__name__!r}")
+        return f"MemberInfo({', '.join(parts)})"

markers/core.py

@@ -0,0 +1,120 @@
+"""
+markers.core - Unified member collection and caching.
+"""
+
+from __future__ import annotations
+
+import weakref
+from typing import get_type_hints
+
+from markers._types import MISSING, MarkerInstance, MemberInfo, MemberKind
+
+__all__: list[str] = []  # No public API — use Marker/Registry instead
+
+
+class Collector:
+    """Walks a class's MRO once, collects all members (fields + methods),
+    and caches the result per-class using weak references.
+
+    Not part of the public API. Access via Marker.collect / Marker.invalidate.
+    """
+
+    def __init__(self) -> None:
+        self._cache: dict[int, dict[str, MemberInfo]] = {}
+        self._refs: dict[int, weakref.ref[type]] = {}
+
+    def _cleanup(self, cls_id: int) -> None:
+        self._cache.pop(cls_id, None)
+        self._refs.pop(cls_id, None)
+
+    def collect(self, cls: type) -> dict[str, MemberInfo]:
+        cls_id = id(cls)
+
+        # Check cache — verify the weakref is still alive
+        if cls_id in self._cache:
+            ref = self._refs.get(cls_id)
+            if ref is not None and ref() is not None:
+                return self._cache[cls_id]
+            else:
+                self._cleanup(cls_id)
+
+        members: dict[str, MemberInfo] = {}
+
+        for klass in reversed(cls.__mro__):
+            if klass is object:
+                continue
+
+            # --- Fields from annotations ---
+            try:
+                hints = get_type_hints(klass, include_extras=True)
+            except Exception:
+                hints = getattr(klass, "__annotations__", {})
+
+            own_names = set(getattr(klass, "__annotations__", {}).keys())
+            for name in own_names:
+                if name.startswith("_"):
+                    continue
+                hint = hints.get(name)
+                if hint is None:
+                    continue
+                if hasattr(hint, "__metadata__"):
+                    base_type = hint.__args__[0]
+                    markers = [m for m in hint.__metadata__ if isinstance(m, MarkerInstance)]
+                else:
+                    base_type = hint
+                    markers = []
+                default = vars(klass).get(name, MISSING)
+                members[name] = MemberInfo(
+                    name=name,
+                    kind=MemberKind.FIELD,
+                    type_=base_type,
+                    markers=markers,
+                    default=default,
+                    owner=klass,
+                )
+
+            # --- Methods with _markers ---
+            for attr, val in vars(klass).items():
+                method_markers: list[MarkerInstance] | None = getattr(val, "_markers", None)
+                if method_markers:
+                    members[attr] = MemberInfo(
+                        name=attr,
+                        kind=MemberKind.METHOD,
+                        markers=list(method_markers),
+                        owner=klass,
+                    )
+
+        self._cache[cls_id] = members
+
+        # Store weakref for cache invalidation on GC.
+        # If weakref creation fails (e.g. some C extension types),
+        # cache without auto-cleanup — manual invalidate() still works.
+        def _weak_callback(ref: weakref.ref[type], cid: int = cls_id) -> None:
+            self._cleanup(cid)
+
+        try:
+            self._refs[cls_id] = weakref.ref(cls, _weak_callback)
+        except TypeError:
+            # Can't weakref this type — cache persists until manual invalidate()
+            pass
+
+        return members
+
+    def invalidate(self, cls: type) -> None:
+        """Clear the cached collection for a class."""
+        self._cleanup(id(cls))
+
+    def filter(self, cls: type, marker_name: str) -> dict[str, MemberInfo]:
+        """Collect and return only members carrying a specific marker."""
+        return {n: m for n, m in self.collect(cls).items() if m.has(marker_name)}
+
+    def fields(self, cls: type) -> dict[str, MemberInfo]:
+        """Collect and return only field members."""
+        return {n: m for n, m in self.collect(cls).items() if m.kind == MemberKind.FIELD}
+
+    def methods(self, cls: type) -> dict[str, MemberInfo]:
+        """Collect and return only method members."""
+        return {n: m for n, m in self.collect(cls).items() if m.kind == MemberKind.METHOD}
+
+
+collector = Collector()

markers/descriptors.py

@@ -0,0 +1,58 @@
+"""
+markers.descriptors - Lazy descriptors and BaseMixin.
+
+BaseMixin carries fields/methods/members descriptors and is
+automatically inherited by every MarkerGroup.mixin, so any class
+using at least one group mixin gets all three for free.
+"""
+
+from markers._types import MemberInfo
+from markers.core import collector
+
+__all__: list[str] = []  # No public API — used internally by Marker
+
+
+class MembersDescriptor:
+    """Descriptor returning all collected members (fields + methods).
+
+    Returns a copy to protect the internal cache from mutation.
+    """
+
+    def __get__(self, obj: object, cls: type) -> dict[str, MemberInfo]:
+        return dict(collector.collect(cls))
+
+
+class FieldsDescriptor:
+    """Descriptor returning only field members."""
+
+    def __get__(self, obj: object, cls: type) -> dict[str, MemberInfo]:
+        return collector.fields(cls)
+
+
+class MethodsDescriptor:
+    """Descriptor returning only method members."""
+
+    def __get__(self, obj: object, cls: type) -> dict[str, MemberInfo]:
+        return collector.methods(cls)
+
+
+class MarkerDescriptor:
+    """Descriptor returning all members matching a specific marker."""
+
+    def __init__(self, marker_name: str) -> None:
+        self._marker_name = marker_name
+
+    def __get__(self, obj: object, cls: type) -> dict[str, MemberInfo]:
+        return collector.filter(cls, self._marker_name)
+
+
+class BaseMixin:
+    """Mixin providing fields/methods/members descriptors.
+
+    Every Marker.mixin inherits from this, so any class using
+    at least one marker mixin automatically gets these.
+    """
+
+    fields = FieldsDescriptor()
+    methods = MethodsDescriptor()
+    members = MembersDescriptor()

markers/groups.py

@@ -0,0 +1,88 @@
+"""
+markers.groups - MarkerGroup for bundling related markers.
+
+MarkerGroup is the only way to get marker descriptors onto model classes.
+Markers themselves are pure schema + factory.
+
+    class DB(MarkerGroup):
+        PrimaryKey = PrimaryKey
+        Indexed = Indexed
+
+    class User(DB.mixin):
+        id: Annotated[int, DB.PrimaryKey()]
+
+    User.primary_key  # → dict[str, MemberInfo]
+    User.fields       # → dict[str, MemberInfo]
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from markers.descriptors import BaseMixin, MarkerDescriptor
+from markers.marker import Marker
+
+if TYPE_CHECKING:
+    from markers.marker import MarkerMeta
+
+__all__ = ["MarkerGroup"]
+
+
+class MarkerGroupMeta(type):
+    """Metaclass that auto-builds a .mixin from Marker class attributes."""
+
+    mixin: type
+    _markers: dict[str, MarkerMeta]
+
+    def __new__(mcs, name: str, bases: tuple, namespace: dict, **kwargs: Any) -> type:
+        cls = super().__new__(mcs, name, bases, namespace)
+
+        if name == "MarkerGroup":
+            return cls
+
+        # Find all Marker subclasses assigned as class attributes
+        found_markers: dict[str, MarkerMeta] = {}
+        for attr, val in namespace.items():
+            if isinstance(val, type) and issubclass(val, Marker) and val is not Marker:
+                found_markers[attr] = val  # type: ignore[assignment]
+
+        # Also check base groups for inherited markers
+        for base in bases:
+            if base is MarkerGroup:
+                continue
+            base_markers: dict[str, MarkerMeta] = getattr(base, "_markers", {})
+            for attr, val in base_markers.items():
+                if attr not in found_markers:
+                    found_markers[attr] = val
+
+        # Build mixin: BaseMixin + a MarkerDescriptor per marker
+        mixin_attrs: dict[str, Any] = {}
+        for marker_cls in found_markers.values():
+            mark_name = marker_cls._mark_name
+            mixin_attrs[mark_name] = MarkerDescriptor(mark_name)
+
+        cls.mixin = type(f"{name}Mixin", (BaseMixin,), mixin_attrs)
+        cls._markers = found_markers
+        return cls
+
+
+class MarkerGroup(metaclass=MarkerGroupMeta):
+    """Base class for grouping related markers.
+
+    Subclass and assign Marker subclasses as class attributes::
+
+        class DB(MarkerGroup):
+            PrimaryKey = PrimaryKey
+            Indexed = Indexed
+
+    The class automatically gets a ``.mixin`` that provides:
+    - A MarkerDescriptor for each marker (e.g. ``.primary_key``, ``.indexed``)
+    - ``fields``, ``methods``, ``members`` from BaseMixin
+
+    Groups can inherit from other groups to compose::
+
+        class FullDB(DB):
+            ForeignKey = ForeignKey
+    """
+
+    _markers: dict[str, MarkerMeta] = {}

markers/marker.py

@@ -0,0 +1,184 @@
+"""
+markers.marker - Marker is both the schema and the factory.
+
+Define markers by subclassing Marker. The class body IS the pydantic
+schema. Calling the class creates a validated MarkerInstance.
+
+    class Searchable(Marker):
+        boost: float = 1.0
+        analyzer: str = "standard"
+
+    class Required(Marker):
+        pass
+
+Markers don't carry mixins — use MarkerGroup for that.
+
+Intermediate base markers for shared schema fields::
+
+    class LifecycleMarker(Marker):
+        priority: int = 0
+
+    class OnSave(LifecycleMarker):
+        mark = "on_save"
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from markers._types import MarkerInstance, MemberInfo
+from markers.core import collector
+
+__all__ = ["Marker"]
+
+# Fields that belong to Marker infrastructure, not the schema
+_MARKER_INTERNAL = {"mark", "collect", "invalidate"}
+
+
+class MarkerMeta(type):
+    """Metaclass that makes Marker subclasses act as schema + factory."""
+
+    _mark_name: str
+    _schema_model: type[BaseModel] | None
+    _schema_annotations: dict[str, Any]
+    _schema_defaults: dict[str, Any]
+
+    def __new__(mcs, name: str, bases: tuple, namespace: dict, **kwargs: Any) -> type:
+        # Don't process Marker base class itself
+        if name == "Marker":
+            return super().__new__(mcs, name, bases, namespace)
+
+        # Determine marker name — only set if explicitly provided or this is a leaf
+        mark_name = namespace.pop("mark", None)
+
+        # Collect schema annotations from this class AND parent markers
+        schema_annotations: dict[str, Any] = {}
+        schema_defaults: dict[str, Any] = {}
+
+        # Walk bases for inherited schema fields
+        for base in reversed(bases):
+            if base is Marker:
+                continue
+            base_schema = getattr(base, "_schema_annotations", {})
+            base_defaults = getattr(base, "_schema_defaults", {})
+            schema_annotations.update(base_schema)
+            schema_defaults.update(base_defaults)
+
+        # Add this class's own annotations
+        own_annotations = namespace.get("__annotations__", {})
+        for k, v in own_annotations.items():
+            if k not in _MARKER_INTERNAL and not k.startswith("_"):
+                schema_annotations[k] = v
+
+        # Extract defaults from namespace
+        for k in list(schema_annotations.keys()):
+            if k in namespace:
+                schema_defaults[k] = namespace.pop(k)
+
+        # Build pydantic model if there are schema fields
+        if schema_annotations:
+            model_ns: dict[str, Any] = {
+                "__annotations__": dict(schema_annotations),
+                "model_config": ConfigDict(extra="forbid"),
+            }
+            model_ns.update(schema_defaults)
+            schema_model = type(f"{name}Params", (BaseModel,), model_ns)
+        else:
+            schema_model = None
+
+        # Clean annotations so they don't interfere with the class
+        if "__annotations__" in namespace:
+            namespace["__annotations__"] = {
+                k: v for k, v in namespace["__annotations__"].items() if k not in schema_annotations
+            }
+
+        cls = super().__new__(mcs, name, bases, namespace)
+
+        # If no explicit mark name, default to lowercased class name
+        if mark_name is None:
+            mark_name = name.lower()
+
+        cls._mark_name = mark_name
+        cls._schema_model = schema_model
+        cls._schema_annotations = schema_annotations
+        cls._schema_defaults = schema_defaults
+
+        return cls
+
+    def __call__(cls, **kwargs: Any) -> MarkerInstance:
+        """Create a validated MarkerInstance."""
+        if cls is Marker:
+            raise TypeError("Cannot instantiate Marker directly — subclass it")
+
+        schema_model = cls._schema_model
+
+        if schema_model is not None:
+            params = schema_model(**kwargs)
+            return MarkerInstance(cls._mark_name, params.model_dump(), params)
+        else:
+            if kwargs:
+                raise TypeError(f"Marker '{cls._mark_name}' accepts no parameters, got: {set(kwargs.keys())}")
+            return MarkerInstance(cls._mark_name, {})
+
+    def __repr__(cls) -> str:
+        if cls is Marker:
+            return "<class 'Marker'>"
+        if cls._schema_model is not None:
+            return f"<Marker '{cls._mark_name}' schema={cls._schema_model.__name__}>"
+        return f"<Marker '{cls._mark_name}'>"
+
+
+class Marker(metaclass=MarkerMeta):
+    """Base class for defining markers.
+
+    Subclass to create a marker. Add typed fields for a validated schema,
+    or leave empty for a schema-less marker.
+
+    Class attributes:
+        mark: Optional explicit marker name. Defaults to lowercased class name.
+
+    Markers are pure schema + factory. Use ``MarkerGroup`` to bundle
+    markers and create mixins for your model classes.
+
+    Intermediate bases work naturally for shared fields::
+
+        class LifecycleMarker(Marker):
+            priority: int = 0
+
+        class OnSave(LifecycleMarker):
+            mark = "on_save"
+
+        class OnDelete(LifecycleMarker):
+            mark = "on_delete"
+
+        # OnSave and OnDelete both have priority, with different mark names.
+    """
+
+    _mark_name: str
+    _schema_model: type[BaseModel] | None
+    _schema_annotations: dict[str, Any]
+    _schema_defaults: dict[str, Any]
+
+    @classmethod
+    def collect(cls, target: type) -> dict[str, MemberInfo]:
+        """Collect all members carrying this marker from target class.
+
+        Must be called on a concrete Marker subclass, not on Marker itself.
+        """
+        if cls is Marker:
+            raise TypeError(
+                "collect() must be called on a Marker subclass, e.g. Required.collect(User), not Marker.collect(User)"
+            )
+        return collector.filter(target, cls._mark_name)
+
+    @classmethod
+    def invalidate(cls, target: type) -> None:
+        """Clear the cached collection for a target class.
+
+        Can be called on any Marker subclass or on Marker itself —
+        invalidation is not marker-specific, it clears the entire
+        cache for the target class.
+        """
+        collector.invalidate(target)

markers/registry.py

@@ -0,0 +1,129 @@
+"""
+markers.registry - Registry base class for cross-subclass collection.
+
+    class Entity(DB.mixin, Registry): ...
+    class User(Entity): ...
+    class Post(Entity): ...
+
+    # List registered subclasses
+    Entity.subclasses()  # [User, Post]
+
+    # Per-class access (same as always)
+    User.required        # {'name': MemberInfo, 'email': MemberInfo}
+
+    # Cross-class access via .all — dict of lists, grouped by member name
+    Entity.all.required  # {'name': [MemberInfo(owner=User)], 'email': [...], 'title': [...]}
+    Entity.all.fields    # {'id': [MemberInfo(owner=User), MemberInfo(owner=Post)], ...}
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+from markers._types import MemberInfo
+from markers.core import collector
+from markers.descriptors import BaseMixin
+
+__all__ = ["Registry"]
+
+
+class AllProxy:
+    """Proxy that gathers members from all subclasses into ``dict[str, list[MemberInfo]]``.
+
+    Each key is a member name. Each value is a list of MemberInfo from
+    every subclass that defines that member — so you can see which
+    classes contribute each field/method.
+
+        Entity.all.fields
+        # {'id': [MemberInfo(owner=User), MemberInfo(owner=Post)],
+        #  'name': [MemberInfo(owner=User)],
+        #  'title': [MemberInfo(owner=Post)], ...}
+
+        Entity.all.required
+        # {'name': [MemberInfo(owner=User)],
+        #  'email': [MemberInfo(owner=User), MemberInfo(owner=Customer)], ...}
+    """
+
+    def __init__(self, registry_cls: type) -> None:
+        self._cls = registry_cls
+
+    def _gather(self, extractor: Any) -> dict[str, list[MemberInfo]]:
+        result: dict[str, list[MemberInfo]] = defaultdict(list)
+        registry: dict[str, type] = getattr(self._cls, "_registry", {})
+        for sub in registry.values():
+            for name, info in extractor(sub).items():
+                result[name].append(info)
+        return dict(result)
+
+    @property
+    def members(self) -> dict[str, list[MemberInfo]]:
+        """All members from all subclasses."""
+        return self._gather(collector.collect)
+
+    @property
+    def fields(self) -> dict[str, list[MemberInfo]]:
+        """All fields from all subclasses."""
+        return self._gather(collector.fields)
+
+    @property
+    def methods(self) -> dict[str, list[MemberInfo]]:
+        """All methods from all subclasses."""
+        return self._gather(collector.methods)
+
+    def __getattr__(self, marker_name: str) -> dict[str, list[MemberInfo]]:
+        """Collect a specific marker across all subclasses."""
+        if marker_name.startswith("_"):
+            raise AttributeError(marker_name)
+        return self._gather(lambda sub: collector.filter(sub, marker_name))
+
+
+class AllDescriptor:
+    """Descriptor that returns an AllProxy bound to the registry class."""
+
+    def __get__(self, obj: object, cls: type) -> AllProxy:
+        return AllProxy(cls)
+
+
+class Registry(BaseMixin):
+    """Base class that tracks all subclasses.
+
+    Inherits BaseMixin so ``fields``, ``methods``, and ``members``
+    are always available.
+
+    Per-class access works as usual::
+
+        User.fields          # dict[str, MemberInfo]
+        User.required        # dict[str, MemberInfo]
+
+    Cross-class access via ``.all`` gathers into lists by member name::
+
+        Entity.all.fields    # dict[str, list[MemberInfo]]
+        Entity.all.required  # dict[str, list[MemberInfo]]
+
+    Each list entry has ``.owner`` so you know which class it came from.
+
+    Use ``subclasses()`` for direct iteration::
+
+        for cls in Entity.subclasses():
+            print(cls.__name__, list(cls.required.keys()))
+    """
+
+    _registry: dict[str, type] = {}
+    all = AllDescriptor()
+
+    def __init_subclass__(cls, abstract: bool = False, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if not abstract:
+            cls._registry = {}
+            for base in cls.__mro__[1:]:
+                if base is Registry:
+                    break
+                if issubclass(base, Registry) and hasattr(base, "_registry"):
+                    base._registry[cls.__name__] = cls
+                    break
+
+    @classmethod
+    def subclasses(cls) -> list[type]:
+        """Return all registered subclasses."""
+        return list(cls._registry.values())