Metadata-Version: 2.5
Name: pycrc
Version: 0.12.0
Summary: A free, easy to use Cyclic Redundancy Check source code generator for C/C++
Project-URL: Homepage, https://pycrc.org
Project-URL: Documentation, https://pycrc.org/pycrc.html
Project-URL: Bug Tracker, https://github.com/tpircher/pycrc/issues
Project-URL: Source Code, https://github.com/tpircher/pycrc
Author-email: Thomas Pircher <thp.oss@p5r.uk>
License-Expression: MIT
License-File: LICENSE
Keywords: c,checksum,code-generator,crc,cyclic-redundancy-check
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# pycrc

[pycrc](https://pycrc.org) is a free, easy to use Cyclic Redundancy Check (CRC)
calculator and C source code generator.


## System Requirements

Python 3.10 or newer is required to run pycrc.
The last version compatible with Python 2 is v0.9.x.


## Running pycrc

The easiest way to run pycrc is to install it in a virtual environment, e.g.:

    python3 -m venv .venv
    . .venv/bin/activate
    python3 -m pip install pycrc

Then the pycrc executable is included in the path in the virtual environment:

    pycrc [OPTIONS]

or

    python3 -m pycrc [OPTIONS]


## Installation

Install pycrc (if required) using pip:

    python3 -m pip install pycrc

or apt (on Debian 13 and later, Ubuntu 23.10 and later, and
derivatives):

    sudo apt install pycrc

Either of these will install a `pycrc` binary in the path.

Once installed you can also run it as a module:

    python3 -m pycrc [OPTIONS]


## Python API

pycrc can also be used as a Python library:

    import pycrc

    # One-shot checksum for a named model.
    print(pycrc.crc("crc-32", b"123456789"))

    from pycrc import Crc

    # Or use a model directly, choosing one of the algorithms.
    crc = Crc.from_model("crc-16-usb")
    print(crc.bit_by_bit_fast("123456789"))
    print(crc.table_driven(b"123456789"))

    # Large inputs can be processed incrementally.
    crc = Crc.from_model("crc-32")
    with open("image.bin", "rb") as f:
        for chunk in iter(lambda: f.read(4096), b""):
            crc.update(chunk)
    print(crc.digest())

The known models are exposed as a read-only mapping:

    from pycrc import CrcModels

    models = CrcModels()
    print(", ".join(models.names()))
    params = models["crc-32"]
    print(params.width, hex(params.poly), params.check)

The package ships inline type annotations (PEP 561), so editors and type
checkers can use them without any extra stub packages.

### Backwards compatibility

The Python API is additive: the API that existed before the typed models is
still available.

- ``CrcModels.get_params()`` still returns a mutable ``dict`` (a copy); the
  immutable ``CrcParams`` objects are available through the mapping interface
  (``models[name]`` / ``models.get(name)``).
- ``Crc.tbl_idx_width`` and ``Crc.gen_table()`` remain available as aliases
  for ``Crc.table_idx_width`` and ``Crc.table``.


## Development

Create a virtual environment and install the package in editable mode together
with the development tools:

    python3 -m venv .venv
    . .venv/bin/activate
    python3 -m pip install -e ".[dev]"


### Running the tests

Run the whole test suite with pytest:

    pytest

The tests in `test/test_codegen.py` and `test/test_cli.py` generate C source
code, compile it and run it, so a C compiler (`cc`) must be installed and
available on the `PATH`.

To run a single test file, class or function, pass it to pytest:

    pytest test/test_algorithms.py
    pytest test/test_codegen.py::TestCodeGen
    pytest test/test_algorithms.py::test_all_models_with_check_input

To measure test coverage (and enforce the minimum coverage configured in
`pyproject.toml`):

    pytest --cov=pycrc --cov-report=term-missing

The code generation and CLI tests spawn subprocesses. To include the code that
runs in those subprocesses in the coverage report, point
`COVERAGE_PROCESS_START` at `pyproject.toml`, as the CI workflow does:

    COVERAGE_PROCESS_START="$PWD/pyproject.toml" pytest --cov=pycrc --cov-report=term-missing

**Checking the code style and types**

    ruff check .
    mypy

### Building the documentation

The HTML manual and the man page are generated from the DocBook source in
`doc`. On Debian/Ubuntu the required tools are installed with:

    sudo apt-get install make xsltproc docbook-xsl-ns docbook5-xml

Generate the documentation with:

    make -C doc

This writes `doc/pycrc.html`, `doc/pycrc.1` and the stylesheet
`doc/docbook.css`. These generated files are not checked in.

Build the source and wheel distributions with:

    python3 -m build

The sdist target regenerates the documentation and includes the generated
files in the source tarball.


## Getting help

If you are new to pycrc and want to generate C code, start with
[the tutorial](https://pycrc.org/tutorial.html).

The [pycrc manual page](https://pycrc.org/pycrc.html) explains the command line
options in some detail and also gives some more examples how to use pycrc.

If you have found a bug in pycrc or want to request a feature please take the
time and submit it to the
[issue tracker](https://github.com/tpircher/pycrc/issues).
Thanks for your help.

Also see the [frequently asked questions](https://pycrc.org/faq.html).


## Feedback

If you like pycrc, let me know and drop me a note. If you don't like pycrc let
me know what you don't like and why.
If you want some idea how to say thanks for this software, please have a look
[here](https://www.tty1.net/say-thanks_en.html).


## Copyright of the generated source code

The MIT licence allows commercial use of the source and the output of the
program. But since I got asked on occasion whether the generated code is
encumbered by the copyright of the author, I give my view on this:

The code generated by pycrc is not considered a substantial portion of the
software, therefore the licence does not cover the generated code; the
author of pycrc will not claim any copyright on the generated code.
