protodantic-py 0.1.0__py3-none-any.whl

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/_version.py

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

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()

protodantic/codegen.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import base64
+import keyword
+import textwrap
+from collections import Counter
+from typing import NamedTuple
+
+from google.protobuf import any_pb2, descriptor_pb2, duration_pb2, struct_pb2, timestamp_pb2, wrappers_pb2
+from google.protobuf.descriptor import Descriptor, EnumDescriptor, FieldDescriptor, OneofDescriptor
+
+from ._version import __version__
+from .runtime import load_pool, python_field_name
+
+# proto scalar type -> (python annotation, default expression); protodantic
+# names go through the _pd module alias so user message names can never
+# shadow them inside the generated module
+_SCALARS: dict[int, tuple[str, str]] = {
+    FieldDescriptor.TYPE_DOUBLE: ("float", "0.0"),
+    FieldDescriptor.TYPE_FLOAT: ("float", "0.0"),
+    FieldDescriptor.TYPE_INT64: ("_pd.Int64", "0"),
+    FieldDescriptor.TYPE_UINT64: ("_pd.UInt64", "0"),
+    FieldDescriptor.TYPE_INT32: ("_pd.Int32", "0"),
+    FieldDescriptor.TYPE_FIXED64: ("_pd.UInt64", "0"),
+    FieldDescriptor.TYPE_FIXED32: ("_pd.UInt32", "0"),
+    FieldDescriptor.TYPE_BOOL: ("bool", "False"),
+    FieldDescriptor.TYPE_STRING: ("str", '""'),
+    FieldDescriptor.TYPE_BYTES: ("bytes", 'b""'),
+    FieldDescriptor.TYPE_UINT32: ("_pd.UInt32", "0"),
+    FieldDescriptor.TYPE_SFIXED32: ("_pd.Int32", "0"),
+    FieldDescriptor.TYPE_SFIXED64: ("_pd.Int64", "0"),
+    FieldDescriptor.TYPE_SINT32: ("_pd.Int32", "0"),
+    FieldDescriptor.TYPE_SINT64: ("_pd.Int64", "0"),
+}
+
+# well-known types are handled by the runtime, not generated as classes; all
+# imported names in generated code are underscore-aliased so user message
+# names (e.g. `message Any`) can never shadow them
+_WKT_PY: dict[str, str] = {
+    timestamp_pb2.Timestamp.DESCRIPTOR.full_name: "_datetime.datetime",
+    duration_pb2.Duration.DESCRIPTOR.full_name: "_datetime.timedelta",
+    any_pb2.Any.DESCRIPTOR.full_name: "_typing.Any",
+    struct_pb2.Struct.DESCRIPTOR.full_name: "_pd.Struct",
+    struct_pb2.Value.DESCRIPTOR.full_name: "_pd.Value",
+    struct_pb2.ListValue.DESCRIPTOR.full_name: "_pd.ListValue",
+    wrappers_pb2.DoubleValue.DESCRIPTOR.full_name: "float",
+    wrappers_pb2.FloatValue.DESCRIPTOR.full_name: "float",
+    wrappers_pb2.Int64Value.DESCRIPTOR.full_name: "_pd.Int64",
+    wrappers_pb2.UInt64Value.DESCRIPTOR.full_name: "_pd.UInt64",
+    wrappers_pb2.Int32Value.DESCRIPTOR.full_name: "_pd.Int32",
+    wrappers_pb2.UInt32Value.DESCRIPTOR.full_name: "_pd.UInt32",
+    wrappers_pb2.BoolValue.DESCRIPTOR.full_name: "bool",
+    wrappers_pb2.StringValue.DESCRIPTOR.full_name: "str",
+    wrappers_pb2.BytesValue.DESCRIPTOR.full_name: "bytes",
+}
+
+_HEADER = f'''\
+"""Generated by protodantic {__version__}. DO NOT EDIT."""
+
+from __future__ import annotations
+
+import base64 as _base64
+import datetime as _datetime
+import typing as _typing
+
+from pydantic import Field as _Field
+
+import protodantic as _pd
+
+'''
+
+_B64_LINE_WIDTH = 84
+
+# names a generated type may not use: builtins that appear in generated
+# annotations/defaults, and the names the generated module itself emits
+_REFERENCED_BUILTINS = frozenset({"bool", "bytes", "dict", "float", "int", "list", "str", "tuple"})
+_EMITTED_MODULE_NAMES = frozenset({"_pd", "_typing", "_datetime", "_base64", "_Field", "_POOL", "_model"})
+# names the enum machinery reserves on members
+_RESERVED_ENUM_MEMBERS = frozenset({"mro"})
+
+
+def _python_type_name(*, name: str) -> str:
+    """Trailing-underscore escape (same rule as fields) for type names that
+    are python keywords or would shadow names the generated module relies on."""
+    if keyword.iskeyword(name) or name in _REFERENCED_BUILTINS or name in _EMITTED_MODULE_NAMES:
+        return name + "_"
+    return name
+
+
+def _python_enum_member(*, name: str) -> str:
+    if keyword.iskeyword(name) or name in _RESERVED_ENUM_MEMBERS:
+        return name + "_"
+    return name
+
+
+class _Entry(NamedTuple):
+    kind: str  # "message" | "enum"
+    desc: Descriptor | EnumDescriptor
+    base_name: str
+    package: str
+
+
+def generate_source(fdset_bytes: bytes) -> str:
+    """Render one python module with pydantic models for every message in the
+    serialized FileDescriptorSet."""
+    return _ModuleGenerator(fdset_bytes=fdset_bytes).render()
+
+
+def _is_wkt_file(*, file_name: str) -> bool:
+    return file_name.startswith("google/protobuf/")
+
+
+def _is_synthetic_oneof(*, oneof: OneofDescriptor) -> bool:
+    # proto3 `optional` is backed by a single-field oneof named _<field>
+    fields = list(oneof.fields)
+    return len(fields) == 1 and oneof.name == "_" + fields[0].name
+
+
+class _ModuleGenerator:
+    def __init__(self, *, fdset_bytes: bytes) -> None:
+        self._fdset_bytes = fdset_bytes
+        self._fdset = descriptor_pb2.FileDescriptorSet.FromString(fdset_bytes)
+        self._pool = load_pool(fdset_bytes)
+        self._entries: list[_Entry] = []
+        self._py_names: dict[str, str] = {}
+
+    def render(self) -> str:
+        self._reject_non_proto3()
+        self._collect_entries()
+        self._assign_python_names()
+
+        parts = [_HEADER, self._render_pool()]
+        parts.extend(self._render_enum(desc=e.desc) for e in self._entries if e.kind == "enum")
+        parts.extend(self._render_message(desc=e.desc) for e in self._entries if e.kind == "message")
+        rebuild = self._render_rebuild()
+        if rebuild:
+            parts.append(rebuild)
+        return "\n\n".join(parts)
+
+    def _reject_non_proto3(self) -> None:
+        for file_proto in self._fdset.file:
+            if _is_wkt_file(file_name=file_proto.name):
+                continue
+            if file_proto.syntax != "proto3":
+                raise NotImplementedError(
+                    f"{file_proto.name}: protodantic supports proto3 only, "
+                    f"got {file_proto.syntax or 'proto2'}"
+                )
+
+    def _collect_entries(self) -> None:
+        for file_proto in self._fdset.file:
+            if _is_wkt_file(file_name=file_proto.name):
+                continue
+            file_desc = self._pool.FindFileByName(file_proto.name)
+            for enum_desc in file_desc.enum_types_by_name.values():
+                self._register_enum(desc=enum_desc, prefix="", package=file_desc.package)
+            for msg_desc in file_desc.message_types_by_name.values():
+                self._register_message(desc=msg_desc, prefix="", package=file_desc.package)
+
+    def _register_message(self, *, desc: Descriptor, prefix: str, package: str) -> None:
+        if desc.GetOptions().map_entry:
+            return
+        base_name = prefix + desc.name
+        self._entries.append(_Entry(kind="message", desc=desc, base_name=base_name, package=package))
+        for enum_desc in desc.enum_types:
+            self._register_enum(desc=enum_desc, prefix=base_name + "_", package=package)
+        for nested in desc.nested_types:
+            self._register_message(desc=nested, prefix=base_name + "_", package=package)
+
+    def _register_enum(self, *, desc: EnumDescriptor, prefix: str, package: str) -> None:
+        self._entries.append(_Entry(kind="enum", desc=desc, base_name=prefix + desc.name, package=package))
+
+    def _assign_python_names(self) -> None:
+        # same base name in two packages -> qualify with the package path
+        base_counts = Counter(entry.base_name for entry in self._entries)
+        for entry in self._entries:
+            if base_counts[entry.base_name] > 1 and entry.package:
+                name = f"{entry.package.replace('.', '_')}_{entry.base_name}"
+            else:
+                name = entry.base_name
+            self._py_names[entry.desc.full_name] = _python_type_name(name=name)
+        self._reject_residual_collisions()
+
+    def _reject_residual_collisions(self) -> None:
+        # flattening joins nesting with "_", so Outer.Inner and a literal
+        # Outer_Inner collide even within one package — refuse, never overwrite
+        by_python_name: dict[str, list[str]] = {}
+        for full_name, py_name in self._py_names.items():
+            by_python_name.setdefault(py_name, []).append(full_name)
+        collisions = {name: fulls for name, fulls in by_python_name.items() if len(fulls) > 1}
+        if collisions:
+            details = "; ".join(
+                f"{' and '.join(sorted(fulls))} both map to {name!r}"
+                for name, fulls in sorted(collisions.items())
+            )
+            raise ValueError(
+                f"python class name collision after flattening: {details}. "
+                "Rename one of the conflicting proto types."
+            )
+
+    def _base_type(self, *, fd: FieldDescriptor) -> str:
+        if fd.type == FieldDescriptor.TYPE_MESSAGE:
+            full_name = fd.message_type.full_name
+            if full_name in _WKT_PY:
+                return _WKT_PY[full_name]
+            return self._py_names[full_name]
+        if fd.type == FieldDescriptor.TYPE_ENUM:
+            return self._py_names[fd.enum_type.full_name]
+        return _SCALARS[fd.type][0]
+
+    def _annotation(self, *, fd: FieldDescriptor) -> str:
+        if _is_map_field(fd=fd):
+            key_fd = fd.message_type.fields_by_name["key"]
+            value_fd = fd.message_type.fields_by_name["value"]
+            return f"dict[{self._base_type(fd=key_fd)}, {self._base_type(fd=value_fd)}]"
+        if fd.is_repeated:
+            return f"list[{self._base_type(fd=fd)}]"
+        if fd.has_presence:
+            return f"{self._base_type(fd=fd)} | None"
+        return self._base_type(fd=fd)
+
+    def _default(self, *, fd: FieldDescriptor) -> str:
+        alias = f'"{fd.name}"' if python_field_name(proto_name=fd.name) != fd.name else None
+        if _is_map_field(fd=fd):
+            return f"_Field(default_factory=dict, alias={alias})" if alias else "_Field(default_factory=dict)"
+        if fd.is_repeated:
+            return f"_Field(default_factory=list, alias={alias})" if alias else "_Field(default_factory=list)"
+        if fd.has_presence:
+            plain = "None"
+        elif fd.type == FieldDescriptor.TYPE_ENUM:
+            plain = f"{self._py_names[fd.enum_type.full_name]}(0)"
+        else:
+            plain = _SCALARS[fd.type][1]
+        return f"_Field(default={plain}, alias={alias})" if alias else plain
+
+    def _render_pool(self) -> str:
+        encoded = base64.b64encode(self._fdset_bytes).decode("ascii")
+        chunks = "\n".join(f'    "{line}"' for line in textwrap.wrap(encoded, _B64_LINE_WIDTH))
+        return f"_POOL = _pd.load_pool(_base64.b64decode(\n{chunks}\n))\n"
+
+    def _render_enum(self, *, desc: EnumDescriptor) -> str:
+        py_name = self._py_names[desc.full_name]
+        members = [(_python_enum_member(name=v.name), v.name, v.number) for v in desc.values]
+        self._reject_member_collisions(enum_name=desc.full_name, members=members)
+        lines = [f"class {py_name}(_pd.OpenEnum):"]
+        lines.extend(f"    {member} = {number}" for member, _, number in members)
+        return "\n".join(lines) + "\n"
+
+    def _reject_member_collisions(
+        self, *, enum_name: str, members: list[tuple[str, str, int]]
+    ) -> None:
+        # escaping can map two proto member names to one python name; python
+        # enums forbid redeclaring a name (even for same-value aliases), so
+        # refuse rather than crash opaquely at import
+        by_member: dict[str, list[str]] = {}
+        for py_member, proto_member, _ in members:
+            by_member.setdefault(py_member, []).append(proto_member)
+        collisions = {py: names for py, names in by_member.items() if len(names) > 1}
+        if collisions:
+            details = "; ".join(
+                f"{' and '.join(names)} both map to {py!r}"
+                for py, names in sorted(collisions.items())
+            )
+            raise ValueError(
+                f"enum {enum_name!r}: member name collision after escaping: {details}. "
+                "Rename one of the conflicting members."
+            )
+
+    def _render_message(self, *, desc: Descriptor) -> str:
+        lines = [
+            f"class {self._py_names[desc.full_name]}(_pd.ProtoModel):",
+            f'    __proto_full_name__: _typing.ClassVar[str] = "{desc.full_name}"',
+            "    __proto_pool__: _typing.ClassVar[_typing.Any] = _POOL",
+        ]
+        oneofs = self._render_oneofs(desc=desc)
+        if oneofs:
+            lines.append(oneofs)
+        if desc.fields:
+            lines.append("")
+        lines.extend(
+            f"    {python_field_name(proto_name=fd.name)}: {self._annotation(fd=fd)} = {self._default(fd=fd)}"
+            for fd in desc.fields
+        )
+        return "\n".join(lines) + "\n"
+
+    def _render_oneofs(self, *, desc: Descriptor) -> str | None:
+        real_oneofs = [o for o in desc.oneofs if not _is_synthetic_oneof(oneof=o)]
+        if not real_oneofs:
+            return None
+        groups = ", ".join(
+            '"{}": ({})'.format(
+                oneof.name,
+                ", ".join(f'"{python_field_name(proto_name=f.name)}"' for f in oneof.fields)
+                + ("," if len(oneof.fields) == 1 else ""),
+            )
+            for oneof in real_oneofs
+        )
+        return f"    __proto_oneofs__: _typing.ClassVar[dict[str, tuple[str, ...]]] = {{{groups}}}"
+
+    def _render_rebuild(self) -> str | None:
+        names = [self._py_names[e.desc.full_name] for e in self._entries if e.kind == "message"]
+        if not names:
+            return None
+        joined = ", ".join(names)
+        trailing = "," if len(names) == 1 else ""
+        return f"for _model in ({joined}{trailing}):\n    _model.model_rebuild()\ndel _model\n"
+
+
+def _is_map_field(*, fd: FieldDescriptor) -> bool:
+    return fd.type == FieldDescriptor.TYPE_MESSAGE and fd.message_type.GetOptions().map_entry

