bytespec 0.1.0__tar.gz

bytespec-0.1.0/LICENSE

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

bytespec-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: bytespec
+Version: 0.1.0
+Summary: Declarative binary serialization and deserialization for Python
+Keywords: binary,serialization,deserialization,codec,protocol
+Author: ink-developer
+Author-email: ink-developer <142109011+ink-developer@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: typing-extensions>=4.16.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/ink-developer/bytespec
+Project-URL: Repository, https://github.com/ink-developer/bytespec
+Project-URL: Issues, https://github.com/ink-developer/bytespec/issues
+Project-URL: Documentation, https://bytespec.pymax.org
+Description-Content-Type: text/markdown
+
+# bytespec
+
+English · [Русский](README.md)
+
+Typed Python models over an explicit sequential binary representation.
+One model reads and writes numbers, strings, lists, and nested objects;
+you choose their representation, and the library tracks lengths and offsets.
+
+```python
+from bytespec import Constructor, PayloadLength, ProtoModel, field
+from bytespec.types import UInt32
+
+
+class User(ProtoModel):
+    __constructor__ = 0x12
+    __header__ = (Constructor(1), PayloadLength(1))
+
+    id: UInt32
+    name: str = field(prefix_length=1)
+
+
+user = User(id=42, name="Anna")
+data = user.encode()
+restored = User.decode(data)
+
+print(data.hex(" "))  # 12 09 00 00 00 2a 04 41 6e 6e 61
+print(restored.name)  # Anna
+assert restored == user
+```
+
+`12` identifies the message; `09` is the computed length of its fields.
+Next come the four-byte `id` and a UTF-8 name with a one-byte length prefix.
+In your application, these are ordinary `int` and `str` values. Your first
+models can use the default framing without setting `__header__`; for an
+existing format, you can customize or remove it.
+
+bytespec fits custom or existing sequential binary protocols when you want
+to work with classes without a separate schema language or code generation.
+It supports optional fields through flags, `IntEnum`, UUID, datetime, numeric
+encodings, and custom codecs. This is a small 0.1.0 library: for a flexible
+binary parser DSL, consider Construct; for standard JSON/MessagePack, msgspec;
+for a schema ecosystem with its own wire format, protobuf.
+
+## Installation
+
+Python 3.10+:
+
+```bash
+pip install bytespec
+```
+
+Or `uv add bytespec`.
+
+## Documentation
+
+The full guide and API reference are available in Russian and English.
+To build both versions from a checkout:
+
+```bash
+uv sync --locked --group docs
+uv run --no-sync python -m sphinx -E -a -n -W --keep-going -b html -D language=ru docs docs/_build/html/ru
+uv run --no-sync python -m sphinx -E -a -n -W --keep-going -b html -D language=en docs docs/_build/html/en
+```
+
+Open `docs/_build/html/en/index.html`. The language switcher keeps you on
+the same page. Start with **Getting started**, **Why bytespec?**, or
+**Headers and framing**, then consult the **API reference**.
+The [documentation sources](docs/index.rst) and
+[build instructions](docs/building.rst) are in Russian; Sphinx applies
+the [English translation catalogs](docs/locale/en/LC_MESSAGES/index.po)
+when building the English version.
+
+Take a known packet from your protocol, describe a few fields, and compare
+the re-encoded result with the original bytes. That is a useful first check
+of whether the library fits your format.
+
+[MIT license](LICENSE).

bytespec-0.1.0/README.md

