code-is-magic-markers 0.1.0__tar.gz

code_is_magic_markers-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## What
+
+<!-- Brief description of the change -->
+
+## Why
+
+<!-- Motivation / context -->
+
+## Testing
+
+- [ ] Tests pass (`make test`)
+- [ ] Lint passes (`make lint`)
+- [ ] Type check passes (`make typecheck`)
+- [ ] New tests added for new functionality

code_is_magic_markers-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,94 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install ruff
+
+      - name: Ruff check
+        run: ruff check src/ tests/
+
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+
+  typecheck:
+    name: Type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          pip install mypy
+          pip install -e .
+
+      - name: Mypy
+        run: mypy src/markers/ --ignore-missing-imports
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    needs: [test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests with coverage
+        run: pytest tests/ --cov=markers --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

code_is_magic_markers-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,104 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  check:
+    name: Pre-release checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]" ruff mypy
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Type check
+        run: mypy src/markers/ --ignore-missing-imports
+
+      - name: Test
+        run: pytest tests/ -v
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: [check]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    needs: [build]
+    environment: testpypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [publish-testpypi]
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: GitHub Release
+    runs-on: ubuntu-latest
+    needs: [publish-pypi]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

code_is_magic_markers-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing / coverage
+.tox/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache/
+
+# claude
+.claude/
+
+# OS
+.DS_Store
+Thumbs.db

code_is_magic_markers-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# 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.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.1.0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# 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
+```

code_is_magic_markers-0.1.0/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.

code_is_magic_markers-0.1.0/Makefile

@@ -0,0 +1,64 @@
+.PHONY: help venv deps deps\:resolve deps\:install deps\:update test test\:cov lint format typecheck check build clean
+
+VENV := .venv
+UV := uv
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_:-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+# --- Environment ---
+
+venv: ## Create virtual environment
+	$(UV) venv $(VENV)
+
+# --- Dependencies ---
+
+deps\:resolve: ## Resolve and lock dependencies
+	$(UV) lock
+
+deps\:install: ## Install project with dev extras into venv
+	$(UV) sync --extra dev
+
+deps\:update: ## Update all dependencies and re-lock
+	$(UV) lock --upgrade
+	$(UV) sync --extra dev
+
+deps: deps\:install ## Alias for deps:install
+
+# --- Testing ---
+
+test: ## Run tests
+	$(UV) run pytest tests/ -v
+
+test\:cov: ## Run tests with coverage
+	$(UV) run pytest tests/ --cov=markers --cov-report=term-missing --cov-report=html
+
+# --- Linting & Formatting ---
+
+lint: ## Run linters (ruff check + format check)
+	$(UV) run ruff check src/ tests/
+	$(UV) run ruff format --check src/ tests/
+
+format: ## Auto-format code
+	$(UV) run ruff format src/ tests/
+	$(UV) run ruff check --fix src/ tests/
+
+# --- Type Checking ---
+
+typecheck: ## Run type checker
+	$(UV) run mypy src/markers/ --ignore-missing-imports
+
+# --- All Checks ---
+
+check: lint typecheck test ## Run all checks (lint, typecheck, test)
+
+# --- Build ---
+
+build: ## Build sdist and wheel
+	$(UV) build
+
+# --- Cleanup ---
+
+clean: ## Clean build artifacts
+	rm -rf dist/ build/ *.egg-info src/*.egg-info .tox .pytest_cache .mypy_cache .ruff_cache htmlcov .coverage coverage.xml
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

code_is_magic_markers-0.1.0/PKG-INFO

@@ -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