bitlab 0.1.0__tar.gz

bitlab-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    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@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check package metadata
+        run: python -m twine check dist/*

bitlab-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+# Triggers when you publish a GitHub Release (recommended: tag it vX.Y.Z
+# matching the version in pyproject.toml). Can also be run manually.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for PyPI Trusted Publishing (OIDC)
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No password/token needed: this uses PyPI's Trusted Publisher
+        # feature. One-time setup required on pypi.org -- see the "Publishing"
+        # section of README.md / CONTRIBUTING.md.

bitlab-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+.venv/
+venv/
+.DS_Store

bitlab-0.1.0/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Planned
+- Register field mapper (`bitlab.registers`) — define a hardware register's
+  bit layout in Python, pack/unpack values, export to C `#define`s or a
+  bitfield struct.
+- Computer architecture toolkit (`bitlab.arch`) — IEEE 754 float
+  deconstruction, endianness swapping, Gray code, Q-format fixed-point
+  conversion.
+- COBS framing (`bitlab.comms`) — Consistent Overhead Byte Stuffing for
+  serial protocols.
+- Reed-Solomon burst error correction — planned as a later, dedicated
+  release given its complexity.
+
+## [0.1.0] - 2026-07-14
+
+### Added
+- **Named the project `bitlab`** and
+  restructured it as submodules under one umbrella package rather than a
+  flat namespace, to give the project room to grow beyond parity:
+  ```
+  bitlab/
+  ├── bitutils/   # foundational bit ops shared by every submodule
+  ├── parity/     # parity bit checking + Hamming(7,4)
+  └── crc/        # new in this release
+  ```
+- **New `bitlab.crc` submodule**: CRC generation, checking, explanation, and
+  C code export.
+  - `crc8()`, `crc16(variant="ccitt"|"modbus")`, `crc32()` convenience
+    functions for the most common industry variants.
+  - Generic `crc(data, config)` for custom polynomials via `CRCConfig`.
+  - Built-in presets — `CRC8_SMBUS`, `CRC16_CCITT_FALSE`, `CRC16_MODBUS`,
+    `CRC32_ISO_HDLC` — each verified against its published CRC-catalogue
+    check value (the CRC of `b"123456789"`).
+  - `explain(data, config)`: step-by-step trace of the real bitwise
+    algorithm, for teaching/learning how CRC actually works.
+  - `export_c(config, function_name=None)`: exports a table-driven C99
+    implementation. The embedded lookup table is generated by the same code
+    used internally by the fast Python path, and is validated by actually
+    compiling the generated C with `gcc` and checking its output against
+    the CRC catalogue in the test suite.
+  - `compute_bitwise()` / `compute_table()` / `build_table()` / `self_test()`
+    as lower-level building blocks.
+- **New `bitlab.bitutils` submodule**: `popcount`, `has_odd_parity`,
+  `get_bit`/`set_bit`/`flip_bit`, `reflect`, `rotate_left`/`rotate_right`,
+  promoted out of the old parity-only utils module so they're shared
+  foundational building blocks for `parity`, `crc`, and future submodules.
+- Unified `bitlab` CLI covering `parity`, `hamming`, and `crc` subcommands
+  (previously `parity-toolkit` had its own separate CLI).
+- 56 tests total, including property-based cross-validation of the bitwise
+  vs. table-driven CRC implementations and end-to-end compilation of
+  generated C source.
+
+---
+
+[Unreleased]: https://github.com/KenKambi/bitlab/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/KenKambi/bitlab/releases/tag/v0.1.0

bitlab-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing to bitlab
+
+## Development setup
+
+```bash
+git clone https://github.com/KenKambi/bitlab.git
+cd bitlab
+pip install -e ".[dev]"
+pytest
+```
+
+Each submodule (`bitutils`, `parity`, `crc`) has its own test file(s) under
+`tests/`. `test_crc_codegen.py` compiles the generated C with `gcc` and
+actually runs it — install `gcc` locally (`apt install gcc` / Xcode Command
+Line Tools / MinGW) or those specific tests will be skipped automatically.
+
+## Project layout
+
+```
+src/bitlab/
+├── bitutils/   # foundational bit ops — add here only if it's used by 2+ other submodules
+├── parity/     # parity + Hamming(7,4)
+└── crc/        # engine.py (compute), presets.py (CRCConfig + built-ins),
+                # explain.py (educational trace), codegen.py (C export)
+```
+
+When adding a new domain (e.g. registers, arch, comms), give it its own
+top-level submodule under `src/bitlab/`, following the same pattern as
+`crc/`: a `presets.py`/config layer, a computation engine, and — where it
+makes sense — an `explain()` and/or `export_c()`.
+
+## Before opening a PR
+
+```bash
+pytest -v                 # all tests must pass
+python -m build             # package must build cleanly
+python -m twine check dist/*  # metadata must be valid
+```
+
+CI runs the same checks across Python 3.9–3.13 on every push/PR.
+

bitlab-0.1.0/LICENSE

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

bitlab-0.1.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: bitlab
+Version: 0.1.0
+Summary: A toolkit for embedded systems, binary data, and digital communications: parity, Hamming codes, and CRC — with C code export.
+Project-URL: Homepage, https://github.com/KenKambi/bitlab
+Project-URL: Issues, https://github.com/KenKambi/bitlab/issues
+License: MIT
+License-File: LICENSE
+Keywords: bit-manipulation,c-code-generation,crc,crc16,crc32,crc8,embedded,error-correction,error-detection,hamming-code,parity,serial,uart
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bitlab
+
+[![CI](https://github.com/KenKambi/bitlab/actions/workflows/ci.yml/badge.svg)](https://github.com/KenKambi/bitlab/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/bitlab.svg)](https://pypi.org/project/bitlab/)
+
+A toolkit for embedded systems, binary data, and digital communications.
+
+Built around the topics an Electronic & Computer Engineering degree
+actually covers: digital logic, computer architecture, embedded systems,
+and communications. Each domain is a self-contained submodule, so the
+package can keep growing without becoming a junk drawer.
+
+- Zero dependencies
+- Type-hinted (PEP 561, ships a `py.typed` marker)
+- One CLI: `bitlab`
+- Production functions **and** step-by-step educational explanations, side by side
+- CRC configs export directly to compiled, table-driven C — the same table your Python code uses
+
+```
+bitlab/
+├── bitutils/   # foundational bit ops used by every other submodule
+├── parity/     # parity bit checking + Hamming(7,4) error correction
+└── crc/        # CRC-8/16/32, generic engine, explain(), export_c()
+```
+
+## Install
+
+```bash
+pip install bitlab
+```
+
+## `bitlab.crc` — CRC generation, checking, explanation, and C export
+
+```python
+from bitlab.crc import crc8, crc16, crc32
+
+crc8(b"hello")              # CRC-8/SMBUS
+crc16(b"hello")             # CRC-16/CCITT-FALSE (default)
+crc16(b"hello", variant="modbus")  # CRC-16/MODBUS
+crc32(b"hello")              # CRC-32/ISO-HDLC (Ethernet, zlib, PNG)
+```
+
+Every built-in preset is verified against its published CRC-catalogue check
+value (the CRC of `b"123456789"`) in the test suite — these aren't "a CRC
+that happens to run", they match what real hardware and protocols expect.
+
+### Custom polynomials
+
+```python
+from bitlab.crc import crc, CRCConfig
+
+my_crc = CRCConfig(
+    name="my-custom-crc",
+    width=16, poly=0x8005, init=0xFFFF,
+    refin=True, refout=True, xorout=0x0000,
+    check=0x4B37,  # CRC of b"123456789", for self-testing your config
+)
+crc(b"some data", my_crc)
+```
+
+### Step-by-step explanation (the same computation, narrated)
+
+```python
+from bitlab.crc import explain, CRC8_SMBUS
+
+print(explain(b"AB", CRC8_SMBUS))
+```
+
+```
+CRC algorithm: CRC-8/SMBUS
+  width=8  poly=0x07  init=0x00  refin=False  refout=False  xorout=0x00
+
+Input bytes (2 total): 41 42
+
+Initial register: 0x00
+
+Byte 0: 0x41 -> XORed in, register = 0x41
+    bit 0: MSB=0 -> shift left -> 0x82
+    bit 1: MSB=1 -> shift left, XOR polynomial -> 0x03
+    ...
+
+Final CRC: 0x87
+```
+
+`explain()` runs the real bitwise algorithm with a narration attached — it's
+not a separate simplified explanation, so what you read is guaranteed to
+match what `crc8`/`crc16`/`crc32` actually compute.
+
+### Export to C
+
+```python
+from bitlab.crc import export_c, CRC32_ISO_HDLC
+
+print(export_c(CRC32_ISO_HDLC, function_name="my_crc32"))
+```
+
+```c
+#include <stdint.h>
+#include <stddef.h>
+
+static const uint32_t my_crc32_table[256] = {
+    0x00000000, 0x77073096, 0xEE0E612C, 0x990951BA, ...
+};
+
+uint32_t my_crc32(const uint8_t *data, size_t len)
+{
+    uint32_t crc = 0xFFFFFFFFU;
+    for (size_t i = 0; i < len; i++) {
+        uint8_t idx = (uint8_t)(crc ^ data[i]);
+        crc = (crc >> 8) ^ my_crc32_table[idx];
+    }
+    return (crc ^ 0xFFFFFFFFU);
+}
+```
+
+The exported table is built by the exact same code Python's fast path
+uses — the test suite actually compiles the generated C with `gcc` and
+checks the output against the CRC catalogue, so this isn't just
+"code that looks right."
+
+## `bitlab.parity` — parity bits and Hamming(7,4)
+
+```python
+from bitlab.parity import get_parity_bit, append_parity, check_parity
+
+get_parity_bit(0b1011, "even", 4)      # -> 1
+append_parity(0b1011, "even", 4)       # -> 0b11011
+check_parity(0b11011, "even", 4)       # -> True
+```
+
+```python
+from bitlab.parity import encode_hamming, decode_hamming
+
+codeword = encode_hamming(0b1101)
+corrupted = codeword ^ 0b0000100        # simulate a single-bit flip
+result = decode_hamming(corrupted)
+# HammingDecodeResult(data=13, error_position=6, corrected=True, codeword=...)
+```
+
+See the full parity/Hamming API reference at the bottom of this file.
+
+## `bitlab.bitutils` — shared low-level bit helpers
+
+```python
+from bitlab.bitutils import popcount, reflect, rotate_left, rotate_right
+
+popcount(0b1011)           # -> 3
+reflect(0b1100, 4)         # -> 0b0011 (bit-mirror, used internally by crc)
+rotate_left(0b10000001, 1, 8)   # -> 0b00000011
+```
+
+## CLI
+
+```bash
+bitlab parity bit 0b1011 --type even --width 4
+# -> 1
+
+bitlab hamming encode 13
+# -> 85 (0b1010101)
+
+bitlab crc compute "123456789" --preset crc32
+# -> 0xCBF43926 (3421780262)
+
+bitlab crc explain "AB" --preset crc8
+# -> step-by-step trace
+
+bitlab crc export-c --preset crc32 --name my_crc32
+# -> C source on stdout
+```
+
+Run `bitlab --help`, `bitlab crc --help`, etc. for full usage.
+
+## API reference
+
+### `bitlab.crc`
+
+| Function | Description |
+|---|---|
+| `crc8(data)` | CRC-8/SMBUS. |
+| `crc16(data, variant="ccitt")` | CRC-16/CCITT-FALSE or CRC-16/MODBUS. |
+| `crc32(data)` | CRC-32/ISO-HDLC (Ethernet/zlib/PNG). |
+| `crc(data, config)` | Generic entry point. `config` is a `CRCConfig` or a preset name string. |
+| `explain(data, config, max_bytes=4)` | Step-by-step trace of the computation. |
+| `export_c(config, function_name=None)` | Table-driven C99 source implementing `config`. |
+| `build_table(config)` | The 256-entry lookup table (also used internally and by `export_c`). |
+| `compute_bitwise(data, config)` | Canonical bit-by-bit reference implementation. |
+| `compute_table(data, config, table=None)` | Fast table-driven implementation. |
+| `self_test(config)` | Verifies a config against its `check` value. |
+| `CRCConfig` | Dataclass: `name, width, poly, init, refin, refout, xorout, check`. |
+| `CRC8_SMBUS`, `CRC16_CCITT_FALSE`, `CRC16_MODBUS`, `CRC32_ISO_HDLC` | Built-in preset configs. |
+
+### `bitlab.parity`
+
+| Function | Description |
+|---|---|
+| `get_parity_bit(value, type="even", bit_width=8)` | Computes the parity bit for `value`. |
+| `append_parity(value, type="even", bit_width=8)` | Returns `value` with a parity bit appended as bit `bit_width`. |
+| `check_parity(value_with_parity, type="even", bit_width=8)` | Returns `True` if the parity bit matches the data. |
+| `generate_parity_array(values, type="even", bit_width=8)` | Parity bit for each value in a sequence. |
+| `check_parity_array(values_with_parity, type="even", bit_width=8)` | Parity check for each value in a sequence. |
+| `compute_message_parity(message, type="even")` | Single overall parity bit for a whole string. |
+| `flip_random_bit(value, bit_width=8)` | Flips one random bit — useful for simulating errors in tests. |
+| `encode_hamming(data)` | Encodes a 4-bit value (0–15) into a 7-bit Hamming codeword. |
+| `decode_hamming(codeword)` | Decodes a 7-bit codeword, correcting a single-bit error if present. |
+
+### `bitlab.bitutils`
+
+| Function | Description |
+|---|---|
+| `popcount(n)` | Number of 1-bits. |
+| `has_odd_parity(n)` | True if `n` has an odd number of 1-bits. |
+| `get_bit` / `set_bit` / `flip_bit` | Single-bit read/write/toggle. |
+| `reflect(value, width)` | Bit-mirror the lowest `width` bits. |
+| `rotate_left` / `rotate_right` | Bitwise rotation within a fixed-width register. |
+
+## Roadmap
+
+Planned next:
+
+- **Register field mapper** — define a hardware register's bit layout in
+  Python, pack/unpack values, export to C `#define`s or a bitfield struct.
+- **Computer architecture toolkit** — IEEE 754 float deconstruction,
+  endianness swapping, Gray code, Q-format fixed-point conversion.
+- **COBS framing** — Consistent Overhead Byte Stuffing for serial protocols.
+- **Reed-Solomon** — burst error correction (QR codes, satellite comms) —
+  planned as a later, dedicated release given its complexity.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest              # run the test suite (56 tests, including compiling
+                     # and running the generated C against gcc)
+python -m build      # produce a wheel + sdist in dist/
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full dev workflow and release
+process, and [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## License
+
+MIT