@@ -0,0 +1,77 @@
+# bytespec
+
+English · [Русский](README.md)
+
+Typed Python models over an explicit sequential binary representation.
+One model reads and writes numbers, strings, lists, and nested objects;
+you choose their representation, and the library tracks lengths and offsets.
+
+```python
+from bytespec import Constructor, PayloadLength, ProtoModel, field
+from bytespec.types import UInt32
+
+
+class User(ProtoModel):
+    __constructor__ = 0x12
+    __header__ = (Constructor(1), PayloadLength(1))
+
+    id: UInt32
+    name: str = field(prefix_length=1)
+
+
+user = User(id=42, name="Anna")
+data = user.encode()
+restored = User.decode(data)
+
+print(data.hex(" "))  # 12 09 00 00 00 2a 04 41 6e 6e 61
+print(restored.name)  # Anna
+assert restored == user
+```
+
+`12` identifies the message; `09` is the computed length of its fields.
+Next come the four-byte `id` and a UTF-8 name with a one-byte length prefix.
+In your application, these are ordinary `int` and `str` values. Your first
+models can use the default framing without setting `__header__`; for an
+existing format, you can customize or remove it.
+
+bytespec fits custom or existing sequential binary protocols when you want
+to work with classes without a separate schema language or code generation.
+It supports optional fields through flags, `IntEnum`, UUID, datetime, numeric
+encodings, and custom codecs. This is a small 0.1.0 library: for a flexible
+binary parser DSL, consider Construct; for standard JSON/MessagePack, msgspec;
+for a schema ecosystem with its own wire format, protobuf.
+
+## Installation
+
+Python 3.10+:
+
+```bash
+pip install bytespec
+```
+
+Or `uv add bytespec`.
+
+## Documentation
+
+The full guide and API reference are available in Russian and English.
+To build both versions from a checkout:
+
+```bash
+uv sync --locked --group docs
+uv run --no-sync python -m sphinx -E -a -n -W --keep-going -b html -D language=ru docs docs/_build/html/ru
+uv run --no-sync python -m sphinx -E -a -n -W --keep-going -b html -D language=en docs docs/_build/html/en
+```
+
+Open `docs/_build/html/en/index.html`. The language switcher keeps you on
+the same page. Start with **Getting started**, **Why bytespec?**, or
+**Headers and framing**, then consult the **API reference**.
+The [documentation sources](docs/index.rst) and
+[build instructions](docs/building.rst) are in Russian; Sphinx applies
+the [English translation catalogs](docs/locale/en/LC_MESSAGES/index.po)
+when building the English version.
+
+Take a known packet from your protocol, describe a few fields, and compare
+the re-encoded result with the original bytes. That is a useful first check
+of whether the library fits your format.
+
+[MIT license](LICENSE).

