bytestruct 0.1.0__tar.gz

bytestruct-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,60 @@
+name: docs
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "bytestruct/**"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "bytestruct/**"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools_scm derives the version from the tags.
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[docs]"
+      - name: Build (strict)
+        run: python -m mkdocs build --strict
+      - name: Upload site artifact
+        if: github.ref == 'refs/heads/master'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    # Only deploy from master; PRs just run the strict build above as a check.
+    if: github.ref == 'refs/heads/master'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

bytestruct-0.1.0/.github/workflows/python-app.yml

@@ -0,0 +1,73 @@
+name: Python application
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+  release:
+    types: [ created ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    if: '! github.event.pull_request.draft'
+    runs-on: ${{ matrix.os }}
+
+    # Pin uv to the interpreter it provisioned instead of an already-installed system Python.
+    env:
+      UV_PYTHON_PREFERENCE: only-managed
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.15 is a prerelease (uv resolves it to the latest beta).
+        python-version: [ "3.9", "3.10", "3.11", "3.12", "3.13", "3.14", "3.15" ]
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools_scm derives the version from the tags.
+          fetch-depth: 0
+      # uv provisions the interpreter (python-build-standalone): unlike actions/setup-python,
+      # it still provides 3.9 on current runner images (ubuntu-24.04, arm64 macOS).
+      - name: Install uv and Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+      - name: Run pre-commit hooks
+        # pyright needs the project installed; it runs in the dedicated job below.
+        env:
+          SKIP: pyright
+        run: uvx pre-commit run --all-files
+      - name: Run tests
+        run: uv run --extra test pytest
+
+  pyright:
+    if: '! github.event.pull_request.draft'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+      - name: Install dependencies
+        run: |
+          uv venv
+          uv pip install -e ".[test]"
+      # Runs the same pre-commit hook contributors get locally (pinned in .pre-commit-config.yaml).
+      - name: Run pyright
+        run: uvx pre-commit run pyright --all-files

bytestruct-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,29 @@
+# This workflow builds and uploads the Python package to PyPI when a release is created
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [ created ]
+
+jobs:
+  deploy:
+    permissions:
+      id-token: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools_scm needs full history + tags to derive the release version
+          # from the tag; a shallow clone yields a PyPI-rejected local version
+          # like 0.1.dev1+g<hash>.
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Build distributions
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          verbose: true

bytestruct-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.DS_Store
+.idea/
+.venv*/
+venv/
+build/
+dist/
+*.pyc
+__pycache__/
+*.egg-info/
+bytestruct/_version.py
+.python-version
+uv.lock
+site/

bytestruct-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.15.4
+  hooks:
+    # Run the linter.
+    - id: ruff-check
+    # Run the formatter.
+    - id: ruff-format
+- repo: local
+  hooks:
+    # Pinned so local hooks and CI agree; bump deliberately together with fixing any new findings.
+    # Resolves the project's dependencies from .venv (venvPath/venv in pyproject.toml); CI's test
+    # matrix skips this hook (SKIP=pyright) — the dedicated pyright CI job runs it after creating the venv.
+    - id: pyright
+      name: pyright
+      entry: uvx pyright@1.1.411
+      language: system
+      types: [python]
+      pass_filenames: false

bytestruct-0.1.0/LICENSE

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

bytestruct-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: bytestruct
+Version: 0.1.0
+Summary: Declarative binary records and composable codecs, using only the standard library
+Author-email: doronz88 <doron88@gmail.com>
+Maintainer-email: doronz88 <doron88@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/doronz88/bytestruct
+Project-URL: Documentation, https://doronz88.github.io/bytestruct/
+Project-URL: Bug Reports, https://github.com/doronz88/bytestruct/issues
+Keywords: binary,struct,parsing,serialization,dataclasses,construct
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing_extensions>=4.1.0; python_version < "3.11"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; python_version >= "3.10" and extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.26; python_version >= "3.10" and extra == "docs"
+Requires-Dist: mkdocs-llmstxt>=0.5; python_version >= "3.10" and extra == "docs"
+Dynamic: license-file
+
+# bytestruct
+
+[![Python application](https://github.com/doronz88/bytestruct/workflows/Python%20application/badge.svg)](https://github.com/doronz88/bytestruct/actions/workflows/python-app.yml "Python application action")
+[![Pypi version](https://img.shields.io/pypi/v/bytestruct.svg)](https://pypi.org/project/bytestruct/ "PyPi package")
+[![Docs](https://github.com/doronz88/bytestruct/actions/workflows/docs.yml/badge.svg)](https://doronz88.github.io/bytestruct/ "Documentation")
+
+`bytestruct` parses and builds binary wire formats with the standard library alone. Fixed-size records are
+dataclasses whose field annotations give each field's wire type; variable-length data is described by small
+codecs that compose like [construct](https://github.com/construct/construct)'s. Everything is fully typed.
+
+The layout of a record is compiled into `struct.Struct` objects once, when the class is defined, so parsing a
+record is a single `unpack_from` per byte-order run.
+
+**Documentation: <https://doronz88.github.io/bytestruct/>**, including a
+[migration guide from construct](https://doronz88.github.io/bytestruct/migrating-from-construct/).
+
+## Install
+
+```shell
+python3 -m pip install -U bytestruct
+```
+
+## Fixed-size records
+
+```python
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import Annotated
+
+from bytestruct import BinaryStruct, Const, PaddedString, u16, u32
+
+
+class Kind(IntEnum):
+    FILE = 1
+    DIRECTORY = 2
+
+
+@dataclass
+class Header(BinaryStruct, byte_order="<"):
+    magic: Annotated[u32, Const(0x1F3D5B79)] = field(default=0x1F3D5B79, init=False)
+    size: u32
+    name: Annotated[str, PaddedString(16)]
+    kind: Annotated[Kind, u16]  # parsed into the enum type
+
+
+data = Header(size=1024, name="notes.txt", kind=Kind.FILE).build()  # a bad value -> BinaryBuildError
+header = Header.parse(data)  # short input -> TruncatedDataError, wrong magic -> UnexpectedConstantError
+assert header.kind is Kind.FILE
+```
+
+Wire fields are positional `__init__` parameters in wire order. A field declared
+`= field(default=..., init=False)` is left out of `__init__`: parse skips its bytes (padding) and build packs
+its default (on a `Const` field, the constant). Fields without a wire type may follow the wire fields and are
+ignored by parse/build. Records cannot be subclassed.
+
+Available field types include `u8`..`u64`, `i16`..`i64`, byte-order pinned `u32le`/`u32be`, `Bytes(n)`,
+`PaddedString(n)`, `uuid_t`, `ipv4`/`ipv6`, `Array(element, n)`, int-enum fields and `Const` magics; custom
+ones subclass `Format`.
+
+## Codecs
+
+```python
+from bytestruct import CSTRING, U32_LE, U64_LE, Aligned, Prefixed, Switch
+
+STRING = Aligned(4, Prefixed(U32_LE, CSTRING))  # u32 length, NUL-terminated UTF-8, padded to 4 bytes
+OBJECT = Switch(U32_LE, {1: STRING, 2: U64_LE})  # parses to (tag, value)
+
+assert OBJECT.parse(OBJECT.build((1, "hi"))) == (1, "hi")
+```
+
+A codec is anything with `read(reader)` and `build(value)`: the combinators (`Prefixed`, `Aligned`,
+`PrefixedArray`, `Tuple`, `Switch`), the leaves (`CSTRING`, `GREEDY_STRING`, `GREEDY_BYTES`, `PASS`), the
+scalars (`U8`, `U16_LE`/`U16_BE`, ..., `F64_BE`), `Bytes(n)`, and record classes themselves. A record field annotated with a codec
+(`name: Annotated[str, CSTRING]`) makes the record variable-length; such fields follow the fixed-size ones.
+Formats with no declarative shape are read by hand with `ByteReader`, whose sub-readers are windows on the same
+buffer (nothing is copied).
+
+## Errors
+
+Every failure raises a `BinaryDataError` (a `ValueError`): `BinaryParseError` (with `TruncatedDataError` and
+`UnexpectedConstantError`) or `BinaryBuildError`. Errors carry the record, field, absolute offset and the path
+through nested codecs, and prefix their message with them:
+
+```text
+Header.magic at offset 0: expected 0x1f3d5b79, got 0x0
+DICTIONARY -> [2] -> STRING at offset 104: expected 200 bytes, found 16
+```
+
+## License
+
+MIT

bytestruct-0.1.0/README.md

@@ -0,0 +1,91 @@
+# bytestruct
+
+[![Python application](https://github.com/doronz88/bytestruct/workflows/Python%20application/badge.svg)](https://github.com/doronz88/bytestruct/actions/workflows/python-app.yml "Python application action")
+[![Pypi version](https://img.shields.io/pypi/v/bytestruct.svg)](https://pypi.org/project/bytestruct/ "PyPi package")
+[![Docs](https://github.com/doronz88/bytestruct/actions/workflows/docs.yml/badge.svg)](https://doronz88.github.io/bytestruct/ "Documentation")
+
+`bytestruct` parses and builds binary wire formats with the standard library alone. Fixed-size records are
+dataclasses whose field annotations give each field's wire type; variable-length data is described by small
+codecs that compose like [construct](https://github.com/construct/construct)'s. Everything is fully typed.
+
+The layout of a record is compiled into `struct.Struct` objects once, when the class is defined, so parsing a
+record is a single `unpack_from` per byte-order run.
+
+**Documentation: <https://doronz88.github.io/bytestruct/>**, including a
+[migration guide from construct](https://doronz88.github.io/bytestruct/migrating-from-construct/).
+
+## Install
+
+```shell
+python3 -m pip install -U bytestruct
+```
+
+## Fixed-size records
+
+```python
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import Annotated
+
+from bytestruct import BinaryStruct, Const, PaddedString, u16, u32
+
+
+class Kind(IntEnum):
+    FILE = 1
+    DIRECTORY = 2
+
+
+@dataclass
+class Header(BinaryStruct, byte_order="<"):
+    magic: Annotated[u32, Const(0x1F3D5B79)] = field(default=0x1F3D5B79, init=False)
+    size: u32
+    name: Annotated[str, PaddedString(16)]
+    kind: Annotated[Kind, u16]  # parsed into the enum type
+
+
+data = Header(size=1024, name="notes.txt", kind=Kind.FILE).build()  # a bad value -> BinaryBuildError
+header = Header.parse(data)  # short input -> TruncatedDataError, wrong magic -> UnexpectedConstantError
+assert header.kind is Kind.FILE
+```
+
+Wire fields are positional `__init__` parameters in wire order. A field declared
+`= field(default=..., init=False)` is left out of `__init__`: parse skips its bytes (padding) and build packs
+its default (on a `Const` field, the constant). Fields without a wire type may follow the wire fields and are
+ignored by parse/build. Records cannot be subclassed.
+
+Available field types include `u8`..`u64`, `i16`..`i64`, byte-order pinned `u32le`/`u32be`, `Bytes(n)`,
+`PaddedString(n)`, `uuid_t`, `ipv4`/`ipv6`, `Array(element, n)`, int-enum fields and `Const` magics; custom
+ones subclass `Format`.
+
+## Codecs
+
+```python
+from bytestruct import CSTRING, U32_LE, U64_LE, Aligned, Prefixed, Switch
+
+STRING = Aligned(4, Prefixed(U32_LE, CSTRING))  # u32 length, NUL-terminated UTF-8, padded to 4 bytes
+OBJECT = Switch(U32_LE, {1: STRING, 2: U64_LE})  # parses to (tag, value)
+
+assert OBJECT.parse(OBJECT.build((1, "hi"))) == (1, "hi")
+```
+
+A codec is anything with `read(reader)` and `build(value)`: the combinators (`Prefixed`, `Aligned`,
+`PrefixedArray`, `Tuple`, `Switch`), the leaves (`CSTRING`, `GREEDY_STRING`, `GREEDY_BYTES`, `PASS`), the
+scalars (`U8`, `U16_LE`/`U16_BE`, ..., `F64_BE`), `Bytes(n)`, and record classes themselves. A record field annotated with a codec
+(`name: Annotated[str, CSTRING]`) makes the record variable-length; such fields follow the fixed-size ones.
+Formats with no declarative shape are read by hand with `ByteReader`, whose sub-readers are windows on the same
+buffer (nothing is copied).
+
+## Errors
+
+Every failure raises a `BinaryDataError` (a `ValueError`): `BinaryParseError` (with `TruncatedDataError` and
+`UnexpectedConstantError`) or `BinaryBuildError`. Errors carry the record, field, absolute offset and the path
+through nested codecs, and prefix their message with them:
+
+```text
+Header.magic at offset 0: expected 0x1f3d5b79, got 0x0
+DICTIONARY -> [2] -> STRING at offset 104: expected 200 bytes, found 16
+```
+
+## License
+
+MIT