Metadata-Version: 2.4
Name: crc8-pure
Version: 0.1.0
Summary: Zero-dependency, pure-Python CRC-8 over 7 RevEng-catalogued variants
Author: crc8-pure contributors
License: MIT
Keywords: crc,crc8,checksum,pure-python,zero-dependency
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# crc8-pure

Zero-dependency, pure-Python CRC-8 over 7 RevEng-catalogued variants.

`crc8-pure` provides a single, self-contained implementation of seven widely
used CRC-8 variants — `crc-8`, `crc-8-darc`, `crc-8-i-code`, `crc-8-itu`
(CCITT), `crc-8-maxim` (DOW), `crc-8-rohc`, and `crc-8-wcdma` — together
with a class-based incremental API and a command-line entry point. No
C-extension dependencies; only the Python standard library is used at
runtime.

## Install

```bash
pip install crc8-pure
```

Or from a local checkout:

```bash
pip install -e .
```

Requires Python ≥ 3.8. There are no runtime dependencies.

## Quickstart

```python
import crc8_pure

# Functional API: returns an int 0–255
crc8_pure.crc8(b"hello")                  # crc-8 variant (default)
crc8_pure.crc8(b"hello", variant="crc-8-maxim")
crc8_pure.crc8_maxim(b"hello")            # convenience wrapper

# Incremental / streaming API
crc8_pure.crc8(b"hel", init=0x00)
crc8_pure.crc8(b"lo", init=<prev>)        # continues from previous state

# Class API
h = crc8_pure.CRC8(variant="crc-8-maxim")
h.update(b"hello")
h.digest()                                # -> bytes
h.hexdigest()                             # -> "3b"
```

### CLI

```bash
# String input
python -m crc8_pure crc8-maxim "123456789"

# Hex-prefixed output
python -m crc8_pure crc8 "123456789" --hex

# File input
python -m crc8_pure crc8-maxim path/to/file.bin

# Read from stdin
cat file.bin | python -m crc8_pure crc-8 -
```

## 7 Variants

| Variant        | Polynomial | Init | RefIn | RefOut | XOR Out | Check (`"123456789"`) |
|----------------|-----------:|-----:|:-----:|:------:|--------:|---------------------:|
| `crc-8`        | `0x07`     | `0x00` |  no  |  no   | `0x00`  | `0xF4`              |
| `crc-8-darc`   | `0x39`     | `0x00` | yes  |  yes  | `0x00`  | `0x15`              |
| `crc-8-i-code` | `0x1D`     | `0xFD` |  no  |  no   | `0x00`  | `0x7E`              |
| `crc-8-itu`    | `0x07`     | `0x55` |  no  |  no   | `0x55`  | `0xA1`              |
| `crc-8-maxim`  | `0x31`     | `0x00` | yes  |  yes  | `0x00`  | `0xA1`              |
| `crc-8-rohc`   | `0x07`     | `0xFF` | yes  |  yes  | `0x00`  | `0xD0`              |
| `crc-8-wcdma`  | `0x9B`     | `0x00` | yes  |  yes  | `0x00`  | `0x25`              |

Check values come from the
[RevEng CRC Catalogue](https://reveng.sourceforge.io/crc-catalogue/all.htm)
and have been verified byte-exact against `crcmod`.

Aliases: `CCITT` → `crc-8-itu`, `MAXIM` → `crc-8-maxim`,
`DOW-CRC` → `crc-8-maxim`.

## API

### `crc8(data=b"", variant="crc-8", init=None) -> int`

Compute a CRC-8 checksum. `init` lets you resume from a previous partial
result: `crc8(b"lo", init=crc8(b"hel"))` is equivalent to
`crc8(b"hello")`.

### `CRC8(variant="crc-8", init=None)`

Incremental calculator. Use `update(data)` to feed bytes, then
`digest()` (bytes) or `hexdigest()` (string).

### CLI

`python -m crc8_pure <variant> [FILE_OR_STRING...] [--hex]`

If no input is given (or `-`), data is read from stdin. A single argument
is treated as a file path if it exists, otherwise as a string literal.
Multiple arguments are concatenated.

## Tests

```bash
pip install pytest
pytest -q
```

The test suite covers all 21 canonical vectors (3 inputs × 7 variants)
plus boundary conditions, alias resolution, incremental equivalence,
class API, and CLI smoke tests.

Current test count: **126 tests**.

## Known Issues / Limitations

The following are honest documented limits of crc8-pure:

- **CRC-8 is not cryptographic.** CRC-8 is for error-detection on trusted media; do not
  use it as a cryptographic integrity check or MAC.
- **CLI stdin/file materialization.** `python -m crc8_pure <variant> <file>` fully
  materializes the file into RAM before processing. For multi-GB inputs this may
  exhaust memory; no streaming boundary is applied.
- **Thread-safety.** A `CRC8` instance is not safe for concurrent `update()` calls
  from multiple threads; create one instance per thread.
- **`data` accepts non-bytes silently.** Pass bytes-like objects (bytes/bytearray/
  memoryview). Passing a non-bytes value will produce a non-canonical result
  without raising an error.
- **No `CRC8.copy()` / `CRC8.reset()`.** Re-using a `CRC8` instance requires
  constructing a new one; there is no `copy()` or `reset()` method.

## License

MIT — see `LICENSE`.
