code-is-magic-markers 0.2.0__tar.gz → 0.3.0__tar.gz

{code_is_magic_markers-0.2.0 → code_is_magic_markers-0.3.0}/.github/workflows/ci.yml

@@ -17,9 +17,9 @@ jobs:
     name: Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v5.0.1
 
-      - uses: astral-sh/setup-uv@v4
+      - uses: astral-sh/setup-uv@v8.0.0
         with:
           python-version: "3.14"
 
@@ -36,9 +36,9 @@ jobs:
     name: Type check
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v5.0.1
 
-      - uses: astral-sh/setup-uv@v4
+      - uses: astral-sh/setup-uv@v8.0.0
         with:
           python-version: "3.14"
 
@@ -56,9 +56,9 @@ jobs:
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v5.0.1
 
-      - uses: astral-sh/setup-uv@v4
+      - uses: astral-sh/setup-uv@v8.0.0
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -73,9 +73,9 @@ jobs:
     runs-on: ubuntu-latest
     needs: [test]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v5.0.1
 
-      - uses: astral-sh/setup-uv@v4
+      - uses: astral-sh/setup-uv@v8.0.0
         with:
           python-version: "3.14"
 
@@ -86,7 +86,7 @@ jobs:
         run: uv run pytest tests/ --cov=markers --cov-report=xml --cov-report=term-missing
 
       - name: Upload coverage
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6.0.0
         with:
           file: coverage.xml
           fail_ci_if_error: false

{code_is_magic_markers-0.2.0 → code_is_magic_markers-0.3.0}/.github/workflows/release.yml

@@ -14,9 +14,9 @@ jobs:
     name: Pre-release checks
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v5.0.1
 
-      - uses: astral-sh/setup-uv@v4
+      - uses: astral-sh/setup-uv@v8.0.0
 
       - name: Install dependencies
         run: uv sync --extra dev
@@ -35,15 +35,15 @@ jobs:
     runs-on: ubuntu-latest
     needs: [check]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v5.0.1
 
-      - uses: astral-sh/setup-uv@v4
+      - uses: astral-sh/setup-uv@v8.0.0
 
       - name: Build sdist and wheel
         run: uv build
 
       - name: Upload build artifacts
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v7.0.1
         with:
           name: dist
           path: dist/
@@ -54,7 +54,7 @@ jobs:
     needs: [build]
     environment: testpypi
     steps:
-      - uses: actions/download-artifact@v5
+      - uses: actions/download-artifact@v8.0.1
         with:
           name: dist
           path: dist/
@@ -70,7 +70,7 @@ jobs:
     needs: [publish-testpypi]
     environment: pypi
     steps:
-      - uses: actions/download-artifact@v5
+      - uses: actions/download-artifact@v8.0.1
         with:
           name: dist
           path: dist/
@@ -83,15 +83,15 @@ jobs:
     runs-on: ubuntu-latest
     needs: [publish-pypi]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v5.0.1
 
