byteforge 0.0.5__tar.gz

byteforge-0.0.5/.github/workflows/release.yml

@@ -0,0 +1,67 @@
+name: "Publish"
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build_sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build sdist
+        run: uv build --sdist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  build_wheels:
+    name: Build wheels (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v3.4.0
+        env:
+          CIBW_ARCHS_MACOS: "x86_64 arm64"
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  publish:
+    name: Publish to PyPI
+    needs: [build_sdist, build_wheels]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        run: uv publish dist/*

byteforge-0.0.5/.github/workflows/test.yml

@@ -0,0 +1,26 @@
+name: Test
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Install uv and set the Python version
+      uses: astral-sh/setup-uv@v7
+      with:
+        enable-cache: true
+        python-version: ${{ matrix.python-version }}
+      
+    - name: Install the project
+      run: uv sync --locked --all-extras --dev
+
+    - name: Run pytest
+      run: uv run pytest tests/

byteforge-0.0.5/.gitignore

@@ -0,0 +1,136 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+__about__.py
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# hatch-vcs
+_version.py
+
+# ruff
+.ruff_cache

byteforge-0.0.5/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.0.4] - 2026-03-06
+
+### Added
+- Unified `encode_errors` parameter on all encodings (except IEEE754 and Boolean):
+  `"clamp"` (default), `"raise"`, `"nan"`, or numeric sentinel.
+- `BCD` now accepts `decode_errors` for invalid-nibble handling during decode.
+- Float encodings (MilStd1750A, TIFloat, IBMFloat, DECFloat, DECFloatG) now
+  support `encode_errors` for out-of-range detection.
+- pytest-benchmark benchmarks for all encoding types.
+- `__version__` attribute powered by setuptools-scm.
+- Docstrings on all `_encode_py()`/`_decode_py()` private helpers.
+
+### Changed
+- **BREAKING**: `errors` parameter renamed to `encode_errors` on all encodings.
+- **BREAKING**: `BCD(errors=...)` renamed to `BCD(decode_errors=...)`.
+- Version management switched from hardcoded to setuptools-scm.
+
+### Fixed
+- Fixed mypy type annotation errors in `_base.py`, `twos_complement.py`,
+  `ieee754.py`, and `bcd.py`.

byteforge-0.0.5/CLAUDE.md

@@ -0,0 +1,35 @@
+# Byteforge
+
+Encode and decode numbers as unsigned integer bit patterns (`np.ndarray`).
+
+## Structure
+
+- `src/byteforge/` — flat package
+- `_base.py` — abstract `Encoding` base class (encode/decode accept scalars or arrays)
+- `_registry.py` — `@register` decorator and `create_encoding()` factory
+- 13 encodings: Unsigned, TwosComplement, OnesComplement, IEEE754, LinearScaled, MilStd1750A, BCD, GrayCode, OffsetBinary, Boolean, TIFloat, IBMFloat, DECFloat/DECFloatG
+
+## Commands
+
+- **Test**: `uv run pytest tests/ -v`
+- **Lint**: `uv run ruff check src/ tests/`
+- **Type check**: `uv run mypy`
+
+## C Extension (`src/byteforge/_c/`)
+
+Optional NumPy C ufuncs accelerate encodings where Python has per-element loops or multi-pass numpy operations. Falls back to pure Python when the C extension is unavailable (set `BYTEFORGE_NO_C=1` to force fallback).
+
+**Has C ufuncs:** BCD (encode/decode), GrayCode (decode only), MilStd1750A, TIFloat, IBMFloat, DECFloat/DECFloatG (all encode+decode).
+
+**No C ufuncs:** Unsigned, TwosComplement, OnesComplement, IEEE754, OffsetBinary, Boolean, LinearScaled — these are already single-pass vectorized numpy ops (`view`, `clip`, `where`, arithmetic) with no loops or multi-pass overhead to eliminate. GrayCode encode is also pure Python since it's a single expression (`n ^ (n >> 1)`).
+
+Each encoding module checks `_HAS_C` and dispatches to either the C ufunc or `_encode_py`/`_decode_py` helpers.
+
+## Conventions
+
+- Python >=3.9, numpy >=2.0
+- Don't use from __future__ import annotations
+- Google style docstrings; use type annotations, not types in docstrings
+- Ruff: rules E, F, W, I, UP, B, SIM; line-length 100
+- Tests use pytest + hypothesis
+- Keep `CHANGELOG.md` up to date under `## Unreleased` for user-facing changes

byteforge-0.0.5/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include src/byteforge/_c *.c

byteforge-0.0.5/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: byteforge
+Version: 0.0.5
+Summary: Encode and decode numbers as unsigned integer bit patterns
+Author-email: Jonathan Olsten <jolsten@gmail.com>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=2.0
+
+# Byteforge
+
+Encode and decode numbers as unsigned integer bit patterns using NumPy arrays.
+
+Requires Python >= 3.9 and NumPy >= 2.0.
+
+## Installation
+
+```
+pip install byteforge
+```
+
+## Usage
+
+Every encoding exposes the same interface: `encode()` converts physical values to bit patterns, `decode()` converts back.
+
+```python
+import numpy as np
+from byteforge import TwosComplement, IEEE754, Unsigned
+
+# Integer encodings
+tc = TwosComplement(16)
+dns = tc.encode(np.array([-1, 0, 127]))   # array([65535, 0, 127], dtype=uint16)
+tc.decode(dns)                              # array([-1, 0, 127], dtype=int16)
+
+# Floating-point encodings
+ieee = IEEE754(32)
+dns = ieee.encode(np.array([3.14]))         # uint32 bit pattern
+ieee.decode(dns)                            # array([3.14], dtype=float32)
+
+# Unsigned with automatic bit width
+u = Unsigned.from_range(max_value=1000)     # Unsigned(10)
+```
+
+### Registry factory
+
+Create encodings by name using the registry:
+
+```python
+from byteforge import create_encoding
+
+enc = create_encoding("twos_complement", 8)
+enc = create_encoding("ieee32")            # aliases have default bit widths
+enc = create_encoding("linear_scaled", 16, scale_factor=0.1, offset=10.0)
+```
+
+### Byte serialization
+
+Convert encoded bit patterns to/from raw bytes:
+
+```python
+enc = Unsigned(16)
+dns = enc.encode(np.array([256, 512]))
+raw = enc.to_bytes(dns, byteorder="big")    # uint8 array, shape (2, 2)
+enc.decode(enc.from_bytes(raw, byteorder="big"))  # roundtrip
+```
+
+For non-byte-aligned widths (e.g. 12-bit), values are zero-padded in the most
+significant bits to fill whole bytes (2 bytes for 12-bit).
+
+## Encodings
+
+| Encoding | Registry names | Bit widths |
+|---|---|---|
+| `Unsigned` | `unsigned`, `u` | 1-64 |
+| `TwosComplement` | `twos_complement`, `2c` | 2-64 |
+| `OnesComplement` | `ones_complement`, `1c` | 2-64 |
+| `OffsetBinary` | `offset_binary` | 1-64 |
+| `GrayCode` | `gray_code`, `gray` | 1-64 |
+| `BCD` | `bcd` | 4-64 (multiples of 4) |
+| `Boolean` | `boolean` | 1 |
+| `IEEE754` | `ieee754`, `ieee16`, `ieee32`, `ieee64` | 16, 32, 64 |
+| `LinearScaled` | `linear_scaled` | 1-64 |
+| `MilStd1750A` | `mil_std_1750a`, `1750a32`, `1750a48` | 32, 48 |
+| `TIFloat` | `ti_float`, `ti32`, `ti40` | 32, 40 |
+| `IBMFloat` | `ibm_float`, `ibm32`, `ibm64` | 32, 64 |
+| `DECFloat` | `dec_float`, `dec32`, `dec64` | 32, 64 |
+| `DECFloatG` | `dec_float_g`, `dec64g` | 64 |
+
+## C Extension
+
+Optional NumPy C ufuncs accelerate encodings that would otherwise require per-element loops
+or multi-pass numpy operations. The C extension is compiled automatically during install and
+falls back to pure Python when unavailable. Set `BYTEFORGE_NO_C=1` to force the pure-Python
+path.
+
+Encodings with C ufuncs: BCD, GrayCode (decode), MilStd1750A, TIFloat, IBMFloat,
+DECFloat, and DECFloatG.
+
+## Development
+
+```
+uv run pytest tests/ -v       # tests
+uv run ruff check src/ tests/ # lint
+uv run mypy                   # type check
+```

byteforge-0.0.5/README.md

@@ -0,0 +1,96 @@
+# Byteforge
+
+Encode and decode numbers as unsigned integer bit patterns using NumPy arrays.
+
+Requires Python >= 3.9 and NumPy >= 2.0.
+
+## Installation
+
+```
+pip install byteforge
+```
+
+## Usage
+
+Every encoding exposes the same interface: `encode()` converts physical values to bit patterns, `decode()` converts back.
+
+```python
+import numpy as np
+from byteforge import TwosComplement, IEEE754, Unsigned
+
+# Integer encodings
+tc = TwosComplement(16)
+dns = tc.encode(np.array([-1, 0, 127]))   # array([65535, 0, 127], dtype=uint16)
+tc.decode(dns)                              # array([-1, 0, 127], dtype=int16)
+
+# Floating-point encodings
+ieee = IEEE754(32)
+dns = ieee.encode(np.array([3.14]))         # uint32 bit pattern
+ieee.decode(dns)                            # array([3.14], dtype=float32)
+
+# Unsigned with automatic bit width
+u = Unsigned.from_range(max_value=1000)     # Unsigned(10)
+```
+
+### Registry factory
+
+Create encodings by name using the registry:
+
+```python
+from byteforge import create_encoding
+
+enc = create_encoding("twos_complement", 8)
+enc = create_encoding("ieee32")            # aliases have default bit widths
+enc = create_encoding("linear_scaled", 16, scale_factor=0.1, offset=10.0)
+```
+
+### Byte serialization
+
+Convert encoded bit patterns to/from raw bytes:
+
+```python
+enc = Unsigned(16)
+dns = enc.encode(np.array([256, 512]))
+raw = enc.to_bytes(dns, byteorder="big")    # uint8 array, shape (2, 2)
+enc.decode(enc.from_bytes(raw, byteorder="big"))  # roundtrip
+```
+
+For non-byte-aligned widths (e.g. 12-bit), values are zero-padded in the most
+significant bits to fill whole bytes (2 bytes for 12-bit).
+
+## Encodings
+
+| Encoding | Registry names | Bit widths |
+|---|---|---|
+| `Unsigned` | `unsigned`, `u` | 1-64 |
+| `TwosComplement` | `twos_complement`, `2c` | 2-64 |
+| `OnesComplement` | `ones_complement`, `1c` | 2-64 |
+| `OffsetBinary` | `offset_binary` | 1-64 |
+| `GrayCode` | `gray_code`, `gray` | 1-64 |
+| `BCD` | `bcd` | 4-64 (multiples of 4) |
+| `Boolean` | `boolean` | 1 |
+| `IEEE754` | `ieee754`, `ieee16`, `ieee32`, `ieee64` | 16, 32, 64 |
+| `LinearScaled` | `linear_scaled` | 1-64 |
+| `MilStd1750A` | `mil_std_1750a`, `1750a32`, `1750a48` | 32, 48 |
+| `TIFloat` | `ti_float`, `ti32`, `ti40` | 32, 40 |
+| `IBMFloat` | `ibm_float`, `ibm32`, `ibm64` | 32, 64 |
+| `DECFloat` | `dec_float`, `dec32`, `dec64` | 32, 64 |
+| `DECFloatG` | `dec_float_g`, `dec64g` | 64 |
+
+## C Extension
+
+Optional NumPy C ufuncs accelerate encodings that would otherwise require per-element loops
+or multi-pass numpy operations. The C extension is compiled automatically during install and
+falls back to pure Python when unavailable. Set `BYTEFORGE_NO_C=1` to force the pure-Python
+path.
+
+Encodings with C ufuncs: BCD, GrayCode (decode), MilStd1750A, TIFloat, IBMFloat,
+DECFloat, and DECFloatG.
+
+## Development
+
+```
+uv run pytest tests/ -v       # tests
+uv run ruff check src/ tests/ # lint
+uv run mypy                   # type check
+```

byteforge-0.0.5/pyproject.toml

@@ -0,0 +1,68 @@
+[project]
+name = "byteforge"
+dynamic = ["version"]
+description = "Encode and decode numbers as unsigned integer bit patterns"
+readme = "README.md"
+authors = [
+    { name = "Jonathan Olsten", email = "jolsten@gmail.com" }
+]
+requires-python = ">=3.9"
+dependencies = [
+    "numpy>=2.0",
+]
+
+[build-system]
+requires = ["setuptools>=64", "setuptools-scm>=8", "numpy>=2.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.141",
+    "mypy>=1.19.1",
+    "pytest>=8.4",
+    "pytest-benchmark>=5.2.3",
+    "ruff>=0.15.4",
+    "setuptools>=64",
+    "setuptools-scm>=8",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--benchmark-disable"
+
+[tool.setuptools_scm]
+version_file = "src/byteforge/_version.py"
+
+[tool.ruff]
+target-version = "py39"
+src = ["src"]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["byteforge"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = false
+warn_unused_configs = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+packages = ["byteforge"]
+mypy_path = "src"
+
+[[tool.mypy.overrides]]
+module = "byteforge._c.*"
+ignore_missing_imports = true
+
+[tool.cibuildwheel]
+build = "cp39-* cp310-* cp311-* cp312-* cp313-*"
+skip = "*-win32 *-manylinux_i686"
+test-requires = ["pytest", "pytest-benchmark", "hypothesis"]
+test-command = "pytest {project}/tests/"

byteforge-0.0.5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

byteforge-0.0.5/setup.py

@@ -0,0 +1,37 @@
+import numpy
+from setuptools import Extension, setup
+from setuptools.command.build_ext import build_ext as _build_ext
+
+
+class optional_build_ext(_build_ext):
+    """Allow C extension build to fail gracefully."""
+
+    def run(self):
+        try:
+            _build_ext.run(self)
+        except Exception:
+            self._warn_unavailable()
+
+    def build_extension(self, ext):
+        try:
+            _build_ext.build_extension(self, ext)
+        except Exception:
+            self._warn_unavailable()
+
+    def _warn_unavailable(self):
+        print("*" * 70)
+        print("WARNING: byteforge C extension could not be compiled.")
+        print("Falling back to pure Python (slower).")
+        print("*" * 70)
+
+
+setup(
+    cmdclass={"build_ext": optional_build_ext},
+    ext_modules=[
+        Extension(
+            "byteforge._c.ufunc",
+            sources=["src/byteforge/_c/ufunc.c"],
+            include_dirs=[numpy.get_include(), "src/byteforge/_c"],
+        ),
+    ],
+)

byteforge-0.0.5/src/byteforge/__init__.py

@@ -0,0 +1,42 @@
+try:
+    from ._version import __version__, __version_tuple__
+except ImportError:
+    __version__ = "0.0.0"
+    __version_tuple__ = (0, 0, 0)
+
+from ._base import Encoding
+from ._registry import create_encoding, register
+from .bcd import BCD
+from .boolean import Boolean
+from .dec_float import DECFloat, DECFloatG
+from .gray_code import GrayCode
+from .ibm_float import IBMFloat
+from .ieee754 import IEEE754
+from .linear_scaled import LinearScaled
+from .mil_std_1750a import MilStd1750A
+from .offset_binary import OffsetBinary
+from .ones_complement import OnesComplement
+from .ti_float import TIFloat
+from .twos_complement import TwosComplement
+from .unsigned import Unsigned
+
+__all__ = [
+    "__version__",
+    "Encoding",
+    "register",
+    "create_encoding",
+    "BCD",
+    "Boolean",
+    "DECFloat",
+    "DECFloatG",
+    "GrayCode",
+    "IBMFloat",
+    "IEEE754",
+    "LinearScaled",
+    "MilStd1750A",
+    "OffsetBinary",
+    "OnesComplement",
+    "TIFloat",
+    "TwosComplement",
+    "Unsigned",
+]