cmodel 0.0.1__tar.gz

cmodel-0.0.1/LICENSE.txt

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c)  Ryan Morshead <ryan.morshead@gmail.com>
+
+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.

cmodel-0.0.1/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.3
+Name: cmodel
+Version: 0.0.1
+Summary: Model C structs with Pydantic
+Keywords: 
+Author: Ryan Morshead
+Author-email: Ryan Morshead <ryan.morshead@gmail.com>
+License: MIT License
+         
+         Copyright (c)  Ryan Morshead <ryan.morshead@gmail.com>
+         
+         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.
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-walk-core-schema>=1.0.0
+Requires-Python: >=3.12, <4
+Project-URL: Source, https://github.com/rmorshea/cmodel
+Description-Content-Type: text/markdown
+
+# CModel
+
+[![PyPI - Version](https://img.shields.io/pypi/v/cmodel.svg)](https://pypi.org/project/cmodel)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cmodel.svg)](https://pypi.org/project/cmodel)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Model C structs with Pydantic

cmodel-0.0.1/README.md

@@ -0,0 +1,7 @@
+# CModel
+
+[![PyPI - Version](https://img.shields.io/pypi/v/cmodel.svg)](https://pypi.org/project/cmodel)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cmodel.svg)](https://pypi.org/project/cmodel)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Model C structs with Pydantic

cmodel-0.0.1/pyproject.toml

@@ -0,0 +1,188 @@
+[build-system]
+requires = ["uv_build>=0.10.3,<0.11.0"]
+build-backend = "uv_build"
+
+[project]
+name = "cmodel"
+version = "0.0.1"
+description = "Model C structs with Pydantic"
+readme = "README.md"
+requires-python = ">=3.12,<4"
+license = { file = "LICENSE.txt" }
+keywords = []
+authors = [{ name = "Ryan Morshead", email = "ryan.morshead@gmail.com" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python",
+]
+dependencies = [
+    "pydantic>=2.12.5",
+    "pydantic-walk-core-schema>=1.0.0",
+]
+[project.urls]
+Source = "https://github.com/rmorshea/cmodel"
+
+[dependency-groups]
+dev = [
+    { include-group = "util" },
+    { include-group = "docs" },
+    { include-group = "lint" },
+    { include-group = "test" },
+]
+util = [
+    "click==8.1.7",
+    "ipykernel==6.29.5",
+    "copier==9.4.1",
+]
+docs = [
+    { include-group = "test" },
+    "mkdocs-gen-files==0.5.0",
+    "mkdocs-literate-nav==0.6.1",
+    "mkdocs-material==9.5.39",
+    "mkdocs-open-in-new-tab==1.0.5",
+    "mkdocs==1.6.1",
+    "mkdocstrings-python==1.16.12",
+]
+lint = [
+    { include-group = "test" },
+    "mdformat-admon @ git+https://github.com/rmorshea/mdformat-admon.git@0e513d7a2c265faf74441938ccbd1010660609f4",
+    "mdformat-mkdocs==4.1.0",
+    "mdformat-pyproject==0.0.1",
+    "mdformat-tables==1.0.0",
+    "mdformat==0.7.22",
+    "pyright==1.1.389",
+    "ruff==0.7.3",
+    "yamlfix==1.17.0",
+    "doccmd==2024.11.14",
+    "deptry==0.24.0",
+]
+test = [
+    "coverage[toml]==7.6.1",
+    "diff-cover==9.2.0",
+    "pycobertura==3.3.2",
+    "pytest-asyncio==0.24.0",
+    "pytest-examples==0.0.13",
+    "pytest==8.3.3",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+python_files = ["test_*.py", "*_test.py", "test/*.py", "tests/**/*.py", "test.py"]
+filterwarnings = ["error"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.format]
+docstring-code-format = true
+quote-style = "double"
+indent-style = "space"
+
+[tool.ruff.lint]
+preview = true
+select = ["ALL"]
+ignore = [
+    "A005",   # Module shadowing built-in
+    "ANN",    # Let pyright handle annotations
+    "ANN401", # Allow Any type hints
+    "ARG005", # Unused lambda argument
+    "B027",   # Allow non-abstract empty methods in abstract base classes
+    "B039",   # Mutable default for contextvars
+    "C901",   # Ignore complexity
+    "COM812", # Trailing comma
+    "CPY001", # Copyright at top of file
+    "D100",   # Docstring for module
+    "D104",   # Ignore missing docstring for __init__.py
+    "D105",   # Docstring for magic method
+    "D107",   # Docstring for __init__ method
+    "D203",   # One blank line before class
+    "D213",   # Multi-line docstring summary second line
+    "D407",   # Docstring dashes under section names
+    "D413",   # Docstring blank line after last section
+    "DOC201", # Return type documentation
+    "DOC402", # Yield type documentation
+    "DOC501", # Ignore raises missing from docstring
+    "ERA001", # Commented out code
+    "FBT003", # Allow boolean positional values in function calls, like `dict.get(... True)`
+    "PL",     # PyLint
+    "PYI",    # Stub files
+    "RET503", # Explicit return
+    "RET505", # Unnecessary return statement after return
+    "S105",   # Ignore checks for possible passwords
+    "SIM117", # Use a single `with` statement
+    "ISC001", # implicitly concatenated strings on a single line
+]
+unfixable = [
+    "COM819", # Trailing comma
+]
+fixable = ["ALL"]
+extend-safe-fixes = ["TCH"]
+[tool.ruff.lint.isort]
+known-first-party = ["cmodel"]
+force-single-line = true
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+[tool.ruff.lint.per-file-ignores]
+"{*_test.py,conftest.py,**/test/*.py,test.py}" = [
+    "ARG001",  # Unused argument (pytest fixtures)
+    "PLC2701", # Private imports
+    "RUF029",  # Async functions without await
+    "S101",    # Assert statements
+    "D",       # Docstrings
+    "ANN",     # Type annotations
+]
+"**.ipynb" = [
+    "T201", # Print statements
+]
+"docs/**" = [
+    "INP001", # Implicit namespace package
+    "D",      # Docstrings
+]
+"doccmd_*.py" = [
+    "ANN",    # Type annotations
+    "B018",   # Useless expression
+    "FA102",  # Unsafe __futures__ annotations usage
+    "RUF029", # No await in async function
+    "S101",   # Assert statements
+    "S106",   # Possible passwords
+    "SIM115", # Use context manager for opening files
+    "T201",   # Print
+    "TCH002", # Move third-party import into a type-checking block
+]
+
+[tool.yamlfix]
+line_length = 100
+
+[tool.coverage.run]
+source_pkgs = ["cmodel", "tests"]
+branch = true
+omit = []
+
+[tool.coverage.paths]
+cmodel = ["python"]
+tests = ["tests"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "# nocov",
+    "@overload",
+    "if TYPE_CHECKING:",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    'if __name__ == .__main__.:',
+    '\.\.\.\n($|\s*#.*)',
+]
+show_missing = true
+skip_covered = true
+sort = "Name"
+
+[tool.diff_cover]
+compare_branch = "origin/main"
+fail_under = 100
+include_untracked = true
+
+[tool.uv.build-backend]
+module-name = "cmodel"
+module-root = "python"
+source-exclude = ["test", "tests", "conftest.py", "*_test.py", "test_*.py"]

cmodel-0.0.1/python/cmodel/__init__.py

@@ -0,0 +1,11 @@
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version
+
+from cmodel import types as types
+from cmodel.base import CFmt as CFmt
+from cmodel.base import CModel as CModel
+
+try:
+    __version__ = version(__name__)
+except PackageNotFoundError:  # nocov
+    __version__ = "0.0.0"

cmodel-0.0.1/python/cmodel/base.py

@@ -0,0 +1,206 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from io import BytesIO
+from struct import calcsize
+from struct import pack
+from struct import unpack_from
+from typing import Any
+from typing import ClassVar
+from typing import Literal
+from typing import Self
+from typing import TypedDict
+from typing import overload
+
+from pydantic import BaseModel
+from pydantic import GetCoreSchemaHandler
+from pydantic import SerializationInfo
+from pydantic import ValidationInfo
+from pydantic import model_validator
+from pydantic_core import core_schema as cs
+from pydantic_walk_core_schema import walk_core_schema
+
+
+class CModel(BaseModel):
+    """Base class for models that can be packed/unpacked to/from C binary data."""
+
+    c_field_formats: ClassVar[tuple[str, ...]] = ()
+    """The struct format strings for each field used to pack/unpack the C binary data."""
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls,
+        source: Any,
+        handler: GetCoreSchemaHandler,
+    ) -> cs.CoreSchema:
+        try:
+            CModel  # type:ignore[reportUnusedExpression] # noqa: B018
+        except NameError:
+            # we're defining the schema for this class - just return it
+            return handler(source)
+        else:
+            # we're defining the schema for a subclass
+            adapter = _ModelSchemaAdapter(handler)
+            schema = adapter.adapt(handler(source))
+            cls.c_format = tuple(adapter.format)
+            return schema
+
+    @classmethod
+    def c_unpack(cls, buffer: BytesIO) -> Self:
+        """Read a C binary data buffer as a packed struct and return an instance of the model."""
+        ctx: _Context = {"io": buffer}
+        return cls.model_validate(_USE_BUFFER, context={_CONTEXT_KEY: ctx})
+
+    def c_pack(self, buffer: BytesIO) -> None:
+        """Write the model instance to a C binary data buffer as a packed struct."""
+        ctx: _Context = {"io": buffer}
+        self.model_dump(context={_CONTEXT_KEY: ctx})
+
+    @model_validator(mode="before")
+    @classmethod
+    def _validate_model(cls, value: Any) -> Any:
+        if value is _USE_BUFFER:
+            # Indicate that we're unpacking by ensuring each field is present and gets "validated".
+            # The validator for each field will then read from the buffer.
+            return dict.fromkeys(cls.model_fields, _USE_BUFFER)
+        else:
+            return value
+
+
+@dataclass
+class CFmt[T]:
+    """Metadata for a C field, used in the Annotated type of each field in a CModel."""
+
+    fmt: str
+    validate: Callable[[tuple[Any, ...]], T] = lambda x: x  # pyright: ignore[reportAssignmentType]
+    dump: Callable[[T], tuple[Any, ...]] = lambda x: x  # pyright: ignore[reportAssignmentType]
+
+    def __get_pydantic_core_schema__(
+        self,
+        source: Any,
+        handler: GetCoreSchemaHandler,
+    ) -> cs.CoreSchema:
+        fmt = self.fmt
+        size = calcsize(fmt)
+        validate = self.validate
+        dump = self.dump
+
+        def validator(value: Any, info: ValidationInfo) -> Any:
+            if value is _USE_BUFFER:
+                ctx = _get_context(info, required=True)
+                io = ctx["io"]
+                value = unpack_from(fmt, io.getbuffer(), io.tell())
+                io.seek(size, 1)
+                return validate(value)
+            else:
+                return value
+
+        def serializer(value: Any, info: SerializationInfo) -> Any:
+            if ctx := _get_context(info):
+                ctx["io"].write(pack(fmt, *dump(value)))
+            else:
+                return value
+
+        return cs.with_info_before_validator_function(
+            validator,
+            schema=handler(source),
+            metadata={_METADATA_KEY: self},
+            serialization=cs.plain_serializer_function_ser_schema(serializer, info_arg=True),
+        )
+
+
+_USE_BUFFER = object()
+
+
+type _Recurse = Callable[[cs.CoreSchema, _Recurse], cs.CoreSchema]
+
+
+class _ModelSchemaAdapter:
+    _VISIT_TYPES: ClassVar[set[cs.CoreSchemaType]] = {
+        "tuple",
+    }
+    _ALLOWED_TYPES: ClassVar[set[cs.CoreSchemaType]] = {
+        "model",
+        "model-fields",
+        "function-before",
+        "default",
+    }
+
+    def __init__(self, handler: GetCoreSchemaHandler) -> None:
+        self.handler = handler
+        self.format: list[str] = []
+        self.visitors: dict[str, _Recurse] = {}
+        for schema_type in self._VISIT_TYPES:
+            method_name = f"visit_{schema_type.replace('-', '_')}"
+            self.visitors[schema_type] = getattr(self, method_name)
+
+    def adapt(self, schema: cs.CoreSchema) -> cs.CoreSchema:
+        return walk_core_schema(schema, self.visit)
+
+    def visit(self, schema: cs.CoreSchema, recurse: _Recurse) -> cs.CoreSchema:
+        if _get_metadata(schema):
+            return schema
+        schema_type = schema["type"]
+        visit_fn = self.visitors.get(schema_type)
+        if visit_fn is not None:
+            return visit_fn(schema, recurse)
+        elif schema_type in self._ALLOWED_TYPES:
+            return recurse(schema, self.visit)
+        else:
+            msg = f"Unsupported schema type {schema['type']!r} in CModel"
+            raise TypeError(msg)
+
+    def visit_tuple(self, schema: cs.TupleSchema, recurse: _Recurse) -> cs.CoreSchema:
+        if schema.get("variadic_item_index") is not None:
+            msg = "CModel does not support variadic tuples"
+            raise ValueError(msg)
+
+        size = len(schema["items_schema"])
+        use_buffer = (_USE_BUFFER,) * size
+
+        def before_validator(value: Any) -> Any:
+            if value is _USE_BUFFER:
+                return use_buffer
+            else:
+                return value
+
+        return cs.no_info_before_validator_function(
+            before_validator,
+            schema=recurse(schema, self.visit),
+        )
+
+    def visit_model(self, schema: cs.ModelSchema, recurse: _Recurse) -> cs.CoreSchema:
+        return recurse(schema, self.visit)
+
+
+class _Context(TypedDict):
+    io: BytesIO
+
+
+@overload
+def _get_context(
+    info: ValidationInfo | SerializationInfo, *, required: Literal[True]
+) -> _Context: ...
+
+
+@overload
+def _get_context(
+    info: ValidationInfo | SerializationInfo, *, required: bool = ...
+) -> _Context | None: ...
+
+
+def _get_context(
+    info: ValidationInfo | SerializationInfo, *, required: bool = False
+) -> _Context | None:
+    ctx = info.context.get(_CONTEXT_KEY) if isinstance(info.context, dict) else None
+    if ctx is None and required:
+        msg = "Context is required for CModel packing/unpacking"
+        raise ValueError(msg)
+    return ctx
+
+
+def _get_metadata(schema: cs.CoreSchema) -> CFmt:
+    return schema.get("metadata", {}).get(_METADATA_KEY, {})
+
+
+_CONTEXT_KEY = "cmodel"
+_METADATA_KEY = "cmodel"

cmodel-0.0.1/python/cmodel/py.typed

@@ -0,0 +1 @@
+PEP-561

cmodel-0.0.1/python/cmodel/types.py

@@ -0,0 +1,94 @@
+import operator
+from collections.abc import Callable
+from typing import Annotated as An
+from uuid import UUID
+
+from cmodel.base import CFmt
+
+
+def _make_one_or_many[T](_: type[T], fmt: str) -> Callable[[int], CFmt[T]]:
+    return lambda count: (
+        CFmt[T](fmt, operator.itemgetter(0), lambda x: (x,))
+        if count == 1
+        else CFmt[T](fmt=f"{count}{fmt}")  # pyright: ignore[reportArgumentType]
+    )
+
+
+c_signed_char = _make_one_or_many(int, "b")
+"""CFormat for one or more signed chars. For count=1 the value is returned as an int."""
+SignedChar = An[int, c_signed_char(1)]
+"""C format for a single signed char."""
+
+c_unsigned_char = _make_one_or_many(int, "B")
+"""CFormat for one or more unsigned chars. For count=1 the value is returned as an int."""
+UnsignedChar = An[int, c_unsigned_char(1)]
+"""C format for a single unsigned char."""
+
+c_bool = _make_one_or_many(bool, "?")
+"""CFormat for one or more bools. For count=1 the value is returned as a bool."""
+Bool = An[bool, c_bool(1)]
+"""C format for a single bool."""
+
+c_short = _make_one_or_many(int, "h")
+"""CFormat for one or more shorts. For count=1 the value is returned as an int."""
+Short = An[int, c_short(1)]
+"""C format for a single short."""
+
+c_unsigned_short = _make_one_or_many(int, "H")
+"""CFormat for one or more unsigned shorts. For count=1 the value is returned as an int."""
+UnsignedShort = An[int, c_unsigned_short(1)]
+"""C format for a single unsigned short."""
+
+c_int = _make_one_or_many(int, "i")
+"""CFormat for one or more ints. For count=1 the value is returned as an int."""
+Int = An[int, c_int(1)]
+"""C format for a single int."""
+
+c_unsigned_int = _make_one_or_many(int, "I")
+"""CFormat for one or more unsigned ints. For count=1 the value is returned as an int."""
+UnsignedInt = An[int, c_unsigned_int(1)]
+"""C format for a single unsigned int."""
+
+c_long = _make_one_or_many(int, "l")
+"""CFormat for one or more longs. For count=1 the value is returned as an int."""
+Long = An[int, c_long(1)]
+"""C format for a single long."""
+
+c_unsigned_long = _make_one_or_many(int, "L")
+"""CFormat for one or more unsigned longs. For count=1 the value is returned as an int."""
+UnsignedLong = An[int, c_unsigned_long(1)]
+"""C format for a single unsigned long."""
+
+c_float = _make_one_or_many(float, "f")
+"""CFormat for one or more floats. For count=1 the value is returned as a float."""
+Float = An[float, c_float(1)]
+"""C format for a single float."""
+
+c_double = _make_one_or_many(float, "d")
+"""CFormat for one or more doubles. For count=1 the value is returned as a float."""
+Double = An[float, c_double(1)]
+"""C format for a single double."""
+
+c_complex_float = _make_one_or_many(complex, "F")
+"""CFormat for one or more complex floats. For count=1 the value is returned as a complex."""
+ComplexFloat = An[complex, c_complex_float(1)]
+"""C format for a single complex float."""
+
+c_complex_double = _make_one_or_many(complex, "D")
+"""CFormat for one or more complex doubles. For count=1 the value is returned as a complex."""
+ComplexDouble = An[complex, c_complex_double(1)]
+"""C format for a single complex double."""
+
+
+def c_uuid() -> CFmt[UUID]:
+    """CFormat for a UUID, represented as a 16-byte array."""
+    return CFmt(fmt="16s", validate=lambda x: UUID(bytes=x[0]), dump=lambda x: (x.bytes,))
+
+
+Uuid = An[UUID, c_uuid()]
+"""C format for a single UUID."""
+
+
+def c_char(count: int) -> CFmt:
+    """CFormat for a char array of the given count."""
+    return CFmt(fmt=f"{count}s", validate=operator.itemgetter(0), dump=lambda x: (x,))