didactic 0.1.0__tar.gz

didactic-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# dev-only working notes, design drafts, scratch
+notes/
+
+# python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# virtualenvs
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# type-checkers / linters
+.mypy_cache/
+.ruff_cache/
+.pyright/
+
+# mkdocs build output
+site/
+
+# editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# os
+.DS_Store
+Thumbs.db

didactic-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: didactic
+Version: 0.1.0
+Summary: Pydantic-class API on top of panproto: GATs, lenses, and VCS.
+Project-URL: Homepage, https://github.com/panproto/didactic
+Project-URL: Repository, https://github.com/panproto/didactic
+Author-email: Aaron Steven White <aaronstevenwhite@gmail.com>
+License-Expression: MIT
+Keywords: gat,lenses,models,panproto,schema,validation
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: annotated-types>=0.7
+Requires-Dist: panproto>=0.43
+Description-Content-Type: text/markdown
+
+# didactic
+
+A typed-data library for Python that uses
+[panproto](https://github.com/panproto/panproto) as its substrate.
+Authoring is class-based and looks like Pydantic. Underneath, every
+Model corresponds to a panproto `Theory`, every value to a panproto
+`Schema`, and every transformation between Models to a panproto
+`Lens`.
+
+```python
+import didactic.api as dx
+
+
+class User(dx.Model):
+    """A user record."""
+
+    id: str
+    email: str
+    display_name: str = ""
+
+
+u = User(id="u1", email="a@b.c")
+u2 = u.with_(display_name="Alice")
+```
+
+This is the core distribution. Three sibling distributions
+(`didactic-pydantic`, `didactic-settings`, `didactic-fastapi`)
+contribute submodules under `didactic.<name>`.
+
+## Install
+
+didactic targets Python 3.14 and panproto 0.42+.
+
+```sh
+pip install didactic
+```
+
+## Documentation
+
+The full documentation site is at
+[https://panproto.dev/didactic/](https://panproto.dev/didactic/)
+and includes a tutorial, task-oriented guides, conceptual background,
+and per-symbol API reference. Source is in the workspace `docs/`
+directory.
+
+## License
+
+MIT.

didactic-0.1.0/README.md

@@ -0,0 +1,48 @@
+# didactic
+
+A typed-data library for Python that uses
+[panproto](https://github.com/panproto/panproto) as its substrate.
+Authoring is class-based and looks like Pydantic. Underneath, every
+Model corresponds to a panproto `Theory`, every value to a panproto
+`Schema`, and every transformation between Models to a panproto
+`Lens`.
+
+```python
+import didactic.api as dx
+
+
+class User(dx.Model):
+    """A user record."""
+
+    id: str
+    email: str
+    display_name: str = ""
+
+
+u = User(id="u1", email="a@b.c")
+u2 = u.with_(display_name="Alice")
+```
+
+This is the core distribution. Three sibling distributions
+(`didactic-pydantic`, `didactic-settings`, `didactic-fastapi`)
+contribute submodules under `didactic.<name>`.
+
+## Install
+
+didactic targets Python 3.14 and panproto 0.42+.
+
+```sh
+pip install didactic
+```
+
+## Documentation
+
+The full documentation site is at
+[https://panproto.dev/didactic/](https://panproto.dev/didactic/)
+and includes a tutorial, task-oriented guides, conceptual background,
+and per-symbol API reference. Source is in the workspace `docs/`
+directory.
+
+## License
+
+MIT.

didactic-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "didactic"
+version = "0.1.0"
+description = "Pydantic-class API on top of panproto: GATs, lenses, and VCS."
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+authors = [
+    { name = "Aaron Steven White", email = "aaronstevenwhite@gmail.com" },
+]
+keywords = ["schema", "models", "validation", "lenses", "gat", "panproto"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "panproto>=0.43",
+    "annotated-types>=0.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/panproto/didactic"
+Repository = "https://github.com/panproto/didactic"
+
+[project.scripts]
+didactic = "didactic.cli._cli:main"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/didactic"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/didactic"]

didactic-0.1.0/src/didactic/_self_describing.py

@@ -0,0 +1,206 @@
+"""Self-describing JSON via fingerprint URIs.
+
+A panproto-native form of self-describing data: an emitted JSON
+payload carries a ``$schema`` URI of the form
+``didactic://v1/<structural-fingerprint>``. A consumer that holds a
+registry of known Theories (by fingerprint) can validate an unknown
+payload by looking the URI up.
+
+This is something Pydantic structurally cannot do, because Pydantic
+has no content-addressed schema identity. didactic's structural
+fingerprint already gives every Model a stable address; this module
+just plumbs it through to JSON.
+
+Examples
+--------
+>>> import didactic.api as dx
+>>>
+>>> class User(dx.Model):
+...     id: str
+...     email: str
+>>>
+>>> u = User(id="u1", email="ada@example.org")
+>>> payload = dx.embed_schema_uri(u)
+>>> payload["$schema"].startswith("didactic://v1/")
+True
+
+See Also
+--------
+didactic.migrations._fingerprint.structural_fingerprint : the underlying address.
+"""
+
+# Cross-translation between ``FieldValue`` and ``JsonValue`` shapes
+# in the schema-URI registry layer.
+# Tracked in panproto/didactic#1.
+# pyright: reportArgumentType=false, reportReturnType=false
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from didactic.models._model import Model
+    from didactic.types._typing import JsonObject
+
+#: URI scheme prefix didactic uses for self-describing payloads.
+URI_PREFIX = "didactic://v1/"
+
+
+def schema_uri(cls: type[Model]) -> str:
+    """Return the canonical schema URI for a Model class.
+
+    Parameters
+    ----------
+    cls
+        A [Model][didactic.api.Model] subclass.
+
+    Returns
+    -------
+    str
+        ``"didactic://v1/<fingerprint>"`` where ``<fingerprint>`` is
+        the Model's structural fingerprint.
+    """
+    from didactic.migrations._fingerprint import structural_fingerprint  # noqa: PLC0415
+    from didactic.theory._theory import build_theory_spec  # noqa: PLC0415
+
+    return f"{URI_PREFIX}{structural_fingerprint(build_theory_spec(cls))}"
+
+
+def embed_schema_uri(instance: Model) -> JsonObject:
+    """Return ``instance.model_dump()`` with a ``$schema`` URI prepended.
+
+    Parameters
+    ----------
+    instance
+        A Model instance.
+
+    Returns
+    -------
+    dict
+        The dump dict, with ``"$schema"`` set to the Model's
+        canonical URI as the first key.
+
+    Notes
+    -----
+    A consumer that knows how to resolve ``didactic://v1/<fp>`` URIs
+    can fetch the Theory by fingerprint and validate the payload
+    without knowing the original Python class.
+    """
+    payload = instance.model_dump()
+    return {"$schema": schema_uri(type(instance)), **payload}
+
+
+class FingerprintRegistry:
+    """An in-memory mapping of structural fingerprint to Model class.
+
+    Use as the lookup side of a self-describing JSON pipeline:
+    register every Model your application understands, then
+    [validate_with_uri_lookup][didactic.api.validate_with_uri_lookup]
+    can resolve an unknown payload's ``$schema`` URI back to a class.
+
+    Examples
+    --------
+    >>> import didactic.api as dx
+    >>> class User(dx.Model):
+    ...     id: str
+    >>>
+    >>> reg = dx.FingerprintRegistry()
+    >>> reg.register(User)
+    >>>
+    >>> u = User(id="u1")
+    >>> payload = dx.embed_schema_uri(u)
+    >>> back = dx.validate_with_uri_lookup(payload, reg)
+    >>> back == u
+    True
+    """
+
+    __slots__ = ("_by_fingerprint",)
+
+    def __init__(self) -> None:
+        self._by_fingerprint: dict[str, type[Model]] = {}
+
+    def register[M: Model](self, cls: type[M]) -> type[M]:
+        """Register ``cls`` under its structural fingerprint."""
+        from didactic.migrations._fingerprint import (  # noqa: PLC0415
+            structural_fingerprint,
+        )
+        from didactic.theory._theory import build_theory_spec  # noqa: PLC0415
+
+        fp = structural_fingerprint(build_theory_spec(cls))
+        self._by_fingerprint[fp] = cls
+        return cls
+
+    def lookup(self, uri: str) -> type[Model] | None:
+        """Resolve a ``didactic://v1/<fp>`` URI to a registered class."""
+        if not uri.startswith(URI_PREFIX):
+            return None
+        fp = uri[len(URI_PREFIX) :]
+        return self._by_fingerprint.get(fp)
+
+    def __contains__(self, cls_or_uri: object) -> bool:
+        if isinstance(cls_or_uri, str):
+            return self.lookup(cls_or_uri) is not None
+        if isinstance(cls_or_uri, type):
+            from didactic.migrations._fingerprint import (  # noqa: PLC0415
+                structural_fingerprint,
+            )
+            from didactic.theory._theory import build_theory_spec  # noqa: PLC0415
+
+            return (
+                structural_fingerprint(build_theory_spec(cls_or_uri))
+                in self._by_fingerprint
+            )
+        return False
+
+    def __len__(self) -> int:
+        return len(self._by_fingerprint)
+
+
+def validate_with_uri_lookup(
+    payload: JsonObject,
+    registry: FingerprintRegistry,
+) -> Model:
+    """Validate ``payload`` against the Model named by its ``$schema`` URI.
+
+    Parameters
+    ----------
+    payload
+        A dict that includes a ``$schema`` key.
+    registry
+        A [FingerprintRegistry][didactic.api.FingerprintRegistry] mapping
+        URIs to Model classes.
+
+    Returns
+    -------
+    Model
+        A validated Model instance whose class came from the
+        registry.
+
+    Raises
+    ------
+    LookupError
+        If the URI is not registered.
+    KeyError
+        If the payload has no ``$schema`` key.
+    """
+    if "$schema" not in payload:
+        msg = "validate_with_uri_lookup: payload has no $schema key"
+        raise KeyError(msg)
+
+    uri = payload["$schema"]
+    cls = registry.lookup(uri)
+    if cls is None:
+        msg = f"validate_with_uri_lookup: no registered model for URI {uri!r}"
+        raise LookupError(msg)
+
+    body = {k: v for k, v in payload.items() if k != "$schema"}
+    return cls.model_validate(body)
+
+
+__all__ = [
+    "URI_PREFIX",
+    "FingerprintRegistry",
+    "embed_schema_uri",
+    "schema_uri",
+    "validate_with_uri_lookup",
+]

didactic-0.1.0/src/didactic/api.py

@@ -0,0 +1,126 @@
+"""Aggregator module for the didactic API.
+
+`didactic` lets you author class-based, declarative data models the way
+[Pydantic][pydantic] does, while the underlying values are
+[panproto][panproto] [Theory][panproto.Theory] and
+[Schema][panproto.Schema] instances rather than ad hoc Python objects with
+bolt-on validation. The selling point is everything you get *for free*
+once your data is panproto-native: lenses, dependent optics, theory
+colimits, schema migrations as data, vertex-level VCS, and cross-language
+semantic export.
+
+[pydantic]: https://docs.pydantic.dev/
+[panproto]: https://github.com/panproto/panproto
+
+Notes
+-----
+The conventional alias for this module is ``dx``::
+
+    import didactic.api as dx
+
+
+    class User(dx.Model):
+        id: str
+        email: str
+
+The ``didactic`` namespace itself is a PEP 420 implicit namespace
+package; the four distributions (``didactic`` / ``didactic-pydantic`` /
+``didactic-settings`` / ``didactic-fastapi``) each contribute a
+sub-package (``didactic.api``, ``didactic.pydantic``,
+``didactic.settings``, ``didactic.fastapi``) without an
+``__init__.py`` at the namespace root. This lets static type checkers
+resolve cross-distribution imports without a ``pkgutil`` workaround.
+"""
+
+from didactic import codegen
+from didactic._self_describing import (
+    FingerprintRegistry,
+    embed_schema_uri,
+    schema_uri,
+    validate_with_uri_lookup,
+)
+from didactic.axioms._axioms import Axiom, axiom
+from didactic.fields._computed import computed
+from didactic.fields._derived import derived
+from didactic.fields._fields import Field, FieldSpec, field
+from didactic.fields._refs import Backref, Embed, Ref
+from didactic.fields._unions import TaggedUnion
+from didactic.fields._validators import (
+    ValidationError,
+    ValidationErrorEntry,
+    validates,
+)
+from didactic.lenses import _testing as testing
+from didactic.lenses._dependent_lens import DependentLens
+from didactic.lenses._lens import Iso, Lens, Mapping, lens
+from didactic.migrations._diff import classify_change, diff, is_breaking_change
+from didactic.migrations._migrations import (
+    load_registry,
+    migrate,
+    register_migration,
+    save_registry,
+)
+from didactic.migrations._synthesis import SynthesisResult, synthesise_migration
+from didactic.models._config import DEFAULT_CONFIG, ExtraPolicy, ModelConfig
+from didactic.models._model import BaseModel, Model
+from didactic.models._root import RootModel, TypeAdapter
+from didactic.types import _types_lib as types
+from didactic.vcs._backref import ModelPool, resolve_backrefs
+from didactic.vcs._repo import Repository
+
+__version__ = "0.1.0"
+
+#: Conventional namespace for lens utilities (`dx.lens.identity(...)`,
+#: `dx.lens.Lens`, etc.). The ``lens`` name doubles as a decorator
+#: (``@dx.lens(A, B)``) and as a module-style namespace. The attributes
+#: are bound by ``_LensNamespace.__init__`` in :mod:`didactic.lenses._lens`.
+
+
+__all__ = [
+    "DEFAULT_CONFIG",
+    "Axiom",
+    "Backref",
+    "BaseModel",
+    "DependentLens",
+    "Embed",
+    "ExtraPolicy",
+    "Field",
+    "FieldSpec",
+    "FingerprintRegistry",
+    "Iso",
+    "Lens",
+    "Mapping",
+    "Model",
+    "ModelConfig",
+    "ModelPool",
+    "Ref",
+    "Repository",
+    "RootModel",
+    "SynthesisResult",
+    "TaggedUnion",
+    "TypeAdapter",
+    "ValidationError",
+    "ValidationErrorEntry",
+    "__version__",
+    "axiom",
+    "classify_change",
+    "codegen",
+    "computed",
+    "derived",
+    "diff",
+    "embed_schema_uri",
+    "field",
+    "is_breaking_change",
+    "lens",
+    "load_registry",
+    "migrate",
+    "register_migration",
+    "resolve_backrefs",
+    "save_registry",
+    "schema_uri",
+    "synthesise_migration",
+    "testing",
+    "types",
+    "validate_with_uri_lookup",
+    "validates",
+]

didactic-0.1.0/src/didactic/axioms/__init__.py

@@ -0,0 +1,11 @@
+"""Class-level axioms and their construction-time enforcement."""
+
+from didactic.axioms._axiom_enforcement import check_class_axioms
+from didactic.axioms._axioms import Axiom, axiom, collect_class_axioms
+
+__all__ = [
+    "Axiom",
+    "axiom",
+    "check_class_axioms",
+    "collect_class_axioms",
+]