Install & Compatibility
Where this runs
tested against v0.9.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.034s · 24.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.6s · import 0.032s · 26MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cli
✓ import zcbor
✗ from zcbor import cli
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)
zcbor --version
Upgrade
Version history
0.9.1latest on PyPI · released Oct 17, 2024
Audit
Dependencies
pycddlrequiredRequired for parsing CDDL schemas.
cbor2requiredUnderpins CBOR encoding and decoding operations.
Jinja2requiredUsed for templating during Python code generation.
tomlrequiredUsed for internal configuration loading within the tool.