structwire 0.1.0__tar.gz → 0.1.0.post1__tar.gz

{structwire-0.1.0 → structwire-0.1.0.post1}/CONTRIBUTING.md

@@ -30,7 +30,7 @@ coverage. Document byte order, width and failure behavior. Update the
 output, or schema validation. Add boundary and differential/property tests for
 numeric changes.
 
-Pytest executes the four Python examples and every Python block in the README and
+Pytest executes the Python examples and every Python block in the README and
 `docs/`. YAML snippets are parsed and their StructWire schemas compiled; application
 routing examples are checked for valid nested layouts. The example routing files
 are checked against the supplied catalog. Property tests compare integer and float
@@ -81,9 +81,10 @@ See [releasing](RELEASING.md) for publication using those artifacts.
 
 ## Source material
 
-Contribute only source, schemas and fixtures that you have the right to publish
-under MIT. Prefer synthetic examples and public protocol specifications. Keep
-private/customer payload databases, bench configuration and device secrets out
-of this repository. Customer and project mappings belong in their private plugins
-unless publication rights are explicit. Automated checks cannot establish those
-rights; the domain-neutral API never requires publishing customer protocol data.
+Contribute only source, schemas, and fixtures that you have the right to publish
+under MIT. Use invented, vendor-neutral examples rather than proprietary
+identifiers, session tables, packet definitions, logs, or internal names.
+Keep private payload catalogs, bench configurations, and credentials out of
+this repository. Application-specific routing and payload definitions belong
+in the consuming application unless publication rights are explicit.
+Automated checks cannot establish those rights.

