zcbor - CDDL Code Generation and Data Validation

Warnings

• breaking The library was renamed from `cddl-gen` to `zcbor` starting with version 0.4.0. Users upgrading from `cddl-gen` will need to update their `pip install` commands and import paths.
  Fix: Change `pip install cddl-gen` to `pip install zcbor`. Update old import statements or command-line invocations accordingly, noting that internal module structures also changed.
• breaking In version 0.8.0, the order of command-line arguments for `zcbor.main` was swapped. Previously (pre-0.8.0), it expected `output_path` then `input_path` (CDDL file). It now expects `input_path` (CDDL file) then `output_path`.
  Fix: Update your `zcbor.main` command-line invocations from `python -m zcbor.main <OUTPUT_DIRECTORY> <CDDL_FILE_PATH>` to `python -m zcbor.main <CDDL_FILE_PATH> <OUTPUT_DIRECTORY>`.
• breaking As of version 0.9.0, the names of the generated encode/decode functions in the output Python files have changed from `CamelCaseEncode`/`CamelCaseDecode` to `snake_case_encode`/`snake_case_decode`.
  Fix: Update calls to generated functions in your application code. For example, `MyMapEncode(...)` becomes `my_map_encode(...)`. Refer to the 0.9.0 migration guide for details.
• breaking Starting from version 0.9.0, the `any` type in CDDL schemas is explicitly unsupported and will cause compilation errors. This change improves type safety and generated code quality.
  Fix: Replace usages of `any` in your CDDL schemas with more specific types or alternative CDDL constructs that precisely define the expected data structure. If flexibility is required, handle the `any` type manually outside of the generated code.

Install

• pip install zcbor Install latest version

Imports

• cli

  from zcbor.main import cli

  Entry point for programmatic code generation using a CDDL schema. Typically invoked via `python -m zcbor.main`.
• encode, decode

  from zcbor.zcbor import encode, decode

  These functions are for direct CBOR encoding/decoding without CDDL schema validation. For CDDL-schema-driven operations, use the code generated by `zcbor.main`.

Quickstart

This quickstart demonstrates how to define a simple CDDL schema, use the `zcbor` command-line tool to generate Python encoding/decoding functions, and then import and use these generated functions to serialize and deserialize data according to the schema.

import os
import subprocess
import sys
import shutil

# 1. Define a simple CDDL schema in a temporary file
cddl_schema_content = """
my_map = {
    ? "label" => tstr,
    ? "value" => int,
}
"""
schema_file = "my_schema.cddl"
with open(schema_file, "w") as f:
    f.write(cddl_schema_content)

output_dir = "generated_code"
# Clean up previous runs if any
if os.path.exists(output_dir):
    shutil.rmtree(output_dir)
os.makedirs(output_dir, exist_ok=True)

print(f"Generating code from {schema_file} into {output_dir}...")
# 2. Run zcbor to generate Python code using the command-line interface
try:
    # Use sys.executable to ensure the correct Python environment's zcbor is used
    result = subprocess.run(
        [sys.executable, "-m", "zcbor.main", schema_file, output_dir],
        capture_output=True,
        check=True,
        text=True
    )
    print("Code generation successful.")
except subprocess.CalledProcessError as e:
    print(f"Error during code generation: {e}")
    print("STDERR:", e.stderr)
    sys.exit(1)

# Add the output directory to the Python path to import generated modules
sys.path.insert(0, output_dir)

try:
    # 3. Import from the generated code and use encode/decode
    # The generated module name will typically be the CDDL filename without extension, lowercased.
    # Function names are snake_case from v0.9.0 onwards.
    from my_schema import my_map_encode, my_map_decode

    data = {"label": "test", "value": 123}
    print(f"Original data: {data}")

    encoded_cbor = my_map_encode(data)
    print(f"Encoded CBOR (hex): {encoded_cbor.hex()}")

    decoded_data, _ = my_map_decode(encoded_cbor) # decode returns (data, remaining_bytes)
    print(f"Decoded data: {decoded_data}")

    assert data == decoded_data
    print("Encoding and decoding successful and data matches.")

except ImportError as e:
    print(f"Could not import generated module: {e}")
    print("Ensure zcbor.main successfully generated 'my_schema.py' in the 'generated_code' directory.")
except Exception as e:
    print(f"An error occurred during encoding/decoding: {e}")
finally:
    # Clean up temporary files and directories
    if os.path.exists(schema_file):
        os.remove(schema_file)
    if os.path.exists(output_dir):
        shutil.rmtree(output_dir)
    # Remove from sys.path
    if output_dir in sys.path:
        sys.path.remove(output_dir)