protodantic/compiler.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import importlib.resources
+import os
+import tempfile
+from collections.abc import Iterable
+
+from grpc_tools import protoc as _protoc
+
+
+def compile_fdset(protos: Iterable[str], includes: Iterable[str] = ()) -> bytes:
+    """Compile .proto files into a serialized FileDescriptorSet, imports
+    included, so the result is self-contained. The directory of each input and
+    the well-known types shipped with grpcio-tools are always on the path."""
+    proto_paths = [os.path.abspath(p) for p in protos]
+    if not proto_paths:
+        raise ValueError("at least one .proto file is required")
+
+    include_paths = [os.path.abspath(i) for i in includes]
+    for path in proto_paths:
+        parent = os.path.dirname(path)
+        if parent not in include_paths:
+            include_paths.append(parent)
+    include_paths.append(str(importlib.resources.files("grpc_tools") / "_proto"))
+
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        out_path = os.path.join(tmp_dir, "fdset.bin")
+        args = [
+            "protoc",
+            f"--descriptor_set_out={out_path}",
+            "--include_imports",
+            *[f"-I{i}" for i in include_paths],
+            *proto_paths,
+        ]
+        exit_code = _protoc.main(args)
+        if exit_code != 0:
+            raise RuntimeError(f"protoc failed with exit code {exit_code} (args: {args[1:]})")
+        with open(out_path, "rb") as f:
+            return f.read()

