protodantic-py 0.1.0__tar.gz

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

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [master, development]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest tests/ -v

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

@@ -0,0 +1,66 @@
+name: Release
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      unpublished: ${{ steps.version.outputs.unpublished }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.11"
+
+      - name: Run tests
+        run: |
+          uv sync
+          uv run pytest tests/
+
+      - name: Check version against PyPI
+        id: version
+        run: |
+          VERSION=$(uv run python -c "from protodantic._version import __version__; print(__version__)")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://pypi.org/pypi/protodantic-py/$VERSION/json")
+          if [ "$STATUS" = "404" ]; then
+            echo "unpublished=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "unpublished=false" >> "$GITHUB_OUTPUT"
+          fi
+          echo "version=$VERSION pypi_status=$STATUS"
+
+      - name: Build distributions
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    # publish only when the version in _version.py is not on PyPI yet:
+    # merging to master releases iff the PR bumped the version
+    if: needs.build.outputs.unpublished == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

protodantic_py-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Agents
+.agent/
+.codex/
+.claude/
+
+# IDE
+.idea/
+
+# Playgrounds
+playground.py
+
+# Env
+*.env
+
+# Python
+**/__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+dist/
+build/
+*.egg-info/
+
+# IDE (editors beyond .idea)
+.vscode/

protodantic_py-0.1.0/AGENTS.md

@@ -0,0 +1,57 @@
+# protodantic — agent guide
+
+Bidirectional bridge between Protocol Buffers and Pydantic. Distribution name `protodantic-py`, import name `protodantic`. proto3 only, by design. Read this before changing anything: the project runs on a small set of hard conventions, and code review enforces them strictly — working code that violates them gets rejected.
+
+## Architecture
+
+```
+src/protodantic/
+  compiler.py   .proto files -> serialized FileDescriptorSet bytes (protoc via grpcio-tools)
+  codegen.py    fdset bytes -> python module source (_ModuleGenerator class)
+  runtime.py    ProtoModel base: conversion both ways, registries, OpenEnum, field-name escaping
+  types.py      range-validated ints, Struct/Value/ListValue aliases, NULL sentinel
+  cli.py        click group; `generate` subcommand (future verbs must be additive)
+  _version.py   single version source (hatch + generated-code stamps read it)
+```
+
+The **fdset-bytes boundary is load-bearing**: codegen takes `FileDescriptorSet` bytes and nothing else. Future input sources (installed `_pb2` packages via descriptor reflection, planned for 0.2) must produce those bytes and feed the same codegen. Do not add codegen inputs that bypass it.
+
+## Philosophy (non-negotiable)
+
+1. **The test suite is the specification.** Every supported behavior exists as a use-case test with a "USE CASE" style docstring. Workflow is red/green: write the failing spec test first, run it to confirm it fails *for the intended reason*, then implement, then confirm green. A red test in the suite is an accepted roadmap item, not a broken build.
+2. **Fail loudly; no magic.** proto2 input → `NotImplementedError`. Name collisions (flattened types, escaped enum members) → `ValueError` naming the culprits and telling the user what to rename. Wrong message type in `from_proto` → `TypeError`. Unknown `Any` type URL → `LookupError`. Unknown field names at construction → rejected (`extra="forbid"`). Never emit silently-wrong data or auto-disambiguate with positional suffixes. The only automatic renaming allowed is the deterministic trailing-underscore escape (`class` → `class_`) — a pure function of the name alone, never dependent on what else exists in the schema.
+3. **Validation is the product.** Models validate at construction *and* on assignment, and assignment is atomic: a rejected mutation must leave the model exactly as it was. If you add a validator, prove atomicity in a test.
+4. **Scope decisions belong to the maintainer.** If "should we support X?" has no clear answer in the tests or this file, raise it as a question before implementing. Precedents: proto2 was consciously dropped; `Any` consciously maps to `typing.Any` with registry pack/unpack.
+
+## Semantics ledger (do not regress; each line is pinned by tests)
+
+- `None` means *unset on the wire*; explicit zero values keep their presence bit. `protodantic.NULL` (identity-checked singleton) means explicit JSON null in `Value` fields.
+- proto3 enums are open: unknown wire values become `OpenEnum` pseudo-members, never errors, and re-serialize byte-identically.
+- Unknown fields are dropped when a model re-serializes (the model is the source of truth). Naive datetimes are interpreted as UTC.
+- Generated modules are deterministic (byte-identical output for the same input — they're meant to be committed and diffed), version-stamped, and depend only on `protodantic` + pydantic + protobuf at runtime (never `grpc_tools`). All imports in generated code are underscore-aliased (`import protodantic as _pd`, `import typing as _typing`, ...) so user message names (`message Any`, `message list`) cannot shadow them.
+- Nested-message resolution is scoped per descriptor pool (per generated module), so duplicate generated modules coexist in one process. `model_for()` is global, last-import-wins. Plain subclasses of generated models do **not** register; re-declaring `__proto_full_name__` in the subclass body is the explicit opt-in.
+- `_pb2` interop is a public contract: `from_proto()` accepts classic protoc-generated instances; `to_proto_bytes()` output parses into `_pb2` classes.
+
+## Code conventions
+
+- **Keyword-only parameters for all internal functions** (`def _fill_map(*, target, fd, value)`). Positional args are reserved for framework-fixed signatures (pydantic serializer callbacks) and stdlib-stable idioms — if a signature could ever grow a flag, it takes kwargs.
+- **No nested function definitions.** State + recursion live in classes (see `_ModuleGenerator`); pure helpers go to module level.
+- **Relative imports** inside the package. Generated code imports only the top-level `protodantic`.
+- **No trivial docstrings or comments.** Comment only the non-obvious "why" (e.g. why registration checks `cls.__dict__`). Public functions get short contract docstrings.
+- Magic strings for well-known types are forbidden — derive full names from the shipped descriptors (`timestamp_pb2.Timestamp.DESCRIPTOR.full_name`).
+- CLI output goes through click (`click.echo`, `click.ClickException`), never bare `print`.
+
+## Workflow
+
+- uv-managed: `uv sync`, then `uv run pytest tests/ -q`.
+- Python floor is 3.11. When touching `runtime.py`/`codegen.py`, run both: `uv run pytest tests/` and `uv run --python 3.11 --isolated pytest tests/`. CI runs ubuntu+windows × 3.11/3.12/3.13; all six must be green.
+- Releases happen on merge to `master`: the workflow publishes to PyPI iff `_version.py` holds a version not yet published. A releasing PR bumps `_version.py` **and** moves `CHANGELOG.md` `[Unreleased]` entries under the new version heading, atomically.
+- Update `CHANGELOG.md` `[Unreleased]` for any user-facing change (Keep a Changelog format).
+- Never commit generated artifacts, secrets, or machine-local paths. Test protos live in `tests/protos/`; temporary schemas belong in `tmp_path`.
+
+## Roadmap context (shapes what "don't block the future" means)
+
+- **0.1.0 (current)** — greenfield: `.proto` → pydantic with lossless bidirectional round-trips.
+- **0.2.0 — brownfield**: reverse schema codegen (pydantic models → `.proto`), generating from installed `_pb2` packages by descriptor reflection, `to_proto(into=TheirPb2Class)`. Weigh brownfield adoption at least as high as greenfield polish.
+- **0.3.0 — performance**: benchmark suite first (vs `json.loads`+pydantic, raw `_pb2`, betterproto) — **benchmarks before perf claims** — then cached field plans and trusted-construction fast paths. The conversion internals are deliberately unconstrained by public API; keep it that way.
+- gRPC service stubs are permanently out of scope: protodantic is a message layer.

protodantic_py-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are 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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-03
+
+Initial release: the greenfield drop.
+
+### Added
+
+- `protodantic generate` CLI and `compile_fdset()`/`generate_source()` API: compile `.proto` files (proto3) into pydantic v2 models with embedded descriptors — no `_pb2.py` files needed.
+- Lossless bidirectional round-trips on every generated model: `to_proto()`, `to_proto_bytes()`, `to_proto_json()`, `from_proto()`, `from_proto_bytes()`, `from_proto_json()` — the wire output is canonical protobuf, parseable by any runtime in any language.
+- Interop with classic protoc-generated `_pb2` classes: `from_proto()` accepts their instances directly.
+- Validation at the boundary: proto integer range constraints, oneof mutual exclusion (construction *and* mutation, atomically), `extra="forbid"`, all overridable via standard pydantic config.
+- Presence semantics: `None` ⇄ unset for `optional` fields, oneof members, and singular messages; explicit zero values keep their presence bit.
+- Open enums (`OpenEnum`): unknown wire values are preserved as pseudo-members instead of raising, matching proto3 semantics.
+- Well-known types: `Timestamp` ⇄ `datetime` (UTC), `Duration` ⇄ `timedelta`, wrappers ⇄ `T | None`, `Struct`/`Value`/`ListValue` ⇄ plain python data with the `protodantic.NULL` sentinel for explicit JSON null, `Any` ⇄ any generated model via registry-based pack/unpack.
+- Field-name hazard handling: python keywords and pydantic-reserved names get a trailing underscore with the proto name as populate alias; generated imports are shadow-proof against user message names.
+- `model_for("pkg.Message")` lookup; duplicate generated modules coexist safely (nested resolution is scoped per generated module).
+- Fail-loud guarantees: proto2 input, flattened-name collisions, unrelated message types in `from_proto()`, and unknown `Any` type URLs all raise clear errors — no silent wrong data.
+
+### Notes
+
+- Distribution name is `protodantic-py`; the import name is `protodantic`.
+- Requires Python >= 3.11. proto3 only, by design. gRPC service stubs are out of scope.

protodantic_py-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

protodantic_py-0.1.0/LICENSE

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

protodantic_py-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: protodantic-py
+Version: 0.1.0
+Summary: Bidirectional bridge between Protocol Buffers and Pydantic: generate pydantic models from .proto files with lossless round-trips to proto messages and wire bytes
+Project-URL: Repository, https://github.com/Koryto/protodantic
+Project-URL: Issues, https://github.com/Koryto/protodantic/issues
+Project-URL: Changelog, https://github.com/Koryto/protodantic/blob/master/CHANGELOG.md
+Author-email: My Koryto <mykoryto93@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: codegen,grpc,proto3,protobuf,pydantic,serialization
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pydantic
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: click>=8.2
+Requires-Dist: grpcio-tools>=1.66
+Requires-Dist: protobuf>=6.30
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# protodantic
+
+[![CI](https://github.com/Koryto/protodantic/actions/workflows/ci.yml/badge.svg)](https://github.com/Koryto/protodantic/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/protodantic-py)](https://pypi.org/project/protodantic-py/)
+[![Python](https://img.shields.io/pypi/pyversions/protodantic-py)](https://pypi.org/project/protodantic-py/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Bidirectional bridge between **Protocol Buffers** and **Pydantic**.
+
+Point it at your `.proto` files and it generates plain pydantic v2 models — with full validation — where every model round-trips losslessly to and from real protobuf messages, wire bytes, and proto JSON. The pydantic → proto direction is a first-class citizen: `to_proto_bytes()` produces genuine wire-format output that any protobuf consumer in any language can parse.
+
+## Install
+
+```sh
+uv add protodantic-py   # or: pip install protodantic-py
+```
+
+The distribution is named `protodantic-py` (the plain name is squatted on PyPI); the import stays `protodantic`:
+
+```python
+import protodantic
+```
+
+## Usage
+
+Given `demo.proto`:
+
+```proto
+syntax = "proto3";
+package demo;
+
+message Address {
+  string street = 1;
+  string city = 2;
+}
+
+message User {
+  int64 id = 1;
+  string name = 2;
+  Address address = 3;
+  repeated string tags = 4;
+  optional string nickname = 5;
+}
+```
+
+Generate models:
+
+```sh
+protodantic generate demo.proto -o models.py
+```
+
+Then:
+
+```python
+from models import User, Address
+
+user = User(id=7, name="kory", address=Address(city="Warsaw"), tags=["a", "b"])
+
+# pydantic -> proto: real wire format, readable by any protobuf runtime
+data: bytes = user.to_proto_bytes()
+msg = user.to_proto()          # a live protobuf Message
+json_str = user.to_proto_json()  # canonical proto JSON
+
+# proto -> pydantic: parse + validate in one step
+restored = User.from_proto_bytes(data)
+assert restored == user
+```
+
+Or drive it from Python:
+
+```python
+from protodantic import compile_fdset, generate_source
+
+source = generate_source(compile_fdset(["demo.proto"]))
+```
+
+## Type mapping
+
+| proto | pydantic |
+| --- | --- |
+| `int32/64`, `uint32/64`, `sint`, `fixed` | range-validated `int` (out-of-range fails at construction) |
+| `float`, `double` | `float` |
+| `string` / `bytes` / `bool` | `str` / `bytes` / `bool` |
+| `enum` | generated `OpenEnum` (`IntEnum` that preserves unknown wire values — proto3 enums are open) |
+| `message` | generated `ProtoModel` (nested types flattened as `Outer_Inner`) |
+| `repeated T` / `map<K, V>` | `list[T]` / `dict[K, V]` |
+| `optional`, oneof members, singular messages | `T \| None` (presence-aware: `None` ⇄ unset) |
+| oneof groups | mutual exclusion enforced by a model validator |
+| `google.protobuf.Timestamp` | `datetime.datetime` (UTC; naive input treated as UTC) |
+| `google.protobuf.Duration` | `datetime.timedelta` |
+| `google.protobuf.*Value` wrappers | `T \| None` |
+| `google.protobuf.Struct` / `Value` / `ListValue` | `dict[str, Any]` / `Any` / `list[Any]` |
+| `google.protobuf.Any` | `typing.Any` — accepts any `ProtoModel`; packed/unpacked via the model registry |
+
+Field names that collide with python keywords or pydantic internals (`class`, `from`, `model_config`, ...) get a trailing underscore (`class_`) with the proto name kept as a populate alias. The same rule applies to message/enum type names and enum members that are python keywords or would shadow generated code (`message list` → `class list_`) — the proto full name stays the source of truth. Same-named messages in different packages get package-qualified class names; every model is also reachable via `protodantic.model_for("pkg.Message")`.
+
+Semantics worth knowing:
+
+- **Validation on mutation is on by default** (`validate_assignment=True`): assigning a second oneof member or an out-of-range int raises immediately. Opt out per-model with standard pydantic config on a subclass.
+- **`protodantic.NULL`** expresses an explicit JSON null in a `google.protobuf.Value` field (`None` means *unset*). In `model_dump_json()` it serializes as real `null`; python-mode dumps keep the sentinel.
+- **Subclassing a generated model does not affect parsing**: `from_proto`/`model_for` keep resolving to the generated class. To make your subclass the resolution target (e.g. to add custom validators applied on parse), re-declare `__proto_full_name__` in its body — explicit opt-in.
+
+## Interop with existing `_pb2` code
+
+Already consuming a centralized proto package as protoc-generated `_pb2` modules? Generated models interoperate directly:
+
+```python
+user = User.from_proto(their_pb2_user_instance)   # accepts _pb2 messages
+their_msg = their_pb2.User.FromString(user.to_proto_bytes())  # canonical bytes
+```
+
+## How it works
+
+`protoc` (bundled via `grpcio-tools`) compiles your protos to a `FileDescriptorSet`, which codegen embeds in the generated module. At runtime, `ProtoModel` builds dynamic protobuf message classes from those descriptors — no `_pb2.py` files needed, and no protobuf internals leak into your models.
+
+If several imported generated modules define the same proto type, the registry behind `model_for()` / nested-message resolution is last-import-wins.
+
+## Status & roadmap
+
+Requires Python ≥ 3.11. proto3 only by design (proto2 input is rejected with a clear error). The full supported-behavior spec lives in [tests/](tests/) — every test documents one use case. Documented policies: unknown fields are dropped when a model re-serializes (the model is the source of truth), and naive datetimes are interpreted as UTC.
+
+- **0.1.0 (current)** — greenfield: `.proto` → pydantic codegen with lossless bidirectional round-trips, plus the semantics future drops build on.
+- **0.2.0 — brownfield** — reverse schema codegen (pydantic models → `.proto`), generating from installed `_pb2` packages by descriptor reflection, `to_proto(into=TheirPb2Class)`.
+- **0.3.0 — performance** — benchmark suite (vs `json.loads`+pydantic, raw `_pb2`, betterproto), then cached field plans and trusted-construction fast paths.
+
+gRPC service stubs are out of scope: protodantic is a message layer.

protodantic_py-0.1.0/README.md

@@ -0,0 +1,126 @@
+# protodantic
+
+[![CI](https://github.com/Koryto/protodantic/actions/workflows/ci.yml/badge.svg)](https://github.com/Koryto/protodantic/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/protodantic-py)](https://pypi.org/project/protodantic-py/)
+[![Python](https://img.shields.io/pypi/pyversions/protodantic-py)](https://pypi.org/project/protodantic-py/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Bidirectional bridge between **Protocol Buffers** and **Pydantic**.
+
+Point it at your `.proto` files and it generates plain pydantic v2 models — with full validation — where every model round-trips losslessly to and from real protobuf messages, wire bytes, and proto JSON. The pydantic → proto direction is a first-class citizen: `to_proto_bytes()` produces genuine wire-format output that any protobuf consumer in any language can parse.
+
+## Install
+
+```sh
+uv add protodantic-py   # or: pip install protodantic-py
+```
+
+The distribution is named `protodantic-py` (the plain name is squatted on PyPI); the import stays `protodantic`:
+
+```python
+import protodantic
+```
+
+## Usage
+
+Given `demo.proto`:
+
+```proto
+syntax = "proto3";
+package demo;
+
+message Address {
+  string street = 1;
+  string city = 2;
+}
+
+message User {
+  int64 id = 1;
+  string name = 2;
+  Address address = 3;
+  repeated string tags = 4;
+  optional string nickname = 5;
+}
+```
+
+Generate models:
+
+```sh
+protodantic generate demo.proto -o models.py
+```
+
+Then:
+
+```python
+from models import User, Address
+
+user = User(id=7, name="kory", address=Address(city="Warsaw"), tags=["a", "b"])
+
+# pydantic -> proto: real wire format, readable by any protobuf runtime
+data: bytes = user.to_proto_bytes()
+msg = user.to_proto()          # a live protobuf Message
+json_str = user.to_proto_json()  # canonical proto JSON
+
+# proto -> pydantic: parse + validate in one step
+restored = User.from_proto_bytes(data)
+assert restored == user
+```
+
+Or drive it from Python:
+
+```python
+from protodantic import compile_fdset, generate_source
+
+source = generate_source(compile_fdset(["demo.proto"]))
+```
+
+## Type mapping
+
+| proto | pydantic |
+| --- | --- |
+| `int32/64`, `uint32/64`, `sint`, `fixed` | range-validated `int` (out-of-range fails at construction) |
+| `float`, `double` | `float` |
+| `string` / `bytes` / `bool` | `str` / `bytes` / `bool` |
+| `enum` | generated `OpenEnum` (`IntEnum` that preserves unknown wire values — proto3 enums are open) |
+| `message` | generated `ProtoModel` (nested types flattened as `Outer_Inner`) |
+| `repeated T` / `map<K, V>` | `list[T]` / `dict[K, V]` |
+| `optional`, oneof members, singular messages | `T \| None` (presence-aware: `None` ⇄ unset) |
+| oneof groups | mutual exclusion enforced by a model validator |
+| `google.protobuf.Timestamp` | `datetime.datetime` (UTC; naive input treated as UTC) |
+| `google.protobuf.Duration` | `datetime.timedelta` |
+| `google.protobuf.*Value` wrappers | `T \| None` |
+| `google.protobuf.Struct` / `Value` / `ListValue` | `dict[str, Any]` / `Any` / `list[Any]` |
+| `google.protobuf.Any` | `typing.Any` — accepts any `ProtoModel`; packed/unpacked via the model registry |
+
+Field names that collide with python keywords or pydantic internals (`class`, `from`, `model_config`, ...) get a trailing underscore (`class_`) with the proto name kept as a populate alias. The same rule applies to message/enum type names and enum members that are python keywords or would shadow generated code (`message list` → `class list_`) — the proto full name stays the source of truth. Same-named messages in different packages get package-qualified class names; every model is also reachable via `protodantic.model_for("pkg.Message")`.
+
+Semantics worth knowing:
+
+- **Validation on mutation is on by default** (`validate_assignment=True`): assigning a second oneof member or an out-of-range int raises immediately. Opt out per-model with standard pydantic config on a subclass.
+- **`protodantic.NULL`** expresses an explicit JSON null in a `google.protobuf.Value` field (`None` means *unset*). In `model_dump_json()` it serializes as real `null`; python-mode dumps keep the sentinel.
+- **Subclassing a generated model does not affect parsing**: `from_proto`/`model_for` keep resolving to the generated class. To make your subclass the resolution target (e.g. to add custom validators applied on parse), re-declare `__proto_full_name__` in its body — explicit opt-in.
+
+## Interop with existing `_pb2` code
+
+Already consuming a centralized proto package as protoc-generated `_pb2` modules? Generated models interoperate directly:
+
+```python
+user = User.from_proto(their_pb2_user_instance)   # accepts _pb2 messages
+their_msg = their_pb2.User.FromString(user.to_proto_bytes())  # canonical bytes
+```
+
+## How it works
+
+`protoc` (bundled via `grpcio-tools`) compiles your protos to a `FileDescriptorSet`, which codegen embeds in the generated module. At runtime, `ProtoModel` builds dynamic protobuf message classes from those descriptors — no `_pb2.py` files needed, and no protobuf internals leak into your models.
+
+If several imported generated modules define the same proto type, the registry behind `model_for()` / nested-message resolution is last-import-wins.
+
+## Status & roadmap
+
+Requires Python ≥ 3.11. proto3 only by design (proto2 input is rejected with a clear error). The full supported-behavior spec lives in [tests/](tests/) — every test documents one use case. Documented policies: unknown fields are dropped when a model re-serializes (the model is the source of truth), and naive datetimes are interpreted as UTC.
+
+- **0.1.0 (current)** — greenfield: `.proto` → pydantic codegen with lossless bidirectional round-trips, plus the semantics future drops build on.
+- **0.2.0 — brownfield** — reverse schema codegen (pydantic models → `.proto`), generating from installed `_pb2` packages by descriptor reflection, `to_proto(into=TheirPb2Class)`.
+- **0.3.0 — performance** — benchmark suite (vs `json.loads`+pydantic, raw `_pb2`, betterproto), then cached field plans and trusted-construction fast paths.
+
+gRPC service stubs are out of scope: protodantic is a message layer.

protodantic_py-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "protodantic-py"
+dynamic = ["version"]
+description = "Bidirectional bridge between Protocol Buffers and Pydantic: generate pydantic models from .proto files with lossless round-trips to proto messages and wire bytes"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "My Koryto", email = "mykoryto93@gmail.com" },
+]
+requires-python = ">=3.11"
+keywords = ["protobuf", "pydantic", "codegen", "serialization", "grpc", "proto3"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Pydantic",
+    "Framework :: Pydantic :: 2",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.7",
+    "protobuf>=6.30",
+    "grpcio-tools>=1.66",
+    "click>=8.2",
+]
+
+[project.urls]
+Repository = "https://github.com/Koryto/protodantic"
+Issues = "https://github.com/Koryto/protodantic/issues"
+Changelog = "https://github.com/Koryto/protodantic/blob/master/CHANGELOG.md"
+
+[project.scripts]
+protodantic = "protodantic.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/protodantic/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/protodantic"]

protodantic_py-0.1.0/src/protodantic/__init__.py

@@ -0,0 +1,25 @@
+"""Bidirectional bridge between Protocol Buffers and Pydantic."""
+
+from ._version import __version__
+from .codegen import generate_source
+from .compiler import compile_fdset
+from .runtime import OpenEnum, ProtoModel, load_pool, model_for
+from .types import NULL, Int32, Int64, ListValue, Struct, UInt32, UInt64, Value
+
+__all__ = [
+    "Int32",
+    "Int64",
+    "ListValue",
+    "NULL",
+    "OpenEnum",
+    "ProtoModel",
+    "Struct",
+    "UInt32",
+    "UInt64",
+    "Value",
+    "__version__",
+    "compile_fdset",
+    "generate_source",
+    "load_pool",
+    "model_for",
+]

protodantic_py-0.1.0/src/protodantic/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

protodantic_py-0.1.0/src/protodantic/cli.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from ._version import __version__
+from .codegen import generate_source
+from .compiler import compile_fdset
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="protodantic")
+def main() -> None:
+    """Bidirectional bridge between Protocol Buffers and pydantic models."""
+
+
+@main.command()
+@click.argument("protos", nargs=-1, required=True)
+@click.option(
+    "-I", "--include", "includes", multiple=True, metavar="DIR",
+    help="Additional import search path (repeatable).",
+)
+@click.option(
+    "-o", "--out", "out", required=True, metavar="FILE",
+    help="Output python module path (e.g. models.py).",
+)
+def generate(protos: tuple[str, ...], includes: tuple[str, ...], out: str) -> None:
+    """Generate pydantic models from .proto files."""
+    try:
+        fdset = compile_fdset(protos=protos, includes=includes)
+        source = generate_source(fdset_bytes=fdset)
+        out_path = Path(out)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(source, encoding="utf-8")
+    except (RuntimeError, NotImplementedError, ValueError, OSError) as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(f"wrote {out_path}")
+
+
+if __name__ == "__main__":
+    main()