{structwire-0.1.0/src/structwire.egg-info → structwire-0.1.0.post1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structwire
-Version: 0.1.0
+Version: 0.1.0.post1
 Summary: A small schema-driven binary payload codec for Python.
 Author: Nidhal Abidi
 License-Expression: MIT
@@ -49,7 +49,13 @@ Your application supplies the bytes and handles transport I/O and routing.
 
 ## Install
 
-Python 3.11 or newer is required. Install from the source checkout:
+Python 3.11 or newer is required. Install from PyPI:
+
+```bash
+python -m pip install "structwire>=0.1.0.post1,<0.2"
+```
+
+Or install from the source checkout:
 
 ```bash
 git clone https://github.com/nidops/structwire.git
@@ -57,7 +63,7 @@ cd structwire
 python -m pip install .
 ```
 
-Version `0.1.0` is an alpha API. PyYAML is installed automatically for YAML loading.
+Version `0.1.0.post1` is an alpha API. PyYAML is installed automatically for YAML loading.
 
 ## Quick start
 
@@ -65,13 +71,13 @@ Version `0.1.0` is an alpha API. PyYAML is installed automatically for YAML load
 from structwire import Field, Layout
 
 codec = Layout(
-    Field("temperature_c", "i16le", scale=0.1),
-    Field("state", "u8"),
+    Field("level", "i16le", scale=0.1),
+    Field("quality", "u8"),
 ).compile()
 
-payload = codec.encode({"temperature_c": 23.5, "state": 1})
+payload = codec.encode({"level": 23.5, "quality": 1})
 assert payload == bytes.fromhex("eb 00 01")
-assert codec.decode(payload) == {"temperature_c": 23.5, "state": 1}
+assert codec.decode(payload) == {"level": 23.5, "quality": 1}
 ```
 
 Compile a layout once and reuse its codec.
@@ -83,27 +89,27 @@ Save this as `codecs.yaml`:
 ```yaml
 version: 1
 codecs:
-  node_status:
+  frame_status:
     size: 4
     fields:
-      - name: mode
+      - name: phase
         type: enum
-        values: {0: asleep, 1: awake, 2: fault}
-      - name: supply_voltage
+        values: {0: idle, 1: running, 2: paused}
+      - name: value
         type: uint16_le
         offset: 2
-        scale: 0.001
-        unit: V
+        scale: 0.01
+        unit: arbitrary
 ```
 
 ```python
 from structwire import catalog_from_yaml
 
 catalog = catalog_from_yaml("codecs.yaml")
-payload = bytes.fromhex("01 00 88 13")
-values = catalog.decode("node_status", payload)
-assert values == {"mode": "awake", "supply_voltage": 5.0}
-assert catalog.encode("node_status", values) == payload
+payload = bytes.fromhex("01 00 64 00")
+values = catalog.decode("frame_status", payload)
+assert values == {"phase": "running", "value": 1.0}
+assert catalog.encode("frame_status", values) == payload
 ```
 
 Offsets and sizes are in bytes. Here, byte 1 is unused and encodes as zero.
@@ -140,6 +146,13 @@ limits; applications must bound untrusted schema and payload sizes. See
 
 ## Documentation and examples
 
+All examples use fictional values and are independent of specific products.
+
+- [BCD records](https://github.com/nidops/structwire/blob/master/examples/bcd_record.py)
+- [Packed bit fields](https://github.com/nidops/structwire/blob/master/examples/packed_fields.py)
+- [YAML codec catalog](https://github.com/nidops/structwire/blob/master/examples/codecs.yaml)
+- [BLE-style payload](https://github.com/nidops/structwire/blob/master/examples/ble_payload.py)
+- [Generic message routing](https://github.com/nidops/structwire/blob/master/examples/transport_bindings.yaml)
 - [Python API](https://github.com/nidops/structwire/blob/master/docs/API.md)
 - [Schema reference](https://github.com/nidops/structwire/blob/master/docs/SCHEMA.md)
 - [Examples](https://github.com/nidops/structwire/tree/master/examples)

{structwire-0.1.0 → structwire-0.1.0.post1}/README.md

@@ -7,7 +7,13 @@ Your application supplies the bytes and handles transport I/O and routing.
 
 ## Install
 
-Python 3.11 or newer is required. Install from the source checkout:
+Python 3.11 or newer is required. Install from PyPI:
+
+```bash
+python -m pip install "structwire>=0.1.0.post1,<0.2"
+```
+
+Or install from the source checkout:
 
 ```bash
 git clone https://github.com/nidops/structwire.git
@@ -15,7 +21,7 @@ cd structwire
 python -m pip install .
 ```
 
-Version `0.1.0` is an alpha API. PyYAML is installed automatically for YAML loading.
+Version `0.1.0.post1` is an alpha API. PyYAML is installed automatically for YAML loading.
 
 ## Quick start
 
@@ -23,13 +29,13 @@ Version `0.1.0` is an alpha API. PyYAML is installed automatically for YAML load
 from structwire import Field, Layout
 
 codec = Layout(
-    Field("temperature_c", "i16le", scale=0.1),
-    Field("state", "u8"),
+    Field("level", "i16le", scale=0.1),
+    Field("quality", "u8"),
 ).compile()
 
-payload = codec.encode({"temperature_c": 23.5, "state": 1})
+payload = codec.encode({"level": 23.5, "quality": 1})
 assert payload == bytes.fromhex("eb 00 01")
-assert codec.decode(payload) == {"temperature_c": 23.5, "state": 1}
+assert codec.decode(payload) == {"level": 23.5, "quality": 1}
 ```
 
 Compile a layout once and reuse its codec.
@@ -41,27 +47,27 @@ Save this as `codecs.yaml`:
 ```yaml
 version: 1
 codecs:
-  node_status:
+  frame_status:
     size: 4
     fields:
-      - name: mode
+      - name: phase
         type: enum
-        values: {0: asleep, 1: awake, 2: fault}
-      - name: supply_voltage
+        values: {0: idle, 1: running, 2: paused}
+      - name: value
         type: uint16_le
         offset: 2
-        scale: 0.001
-        unit: V
+        scale: 0.01
+        unit: arbitrary
 ```
 
 ```python
 from structwire import catalog_from_yaml
 
 catalog = catalog_from_yaml("codecs.yaml")
-payload = bytes.fromhex("01 00 88 13")
-values = catalog.decode("node_status", payload)
-assert values == {"mode": "awake", "supply_voltage": 5.0}
-assert catalog.encode("node_status", values) == payload
+payload = bytes.fromhex("01 00 64 00")
+values = catalog.decode("frame_status", payload)
+assert values == {"phase": "running", "value": 1.0}
+assert catalog.encode("frame_status", values) == payload
 ```
 
 Offsets and sizes are in bytes. Here, byte 1 is unused and encodes as zero.
@@ -98,6 +104,13 @@ limits; applications must bound untrusted schema and payload sizes. See
 
 ## Documentation and examples
 
+All examples use fictional values and are independent of specific products.
+
+- [BCD records](https://github.com/nidops/structwire/blob/master/examples/bcd_record.py)
+- [Packed bit fields](https://github.com/nidops/structwire/blob/master/examples/packed_fields.py)
+- [YAML codec catalog](https://github.com/nidops/structwire/blob/master/examples/codecs.yaml)
+- [BLE-style payload](https://github.com/nidops/structwire/blob/master/examples/ble_payload.py)
+- [Generic message routing](https://github.com/nidops/structwire/blob/master/examples/transport_bindings.yaml)
 - [Python API](https://github.com/nidops/structwire/blob/master/docs/API.md)
 - [Schema reference](https://github.com/nidops/structwire/blob/master/docs/SCHEMA.md)
 - [Examples](https://github.com/nidops/structwire/tree/master/examples)

structwire-0.1.0.post1/RELEASING.md

@@ -0,0 +1,52 @@
+# Releasing StructWire
+
+Package version lives in `src/structwire/__init__.py`; setuptools derives metadata
+from it. Keep this as the single version source.
+
+## Setup
+
+Configure [trusted publishing](https://docs.pypi.org/trusted-publishers/)
+separately on TestPyPI and PyPI for project `structwire`, repository
+`nidops/structwire`, and workflow `publish.yml`. Use GitHub environments `testpypi`
+and `pypi` respectively, restricted to release tags. For a new project, register
+a pending publisher; this does not reserve the package name. Confirm account
+ownership and public documentation links.
+
+## Release
+
+Before tagging, perform a publication-content review across source, examples,
+tests, documentation, and configuration. Check the actual contents of both built
+archives, not just their filenames. Ensure example schemas, identifiers, byte
+sequences, and names are invented or explicitly cleared for public release.
+Automated checks and passing CI do not prove publication rights.
+
+1. Update the package version and documentation.
+2. Run the [development checks](CONTRIBUTING.md#development) and
+   [distribution checks](CONTRIBUTING.md#distribution-checks).
+3. From a clean checkout, tag the reviewed `master` commit as `v<package version>`
+   after all supported CI jobs pass. For `0.1.0.post1`, use `v0.1.0.post1` and verify
+   it with `python scripts/check_dist.py dist --tag v0.1.0.post1`.
+4. Push the tag, then manually run **Publish** in GitHub Actions with that tag selected.
+
+The workflow reruns CI, uploads verified artifacts to TestPyPI, checks the downloaded
+wheel's hash and installation, then publishes the same artifacts to PyPI and verifies
+again. Pushes alone do not publish. Check the package page after completion.
+
+If publication fails, rerun failed jobs in the same run while its `release-dist`
+artifact is available. Never overwrite tags or uploaded files, or hide mismatches
+with `skip-existing`. Changed release contents require a new version.
+
+## Replacing an existing release
+
+`0.1.0.post1` replaces the examples, documentation and test fixtures shipped in
+`0.1.0` while preserving library behavior. Publish and verify the replacement on
+both indexes before retiring the earlier release. Consumers with exact `==0.1.0`
+pins must update them; a post-release cannot satisfy that exact pin.
+
+[Yanking](https://docs.pypi.org/project-management/yanking/) leaves files available
+to exact pins and direct downloads. If the old files must be removed, delete the
+old release separately on PyPI and TestPyPI after verifying the replacement.
+[Deleted filenames cannot be reused](https://pypi.org/help/#file-name-reuse).
+Deleting an index release does not remove Git tags, branches, source archives,
+or copies already downloaded. Keep recovery branches local when retiring public
+history, and review old public refs separately.

{structwire-0.1.0 → structwire-0.1.0.post1}/docs/COMPATIBILITY.md

@@ -2,8 +2,13 @@
 
 ## API and versions
 
-StructWire `0.1.0` is an alpha API. Consumers that depend on this series can use
-`structwire>=0.1,<0.2`.
+StructWire `0.1.0.post1` is an alpha API. Consumers that depend on this series can use
+`structwire>=0.1.0.post1,<0.2`.
+
+This post-release updates documentation, examples and test fixtures. The public
+API, schema version and encoding/decoding behavior are unchanged from `0.1.0`.
+The example files are teaching material, outside the library's compatibility
+contract. Exact pins to `structwire==0.1.0` must be updated to select the post-release.
 
 Schema documents have a separate `version: 1`. Unsupported schema versions,
 unknown keys, conflicting aliases, and duplicate YAML mapping keys are rejected

structwire-0.1.0.post1/docs/INTEGRATION_MODEL.md

@@ -0,0 +1,61 @@
+# Integration examples
+
+These teaching examples use invented identifiers and payloads, not real-world
+message definitions.
+
+The application selects a codec and passes it payload bytes. It handles
+identifiers, framing, checksums and device I/O. The YAML below is illustrative
+**application configuration**; StructWire does not load the outer mappings.
+
+## Named codec reference
+
+A fictional message type can be mapped to a named catalog entry:
+
+```yaml
+messages:
+  by_kind:
+    status:
+      codec: frame_status
+```
+
+The application looks up `frame_status` and calls
+`catalog.decode("frame_status", payload)`.
+See [catalog_demo.py](../examples/catalog_demo.py) and
+[codecs.yaml](../examples/codecs.yaml) for runnable examples.
+
+## Inline layout
+
+Application configuration may also contain a complete synthetic layout:
+
+```yaml
+messages:
+  by_kind:
+    custom:
+      layout:
+        size: 2
+        fields:
+          - name: category
+            type: enum
+            values: {0: basic, 1: extended}
+          - name: count
+            type: uint8
+```
+
+The application extracts the nested `layout` mapping and passes it to
+`layout_from_mapping(...).compile()`. All routing remains outside StructWire.
+
+## Framed byte stream
+
+For example, an imaginary stream might contain:
+
+```text
+C7 21 | <6 payload bytes> | checksum
+```
+
+The application checks the packet envelope, extracts six bytes and uses
+`catalog.decode("environment_sample", payload)`. This library does **not**
+implement the fictional envelope or checksum.
+
+The [transport bindings](../examples/transport_bindings.yaml) and
+[UART bindings](../examples/uart_bindings.yaml) illustrate application-owned
+routing independently of any particular framework.

{structwire-0.1.0 → structwire-0.1.0.post1}/docs/SCHEMA.md

@@ -52,11 +52,11 @@ Encoding fills unused bytes with zero; decoding does not preserve their values.
 - `unit`: display/documentation metadata only
 - `description`: display/documentation metadata only
 
-Numeric `bias` also accepts the compatibility alias `physical_offset`. If both
+Numeric `bias` also accepts the alias `physical_offset`. If both
 spellings of an alias are supplied, their values must agree. Unknown catalog,
 layout and field keys are rejected.
 
-For compatibility, a valid `byteorder` is accepted on every kind. Integer/float
+A valid `byteorder` is accepted on every kind. Integer/float
 kind names take precedence even when the supplied order disagrees (including a
 little-endian kind with the default `big`). BCD, ASCII and bytes ignore it and
 retain wire order. `describe()` reports the kind-defined order for integers and
@@ -90,7 +90,7 @@ labels must be strings; field, flag and catalog names must be non-empty. Enum
 labels must be unique. Quote YAML labels such as
 `"on"`, `"off"`, `"yes"` and `"no"`: PyYAML otherwise resolves these as booleans.
 
-### Compatibility kind aliases
+### Kind aliases
 
 `uint8`/`int8` map to `u8`/`i8`. For widths 16, 24, 32 and 64,
 `uint<width>_be`/`uint<width>_le` and `int<width>_be`/`int<width>_le` map to their
@@ -137,12 +137,12 @@ overlapping fields unless their masks are disjoint:
 from structwire import Field, Layout
 
 status = Layout(
-    Field("error", "u8", mask=0xF0, shift=4),
-    Field("alive", "u8", offset=0, mask=0x0F),
+    Field("upper_nibble", "u8", mask=0xF0, shift=4),
+    Field("lower_nibble", "u8", offset=0, mask=0x0F),
 ).compile()
 
-assert status.decode(b"\x53") == {"error": 5, "alive": 3}
-assert status.encode({"error": 5, "alive": 3}) == b"\x53"
+assert status.decode(b"\x53") == {"upper_nibble": 5, "lower_nibble": 3}
+assert status.encode({"upper_nibble": 5, "lower_nibble": 3}) == b"\x53"
 ```
 
 Routing keys belong in project configuration, outside this schema.

structwire-0.1.0.post1/examples/bcd_record.py

@@ -0,0 +1,14 @@
+from structwire import Field, Layout
+
+# Invented numeric record demonstrating one-byte and multi-byte packed BCD.
+record = Layout(
+    Field("batch", "bcd", length=2),
+    Field("quantity", "bcd"),
+    name="example-bcd-record",
+).compile()
+
+values = {"batch": 1234, "quantity": 25}
+encoded = record.encode(values)
+
+assert encoded == bytes.fromhex("12 34 25")
+assert record.decode(encoded) == values

structwire-0.1.0.post1/examples/ble_payload.py

@@ -0,0 +1,21 @@
+from structwire import Field, Layout
+
+# Invented BLE application payload. Not based on any product's GATT specification.
+measurement = Layout(
+    Field("format", "u8"),
+    Field("channel", "u8"),
+    Field("temperature_c", "i16le", scale=0.1),
+    Field("humidity_pct", "u8"),
+    Field("battery_pct", "u8"),
+    name="example-ble-measurement",
+).compile()
+
+values = {
+    "format": 1,
+    "channel": 3,
+    "temperature_c": 21.5,
+    "humidity_pct": 48,
+    "battery_pct": 82,
+}
+raw = measurement.encode(values)
+assert measurement.decode(raw) == values

structwire-0.1.0.post1/examples/catalog_demo.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+
+from structwire import catalog_from_yaml
+
+catalog = catalog_from_yaml(Path(__file__).with_name("codecs.yaml"))
+
+# Purely synthetic example bytes: phase=running, both flags set, value=100.
+payload = bytes.fromhex("01 03 10 27")
+decoded = catalog.decode("frame_status", payload)
+assert decoded == {"phase": "running", "ready": True, "flagged": True, "value": 100.0}
+assert catalog.encode("frame_status", decoded) == payload
+
+values = {
+    "channel": 7,
+    "state": "sampling",
+    "temperature_c": 21.5,
+    "humidity_pct": 48.0,
+}
+encoded = catalog.encode("environment_sample", values)
+assert catalog.decode("environment_sample", encoded) == values
+print(encoded.hex(" ").upper())

structwire-0.1.0.post1/examples/codecs.yaml

@@ -0,0 +1,43 @@
+# All layouts and values are fictional teaching examples, not production formats.
+version: 1
+
+codecs:
+  frame_status:
+    description: Synthetic packed record demonstrating enums, bits and scaling.
+    size: 4
+    fields:
+      - name: phase
+        type: enum
+        values: {0: idle, 1: running, 2: paused}
+      - name: ready
+        type: bool
+        offset: 1
+        bitmask: 0x01
+      - name: flagged
+        type: bool
+        offset: 1
+        bitmask: 0x02
+        bitshift: 1
+      - name: value
+        type: uint16_le
+        offset: 2
+        scale: 0.01
+        unit: arbitrary
+
+  environment_sample:
+    description: Synthetic six-byte environmental measurement.
+    size: 6
+    fields:
+      - name: channel
+        type: uint8
+      - name: state
+        type: enum
+        values: {0: idle, 1: sampling, 2: paused}
+      - name: temperature_c
+        type: int16_le
+        scale: 0.01
+        unit: degC
+      - name: humidity_pct
+        type: uint16_le
+        scale: 0.01
+        unit: pct

structwire-0.1.0.post1/examples/packed_fields.py

@@ -0,0 +1,14 @@
+from structwire import Field, Layout
+
+# Invented record demonstrating two disjoint nibble masks in the same byte.
+record = Layout(
+    Field("upper_code", "u8", mask=0xF0, shift=4),
+    Field("lower_code", "u8", offset=0, mask=0x0F),
+    Field("reading", "u16le", scale=0.1),
+    name="example-packed-fields",
+).compile()
+
+values = {"upper_code": 2, "lower_code": 7, "reading": 12.5}
+payload = record.encode(values)
+assert record.decode(payload) == values
+print(payload.hex(" ").upper())

structwire-0.1.0.post1/examples/transport_bindings.yaml

@@ -0,0 +1,35 @@
+# Invented routing keys, not values from any real device or protocol.
+# This is application configuration, not a StructWire schema.
+messages:
+  by_kind:
+    sample:
+      codec: environment_sample
+    status:
+      codec: frame_status
+  by_address:
+    0x10:
+      codec: frame_status
+    0x20:
+      codec: environment_sample
+  address_ranges:
+    - base: 0x40
+      count: 4
+      codec: environment_sample
+      index_name: channel
+
+# Only the nested layout is passed to layout_from_mapping().
+inline_example:
+  kinds:
+    custom:
+      layout:
+        size: 4
+        fields:
+          - name: category
+            type: enum
+            values: {0: basic, 1: extended}
+          - name: count
+            type: uint8
+          - name: ratio
+            type: uint16_le
+            scale: 0.01
+            unit: pct

structwire-0.1.0.post1/examples/uart_bindings.yaml

@@ -0,0 +1,13 @@
+# Completely fictional packet envelope used to illustrate application-side routing.
+# The application owns framing, checksums and I/O; StructWire sees only payload bytes.
+# Example: [marker=0xC7][kind=0x21][6-byte payload][checksum]
+uart:
+  messages:
+    sample:
+      match:
+        marker: 0xC7
+        kind: 0x21
+      payload:
+        offset: 2
+        length: 6
+        codec: environment_sample

{structwire-0.1.0 → structwire-0.1.0.post1}/scripts/check_dist.py

@@ -135,7 +135,9 @@ def inspect_distributions(directory: Path, tag: str | None = None) -> dict:
 def main() -> None:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("directory", type=Path, nargs="?", default=Path("dist"))
-    parser.add_argument("--tag", help="Require a vX.Y.Z tag matching the built version")
+    parser.add_argument(
+        "--tag", help="Require a version tag matching the built version (e.g. v0.1.0.post1)"
+    )
     args = parser.parse_args()
     print(json.dumps(inspect_distributions(args.directory, args.tag), indent=2))
 

{structwire-0.1.0 → structwire-0.1.0.post1}/src/structwire/__init__.py

@@ -30,4 +30,4 @@ __all__ = [
     "layout_from_yaml",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.1.0.post1"

{structwire-0.1.0 → structwire-0.1.0.post1}/src/structwire/model.py

@@ -78,7 +78,7 @@ def _schema_integer(value: Any, where: str) -> int:
 
 
 def canonical_kind(kind: str) -> str:
-    """Return a stable kind name, accepting compatibility aliases."""
+    """Return a stable kind name, accepting kind aliases."""
     if not isinstance(kind, str):
         raise SchemaError("Field kind must be a string")
     key = kind.strip().lower().replace("-", "_")

{structwire-0.1.0 → structwire-0.1.0.post1/src/structwire.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structwire
-Version: 0.1.0
+Version: 0.1.0.post1
 Summary: A small schema-driven binary payload codec for Python.
 Author: Nidhal Abidi
 License-Expression: MIT
@@ -49,7 +49,13 @@ Your application supplies the bytes and handles transport I/O and routing.
 
 ## Install
 
-Python 3.11 or newer is required. Install from the source checkout:
+Python 3.11 or newer is required. Install from PyPI:
+
+```bash
+python -m pip install "structwire>=0.1.0.post1,<0.2"
+```
+
+Or install from the source checkout:
 
 ```bash
 git clone https://github.com/nidops/structwire.git
@@ -57,7 +63,7 @@ cd structwire
 python -m pip install .
 ```
 
-Version `0.1.0` is an alpha API. PyYAML is installed automatically for YAML loading.
+Version `0.1.0.post1` is an alpha API. PyYAML is installed automatically for YAML loading.
 
 ## Quick start
 
@@ -65,13 +71,13 @@ Version `0.1.0` is an alpha API. PyYAML is installed automatically for YAML load
 from structwire import Field, Layout
 
 codec = Layout(
-    Field("temperature_c", "i16le", scale=0.1),
-    Field("state", "u8"),
+    Field("level", "i16le", scale=0.1),
+    Field("quality", "u8"),
 ).compile()
 
-payload = codec.encode({"temperature_c": 23.5, "state": 1})
+payload = codec.encode({"level": 23.5, "quality": 1})
 assert payload == bytes.fromhex("eb 00 01")
-assert codec.decode(payload) == {"temperature_c": 23.5, "state": 1}
+assert codec.decode(payload) == {"level": 23.5, "quality": 1}
 ```
 
 Compile a layout once and reuse its codec.
@@ -83,27 +89,27 @@ Save this as `codecs.yaml`:
 ```yaml
 version: 1
 codecs:
-  node_status:
+  frame_status:
     size: 4
     fields:
-      - name: mode
+      - name: phase
         type: enum
-        values: {0: asleep, 1: awake, 2: fault}
-      - name: supply_voltage
+        values: {0: idle, 1: running, 2: paused}
+      - name: value
         type: uint16_le
         offset: 2
-        scale: 0.001
-        unit: V
+        scale: 0.01
+        unit: arbitrary
 ```
 
 ```python
 from structwire import catalog_from_yaml
 
 catalog = catalog_from_yaml("codecs.yaml")
-payload = bytes.fromhex("01 00 88 13")
-values = catalog.decode("node_status", payload)
-assert values == {"mode": "awake", "supply_voltage": 5.0}
-assert catalog.encode("node_status", values) == payload
+payload = bytes.fromhex("01 00 64 00")
+values = catalog.decode("frame_status", payload)
+assert values == {"phase": "running", "value": 1.0}
+assert catalog.encode("frame_status", values) == payload
 ```
 
 Offsets and sizes are in bytes. Here, byte 1 is unused and encodes as zero.
@@ -140,6 +146,13 @@ limits; applications must bound untrusted schema and payload sizes. See
 
 ## Documentation and examples
 
+All examples use fictional values and are independent of specific products.
+
+- [BCD records](https://github.com/nidops/structwire/blob/master/examples/bcd_record.py)
+- [Packed bit fields](https://github.com/nidops/structwire/blob/master/examples/packed_fields.py)
+- [YAML codec catalog](https://github.com/nidops/structwire/blob/master/examples/codecs.yaml)
+- [BLE-style payload](https://github.com/nidops/structwire/blob/master/examples/ble_payload.py)
+- [Generic message routing](https://github.com/nidops/structwire/blob/master/examples/transport_bindings.yaml)
 - [Python API](https://github.com/nidops/structwire/blob/master/docs/API.md)
 - [Schema reference](https://github.com/nidops/structwire/blob/master/docs/SCHEMA.md)
 - [Examples](https://github.com/nidops/structwire/tree/master/examples)

{structwire-0.1.0 → structwire-0.1.0.post1}/src/structwire.egg-info/SOURCES.txt

@@ -6,17 +6,16 @@ RELEASING.md
 SECURITY.md
 pyproject.toml
 docs/API.md
-docs/AUTOSPAN_ADOPTION.md
 docs/COMPATIBILITY.md
 docs/DESIGN.md
 docs/INTEGRATION_MODEL.md
 docs/SCHEMA.md
-examples/automotive_bindings.yaml
+examples/bcd_record.py
 examples/ble_payload.py
-examples/can_like_signal.py
 examples/catalog_demo.py
 examples/codecs.yaml
-examples/diagnostic_record.py
+examples/packed_fields.py
+examples/transport_bindings.yaml
 examples/uart_bindings.yaml
 scripts/check_dist.py
 scripts/check_readme.py

{structwire-0.1.0 → structwire-0.1.0.post1}/tests/test_codec.py

@@ -42,21 +42,19 @@ def test_nonfinite_integer_values_raise_encode_error(value: float) -> None:
         Layout(Field("count", "u8")).encode({"count": value})
 
 
-def test_sequential_bcd_and_integers_compatibility() -> None:
+def test_sequential_bcd_and_integers_round_trip() -> None:
     codec = Layout(
-        Field("version_major", "bcd"),
-        Field("version_minor", "bcd"),
-        Field("version_patch", "bcd"),
-        Field("compile_hour", "uint8"),
-        Field("compile_minute", "bcd"),
+        Field("batch", "bcd", length=2),
+        Field("quantity", "uint8"),
+        Field("group", "bcd"),
+        Field("sequence", "bcd"),
     ).compile()
-    payload = bytes.fromhex("26 29 01 08 36")
+    payload = bytes.fromhex("12 34 07 25 05")
     assert codec.decode(payload) == {
-        "version_major": 26,
-        "version_minor": 29,
-        "version_patch": 1,
-        "compile_hour": 8,
-        "compile_minute": 36,
+        "batch": 1234,
+        "quantity": 7,
+        "group": 25,
+        "sequence": 5,
     }
     assert codec.encode(codec.decode(payload)) == payload
 
@@ -96,9 +94,9 @@ def test_raw_bytes_exact_width() -> None:
 
 def test_mac_roundtrip() -> None:
     codec = Layout(Field("address", "mac_address")).compile()
-    payload = bytes.fromhex("7B 7C FA 58 1A A6")
-    assert codec.decode(payload)["address"] == "7B:7C:FA:58:1A:A6"
-    assert codec.encode({"address": "7B:7C:FA:58:1A:A6"}) == payload
+    payload = bytes.fromhex("02 00 00 00 00 01")
+    assert codec.decode(payload)["address"] == "02:00:00:00:00:01"
+    assert codec.encode({"address": "02:00:00:00:00:01"}) == payload
 
 
 @pytest.mark.parametrize("kind,raw", [("u64be", 2**53 + 1), ("i64be", -(2**53 + 1))])
@@ -368,9 +366,9 @@ def test_raw_integer_is_not_treated_as_zero_bytes() -> None:
 
 def test_little_endian_mac_roundtrip() -> None:
     codec = Layout(Field("address", "mac", byteorder="little")).compile()
-    payload = bytes.fromhex("A6 1A 58 FA 7C 7B")
-    assert codec.decode(payload) == {"address": "7B:7C:FA:58:1A:A6"}
-    assert codec.encode({"address": "7B:7C:FA:58:1A:A6"}) == payload
+    payload = bytes.fromhex("01 00 00 00 00 02")
+    assert codec.decode(payload) == {"address": "02:00:00:00:00:01"}
+    assert codec.encode({"address": "02:00:00:00:00:01"}) == payload
 
 
 @pytest.mark.parametrize("payload", [1, True, "x", [1], None])

{structwire-0.1.0 → structwire-0.1.0.post1}/tests/test_examples.py

@@ -119,5 +119,5 @@ def test_example_bindings_reference_existing_codecs() -> None:
             for nested in value:
                 validate_bindings(nested)
 
-    for name in ("automotive_bindings.yaml", "uart_bindings.yaml"):
+    for name in ("transport_bindings.yaml", "uart_bindings.yaml"):
         validate_bindings(_yaml_load(ROOT / "examples" / name))

{structwire-0.1.0 → structwire-0.1.0.post1}/tests/test_loaders.py

@@ -15,18 +15,18 @@ from structwire import (
 )
 
 
-def test_mapping_loader_accepts_compatibility_names() -> None:
+def test_mapping_loader_accepts_schema_aliases() -> None:
     layout = layout_from_mapping(
         {
             "name": "status",
             "fields": [
-                {"name": "error", "type": "uint8", "bitmask": "0xF0", "bitshift": 4},
-                {"name": "alive", "type": "uint8", "offset": 0, "bitmask": "0x0F"},
+                {"name": "upper_nibble", "type": "uint8", "bitmask": "0xF0", "bitshift": 4},
+                {"name": "lower_nibble", "type": "uint8", "offset": 0, "bitmask": "0x0F"},
             ],
         }
     )
     codec = layout.compile()
-    assert codec.decode(b"\x53") == {"error": 5, "alive": 3}
+    assert codec.decode(b"\x53") == {"upper_nibble": 5, "lower_nibble": 3}
 
 
 def test_mapping_loader_parses_enum_hex_keys() -> None:

{structwire-0.1.0 → structwire-0.1.0.post1}/tests/test_schema.py

@@ -45,13 +45,13 @@ def test_describe_reports_resolved_offsets() -> None:
     assert description["fields"][1]["offset"] == 1
 
 
-def test_formatting_helpers_preserve_legacy_human_readability() -> None:
-    assert format_mac_address(bytes.fromhex("7B 7C FA 58 1A A6")) == "7B:7C:FA:58:1A:A6"
+def test_formatting_helpers_render_readable_values() -> None:
+    assert format_mac_address(bytes.fromhex("02 00 00 00 00 01")) == "02:00:00:00:00:01"
     assert (
-        format_mac_address(bytes.fromhex("A6 1A 58 FA 7C 7B"), byteorder="little")
-        == "7B:7C:FA:58:1A:A6"
+        format_mac_address(bytes.fromhex("01 00 00 00 00 02"), byteorder="little")
+        == "02:00:00:00:00:01"
     )
-    assert format_value(b"\x7b\x7c\xfa") == "7B 7C FA"
+    assert format_value(b"\x12\x34\x56") == "12 34 56"
     assert format_value(b"") == "<empty>"
     assert format_record({"raw": b"\x01", "nested": {"x": b"\x02"}}) == {
         "raw": "01",

structwire-0.1.0/RELEASING.md

@@ -1,31 +0,0 @@
-# Releasing StructWire
-
-Package version lives in `src/structwire/__init__.py`; setuptools derives metadata
-from it. Keep this as the single version source.
-
-## Setup
-
-Configure [trusted publishing](https://docs.pypi.org/trusted-publishers/)
-separately on TestPyPI and PyPI for project `structwire`, repository
-`nidops/structwire`, and workflow `publish.yml`. Use GitHub environments `testpypi`
-and `pypi` respectively, restricted to release tags. For a new project, register
-a pending publisher; this does not reserve the package name. Confirm account
-ownership and public documentation links.
-
-## Release
-
-1. Update the package version and documentation.
-2. Run the [development checks](CONTRIBUTING.md#development) and
-   [distribution checks](CONTRIBUTING.md#distribution-checks).
-3. From a clean checkout, tag the reviewed `master` commit as `vX.Y.Z` after all
-   supported CI jobs pass. Verify the version with
-   `python scripts/check_dist.py dist --tag vX.Y.Z`, substituting the actual version.
-4. Push the tag, then manually run **Publish** in GitHub Actions with that tag selected.
-
-The workflow reruns CI, uploads verified artifacts to TestPyPI, checks the downloaded
-wheel's hash and installation, then publishes the same artifacts to PyPI and verifies
-again. Pushes alone do not publish. Check the package page after completion.
-
-If publication fails, rerun failed jobs in the same run while its `release-dist`
-artifact is available. Never overwrite tags or uploaded files, or hide mismatches
-with `skip-existing`. Changed release contents require a new version.

structwire-0.1.0/docs/AUTOSPAN_ADOPTION.md

@@ -1,41 +0,0 @@
-# Optional AutoSpan adoption
-
-An AutoSpan project plugin can use StructWire to encode and decode payloads.
-StructWire has no AutoSpan dependency, and using it does not require AutoSpan core
-to depend on it.
-
-Suggested responsibilities for this optional integration:
-
-| Component | Responsibility |
-|---|---|
-| AutoSpan core | Test planning, execution and evidence |
-| StructWire | Payload layouts, encoding, decoding and value formatting |
-| Driver or adapter | Transport, protocol and device operations |
-| Project plugin | Device configuration, routing and payload definitions |
-
-## Project payload catalog
-
-A project-specific diagnostic or signal catalog should own the mapping from its identifier to a
-StructWire `Codec`:
-
-```python
-from structwire import Field, Layout
-
-SOFTWARE_VERSION = Layout(
-    Field("major", "bcd"),
-    Field("minor", "bcd"),
-    Field("patch", "bcd"),
-).compile()
-
-PAYLOADS = {
-    0x1001: SOFTWARE_VERSION,
-}
-```
-
-The protocol layer remains responsible for extracting or adding service identifiers and headers.
-StructWire receives only the payload region whose binary layout it owns.
-
-## Integration rule
-
-Declare the StructWire dependency in the plugin that uses it. For named catalogs
-and inline layouts, see the [integration examples](INTEGRATION_MODEL.md).

structwire-0.1.0/docs/INTEGRATION_MODEL.md

@@ -1,68 +0,0 @@
-# Integration examples
-
-The application selects a codec and passes it payload bytes. It handles protocol
-identifiers, headers, framing, checksums and device I/O.
-
-The routing YAML below is illustrative application configuration. StructWire does
-not load these outer mappings; application code must extract the codec name or
-nested layout.
-
-## Named codec reference
-
-Use a named catalog when several messages or tests share a layout:
-
-```yaml
-can:
-  frames:
-    0x321:
-      codec: node_status
-```
-
-The application reads the frame identifier, looks up `node_status` in its
-configuration, then calls `catalog.decode("node_status", payload)`.
-See [catalog_demo.py](../examples/catalog_demo.py) and
-[codecs.yaml](../examples/codecs.yaml) for a working catalog example.
-
-## Inline layout
-
-An application can keep a layout alongside a single routing entry:
-
-```yaml
-diagnostics:
-  dids:
-    0xF186:
-      layout:
-        size: 1
-        fields:
-          - name: session
-            type: enum
-            values: {0x01: default, 0x02: programming, 0x03: extended}
-```
-
-The diagnostic application passes the nested `layout` mapping to
-`layout_from_mapping(...).compile()`. The diagnostic identifier (`0xF186`) stays
-in the application.
-
-## UART example
-
-A small device may use a packet envelope such as:
-
-```text
-A5 10 | <6 payload bytes> | CRC16
-```
-
-The application validates the framing and CRC, then extracts the payload.
-Its configuration could map the message type to a codec:
-
-```yaml
-uart:
-  messages:
-    status:
-      match: {sync: 0xA5, type: 0x10}
-      payload: {offset: 2, length: 6, codec: sensor_status}
-```
-
-The application passes exactly six bytes to `catalog.decode("sensor_status", payload)`.
-The illustrative [automotive](../examples/automotive_bindings.yaml) and
-[UART](../examples/uart_bindings.yaml) configuration files reference codecs from
-the example catalog. For AutoSpan projects, see [optional adoption](AUTOSPAN_ADOPTION.md).

structwire-0.1.0/examples/automotive_bindings.yaml

@@ -1,36 +0,0 @@
-# Illustrative application configuration, not a StructWire schema.
-# Application code maps these protocol identifiers to codecs from codecs.yaml.
-
-diagnostics:
-  dids:
-    0xF186:
-      codec: diagnostic_session
-
-can:
-  frames:
-    0x321:
-      codec: node_status
-
-  # Application-defined range routing.
-  ranges:
-    - base_id: 0x300
-      count: 16
-      codec: node_status
-      index_name: node_id
-
-# Application code passes only the nested layout to layout_from_mapping().
-diagnostics_inline_example:
-  dids:
-    0xF187:
-      layout:
-        size: 4
-        fields:
-          - name: state
-            type: enum
-            values: {0x00: inactive, 0x01: active}
-          - name: counter
-            type: uint8
-          - name: voltage
-            type: uint16_le
-            scale: 0.001
-            unit: V

structwire-0.1.0/examples/ble_payload.py

@@ -1,14 +0,0 @@
-from structwire import Field, Layout
-
-advertisement = Layout(
-    Field("version", "u8"),
-    Field("sensor_id", "u16le"),
-    Field("temperature_c", "i16le", scale=0.01),
-    Field("battery_pct", "u8"),
-    name="sensor-advertisement",
-).compile()
-
-raw = advertisement.encode(
-    {"version": 1, "sensor_id": 42, "temperature_c": 23.75, "battery_pct": 91}
-)
-assert advertisement.decode(raw)["sensor_id"] == 42

structwire-0.1.0/examples/can_like_signal.py

@@ -1,12 +0,0 @@
-from structwire import Field, Layout
-
-status = Layout(
-    Field("error_state", "u8", mask=0xF0, shift=4),
-    Field("alive_state", "u8", offset=0, mask=0x0F),
-    Field("voltage", "u16le", scale=0.01),
-    name="status-frame",
-).compile()
-
-payload = status.encode({"error_state": 2, "alive_state": 7, "voltage": 13.42})
-print(payload.hex(" ").upper())
-print(status.decode(payload))

structwire-0.1.0/examples/catalog_demo.py

@@ -1,19 +0,0 @@
-from pathlib import Path
-
-from structwire import catalog_from_yaml
-
-catalog = catalog_from_yaml(Path(__file__).with_name("codecs.yaml"))
-
-payload = bytes.fromhex("01 03 34 30")
-print(catalog.decode("node_status", payload))
-
-encoded = catalog.encode(
-    "sensor_status",
-    {
-        "sensor_id": 7,
-        "state": "measuring",
-        "temperature": 23.45,
-        "battery_voltage": 3.721,
-    },
-)
-print(encoded.hex(" ").upper())

structwire-0.1.0/examples/codecs.yaml

@@ -1,59 +0,0 @@
-version: 1
-
-codecs:
-  diagnostic_session:
-    description: One-byte diagnostic session state.
-    size: 1
-    fields:
-      - name: session
-        type: enum
-        values:
-          0x01: default
-          0x02: programming
-          0x03: extended
-
-  node_status:
-    description: Synthetic automotive cyclic status payload.
-    size: 4
-    fields:
-      - name: mode
-        type: enum
-        values:
-          0x00: asleep
-          0x01: awake
-          0x02: fault
-      - name: communication_ok
-        type: bool
-        offset: 1
-        bitmask: 0x01
-      - name: sensor_ok
-        type: bool
-        offset: 1
-        bitmask: 0x02
-        bitshift: 1
-      - name: supply_voltage
-        type: uint16_le
-        offset: 2
-        scale: 0.001
-        unit: V
-
-  sensor_status:
-    description: Small device payload suitable for UART, BLE, or another transport.
-    size: 6
-    fields:
-      - name: sensor_id
-        type: uint8
-      - name: state
-        type: enum
-        values:
-          0x00: idle
-          0x01: measuring
-          0x02: error
-      - name: temperature
-        type: int16_le
-        scale: 0.01
-        unit: degC
-      - name: battery_voltage
-        type: uint16_le
-        scale: 0.001
-        unit: V

structwire-0.1.0/examples/diagnostic_record.py

@@ -1,13 +0,0 @@
-from structwire import Field, Layout
-
-software_version = Layout(
-    Field("major", "bcd"),
-    Field("minor", "bcd"),
-    Field("patch", "bcd"),
-    Field("build", "u16be"),
-    name="software-version",
-).compile()
-
-raw = bytes.fromhex("26 10 03 01 F4")
-assert software_version.decode(raw) == {"major": 26, "minor": 10, "patch": 3, "build": 500}
-assert software_version.encode(software_version.decode(raw)) == raw

structwire-0.1.0/examples/uart_bindings.yaml

@@ -1,13 +0,0 @@
-# Illustrative application configuration; the application handles framing and routing.
-# Example wire packet: [sync=0xA5][type=0x10][6-byte payload][crc16]
-
-uart:
-  messages:
-    status:
-      match:
-        sync: 0xA5
-        type: 0x10
-      payload:
-        offset: 2
-        length: 6
-        codec: sensor_status