protodantic/runtime.py

@@ -0,0 +1,345 @@
+from __future__ import annotations
+
+import datetime
+import enum
+import keyword
+from typing import Any, ClassVar, Self
+
+from google.protobuf import (
+    any_pb2,
+    descriptor_pb2,
+    descriptor_pool,
+    duration_pb2,
+    json_format,
+    message_factory,
+    struct_pb2,
+    timestamp_pb2,
+    wrappers_pb2,
+)
+from google.protobuf.descriptor import FieldDescriptor
+from google.protobuf.message import Message
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from .types import NULL, _strip_null_sentinel
+
+_TIMESTAMP = timestamp_pb2.Timestamp.DESCRIPTOR.full_name
+_DURATION = duration_pb2.Duration.DESCRIPTOR.full_name
+_ANY = any_pb2.Any.DESCRIPTOR.full_name
+_VALUE = struct_pb2.Value.DESCRIPTOR.full_name
+_STRUCT_TYPES = frozenset(
+    m.DESCRIPTOR.full_name for m in (struct_pb2.Struct, struct_pb2.Value, struct_pb2.ListValue)
+)
+_WRAPPER_TYPES = frozenset(
+    m.DESCRIPTOR.full_name
+    for m in (
+        wrappers_pb2.DoubleValue,
+        wrappers_pb2.FloatValue,
+        wrappers_pb2.Int64Value,
+        wrappers_pb2.UInt64Value,
+        wrappers_pb2.Int32Value,
+        wrappers_pb2.UInt32Value,
+        wrappers_pb2.BoolValue,
+        wrappers_pb2.StringValue,
+        wrappers_pb2.BytesValue,
+    )
+)
+
+# nested-message resolution is scoped per descriptor pool (i.e. per generated
+# module) so duplicate generated modules can coexist in one process; the
+# by-name registry backs model_for() and Any fallback (last import wins)
+_MODELS_BY_POOL: dict[tuple[Any, str], type[ProtoModel]] = {}
+_MODELS_BY_NAME: dict[str, type[ProtoModel]] = {}
+
+_RESERVED_NAMES = frozenset({
+    "proto_class",
+    "to_proto",
+    "to_proto_bytes",
+    "to_proto_json",
+    "from_proto",
+    "from_proto_bytes",
+    "from_proto_json",
+})
+
+
+def python_field_name(*, proto_name: str) -> str:
+    """Python attribute for a proto field: keywords, model_*, and ProtoModel API
+    names get a trailing underscore; the proto name stays usable as an alias."""
+    if (
+        keyword.iskeyword(proto_name)
+        or proto_name.startswith("model_")
+        or proto_name in _RESERVED_NAMES
+    ):
+        return proto_name + "_"
+    return proto_name
+
+
+def model_for(full_name: str) -> type[ProtoModel]:
+    """Generated model class for a proto full name (e.g. "pkg.Msg"). The module
+    defining it must be imported first; on duplicates the last import wins."""
+    try:
+        return _MODELS_BY_NAME[full_name]
+    except KeyError:
+        raise KeyError(
+            f"no generated model imported for proto type {full_name!r}"
+        ) from None
+
+
+def load_pool(fdset_bytes: bytes) -> descriptor_pool.DescriptorPool:
+    """Build a fresh DescriptorPool from a serialized FileDescriptorSet."""
+    fdset = descriptor_pb2.FileDescriptorSet.FromString(fdset_bytes)
+    pool = descriptor_pool.DescriptorPool()
+    for file_proto in fdset.file:
+        pool.Add(file_proto)
+    return pool
+
+
+class OpenEnum(enum.IntEnum):
+    """IntEnum matching proto3 open-enum semantics: values missing from the
+    schema become pseudo-members instead of raising."""
+
+    @classmethod
+    def _missing_(cls, value: object) -> OpenEnum | None:
+        if not isinstance(value, int) or isinstance(value, bool):
+            return None
+        pseudo = int.__new__(cls, value)
+        pseudo._name_ = None
+        pseudo._value_ = value
+        return pseudo
+
+
+def _is_map(*, fd: FieldDescriptor) -> bool:
+    return (
+        fd.type == FieldDescriptor.TYPE_MESSAGE
+        and fd.message_type.GetOptions().map_entry
+    )
+
+
+def _scalar_to_proto(*, value: Any) -> Any:
+    # enum members (incl. open-enum pseudo-members) flatten to plain ints
+    return int(value) if isinstance(value, int) and not isinstance(value, bool) else value
+
+
+def _resolve_model(*, full_name: str, pool: Any) -> type[ProtoModel] | None:
+    model_cls = _MODELS_BY_POOL.get((pool, full_name))
+    if model_cls is not None:
+        return model_cls
+    return _MODELS_BY_NAME.get(full_name)
+
+
+def _fill_message(*, target: Message, value: Any) -> None:
+    full_name = target.DESCRIPTOR.full_name
+    if full_name == _TIMESTAMP:
+        target.FromDatetime(value)
+    elif full_name == _DURATION:
+        target.FromTimedelta(value)
+    elif full_name == _ANY:
+        if not isinstance(value, ProtoModel):
+            raise TypeError(
+                f"google.protobuf.Any fields accept ProtoModel instances, got {type(value).__name__}"
+            )
+        target.Pack(value.to_proto())
+    elif full_name in _STRUCT_TYPES:
+        json_format.ParseDict(_strip_null_sentinel(value), target)
+    elif full_name in _WRAPPER_TYPES:
+        target.value = value
+    else:
+        target.CopyFrom(value.to_proto())
+
+
+def _message_to_python(*, msg: Message, pool: Any) -> Any:
+    full_name = msg.DESCRIPTOR.full_name
+    if full_name == _TIMESTAMP:
+        return msg.ToDatetime(tzinfo=datetime.timezone.utc)
+    if full_name == _DURATION:
+        return msg.ToTimedelta()
+    if full_name == _ANY:
+        return _unpack_any(msg=msg, pool=pool)
+    if full_name in _STRUCT_TYPES:
+        result = json_format.MessageToDict(msg)
+        # a set-but-null Value maps to NULL; None is reserved for "unset"
+        if full_name == _VALUE and result is None:
+            return NULL
+        return result
+    if full_name in _WRAPPER_TYPES:
+        return msg.value
+    model_cls = _resolve_model(full_name=full_name, pool=pool)
+    if model_cls is None:
+        raise LookupError(
+            f"no protodantic model registered for {full_name!r}; "
+            "import the generated module that defines it first"
+        )
+    return model_cls.from_proto(msg)
+
+
+def _unpack_any(*, msg: Message, pool: Any) -> ProtoModel:
+    type_name = msg.type_url.rpartition("/")[2]
+    model_cls = _resolve_model(full_name=type_name, pool=pool)
+    if model_cls is None:
+        raise LookupError(
+            f"cannot unpack Any: no generated model imported for {type_name!r}"
+        )
+    inner = model_cls._new_message()
+    if not msg.Unpack(inner):
+        raise ValueError(f"failed to unpack Any containing {type_name!r}")
+    return model_cls.from_proto(inner)
+
+
+def _set_proto_field(*, msg: Message, fd: FieldDescriptor, value: Any) -> None:
+    if _is_map(fd=fd):
+        _fill_map(target=getattr(msg, fd.name), fd=fd, value=value)
+        return
+    if fd.is_repeated:
+        _fill_repeated(target=getattr(msg, fd.name), fd=fd, value=value)
+        return
+    if fd.type == FieldDescriptor.TYPE_MESSAGE:
+        _fill_message(target=getattr(msg, fd.name), value=value)
+        return
+    setattr(msg, fd.name, _scalar_to_proto(value=value))
+
+
+def _fill_map(*, target: Any, fd: FieldDescriptor, value: dict) -> None:
+    value_fd = fd.message_type.fields_by_name["value"]
+    if value_fd.type == FieldDescriptor.TYPE_MESSAGE:
+        for key, item in value.items():
+            _fill_message(target=target[key], value=item)
+    else:
+        for key, item in value.items():
+            target[key] = _scalar_to_proto(value=item)
+
+
+def _fill_repeated(*, target: Any, fd: FieldDescriptor, value: list) -> None:
+    if fd.type == FieldDescriptor.TYPE_MESSAGE:
+        for item in value:
+            _fill_message(target=target.add(), value=item)
+    else:
+        target.extend(_scalar_to_proto(value=item) for item in value)
+
+
+def _read_proto_field(*, msg: Message, fd: FieldDescriptor, pool: Any) -> Any:
+    if _is_map(fd=fd):
+        return _read_map(target=getattr(msg, fd.name), fd=fd, pool=pool)
+    if fd.is_repeated:
+        value = getattr(msg, fd.name)
+        if fd.type == FieldDescriptor.TYPE_MESSAGE:
+            return [_message_to_python(msg=item, pool=pool) for item in value]
+        return list(value)
+    if fd.has_presence and not msg.HasField(fd.name):
+        return None
+    if fd.type == FieldDescriptor.TYPE_MESSAGE:
+        return _message_to_python(msg=getattr(msg, fd.name), pool=pool)
+    return getattr(msg, fd.name)
+
+
+def _read_map(*, target: Any, fd: FieldDescriptor, pool: Any) -> dict:
+    value_fd = fd.message_type.fields_by_name["value"]
+    if value_fd.type == FieldDescriptor.TYPE_MESSAGE:
+        return {key: _message_to_python(msg=item, pool=pool) for key, item in target.items()}
+    return dict(target)
+
+
+class ProtoModel(BaseModel):
+    """Pydantic base model bound to a protobuf message type."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        protected_namespaces=(),
+        validate_assignment=True,
+        extra="forbid",
+    )
+
+    __proto_full_name__: ClassVar[str] = ""
+    __proto_pool__: ClassVar[Any] = None
+    __proto_oneofs__: ClassVar[dict[str, tuple[str, ...]]] = {}
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:
+        super().__pydantic_init_subclass__(**kwargs)
+        # own-body declaration only: plain subclasses don't hijack resolution;
+        # re-declaring __proto_full_name__ is the explicit opt-in to take over
+        if cls.__dict__.get("__proto_full_name__"):
+            _MODELS_BY_POOL[(cls.__proto_pool__, cls.__proto_full_name__)] = cls
+            _MODELS_BY_NAME[cls.__proto_full_name__] = cls
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        # pydantic mutates before after-validators run; restore on failure so
+        # a rejected assignment cannot leave the model in an invalid state
+        had_value = name in self.__dict__
+        old_value = self.__dict__.get(name)
+        was_set = name in self.__pydantic_fields_set__
+        try:
+            super().__setattr__(name, value)
+        except Exception:
+            if had_value:
+                self.__dict__[name] = old_value
+            else:
+                self.__dict__.pop(name, None)
+            if not was_set:
+                self.__pydantic_fields_set__.discard(name)
+            raise
+
+    @model_validator(mode="after")
+    def _validate_oneofs(self) -> Self:
+        for group, fields in type(self).__proto_oneofs__.items():
+            set_fields = [name for name in fields if getattr(self, name) is not None]
+            if len(set_fields) > 1:
+                raise ValueError(
+                    f"oneof {group!r} allows at most one field to be set, got {set_fields}"
+                )
+        return self
+
+    @classmethod
+    def proto_class(cls) -> type[Message]:
+        """The dynamic protobuf message class this model is bound to."""
+        descriptor = cls.__proto_pool__.FindMessageTypeByName(cls.__proto_full_name__)
+        return message_factory.GetMessageClass(descriptor)
+
+    @classmethod
+    def _new_message(cls) -> Message:
+        message_cls = cls.proto_class()
+        return message_cls()
+
+    def to_proto(self) -> Message:
+        """Convert this model to a protobuf message."""
+        msg = self._new_message()
+        for fd in msg.DESCRIPTOR.fields:
+            value = getattr(self, python_field_name(proto_name=fd.name))
+            if value is not None:
+                _set_proto_field(msg=msg, fd=fd, value=value)
+        return msg
+
+    def to_proto_bytes(self) -> bytes:
+        """Serialize this model to protobuf wire format."""
+        return self.to_proto().SerializeToString()
+
+    def to_proto_json(self, **kwargs: Any) -> str:
+        """Serialize this model to canonical proto JSON."""
+        return json_format.MessageToJson(self.to_proto(), **kwargs)
+
+    @classmethod
+    def from_proto(cls, msg: Message) -> Self:
+        """Build a model from a protobuf message of this model's proto type.
+        Works with any message whose descriptor matches this schema, including
+        classic _pb2 instances; unrelated message types are rejected."""
+        if msg.DESCRIPTOR.full_name != cls.__proto_full_name__:
+            raise TypeError(
+                f"{cls.__name__}.from_proto expects {cls.__proto_full_name__!r}, "
+                f"got {msg.DESCRIPTOR.full_name!r}"
+            )
+        data = {
+            python_field_name(proto_name=fd.name): _read_proto_field(
+                msg=msg, fd=fd, pool=cls.__proto_pool__
+            )
+            for fd in msg.DESCRIPTOR.fields
+        }
+        return cls(**data)
+
+    @classmethod
+    def from_proto_bytes(cls, data: bytes) -> Self:
+        """Parse protobuf wire format into a model instance."""
+        return cls.from_proto(cls.proto_class().FromString(data))
+
+    @classmethod
+    def from_proto_json(cls, data: str, **kwargs: Any) -> Self:
+        """Parse canonical proto JSON into a model instance. kwargs pass
+        through to json_format.Parse (e.g. ignore_unknown_fields=True)."""
+        return cls.from_proto(json_format.Parse(data, cls._new_message(), **kwargs))

protodantic/types.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from pydantic import Field, PlainSerializer
+
+Int32 = Annotated[int, Field(ge=-(2**31), le=2**31 - 1)]
+UInt32 = Annotated[int, Field(ge=0, le=2**32 - 1)]
+Int64 = Annotated[int, Field(ge=-(2**63), le=2**63 - 1)]
+UInt64 = Annotated[int, Field(ge=0, le=2**64 - 1)]
+
+
+class _NullType:
+    """Singleton sentinel: an explicit JSON null in a google.protobuf.Value
+    field, as opposed to None which means "field unset"."""
+
+    _instance: _NullType | None = None
+
+    def __new__(cls) -> _NullType:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "protodantic.NULL"
+
+    def __bool__(self) -> bool:
+        return False
+
+    # copies must preserve identity: `x is NULL` is the documented check
+    def __copy__(self) -> _NullType:
+        return self
+
+    def __deepcopy__(self, memo: dict) -> _NullType:
+        return self
+
+
+NULL = _NullType()
+
+
+# positional arg by contract: pydantic's PlainSerializer invokes this callback
+# as f(value), so the signature is fixed by the framework
+def _strip_null_sentinel(value: Any) -> Any:
+    if value is NULL:
+        return None
+    if isinstance(value, dict):
+        return {k: _strip_null_sentinel(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_strip_null_sentinel(v) for v in value]
+    return value
+
+
+# JSON dumps turn the sentinel into a real null; python-mode dumps keep it so
+# NULL-vs-unset survives a model_dump()/model_validate() round-trip
+_NullSafe = PlainSerializer(_strip_null_sentinel, when_used="json")
+
+Struct = Annotated[dict[str, Any], _NullSafe]
+Value = Annotated[Any, _NullSafe]
+ListValue = Annotated[list[Any], _NullSafe]

protodantic_py-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+protodantic/__init__.py,sha256=emVIfT8_5hVoo_74Snyfq92ZnR2MuuB6Cfa6M3wI9t8,574
+protodantic/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+protodantic/cli.py,sha256=Z5gR04_mR3jpPSSolPIWwUYNI6WV_Pl15D3BSlEWRZQ,1361
+protodantic/codegen.py,sha256=bA0XQtqUzuWMdzRqzgKb36L3e27heZS3fQrjKe1EI40,13669
+protodantic/compiler.py,sha256=O8-y2udmeGbS4yHtDgAEIAfNlvYrtf7A26SRfoJvli4,1455
+protodantic/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+protodantic/runtime.py,sha256=131pfqlUv2TLGjrm812uE64tuHN2ZKRlJjFMeUu74pM,12566
+protodantic/types.py,sha256=3IOhXkRN4fLxQRLw9ccSsMSrwln-JVrHxuKsKcRnjsg,1804
+protodantic_py-0.1.0.dist-info/METADATA,sha256=murSwqAf8qfU5gqZ47xVaRTmB-aFGZ0moB5v8QZ6kvg,7477
+protodantic_py-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+protodantic_py-0.1.0.dist-info/entry_points.txt,sha256=40KPnPZrJRvt_4-f9ds1eE957hFbR2DNsWtg8__0V84,53
+protodantic_py-0.1.0.dist-info/licenses/LICENSE,sha256=AruywRaIPJhOHT3mzIonIdc92XVgdFbxBi2FGjYBsTc,1066
+protodantic_py-0.1.0.dist-info/RECORD,,

protodantic_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

protodantic_py-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+protodantic = protodantic.cli:main

protodantic_py-0.1.0.dist-info/licenses/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.