synta 0.2.0

ASN.1 parser, decoder, and encoder library with DER/BER support and C FFI
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

# Development


## Running Tests

```bash
# Build in development mode
python -m venv venv
source venv/bin/activate
maturin develop

# Run Python tests
python -m pytest tests/python/

# Or via the CI helper script
./contrib/ci/local-ci.sh python-test
```

## Running Benchmarks

```bash
# Build release extension first (verify .so is ~1.4 MB, not ~20 MB debug)
maturin develop --release

# Certificate parsing and field-access benchmark (synta vs cryptography)
python python/bench_certificate.py

# Include per-field getter breakdown
python python/bench_certificate.py --per-field

# PKCS#7 / PKCS#12 certificate extraction benchmark (synta vs cryptography)
python python/bench_pkcs.py

# Save Criterion-compatible JSON alongside Rust benchmarks
# (default output: target/criterion/)
python python/bench_certificate.py --save-criterion
python python/bench_pkcs.py --save-criterion

# Custom output directory
python python/bench_certificate.py --save-criterion path/to/criterion

# Compare with a previous run using criterion-compare
# (first run writes new/, second run rotates new/→base/ then writes new/)
python python/bench_certificate.py --save-criterion
criterion-compare target/criterion
```

The benchmark certificate files are cloned by the Rust Criterion benchmarks on
their first run. If `tests/vectors/` is missing, run:

```bash
cargo bench -p synta-bench --bench bindings --features bench-bindings --no-run
```

The parse-only group prints three Python entries per certificate in the
`binding_comparison` and `binding_post_quantum` groups:

```
binding_comparison/synta/cert_00_…       # from_der: shallow scan only (~0.15 µs)
binding_comparison/synta_full/cert_00_…  # full_from_der: complete RFC 5280 decode
binding_comparison/cryptography_x509/…   # envelope validation
```

The Rust benchmark (`cargo bench --bench bindings`) adds matching entries:

```
binding_comparison/rust_shallow/…        # validate_envelope: same 4-op scan as from_der
binding_comparison/rust_typed/…          # full Certificate::decode — apples-to-apples with synta_full
```

## criterion_compat.py

`python/criterion_compat.py` is a standalone, import-ready module that provides
the Criterion-compatible sampling and JSON-writing primitives. Import it
directly from other benchmark or test scripts:

```python
from criterion_compat import measure, save_criterion_files
from pathlib import Path

avg_us, iters, times_ns = measure(fn, warmup_s=3.0, measure_s=5.0)
print(f"avg: {avg_us:.2f} µs  ({sum(int(n) for n in iters)} iterations)")

save_criterion_files(
    Path("target/criterion"),
    group_id="my_group",
    function_id="my_fn",
    value_str="param_name",
    iters=iters,
    times_ns=times_ns,
)
```

See also [Performance](performance.md) for benchmark result tables and [Project Structure](project-structure.md) for the source tree layout.