-      - uses: actions/download-artifact@v5
+      - uses: actions/download-artifact@v8.0.1
         with:
           name: dist
           path: dist/
 
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3.0.0
         with:
           files: dist/*
           generate_release_notes: true

code_is_magic_markers-0.3.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-04-13
+
+### Added
+
+- PEP 681 `dataclass_transform` support — marker constructor parameters (`MaxLen(limit=100)`) are fully validated by type checkers (Pylance, Pyright, mypy). Typos, wrong types, and missing required params are caught statically.
+- Type stubs (`marker.pyi`, `groups.pyi`) for full IDE integration
+- `BaseMixinMeta` metaclass for generated mixin classes
+- `.fields`, `.methods`, `.members` are now fully typed as `dict[str, MemberInfo]` on any class using a group mixin
+- Decorator usage (`@OnSave(priority=10)`) preserves the decorated function's type signature
+- Type checking example (`examples/type_check_example.py`) demonstrating all typed patterns
+- "Type checking" section in README documenting what's typed and escape hatches for dynamic descriptors
+
+### Changed
+
+- `MarkerInstance.__call__` signature uses `TypeVar` to preserve decorated function types
+- `MarkerGroupMeta.__new__` return type narrowed to `MarkerGroupMeta` (was `type`)
+- `MarkerGroup.mixin` typed as `type[BaseMixin]` (was `type`)
+- Generated mixin classes now use `BaseMixinMeta` metaclass (was `type`)
+- Removed `from __future__ import annotations` from `groups.py` for better type checker resolution
+
+## [0.2.0] - 2026-04-13
+
+### Added
+
+- Python 3.14 support (PEP 749 deferred annotations)
+- Python 3.14 in CI test matrix, tox env list, and pyproject.toml classifiers
+
+### Changed
+
+- `MarkerMeta.__new__` restructured to read annotations from the created class rather than the namespace dict, for compatibility with Python 3.14.4+ where `__annotations__` is no longer populated in the namespace
+- `Collector.collect` uses `annotationlib.get_annotations(format=STRING)` on Python 3.14+ instead of reading `__annotations__` directly
+- CI lint, typecheck, and coverage jobs now default to Python 3.14
+
+## [0.1.1] - 2026-04-13
+
+### Changed
+
+- Expanded README with motivation, detailed guides for all concepts, caching/invalidation docs, reusable mixins pattern, and complete API reference tables
+
+## [0.1.0] - 2025-04-12
+
+### Added
+
+- `Marker` base class — subclass to define markers with optional pydantic schema
+- `MarkerGroup` — bundle related markers into a `.mixin` for clean inheritance
+- `Registry` — track subclasses with `.subclasses()` and `.all` aggregation
+- `MarkerInstance` — validated marker usage, works as both `Annotated[]` metadata and method decorator
+- `MemberInfo` — unified metadata for fields and methods with `has`/`get`/`get_all` queries
+- MRO-walking `Collector` with weakref-based per-class caching
+- Intermediate marker base classes for shared schema fields
+- `AllProxy` for cross-subclass collection via `Registry.all`
+- PEP 561 `py.typed` marker
+- 70 tests covering all features
+- ORM-style real-world usage example with SQL generation

code_is_magic_markers-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Contributing
+
+## Setup
+
+```bash
+git clone https://github.com/Richard-Lynch/markers.git
+cd markers
+make venv
+make deps
+```
+
+## Development workflow
+
+### Run tests
+
+```bash
+# Quick run
+make test
+
+# With coverage
+make test:cov
+
+# Full matrix (Python 3.10–3.14)
+tox
+```
+
+### Lint and format
+
+```bash
+# Check
+make lint
+
+# Auto-fix
+make format
+```
+
+### Type check
+
+```bash
+make typecheck
+```
+
+### Run all checks
+
+```bash
+make check
+```
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/):
+
+- **Patch** (0.1.x): Bug fixes, documentation, CI changes
+- **Minor** (0.x.0): New features, new Python version support, backwards-compatible changes
+- **Major** (x.0.0): Breaking API changes
+
+## Release process
+
+`main` is protected — all changes go through pull requests.
+
+1. Create a release branch: `git checkout -b release/v0.x.y`
+2. Update version in `pyproject.toml`
+3. Update `CHANGELOG.md`
+4. Open a PR, get CI green, merge
+5. Tag main: `git checkout main && git pull && git tag v0.x.y && git push origin v0.x.y`
+
+The GitHub Actions release workflow will automatically:
+- Run all checks
+- Build sdist + wheel
+- Publish to TestPyPI
+- Publish to PyPI
+- Create a GitHub Release with auto-generated notes
+
+## Project structure
+
+```
+src/markers/
+├── __init__.py      # Public API exports
+├── _types.py        # MarkerInstance, MemberInfo, MemberKind, MISSING
+├── core.py          # Collector — MRO walking + caching
+├── descriptors.py   # BaseMixin, BaseMixinMeta + descriptor classes
+├── marker.py        # Marker + MarkerMeta
+├── marker.pyi       # Type stub — dataclass_transform for marker kwargs
+├── groups.py        # MarkerGroup + MarkerGroupMeta
+├── groups.pyi       # Type stub — mixin base class typing
+├── registry.py      # Registry + AllProxy
+└── py.typed         # PEP 561 marker
+```
+
+## Type stubs
+
+The library uses `.pyi` stubs for `marker.py` and `groups.py` to provide
+type information that can't be expressed inline:
+
+- **`marker.pyi`** — Uses PEP 681 `dataclass_transform` on `MarkerMeta` so
+  type checkers validate marker constructor kwargs against the schema
+  annotations on each `Marker` subclass. Also exposes `__call__` and
+  `__getattr__` on `Marker` instances for decorator and attribute access.
+
+- **`groups.pyi`** — Declares `MarkerGroup.mixin = BaseMixin` so type checkers
+  accept `class User(DB.mixin):` as valid and know the class inherits
+  `BaseMixin`'s typed `.fields`, `.methods`, `.members` descriptors.
+
+When modifying `marker.py` or `groups.py`, check that the corresponding
+`.pyi` stub stays in sync.

{code_is_magic_markers-0.2.0 → code_is_magic_markers-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-is-magic-markers
-Version: 0.2.0
+Version: 0.3.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
@@ -372,6 +372,81 @@ inst.analyzer     # 'english'
 | `inst.marker_name` | `str` | The marker type name |
 | `inst.<field>` | `Any` | Access any schema field as an attribute |
 
+## Type checking
+
+The library ships with PEP 561 `py.typed` support and type stubs for full IDE integration (Pylance, Pyright, mypy).
+
+### What's typed automatically
+
+**Marker constructors** — parameters are fully validated by type checkers via [PEP 681 `dataclass_transform`](https://peps.python.org/pep-0681/). Typos, wrong types, and missing required params are all caught:
+
+```python
+class MaxLen(Marker):
+    mark = "max_length"
+    limit: int
+
+MaxLen(limit=100)          # ok
+MaxLen(limit="oops")       # type error: str is not int
+MaxLen()                   # type error: missing 'limit'
+MaxLen(limti=100)          # type error: no param 'limti'
+```
+
+**BaseMixin descriptors** — `.fields`, `.methods`, `.members` are typed as `dict[str, MemberInfo]` on any class using a group mixin. Full dict operations (`.items()`, `.keys()`, `.values()`, indexing) work without casts:
+
+```python
+class User(DB.mixin):
+    id: Annotated[int, DB.PrimaryKey()]
+
+for name, info in User.fields.items():  # (str, MemberInfo) — fully typed
+    print(info.is_field, info.has("primary_key"))
+```
+
+**Decorator signatures** — `@OnSave(priority=10)` preserves the decorated function's type. Type checkers see the original return type, not `MarkerInstance`:
+
+```python
+@Lifecycle.OnSave(priority=10)
+def validate(self) -> list[str]: ...
+
+reveal_type(User().validate())  # list[str]
+```
+
+**Registry `.all` proxy** — `.all.fields`, `.all.methods`, `.all.members`, and `.all.<marker_name>` are typed as `dict[str, list[MemberInfo]]`.
+
+**`Marker.collect()`** — always returns `dict[str, MemberInfo]`, fully typed:
+
+```python
+PrimaryKey.collect(User)  # dict[str, MemberInfo] — no type: ignore needed
+```
+
+### What's not typed automatically
+
+**Marker-specific descriptors** like `.primary_key`, `.required`, `.indexed` are added dynamically by `MarkerGroupMeta` and are not visible to type checkers. Two options:
+
+**Option A** — Use `Marker.collect()` (no annotations needed):
+
+```python
+# Instead of User.primary_key, use:
+PrimaryKey.collect(User)  # fully typed: dict[str, MemberInfo]
+```
+
+**Option B** — Add explicit `ClassVar` annotations (opt-in per class):
+
+```python
+from typing import TYPE_CHECKING, ClassVar
+
+class User(DB.mixin):
+    if TYPE_CHECKING:
+        primary_key: ClassVar[dict[str, MemberInfo]]
+        indexed: ClassVar[dict[str, MemberInfo]]
+
+    id: Annotated[int, DB.PrimaryKey()]
+    email: Annotated[str, DB.Indexed(unique=True)]
+
+User.primary_key  # now typed as dict[str, MemberInfo]
+```
+
+The `TYPE_CHECKING` guard ensures these annotations don't affect runtime behavior — the actual values come from the dynamically-installed `MarkerDescriptor` instances.
+
 ## How collection works
 
 When you access a descriptor like `User.fields` or `User.required`, the library:

{code_is_magic_markers-0.2.0 → code_is_magic_markers-0.3.0}/README.md

@@ -340,6 +340,81 @@ inst.analyzer     # 'english'
 | `inst.marker_name` | `str` | The marker type name |
 | `inst.<field>` | `Any` | Access any schema field as an attribute |
 
+## Type checking
+
+The library ships with PEP 561 `py.typed` support and type stubs for full IDE integration (Pylance, Pyright, mypy).
+
+### What's typed automatically
+
+**Marker constructors** — parameters are fully validated by type checkers via [PEP 681 `dataclass_transform`](https://peps.python.org/pep-0681/). Typos, wrong types, and missing required params are all caught:
+
+```python
+class MaxLen(Marker):
+    mark = "max_length"
+    limit: int
+
+MaxLen(limit=100)          # ok
+MaxLen(limit="oops")       # type error: str is not int
+MaxLen()                   # type error: missing 'limit'
+MaxLen(limti=100)          # type error: no param 'limti'
+```
+
+**BaseMixin descriptors** — `.fields`, `.methods`, `.members` are typed as `dict[str, MemberInfo]` on any class using a group mixin. Full dict operations (`.items()`, `.keys()`, `.values()`, indexing) work without casts:
+
+```python
+class User(DB.mixin):
+    id: Annotated[int, DB.PrimaryKey()]
+
+for name, info in User.fields.items():  # (str, MemberInfo) — fully typed
+    print(info.is_field, info.has("primary_key"))
+```
+
+**Decorator signatures** — `@OnSave(priority=10)` preserves the decorated function's type. Type checkers see the original return type, not `MarkerInstance`:
+
+```python
+@Lifecycle.OnSave(priority=10)
+def validate(self) -> list[str]: ...
+
+reveal_type(User().validate())  # list[str]
+```
+
+**Registry `.all` proxy** — `.all.fields`, `.all.methods`, `.all.members`, and `.all.<marker_name>` are typed as `dict[str, list[MemberInfo]]`.
+
+**`Marker.collect()`** — always returns `dict[str, MemberInfo]`, fully typed:
+
+```python
+PrimaryKey.collect(User)  # dict[str, MemberInfo] — no type: ignore needed
+```
+
+### What's not typed automatically
+
+**Marker-specific descriptors** like `.primary_key`, `.required`, `.indexed` are added dynamically by `MarkerGroupMeta` and are not visible to type checkers. Two options:
+
+**Option A** — Use `Marker.collect()` (no annotations needed):
+
+```python
+# Instead of User.primary_key, use:
+PrimaryKey.collect(User)  # fully typed: dict[str, MemberInfo]
+```
+
+**Option B** — Add explicit `ClassVar` annotations (opt-in per class):
+
+```python
+from typing import TYPE_CHECKING, ClassVar
+
+class User(DB.mixin):
+    if TYPE_CHECKING:
+        primary_key: ClassVar[dict[str, MemberInfo]]
+        indexed: ClassVar[dict[str, MemberInfo]]
+
+    id: Annotated[int, DB.PrimaryKey()]
+    email: Annotated[str, DB.Indexed(unique=True)]
+
+User.primary_key  # now typed as dict[str, MemberInfo]
+```
+
+The `TYPE_CHECKING` guard ensures these annotations don't affect runtime behavior — the actual values come from the dynamically-installed `MarkerDescriptor` instances.
+
 ## How collection works
 
 When you access a descriptor like `User.fields` or `User.required`, the library:

code_is_magic_markers-0.3.0/examples/type_check_example.py

@@ -0,0 +1,181 @@
+"""
+Example for validating type checker behavior with markers.
+
+Open this file in your IDE (Pylance/Pyright) and verify:
+- .fields, .members, .methods are fully typed as dict[str, MemberInfo]
+- .items(), .keys(), .values() all work on descriptor results
+- Decorated methods preserve their signatures
+- Registry .all proxy returns dict[str, list[MemberInfo]]
+
+Marker-specific descriptors (.primary_key, .required, etc.) are
+dynamic — type checkers can't see them without help. Two options:
+
+1. Use Marker.collect(cls) — fully typed, no annotations needed.
+2. Add ClassVar annotations under TYPE_CHECKING on your class.
+"""
+
+from typing import TYPE_CHECKING, Annotated, ClassVar
+
+from markers import Marker, MarkerGroup, MemberInfo, Registry
+
+
+# -- Markers --
+
+
+class Required(Marker):
+    pass
+
+
+class MaxLen(Marker):
+    mark = "max_length"
+    limit: int
+
+
+class PrimaryKey(Marker):
+    mark = "primary_key"
+    auto_increment: bool = True
+
+
+class Indexed(Marker):
+    unique: bool = False
+
+
+class Transition(Marker):
+    source: list[str]
+    target: str
+
+
+# -- Groups --
+
+
+class Validation(MarkerGroup):
+    Required = Required
+    MaxLen = MaxLen
+
+
+class DB(MarkerGroup):
+    PrimaryKey = PrimaryKey
+    Indexed = Indexed
+
+
+class SM(MarkerGroup):
+    Transition = Transition
+
+
+# ============================================================
+# 1. BaseMixin descriptors: always typed
+# ============================================================
+
+class User(DB.mixin):
+    id: Annotated[int, DB.PrimaryKey()]
+    email: Annotated[str, DB.Indexed(unique=True)]
+
+
+# .fields, .methods, .members — all dict[str, MemberInfo]
+fields: dict[str, MemberInfo] = User.fields
+methods: dict[str, MemberInfo] = User.methods
+members: dict[str, MemberInfo] = User.members
+
+# .items() yields (str, MemberInfo)
+for field_name, info in User.fields.items():
+    print(f"{field_name}: is_field={info.is_field}, has_default={info.has_default}")
+
+for field_name in User.fields.keys():
+    print(field_name)
+
+for info in User.fields.values():
+    print(info.name, info.kind)
+
+
+# ============================================================
+# 2. MemberInfo methods
+# ============================================================
+
+id_info = User.fields["id"]
+print(id_info.has("primary_key"))       # bool
+print(id_info.get("primary_key"))       # MarkerInstance | None
+print(id_info.get_all("primary_key"))   # list[MarkerInstance]
+
+
+# ============================================================
+# 3. Marker-specific descriptors: option A — Marker.collect()
+#    Fully typed, no annotations needed.
+# ============================================================
+
+pk: dict[str, MemberInfo] = PrimaryKey.collect(User)
+idx: dict[str, MemberInfo] = Indexed.collect(User)
+
+for field_name, info in PrimaryKey.collect(User).items():
+    marker = info.get("primary_key")
+    print(f"{field_name}: has pk = {marker is not None}")
+
+
+# ============================================================
+# 4. Marker-specific descriptors: option B — ClassVar annotations
+#    Opt-in explicit typing for descriptor access on the class.
+# ============================================================
+
+class Product(DB.mixin):
+    if TYPE_CHECKING:
+        primary_key: ClassVar[dict[str, MemberInfo]]
+        indexed: ClassVar[dict[str, MemberInfo]]
+
+    id: Annotated[int, DB.PrimaryKey()]
+    sku: Annotated[str, DB.Indexed(unique=True)]
+
+
+# Now type checkers know about these:
+product_pk: dict[str, MemberInfo] = Product.primary_key
+product_idx: dict[str, MemberInfo] = Product.indexed
+
+for field_name, info in Product.primary_key.items():
+    print(f"{field_name}: {info.name}")
+
+
+# ============================================================
+# 5. Decorator preserves function type
+# ============================================================
+
+class Task(SM.mixin):
+    title: Annotated[str, SM.Transition(source=["backlog"], target="todo")]
+
+    @SM.Transition(source=["backlog"], target="todo")
+    def move_to_todo(self) -> str:
+        return "moved"
+
+    @SM.Transition(source=["todo", "in_progress"], target="done")
+    def complete(self) -> bool:
+        return True
+
+
+task = Task()
+
+# These preserve the original return types
+result_str: str = task.move_to_todo()
+result_bool: bool = task.complete()
+
+
+# ============================================================
+# 6. Registry .all proxy: dict[str, list[MemberInfo]]
+# ============================================================
+
+class Entity(DB.mixin, Registry):
+    id: Annotated[int, DB.PrimaryKey()]
+
+
+class Customer(Entity):
+    tier: Annotated[str, DB.Indexed()] = "free"
+
+
+class Order(Entity):
+    total: Annotated[float, DB.Indexed(unique=True)]
+
+
+all_fields: dict[str, list[MemberInfo]] = Entity.all.fields
+
+for member_name, infos in Entity.all.fields.items():
+    owners = [i.owner.__name__ for i in infos if i.owner]
+    print(f"{member_name}: {owners}")
+
+for cls in Entity.subclasses():
+    print(cls.__name__)

{code_is_magic_markers-0.2.0 → code_is_magic_markers-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "code-is-magic-markers"
-version = "0.2.0"
+version = "0.3.0"
 description = "Lightweight class introspection toolkit — define typed markers, annotate fields and methods, collect metadata via MRO-walking descriptors."
 readme = "README.md"
 license = "MIT"

{code_is_magic_markers-0.2.0 → code_is_magic_markers-0.3.0}/src/markers/__init__.py

@@ -42,6 +42,22 @@ Supporting types:
     MemberInfo      Metadata about a field or method. Use .has()/.get()/.get_all().
     MemberKind      Enum: FIELD or METHOD.
     MISSING         Sentinel for fields with no default value.
+
+Type checking:
+    The library ships with PEP 561 ``py.typed`` support and type stubs.
+
+    - Marker constructor kwargs are **fully validated** by type checkers
+      (e.g. ``MaxLen(limit="oops")`` is a type error). This is powered by
+      PEP 681 ``dataclass_transform`` on the ``Marker`` metaclass.
+    - ``.fields``, ``.methods``, ``.members`` are typed as
+      ``dict[str, MemberInfo]`` on any class using a group mixin.
+    - ``Marker.collect(cls)`` is the fully-typed alternative for
+      marker-specific queries (e.g. ``Required.collect(User)``).
+    - Decorator usage preserves function signatures (``@OnSave()``
+      does not erase the decorated function's type).
+    - Marker-specific descriptors (``.primary_key``, ``.required``)
+      are dynamic and not visible to type checkers. See ``MarkerGroup``
+      docstring for typed alternatives.
 """
 
 from markers._types import MISSING, MarkerInstance, MemberInfo, MemberKind

{code_is_magic_markers-0.2.0 → code_is_magic_markers-0.3.0}/src/markers/_types.py

@@ -6,7 +6,9 @@ from __future__ import annotations
 
 from collections.abc import Callable
 from enum import Enum, auto
-from typing import Any
+from typing import Any, TypeVar
+
+_F = TypeVar("_F", bound=Callable[..., Any])
 
 __all__ = ["MISSING", "MarkerInstance", "MemberInfo", "MemberKind"]
 
@@ -69,8 +71,12 @@ class MarkerInstance:
         """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."""
+    def __call__(self, fn: _F) -> _F:
+        """Decorate a function, attaching this MarkerInstance.
+
+        The decorated function's type signature is preserved — type checkers
+        will see the original return type, not ``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", []))

{code_is_magic_markers-0.2.0 → code_is_magic_markers-0.3.0}/src/markers/descriptors.py

@@ -46,11 +46,33 @@ class MarkerDescriptor:
         return collector.filter(cls, self._marker_name)
 
 
-class BaseMixin:
+class BaseMixinMeta(type):
+    """Metaclass for generated mixin classes.
+
+    Used by ``MarkerGroupMeta`` to create mixin classes that inherit
+    from ``BaseMixin`` and carry ``MarkerDescriptor`` instances for
+    each marker in the group.
+    """
+
+
+class BaseMixin(metaclass=BaseMixinMeta):
     """Mixin providing fields/methods/members descriptors.
 
     Every Marker.mixin inherits from this, so any class using
     at least one marker mixin automatically gets these.
+
+    Marker-specific descriptors (e.g. ``.primary_key``, ``.required``)
+    are added dynamically by ``MarkerGroupMeta`` and work at runtime.
+    For static type checking of these descriptors, either:
+
+    - Use ``Marker.collect()``::
+
+          PrimaryKey.collect(User)  # fully typed: dict[str, MemberInfo]
+
+    - Add explicit type annotations under ``TYPE_CHECKING``::
+
+          if TYPE_CHECKING:
+              primary_key: ClassVar[dict[str, MemberInfo]]
     """
 
     fields = FieldsDescriptor()

{code_is_magic_markers-0.2.0 → code_is_magic_markers-0.3.0}/src/markers/groups.py

@@ -15,15 +15,10 @@ Markers themselves are pure schema + factory.
     User.fields       # → dict[str, MemberInfo]
 """
 
-from __future__ import annotations
+from typing import Any
 
-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
+from markers.descriptors import BaseMixin, BaseMixinMeta, MarkerDescriptor
+from markers.marker import Marker, MarkerMeta
 
 __all__ = ["MarkerGroup"]
 
@@ -31,10 +26,10 @@ __all__ = ["MarkerGroup"]
 class MarkerGroupMeta(type):
     """Metaclass that auto-builds a .mixin from Marker class attributes."""
 
-    mixin: type
+    mixin: type[BaseMixin]
     _markers: dict[str, MarkerMeta]
 
-    def __new__(mcs, name: str, bases: tuple, namespace: dict, **kwargs: Any) -> type:
+    def __new__(mcs, name: str, bases: tuple, namespace: dict, **kwargs: Any) -> "MarkerGroupMeta":
         cls = super().__new__(mcs, name, bases, namespace)
 
         if name == "MarkerGroup":
@@ -61,7 +56,7 @@ class MarkerGroupMeta(type):
             mark_name = marker_cls._mark_name
             mixin_attrs[mark_name] = MarkerDescriptor(mark_name)
 
-        cls.mixin = type(f"{name}Mixin", (BaseMixin,), mixin_attrs)
+        cls.mixin = BaseMixinMeta(f"{name}Mixin", (BaseMixin,), mixin_attrs)  # type: ignore[assignment]
         cls._markers = found_markers
         return cls
 
@@ -108,9 +103,28 @@ class MarkerGroup(metaclass=MarkerGroupMeta):
 
         # FullDB.mixin has all of DB's descriptors plus 'unique' and 'check'
 
+    Type checking:
+        ``.fields``, ``.methods``, and ``.members`` are fully typed as
+        ``dict[str, MemberInfo]`` via ``BaseMixin``. Marker-specific
+        descriptors (e.g. ``.primary_key``) are dynamic and not visible
+        to type checkers. Two typed alternatives:
+
+        - Use ``Marker.collect()``::
+
+              PrimaryKey.collect(User)  # fully typed: dict[str, MemberInfo]
+
+        - Add explicit ``ClassVar`` annotations::
+
+              if TYPE_CHECKING:
+                  primary_key: ClassVar[dict[str, MemberInfo]]
+
+        Marker constructor parameters (e.g. ``MaxLen(limit=100)``) are
+        fully validated by type checkers via ``dataclass_transform``.
+
     Attributes:
-        mixin (type): The generated mixin class. Inherit from this.
+        mixin (type[BaseMixin]): The generated mixin class. Inherit from this.
         _markers (dict[str, MarkerMeta]): Mapping of attribute name to Marker class.
     """
 
+    mixin: type[BaseMixin]
     _markers: dict[str, MarkerMeta] = {}

code_is_magic_markers-0.3.0/src/markers/groups.pyi

@@ -0,0 +1,19 @@
+from typing import Any
+
+from markers.descriptors import BaseMixin
+from markers.marker import MarkerMeta
+
+class MarkerGroupMeta(type):
+    mixin: type[BaseMixin]
+    _markers: dict[str, MarkerMeta]
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        **kwargs: Any,
+    ) -> MarkerGroupMeta: ...
+
+class MarkerGroup(metaclass=MarkerGroupMeta):
+    mixin = BaseMixin
+    _markers: dict[str, MarkerMeta]

{code_is_magic_markers-0.2.0 → code_is_magic_markers-0.3.0}/src/markers/marker.py

@@ -203,13 +203,26 @@ class Marker(metaclass=MarkerMeta):
 
         # Both have 'priority' with default 0, different mark names.
 
+    Type checking:
+        Marker constructor parameters are fully validated by type checkers
+        via PEP 681 ``dataclass_transform`` (declared in ``marker.pyi``).
+        This means ``MaxLen(limit="oops")`` is a static type error, and
+        ``MaxLen()`` flags the missing required ``limit`` parameter.
+
+        Decorator usage preserves the decorated function's type signature::
+
+            @OnSave(priority=10)
+            def validate(self) -> list[str]: ...
+            # type checkers see validate as (self) -> list[str]
+
     Class methods:
         collect(cls, target):
             Collect all members carrying this marker from ``target``.
-            Returns ``dict[str, MemberInfo]``.
-            Must be called on a subclass, not ``Marker`` itself::
+            Returns ``dict[str, MemberInfo]``. Fully typed — this is
+            the recommended way to query markers when you need static
+            type safety::
 
-                Required.collect(User)  # {'name': MemberInfo, 'email': MemberInfo}
+                Required.collect(User)  # dict[str, MemberInfo]
 
         invalidate(cls, target):
             Clear cached collection for ``target``. Useful after dynamic

code_is_magic_markers-0.3.0/src/markers/marker.pyi

@@ -0,0 +1,30 @@
+from collections.abc import Callable
+from typing import Any, ClassVar, TypeVar
+
+from pydantic import BaseModel
+from typing_extensions import dataclass_transform
+
+from markers._types import MemberInfo
+
+_F = TypeVar("_F", bound=Callable[..., Any])
+
+@dataclass_transform()
+class MarkerMeta(type):
+    _mark_name: str
+    _schema_model: type[BaseModel] | None
+    _schema_annotations: dict[str, Any]
+    _schema_defaults: dict[str, Any]
+
+class Marker(metaclass=MarkerMeta):
+    _mark_name: ClassVar[str]
+    _schema_model: ClassVar[type[BaseModel] | None]
+    _schema_annotations: ClassVar[dict[str, Any]]
+    _schema_defaults: ClassVar[dict[str, Any]]
+    mark: ClassVar[str]
+    marker_name: ClassVar[str]
+    def __call__(self, fn: _F) -> _F: ...
+    def __getattr__(self, key: str) -> Any: ...
+    @classmethod
+    def collect(cls, target: type) -> dict[str, MemberInfo]: ...
+    @classmethod
+    def invalidate(cls, target: type) -> None: ...

code_is_magic_markers-0.2.0/CHANGELOG.md

@@ -1,28 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [0.1.1] - 2026-04-13
-
-### Changed
-
-- Expanded README with motivation, detailed guides for all concepts, caching/invalidation docs, reusable mixins pattern, and complete API reference tables
-
-## [0.1.0] - 2025-04-12
-
-### Added
-
-- `Marker` base class — subclass to define markers with optional pydantic schema
-- `MarkerGroup` — bundle related markers into a `.mixin` for clean inheritance
-- `Registry` — track subclasses with `.subclasses()` and `.all` aggregation
-- `MarkerInstance` — validated marker usage, works as both `Annotated[]` metadata and method decorator
-- `MemberInfo` — unified metadata for fields and methods with `has`/`get`/`get_all` queries
-- MRO-walking `Collector` with weakref-based per-class caching
-- Intermediate marker base classes for shared schema fields
-- `AllProxy` for cross-subclass collection via `Registry.all`
-- PEP 561 `py.typed` marker
-- 70 tests covering all features
-- ORM-style real-world usage example with SQL generation

code_is_magic_markers-0.2.0/CONTRIBUTING.md

@@ -1,75 +0,0 @@
-# Contributing
-
-## Setup
-
-```bash
-git clone https://github.com/Richard-Lynch/markers.git
-cd markers
-make venv
-make deps
-```
-
-## Development workflow
-
-### Run tests
-
-```bash
-# Quick run
-make test
-
-# With coverage
-make test:cov
-
-# Full matrix (Python 3.10–3.13)
-tox
-```
-
-### Lint and format
-
-```bash
-# Check
-make lint
-
-# Auto-fix
-make format
-```
-
-### Type check
-
-```bash
-make typecheck
-```
-
-### Run all checks
-
-```bash
-make check
-```
-
-## Release process
-
-1. Update version in `pyproject.toml`
-2. Update `CHANGELOG.md`
-3. Commit: `git commit -am "Release v0.x.y"`
-4. Tag: `git tag v0.x.y`
-5. Push: `git push origin main --tags`
-
-The GitHub Actions release workflow will automatically:
-- Run all checks
-- Build sdist + wheel
-- Publish to TestPyPI
-- Publish to PyPI
-- Create a GitHub Release with auto-generated notes
-
-## Project structure
-
-```
-src/markers/
-├── __init__.py      # Public API exports
-├── _types.py        # MarkerInstance, MemberInfo, MemberKind, MISSING
-├── core.py          # Collector — MRO walking + caching
-├── descriptors.py   # BaseMixin + descriptor classes
-├── marker.py        # Marker + MarkerMeta
-├── groups.py        # MarkerGroup + MarkerGroupMeta
-└── registry.py      # Registry + AllProxy
-```