pydantic-prism 0.1.0__tar.gz

pydantic_prism-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilja Orlovs
+
+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.

pydantic_prism-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: pydantic-prism
+Version: 0.1.0
+Summary: One canonical pydantic model, many scoped projections — with a relationship graph that survives them.
+Keywords: pydantic,schema,projection,scopes,dto,serialization,validation,json-schema,fastapi,data-classification,pii,code-generation,type-safety
+Author-Email: Ilja Orlovs <IljaOrlovs@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Framework :: Pydantic
+Classifier: Framework :: Pydantic :: 2
+Classifier: Framework :: FastAPI
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://github.com/release-art/pydantic-prism
+Project-URL: Documentation, https://github.com/release-art/pydantic-prism/blob/main/docs/README.md
+Project-URL: Repository, https://github.com/release-art/pydantic-prism
+Project-URL: Changelog, https://github.com/release-art/pydantic-prism/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/release-art/pydantic-prism/issues
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.12
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.15.1; extra == "dev"
+Requires-Dist: ruff>=0.15.16; extra == "dev"
+Requires-Dist: pyright>=1.1.410; extra == "dev"
+Requires-Dist: fastapi>=0.115; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: pytest-local-badge>=1.3.0; extra == "dev"
+Requires-Dist: sqlmodel>=0.0.22; extra == "dev"
+Requires-Dist: sqlalchemy>=2.0; extra == "dev"
+Description-Content-Type: text/markdown
+
+# pydantic-prism
+
+![Tests](https://raw.githubusercontent.com/release-art/pydantic-prism/main/docs/badges/tests.svg)
+![Coverage](https://raw.githubusercontent.com/release-art/pydantic-prism/main/docs/badges/coverage.svg)
+![Skipped](https://raw.githubusercontent.com/release-art/pydantic-prism/main/docs/badges/skipped.svg)
+![XFailed](https://raw.githubusercontent.com/release-art/pydantic-prism/main/docs/badges/xfailed.svg)
+![Warnings](https://raw.githubusercontent.com/release-art/pydantic-prism/main/docs/badges/warnings.svg)
+![Duration](https://raw.githubusercontent.com/release-art/pydantic-prism/main/docs/badges/duration.svg)
+![Last run](https://raw.githubusercontent.com/release-art/pydantic-prism/main/docs/badges/last-run.svg)
+
+Project one canonical pydantic model along any axis — and keep the
+relationship graph that survives the projection.
+
+Tag a single model's fields with named **scopes**; derive real
+`pydantic.BaseModel` subclasses per scope (API response, storage row, LLM
+tool input, audit log) with working validation, serialization, and JSON
+schema. Declare FK-style **references** in the same metadata and introspect
+them through `__refs__` — the graph survives every projection. The
+projection half has prior art; [combining it with an introspectable
+relationship graph](docs/explanation/vs-prior-art.md) does not.
+
+## 30 seconds
+
+```python
+from typing import Annotated
+from uuid import UUID
+
+from pydantic_prism import Scope, ScopedModel, scoped
+
+
+class Public(Scope): ...
+class Internal(Public): ...   # Internal sees everything Public sees
+class Storage(Internal): ...  # Storage sees everything Internal sees
+
+
+class User(ScopedModel):
+    id: Annotated[UUID, scoped(Public)]
+    email: Annotated[str, scoped(Internal)]
+    password_hash: Annotated[str, scoped(Storage)]
+    display_name: Annotated[str, scoped(Public)]
+
+
+UserPublic = User.scope(Public)      # fields: id, display_name
+UserInternal = User.scope(Internal)  # fields: id, email, display_name
+UserStorage = User.scope(Storage)    # all four fields
+```
+
+`UserPublic` is a real, cached `BaseModel` subclass named `"UserPublic"` —
+`User.scope(Public) is User.scope(Public)`, so FastAPI response models and
+OpenAPI component schemas stay stable.
+
+Scopes are classes; inheritance forms the scope graph, so the membership
+rule is one line: a field tagged `T` is in projection `S` iff
+`issubclass(S, T)`. Untagged fields belong to no scope and can never leak
+into a projection. Scopes compose with set operators (`| & - ~`), both in
+field tags and at the call site.
+
+## Why not hand-write `UserIn` / `UserOut`?
+
+Parallel classes drift from the canonical, lose constraints, and have no
+idea your models reference each other. Prism derives every face from one
+source of truth and keeps the references coherent across all of them.
+See [projections, not inheritance](docs/explanation/projections-not-inheritance.md).
+
+## Install
+
+```sh
+pip install pydantic-prism        # pydantic >= 2.12, Python >= 3.12
+```
+
+## Documentation
+
+The docs follow the [Diátaxis](https://diataxis.fr) framework — start where
+your need fits:
+
+- **[Documentation home](docs/README.md)** — the full table of contents.
+- **[Tutorial: your first scoped model](docs/tutorial/first-scoped-model.md)** —
+  one hand-held lesson, one model to two projections.
+- **[How-to guides](docs/how-to/README.md)** — short recipes: redact PII,
+  trace data flow, PATCH models, FastAPI, ORM bridge, editor stubs, diagrams.
+- **[Reference](docs/reference/README.md)** — the [API](docs/reference/api.md),
+  the [`prism` CLI](docs/reference/cli.md), and the [error table](docs/reference/errors.md).
+- **[Explanation](docs/explanation/README.md)** — the scope algebra, why
+  projections aren't inheritance, what `ref()` does and does not model.
+
+[**ROADMAP.md**](ROADMAP.md) lists what is shipped, planned, and deliberately
+out of scope.
+
+## Develop
+
+```sh
+pdm install -G dev
+bin/test.sh                       # pytest with coverage (100% gate)
+bin/autoformat.sh                 # ruff format + ruff check --fix
+pdm run pyright                   # strict, src/
+```
+
+MIT licensed. Built on the public pydantic API only — no `pydantic._internal`.

pydantic_prism-0.1.0/README.md

@@ -0,0 +1,98 @@
+# pydantic-prism
+
+![Tests](https://raw.githubusercontent.com/release-art/pydantic-prism/main/docs/badges/tests.svg)
+![Coverage](https://raw.githubusercontent.com/release-art/pydantic-prism/main/docs/badges/coverage.svg)
+![Skipped](https://raw.githubusercontent.com/release-art/pydantic-prism/main/docs/badges/skipped.svg)
+![XFailed](https://raw.githubusercontent.com/release-art/pydantic-prism/main/docs/badges/xfailed.svg)
+![Warnings](https://raw.githubusercontent.com/release-art/pydantic-prism/main/docs/badges/warnings.svg)
+![Duration](https://raw.githubusercontent.com/release-art/pydantic-prism/main/docs/badges/duration.svg)
+![Last run](https://raw.githubusercontent.com/release-art/pydantic-prism/main/docs/badges/last-run.svg)
+
+Project one canonical pydantic model along any axis — and keep the
+relationship graph that survives the projection.
+
+Tag a single model's fields with named **scopes**; derive real
+`pydantic.BaseModel` subclasses per scope (API response, storage row, LLM
+tool input, audit log) with working validation, serialization, and JSON
+schema. Declare FK-style **references** in the same metadata and introspect
+them through `__refs__` — the graph survives every projection. The
+projection half has prior art; [combining it with an introspectable
+relationship graph](docs/explanation/vs-prior-art.md) does not.
+
+## 30 seconds
+
+```python
+from typing import Annotated
+from uuid import UUID
+
+from pydantic_prism import Scope, ScopedModel, scoped
+
+
+class Public(Scope): ...
+class Internal(Public): ...   # Internal sees everything Public sees
+class Storage(Internal): ...  # Storage sees everything Internal sees
+
+
+class User(ScopedModel):
+    id: Annotated[UUID, scoped(Public)]
+    email: Annotated[str, scoped(Internal)]
+    password_hash: Annotated[str, scoped(Storage)]
+    display_name: Annotated[str, scoped(Public)]
+
+
+UserPublic = User.scope(Public)      # fields: id, display_name
+UserInternal = User.scope(Internal)  # fields: id, email, display_name
+UserStorage = User.scope(Storage)    # all four fields
+```
+
+`UserPublic` is a real, cached `BaseModel` subclass named `"UserPublic"` —
+`User.scope(Public) is User.scope(Public)`, so FastAPI response models and
+OpenAPI component schemas stay stable.
+
+Scopes are classes; inheritance forms the scope graph, so the membership
+rule is one line: a field tagged `T` is in projection `S` iff
+`issubclass(S, T)`. Untagged fields belong to no scope and can never leak
+into a projection. Scopes compose with set operators (`| & - ~`), both in
+field tags and at the call site.
+
+## Why not hand-write `UserIn` / `UserOut`?
+
+Parallel classes drift from the canonical, lose constraints, and have no
+idea your models reference each other. Prism derives every face from one
+source of truth and keeps the references coherent across all of them.
+See [projections, not inheritance](docs/explanation/projections-not-inheritance.md).
+
+## Install
+
+```sh
+pip install pydantic-prism        # pydantic >= 2.12, Python >= 3.12
+```
+
+## Documentation
+
+The docs follow the [Diátaxis](https://diataxis.fr) framework — start where
+your need fits:
+
+- **[Documentation home](docs/README.md)** — the full table of contents.
+- **[Tutorial: your first scoped model](docs/tutorial/first-scoped-model.md)** —
+  one hand-held lesson, one model to two projections.
+- **[How-to guides](docs/how-to/README.md)** — short recipes: redact PII,
+  trace data flow, PATCH models, FastAPI, ORM bridge, editor stubs, diagrams.
+- **[Reference](docs/reference/README.md)** — the [API](docs/reference/api.md),
+  the [`prism` CLI](docs/reference/cli.md), and the [error table](docs/reference/errors.md).
+- **[Explanation](docs/explanation/README.md)** — the scope algebra, why
+  projections aren't inheritance, what `ref()` does and does not model.
+
+[**ROADMAP.md**](ROADMAP.md) lists what is shipped, planned, and deliberately
+out of scope.
+
+## Develop
+
+```sh
+pdm install -G dev
+bin/test.sh                       # pytest with coverage (100% gate)
+bin/autoformat.sh                 # ruff format + ruff check --fix
+pdm run pyright                   # strict, src/
+```
+
+MIT licensed. Built on the public pydantic API only — no `pydantic._internal`.

pydantic_prism-0.1.0/pyproject.toml

@@ -0,0 +1,151 @@
+[project]
+name = "pydantic-prism"
+version = "0.1.0"
+description = "One canonical pydantic model, many scoped projections — with a relationship graph that survives them."
+authors = [
+    { name = "Ilja Orlovs", email = "IljaOrlovs@users.noreply.github.com" },
+]
+dependencies = [
+    "pydantic>=2.12",
+]
+requires-python = ">=3.12"
+readme = "README.md"
+license = "MIT"
+keywords = [
+    "pydantic",
+    "schema",
+    "projection",
+    "scopes",
+    "dto",
+    "serialization",
+    "validation",
+    "json-schema",
+    "fastapi",
+    "data-classification",
+    "pii",
+    "code-generation",
+    "type-safety",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Code Generators",
+    "Framework :: Pydantic",
+    "Framework :: Pydantic :: 2",
+    "Framework :: FastAPI",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/release-art/pydantic-prism"
+Documentation = "https://github.com/release-art/pydantic-prism/blob/main/docs/README.md"
+Repository = "https://github.com/release-art/pydantic-prism"
+Changelog = "https://github.com/release-art/pydantic-prism/blob/main/CHANGELOG.md"
+Issues = "https://github.com/release-art/pydantic-prism/issues"
+
+[project.scripts]
+prism = "pydantic_prism._internal.codegen:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-cov>=6.0",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.15.16",
+    "pyright>=1.1.410",
+    "fastapi>=0.115",
+    "httpx>=0.27",
+    "pytest-local-badge>=1.3.0",
+    "sqlmodel>=0.0.22",
+    "sqlalchemy>=2.0",
+]
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm]
+distribution = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "A",
+    "B",
+    "C",
+    "E",
+    "F",
+    "I",
+    "W",
+    "N",
+    "C4",
+    "T20",
+    "PTH",
+]
+ignore = [
+    "N802",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = [
+    "F401",
+    "E402",
+]
+"src/pydantic_prism/_internal/codegen/cli.py" = [
+    "T201",
+]
+"bin/*.py" = [
+    "T201",
+]
+"tests/**" = [
+    "N806",
+]
+"examples/**" = [
+    "N806",
+    "T201",
+]
+
+[tool.ruff.lint.isort]
+order-by-type = true
+known-first-party = [
+    "pydantic_prism",
+]
+forced-separate = [
+    "tests",
+]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.pyright]
+include = [
+    "src",
+]
+typeCheckingMode = "strict"
+pythonVersion = "3.12"
+venvPath = "."
+venv = ".venv"
+
+[tool.coverage.report]
+exclude_also = [
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+]
+
+[tool.pytest.ini_options]
+minversion = "8.4"
+testpaths = [
+    "tests",
+]
+addopts = "    --cov --no-cov-on-fail\n    -v -l --color=yes\n    --local-badge-output-dir docs/badges/\n    --cov-fail-under=100\n    --local-badge-package=pydantic_prism\n"

pydantic_prism-0.1.0/src/pydantic_prism/__init__.py

@@ -0,0 +1,73 @@
+"""pydantic-prism: one canonical pydantic model, many scoped projections.
+
+Tag fields on a single model with named scopes via ``Annotated`` metadata,
+derive real pydantic model subclasses per scope, and keep FK-style
+relationships introspectable across projections.
+"""
+
+from pydantic.experimental.missing_sentinel import MISSING
+
+from ._internal.diagram import Diagram, projection_diagram, scope_diagram
+from ._internal.flow import (
+    ClassifiedField,
+    FlowEdge,
+    FlowNode,
+    FlowReport,
+    build_flow_report,
+)
+from ._internal.markers import BackRef, Ref, Scoped, backref, ref, scoped
+from ._internal.model import Projection, ScopedModel
+from ._internal.refs import (
+    BackRefInfo,
+    EmbeddedRefInfo,
+    IdRefInfo,
+    RefGraph,
+    RefInfo,
+    RefShape,
+)
+from ._internal.scopes import Classification, Scope, ScopeExpr
+from ._internal.validators import scoped_validator
+from .errors import (
+    EmptyProjectionError,
+    PrismError,
+    ProjectionBaseError,
+    ProjectionNameError,
+    RefResolutionError,
+    StaleProjectionStubError,
+)
+
+__all__ = [
+    "MISSING",
+    "BackRef",
+    "BackRefInfo",
+    "Classification",
+    "ClassifiedField",
+    "Diagram",
+    "EmbeddedRefInfo",
+    "EmptyProjectionError",
+    "FlowEdge",
+    "FlowNode",
+    "FlowReport",
+    "IdRefInfo",
+    "PrismError",
+    "Projection",
+    "ProjectionBaseError",
+    "ProjectionNameError",
+    "Ref",
+    "RefGraph",
+    "RefInfo",
+    "RefResolutionError",
+    "RefShape",
+    "Scope",
+    "ScopeExpr",
+    "Scoped",
+    "ScopedModel",
+    "StaleProjectionStubError",
+    "backref",
+    "build_flow_report",
+    "projection_diagram",
+    "ref",
+    "scope_diagram",
+    "scoped",
+    "scoped_validator",
+]

pydantic_prism-0.1.0/src/pydantic_prism/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m pydantic_prism`` — equivalent to the ``prism`` console script."""
+
+from ._internal.codegen import main
+
+raise SystemExit(main())

pydantic_prism-0.1.0/src/pydantic_prism/_internal/__init__.py

@@ -0,0 +1,7 @@
+"""Private implementation package for pydantic-prism.
+
+Everything here is internal: the public API is re-exported from
+:mod:`pydantic_prism`'s top-level ``__init__``. Import paths under
+``pydantic_prism._internal`` are not part of the supported surface and may change
+between releases without notice.
+"""

pydantic_prism-0.1.0/src/pydantic_prism/_internal/codegen/__init__.py

@@ -0,0 +1,44 @@
+"""``prism gen`` / ``prism check`` — generate static-typing stubs for projections.
+
+Static type checkers (pyright/Pylance — and thus VSCode — plus mypy) cannot see
+the fields of ``Model.scope(...)``: scope membership lives in ``Annotated``
+metadata and the selection runs the scope algebra at runtime. Pyright has no
+third-party plugin API, so the only *universal* fix is ordinary type
+declarations every tool already reads. This package generates them.
+
+For each projection it emits, into one module::
+
+    if TYPE_CHECKING:
+        class ScreenshotRef(Projection):     # the checker reads this
+            id: UUID
+            timestamp: datetime
+    else:
+        ScreenshotRef = Screenshot.scope(Ref)   # the genuine cached projection
+
+    assert_fresh(ScreenshotRef, "<signature>")   # startup drift guard
+
+Layout: :mod:`config` (load `[tool.pydantic-prism]`), :mod:`discover` (find
+the projection workset), :mod:`render` (annotations/scopes/defaults → source),
+:mod:`generate` (assemble the stub + README), :mod:`cli` (the ``prism``
+command). Names re-exported here (with ``as`` aliases) keep the
+``pydantic_prism._internal.codegen.X`` import paths stable.
+"""
+
+from .cli import main as main
+from .config import CodegenError as CodegenError
+from .config import Config as Config
+from .config import ProjectionSpec as ProjectionSpec
+from .config import load_config as load_config
+from .discover import _projections_in as _projections_in
+from .discover import _reject_name_clashes as _reject_name_clashes
+from .generate import generate as generate
+from .generate import generate_readme as generate_readme
+from .render import _field_suffix as _field_suffix
+from .render import _import_lines as _import_lines
+from .render import _Imports as _Imports
+from .render import _render_annotation as _render_annotation
+from .render import _render_bare as _render_bare
+from .render import _render_literal as _render_literal
+from .render import _render_scope_expr as _render_scope_expr
+
+__all__ = ["CodegenError", "Config", "ProjectionSpec", "generate", "main"]