Install & Compatibility
Where this runs
tested against v1.0.0.post1 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.135s · 18.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.124s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
decode
✓ from x690 import decode
The primary function for decoding BER bytes.
types
✓ import x690.types as t
Provides access to standard X.690 types like Integer, Sequence, OctetString.
exc
✓ from x690 import exc
Contains custom exceptions like IncompleteDecoding and UnexpectedType.
Type
✓ from x690.types import Type
Base class for defining custom X.690 types. When subclassing, ensure the new type is imported for registration.
This quickstart demonstrates how to encode basic X.690 types like Integer and Sequence into bytes, and how to decode BER-encoded bytes back into Python objects using the `decode` function. It also shows how to use `pretty()` for human-readable output and how to leverage `expected_type` for type validation during decoding.
import x690.types as t
from x690 import decode
# 1. Encoding a value
my_integer = t.Integer(123)
encoded_bytes = bytes(my_integer)
print(f"Encoded Integer: {encoded_bytes.hex()}")
# 2. Encoding a composite value (Sequence)
my_sequence = t.Sequence([t.Integer(1), t.OctetString(b'hello')])
encoded_sequence_bytes = bytes(my_sequence)
print(f"Encoded Sequence: {encoded_sequence_bytes.hex()}")
# 3. Decoding bytes
decoded_value, next_offset = decode(encoded_bytes)
print(f"Decoded value: {decoded_value.pyvalue} (Type: {type(decoded_value).__name__})")
# 4. Decoding a sequence (multiple values)
data_to_decode = b'0\x06\x02\x01\x01\x04\x01a'
decoded_obj_1, offset_1 = decode(data_to_decode)
decoded_obj_2, offset_2 = decode(data_to_decode, offset_1)
print(f"Decoded obj 1: {decoded_obj_1.pretty()}")
print(f"Decoded obj 2: {decoded_obj_2.pretty()}")
# 5. Decoding with an expected type (optional but good for type checking)
# This helps ensure the decoded type matches expectations and aids type checkers.
from x690.exc import UnexpectedType
try:
expected_int_value, _ = decode(encoded_bytes, expected_type=t.Integer)
print(f"Decoded with expected type: {expected_int_value.pyvalue}")
# This would raise UnexpectedType if encoded_bytes was not an Integer
# decode(encoded_bytes, expected_type=t.OctetString)
except UnexpectedType as e:
print(f"Error decoding with unexpected type: {e}")
Debug
Known issues
gotchaWhen decoding, the `decode` function returns a tuple: `(decoded_object, next_offset)`. It does not automatically consume all bytes if there are multiple BER-encoded objects concatenated. You must loop and pass `next_offset` to decode subsequent objects.fixAlways check the `next_offset` value and pass it for subsequent `decode` calls. If you expect only one object, use `strict=True` to catch remaining bytes as an error.
affects: All versions
breakingThe library's last update was in September 2022. While functional for X.690 BER, it may not actively incorporate new Python language features or security patches. Users should be aware of this if integrating into highly active or security-sensitive projects.fixReview the GitHub repository for any unreleased fixes or forks if critical updates are needed. Consider vendor-specific or more actively maintained ASN.1 libraries if advanced features or aggressive maintenance is required.
affects: 1.0.0.post1 and earlier
gotchaTo support custom X.690 types not defined in the standard, you must subclass `x690.types.Type` and define `TYPECLASS`, `NATURE`, and `TAG`. Crucially, this custom type *must be imported* somewhere in your application code for the library to automatically register it for decoding. If not imported, it will be treated as an `UnknownType`.fixEnsure that the module containing your custom `x690.types.Type` subclass is imported at runtime before any decoding operations that might encounter that type.
affects: All versions
Errors
Common errors & fixes
x690.exc.IncompleteDecoding: Strict decoding still had X remaining bytes!
This error occurs when `x690.decode` is called with `strict=True`, but the input `bytes` object contains more BER-encoded data after the first object has been successfully decoded. It indicates that the entire byte stream was not consumed by a single decoding operation.
fixIf you expect multiple objects, remove `strict=True` and loop through the data, passing the `next_offset` returned by `decode` to subsequent calls. If you genuinely expect only one object and this is an error, check your input data for unexpected trailing bytes.
x690.exc.UnexpectedType: Expected type 'Integer' but got 'OctetString'
This error is raised when `x690.decode` is called with the `expected_type` argument, and the actual BER-encoded object's type identifier (tag) does not match the provided `expected_type`.
fixVerify that the `expected_type` passed to `decode` accurately reflects the type of the BER object you are trying to parse. If the type is unknown or can vary, omit `expected_type` and check the type of the returned object dynamically.
AttributeError: 'UnknownType' object has no attribute 'my_custom_field'
This typically happens when you define a custom X.690 type (by subclassing `x690.types.Type`) but fail to import the module where it's defined before attempting to decode data containing that type. The library defaults to `UnknownType` if it can't find a registered class for the tag.
fixEnsure that the Python module where your custom `x690.types.Type` subclass is defined is imported somewhere in your application's startup code. This allows the class to be registered with the `x690` library.
Upgrade
Version history
1.0.0.post1latest on PyPI · released Sep 30, 2022
Audit
Dependencies
No dependency data recorded yet.