bytespec-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "bytespec"
+version = "0.1.0"
+description = "Declarative binary serialization and deserialization for Python"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "ink-developer", email = "142109011+ink-developer@users.noreply.github.com" }
+]
+requires-python = ">=3.10"
+
+dependencies = [
+    "typing-extensions>=4.16.0",
+]
+
+keywords = [
+    "binary",
+    "serialization",
+    "deserialization",
+    "codec",
+    "protocol",
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/ink-developer/bytespec"
+Repository = "https://github.com/ink-developer/bytespec"
+Issues = "https://github.com/ink-developer/bytespec/issues"
+Documentation = "https://bytespec.pymax.org"
+
+[build-system]
+requires = ["uv_build>=0.11.4,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.18",
+    "ruff>=0.13",
+]
+test = [
+    "pytest>=9.1.1",
+]
+docs = [
+    "construct>=2.10.70,<2.11",
+    "furo>=2025.12.19",
+    "sphinx>=8.1.3",
+    "sphinx-copybutton>=0.5.2",
+    "sphinx-intl>=2.4.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

bytespec-0.1.0/src/bytespec/__init__.py

@@ -0,0 +1,21 @@
+# Copyright (c) 2026 ink-developer
+
+__version__ = "0.1.0"
+
+from .core import ProtoModel, field
+from .enums import ByteOrder
+from .errors import BytespecError, DecodeError, EncodeError, SchemaError
+from .headers import Constructor, Flags, PayloadLength
+
+__all__ = [
+    "ByteOrder",
+    "BytespecError",
+    "Constructor",
+    "DecodeError",
+    "EncodeError",
+    "Flags",
+    "PayloadLength",
+    "ProtoModel",
+    "SchemaError",
+    "field",
+]

bytespec-0.1.0/src/bytespec/base.py

@@ -0,0 +1,52 @@
+# Copyright (c) 2026 ink-developer
+
+from types import NoneType, UnionType
+from typing import Annotated, Any, ClassVar, Final, Union, get_args, get_origin
+
+from bytespec.enums import ByteOrder
+from bytespec.headers import Constructor, Flags, HeaderElement, PayloadLength
+from bytespec.resolvers import CodecFactory
+from bytespec.schema import ModelSchema
+
+DEFAULT_HEADER: Final[tuple[HeaderElement, ...]] = (Constructor(2), Flags(8), PayloadLength(4))
+
+
+class ProtoModelBase:
+    __constructor__: int = 0x1
+    __byte_order__: ByteOrder = ByteOrder.BIG
+    __header__: ClassVar[tuple[HeaderElement, ...]] = DEFAULT_HEADER
+    __schema__: ModelSchema
+
+    @classmethod
+    def _is_valid_value(cls, value: Any, annotation: Any) -> bool:
+        origin = get_origin(annotation)
+
+        if origin is Annotated:
+            base_type, *_ = get_args(annotation)
+            return cls._is_valid_value(value, base_type)
+
+        if origin in (Union, UnionType):
+            return any(
+                (arg is NoneType and value is None)
+                or (arg is not NoneType and cls._is_valid_value(value, arg))
+                for arg in get_args(annotation)
+            )
+
+        if origin is list:
+            return isinstance(value, list)
+
+        return isinstance(value, annotation)
+
+    @classmethod
+    def configure_codecs(cls) -> dict[type, CodecFactory]:
+        """Define additional codec selection rules for field types.
+
+        Override this classmethod in the model. Rules apply at class declaration, extending
+        inherited rules and replacing matching keys.
+
+        Returns:
+            A mapping from Python types to codec factories. A factory receives the annotation and
+            ``FieldInfo`` and returns a ready-to-use codec instance. There are no additional rules
+            by default.
+        """
+        return {}

bytespec-0.1.0/src/bytespec/codecs/__init__.py

@@ -0,0 +1,48 @@
+# Copyright (c) 2026 ink-developer
+
+from .base import ICodec
+from .bool import BoolCodec
+from .bytes import BytesCodec, FixedBytesCodec
+from .datetime import DatetimeCodec
+from .enum import EnumCodec
+from .float import Float32Codec, Float64Codec
+from .int import (
+    Int8Codec,
+    Int16Codec,
+    Int32Codec,
+    Int64Codec,
+    UInt8Codec,
+    UInt16Codec,
+    UInt32Codec,
+    UInt64Codec,
+)
+from .list import ListCodec
+from .model import ModelCodec
+from .str import StrCodec
+from .uuid import UUIDCodec
+from .varint import VarIntCodec, VarUIntCodec
+
+__all__ = [
+    "BoolCodec",
+    "BytesCodec",
+    "DatetimeCodec",
+    "EnumCodec",
+    "FixedBytesCodec",
+    "Float32Codec",
+    "Float64Codec",
+    "ICodec",
+    "Int8Codec",
+    "Int16Codec",
+    "Int32Codec",
+    "Int64Codec",
+    "ListCodec",
+    "ModelCodec",
+    "StrCodec",
+    "UInt8Codec",
+    "UInt16Codec",
+    "UInt32Codec",
+    "UInt64Codec",
+    "UUIDCodec",
+    "VarIntCodec",
+    "VarUIntCodec",
+]

bytespec-0.1.0/src/bytespec/codecs/_utils.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2026 ink-developer
+
+from bytespec.errors import DecodeError
+
+
+def check_available(buffer: bytes, offset: int, size: int, *, codec: str) -> None:
+    if offset < 0:
+        raise ValueError(f"offset must be non-negative, got {offset}")
+    if size < 0:
+        raise ValueError(f"size must be non-negative, got {size}")
+
+    available = max(0, len(buffer) - offset)
+    if available < size:
+        raise DecodeError(
+            f"{codec} at offset {offset}: expected {size} bytes, available {available}"
+        )

bytespec-0.1.0/src/bytespec/codecs/base.py

@@ -0,0 +1,60 @@
+# Copyright (c) 2026 ink-developer
+
+from typing import Any, Generic, Protocol, TypeVar
+
+from typing_extensions import runtime_checkable
+
+from bytespec.enums import ByteOrder
+
+T = TypeVar("T")
+
+
+@runtime_checkable
+class ICodec(Protocol, Generic[T]):
+    """Interface for writing and reading a single value of type T.
+
+    An instance can be passed to ``field(codec=...)``. Inheriting from ICodec is optional: encode
+    and decode methods that follow this contract are sufficient. A codec can be reused; the read
+    position is passed through offset.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__()
+
+    def encode(self, value: T, byte_order: ByteOrder, /) -> bytes:
+        """Write a single value in the selected representation.
+
+        Args:
+            value: The value to write.
+            byte_order: The byte order of fixed-width numbers and prefixes.
+
+        Returns:
+            The binary representation of the value.
+
+        Raises:
+            EncodeError: The value cannot be represented. A custom codec must raise this error
+                itself for data errors.
+        """
+        ...
+
+    def decode(self, buffer: bytes, byte_order: ByteOrder, offset: int, /) -> tuple[T, int]:
+        """Read a single value starting at offset.
+
+        Args:
+            buffer: The buffer containing the encoded value.
+            byte_order: The byte order of fixed-width numbers and prefixes.
+            offset: The nonnegative absolute position where the value starts.
+
+        Returns:
+            The value and the absolute position after it in the same buffer. The remaining bytes do
+            not have to be consumed.
+
+        Raises:
+            DecodeError: There are not enough bytes, or the value is invalid. The implementation
+                must check bounds and contents itself.
+
+        Note:
+            A list item codec must advance offset by a positive number of bytes while staying within
+            the supplied buffer.
+        """
+        ...

bytespec-0.1.0/src/bytespec/codecs/bool.py

@@ -0,0 +1,45 @@
+# Copyright (c) 2026 ink-developer
+
+import struct
+
+from typing_extensions import override
+
+from bytespec.codecs import ICodec
+from bytespec.enums import ByteOrder
+from bytespec.errors import DecodeError
+
+from ._utils import check_available
+
+
+class BoolCodec(ICodec[bool]):
+    """A Boolean value in one byte: 0 or 1."""
+
+    @override
+    def encode(
+        self,
+        value: bool,
+        byte_order: ByteOrder,
+    ) -> bytes:
+        """Write the truth value of value as 0/1 without strict type checking."""
+        return struct.pack(byte_order.value + "B", 1 if value else 0)
+
+    @override
+    def decode(
+        self,
+        buffer: bytes,
+        byte_order: ByteOrder,
+        offset: int,
+    ) -> tuple[bool, int]:
+        """Read a bool and return it with its absolute end offset.
+
+        Raises:
+            DecodeError: The byte is missing or is neither 0 nor 1.
+            ValueError: Negative offset.
+        """
+        check_available(buffer, offset, 1, codec=type(self).__name__)
+        value = struct.unpack_from(byte_order.value + "B", buffer, offset)[0]
+
+        if value not in (0, 1):
+            raise DecodeError(f"BoolCodec at offset {offset}: invalid bool value {value}")
+
+        return bool(value), offset + 1

bytespec-0.1.0/src/bytespec/codecs/bytes.py

@@ -0,0 +1,105 @@
+# Copyright (c) 2026 ink-developer
+
+from typing_extensions import override
+
+from bytespec.codecs import ICodec
+from bytespec.enums import ByteOrder
+from bytespec.errors import EncodeError, SchemaError
+from bytespec.models import PrefixLength
+
+from ._utils import check_available
+from .map import UINT_CODEC_MAPPING
+
+
+class BytesCodec(ICodec[bytes]):
+    """Bytes prefixed with their length.
+
+    Args:
+        prefix_length: Prefix size: 1, 2, 4, or 8 bytes, or ``VarUInt``. Defaults to 4 bytes. The
+            prefix itself is not included in the stored length.
+
+    Raises:
+        SchemaError: Unsupported prefix, including ``VarInt``.
+    """
+
+    def __init__(self, prefix_length: PrefixLength = 4) -> None:
+        self.prefix_length = prefix_length
+
+        codec = UINT_CODEC_MAPPING.get(prefix_length)
+        if codec is None:
+            raise SchemaError(f"BytesCodec: invalid length prefix {prefix_length!r}")
+
+        self.codec = codec
+
+        super().__init__()
+
+    @override
+    def encode(self, value: bytes, byte_order: ByteOrder) -> bytes:
+        """Write the length of value followed by the bytes themselves.
+
+        Raises:
+            EncodeError: The length does not fit in the selected prefix.
+        """
+        return self.codec.encode(len(value), byte_order) + value
+
+    @override
+    def decode(self, buffer: bytes, byte_order: ByteOrder, offset: int) -> tuple[bytes, int]:
+        """Read the prefix and return the bytes with their absolute end offset.
+
+        Raises:
+            DecodeError: The prefix or declared data is incomplete or invalid.
+            ValueError: Negative offset.
+        """
+        length, start = self.codec.decode(buffer, byte_order, offset)
+        end = start + length
+
+        check_available(buffer, start, length, codec=type(self).__name__)
+
+        return buffer[start:end], end
+
+
+class FixedBytesCodec(BytesCodec):
+    """Exactly length bytes without a length prefix.
+
+    Args:
+        length: The nonnegative fixed size of the value.
+
+    Raises:
+        SchemaError: Negative length.
+    """
+
+    def __init__(self, length: int) -> None:
+        if length < 0:
+            raise SchemaError(f"FixedBytesCodec: length must be non-negative, got {length}")
+        self.length = length
+
+    @override
+    def encode(self, value: bytes, byte_order: ByteOrder) -> bytes:
+        """Return value after checking its length; byte order has no effect.
+
+        Raises:
+            EncodeError: The size of value is not equal to length.
+        """
+        if len(value) != self.length:
+            raise EncodeError(f"FixedBytesCodec: expected {self.length} bytes, got {len(value)}")
+
+        return value
+
+    @override
+    def decode(
+        self,
+        buffer: bytes,
+        byte_order: ByteOrder,
+        offset: int,
+    ) -> tuple[bytes, int]:
+        """Read length bytes and return them with their absolute end offset.
+
+        Raises:
+            DecodeError: There are not enough bytes.
+            ValueError: Negative offset.
+        """
+        end = offset + self.length
+
+        check_available(buffer, offset, self.length, codec=type(self).__name__)
+
+        return buffer[offset:end], end

bytespec-0.1.0/src/bytespec/codecs/datetime.py

@@ -0,0 +1,59 @@
+# Copyright (c) 2026 ink-developer
+
+from datetime import datetime
+
+from typing_extensions import override
+
+from bytespec.codecs import ICodec
+from bytespec.enums import ByteOrder
+from bytespec.errors import DecodeError
+from bytespec.models import PrefixLength
+
+from .str import StrCodec
+
+
+class DatetimeCodec(ICodec[datetime]):
+    """A datetime as a length-prefixed ISO 8601 string.
+
+    Preserves the UTC offset from isoformat(), but not the time zone name. A datetime without tzinfo
+    remains naive after reading.
+
+    Args:
+        prefix_length: Prefix size: 1, 2, 4, or 8 bytes, or ``VarUInt``.
+        encoding: Encoding of the ISO string, UTF-8 by default.
+
+    Raises:
+        SchemaError: Unsupported prefix or unknown encoding.
+    """
+
+    def __init__(self, prefix_length: PrefixLength = 4, encoding: str = "utf-8") -> None:
+        self.codec = StrCodec(prefix_length, encoding=encoding)
+
+    @override
+    def encode(self, value: datetime, byte_order: ByteOrder) -> bytes:
+        """Write value.isoformat() as a length-prefixed string.
+
+        Raises:
+            EncodeError: The string cannot be represented in the encoding, or its length does not
+                fit in the prefix.
+            SchemaError: The selected codec is not a text encoding.
+        """
+        return self.codec.encode(value.isoformat(), byte_order)
+
+    @override
+    def decode(self, buffer: bytes, byte_order: ByteOrder, offset: int) -> tuple[datetime, int]:
+        """Restore a datetime and return it with its absolute end offset.
+
+        Raises:
+            DecodeError: There are not enough bytes, or the string or ISO date is invalid.
+            SchemaError: The selected codec is not a text encoding.
+            ValueError: Negative offset.
+        """
+        value, end = self.codec.decode(buffer, byte_order, offset)
+        try:
+            decoded = datetime.fromisoformat(value)
+        except ValueError as exc:
+            raise DecodeError(
+                f"DatetimeCodec at offset {offset}: invalid datetime {value!r}"
+            ) from exc
+        return decoded, end