Changelog¶
Release 2.0.0¶
2.0.0 is the first release since 1.0.0post1. It includes the changes prepared as 1.1.0, which was never published.
Changes that need updates to your code
Context-specific types such as SNMP PDUs are now declared on the type that contains them, in
CHILD_TYPES, instead of being registered globally when the class is defined. The same tag can now mean a different type in every structure, as in X.509 and LDAP. See Add custom types (#6).A subclass that only changes how a type converts its value must set its
TAGagain to replace the built-in type.Most string types now give a
str,UtcTimeandGeneralizedTimeadatetime,Enumeratedanint,Realafloat,BitStringaBitsvalue andSeta list of values, instead of bytes. See Supported types (#7).raw_bytesof a decoded value is now only that value’s bytes, and theboundsattribute is gone (#14).Values are equal only when they have the same class and value, so a subclass no longer equals its base class.
repr()of aSequencesubclass shows the subclass name (#19).T61Stringfollows ITU-T T.61 strictly: accented letters decode to single characters (b"Caf\xc2e"gives"Café"),0xE0is Ω U+03A9, and invalid data raises an error. Data written by OpenSSL is often Latin-1; decode such values withlatin-1yourself (#3).Importing x690 no longer makes the
t61codec available to Python’scodecsmodule.Requires Python 3.11 or newer.
New
Explicitdescribes explicitly tagged values.detach()lets you keep a value from a large document without keeping the whole document in memory.decode()takes the types of a context-tagged value astypes=.Decoding decisions (unknown types, overrides, lenient decoding and saturated values) are logged at DEBUG on the
x690.typeslogger. See Observability.
Faster and smaller
Large documents decode with a fraction of the memory, and reading items by index no longer slows down as documents grow (#16, #17). Choosing x690 compares the results with other ASN.1 libraries.
Fixes
decode(..., strict=True)raises on a single trailing byte (#12).GraphicStringvalues can be encoded (#13).repr()of an unknown type no longer changes between Python versions.A truncated
ObjectIdentifierraisesValueErrorinstead ofStopIteration.The type hints of
VideotexString,GeneralStringandCharacterStringsaybytes, which is what they hold.
Documentation
New documentation at https://exhuma.github.io/x690/, with guides, a list of supported types and a comparison with other ASN.1 libraries.
The start page states the compatibility and deprecation policy, and the API reference documents every public class and function.
Release 1.0.0post1 - Maintenance release¶
This fixes the incorrectly provided extra
restin the dependency metadata. This extra has become obsolete and removing it fixed versioning errors when installingx690.
1.0.0¶
Renamed
x690.types.Typetox690.types.X690TypeFlagged as “stable”
Dropped support for Python 3.6
0.5.0¶
Flagged as “production” release
All changes from 0.5.0-alpha.0 - 0.5.0-alpha.6
0.5.0-alpha.6¶
Relaxed dev-dependencies a bit which caused issues in some installations
0.5.0-alpha.5¶
Allow ObjectIdentifier instances to be created for “relative” sub-trees by delaying the byte-conversion.
When converting ObjectIdentifiers to bytes, the first two objects are “folded” together. This is not possible for some values. Delaying this folding until the “is-needed” moment allows the use for such OIDs to be used for subtree modifications/concatenation. They will still raise errors if they are converted to bytes unmodified.
Internal typing improvement
0.5.0-alpha.4¶
Raise an exception when trying to decode data that is out-of-bounds of the processed blob.
Accessing a scalar index (not a slice) from an OID returns the integer value.
0.5.0-alpha.3¶
Housekeeping & typing improvements
0.5.0-alpha.2¶
Don’t consider “None/NULL” values as “uninitialised”. This prevents unnecessary/repetitive byte-conversions.
0.5.0-alpha.1¶
ObjectIdentifiers now “feel” more like strings. The constructor changed to reflect this:
ObjectIdentifier("1.2.3")Improve error message when creating custom types without no-arg constructor
Fix “unsigned int” values
Fix handling of empty
Sequenceinstances
0.5.0-alpha.0¶
This release focussed on performance (both memory and CPU) in order to decode large x690 documents.
As it goes with performance, a fair amount of refactoring was needed and the external API could not be guaranteed easily. And as we’re still on the 0.x branch, the backwards-compatibility was dropped in favor of cleaner code.
It is flagged as “alpha” until I feel confident that the new changes have not introduced breaking bugs.
Replaced
x690.pop_tlvhas been replaced byx690.decode. This no longer copies data in-memory and therefore no longer returns the “remaining” data-bytes. Instead it returns the position of the next data-block.decodealso takes an additional argument to define where to start decoding data from.changed
ObjectIdentifierhas been aligned to the existing types and no longer use*argsto initialise instances. Instead ofObjectIdentifier(1, 2, 3)you must now writeSequence((1, 2, 3))changed
Sequencehas been aligned to the existing types and no longer use*argsto initialise instances. Instead ofSequence(a, b, c)you must now writeSequence([a, b, c])changed
UnknownTypehas been aligned to the existing types. It now takes the value as first argument instead of second. Instead ofUnknownType(99, b"abc")you must now writeUnknownType(b"abc", 99).changed Subclasses of
x690.Typemust now override theType.decode_rawmethod if the data is needed in another type thatbytes.changed Subclasses of
x690.Typemust now override theType.encode_rawmethod if the python-value is a non-bytes object.dataclasses in have been replaced with named-tuples for increased performance.
An instance can now be created from raw-bytes (excluding the type and length header bytes) by calling
Type.from_bytes(...)(by using the class of the appropriate type!).New function
x690.util.get_value_slicecan be used to find the location of the raw-bytes of a value at any given location. The location must however be the start of an x690 “TLV” block. This will return the slice of the value location (The “V” part excluding the “TL” part) and the location of the next value-block.
0.4.0¶
Removed Decoding no longer raises a “ValueError” if a value contains junk-bytes after decoding. Use either “strict” mode or inspect the “remainder” after decoding yourself. This was a necessity to remove a duplication with length-decoding and was too impactful to re-introduce.
Removed Types no longer have a
from_bytesimplementation. This was the core of the code-duplication and is now gone in favor of thedecodefunction.Support for “indefinite length” values
Allow registering types with “non-constructed” nature
Improved prettification of unknown types
Support types which can be encoded as either “primitive” or “constructed”
Implement decoding of the GraphicString type
Removed duplication of length-decoding
0.3.0¶
The most visible changes in this release are the additional arguments on
pop_tlv. Using enforce_type adds valuable typing information for IDEs.
As long as they are known in advance of course. By default, the type will be
Any. Using strict=True can be helpful for fail-fast programming.
Finally, some internals have been modified for more maintainable code. They
should only have an impact if you extended x690 with new types.
Dropped Support for Python <3.6
Removed
x690.types.NonASN1TypeRemoved custom
to_bytesimplementation (use the builtinbytes()instead). For example:bytes(x690.types.Integer(10))Added
enforce_typetopop_tlvfor improved type-safety and -checkingAdded
stricttopop_tlvfor quick & easy sanity checksImproved prettification of byte-values and unknown types
Improved prettification of nested sequences
Improved type-hints
Added default values to all types
Changed
x690.util.LengthValueandx690.util.TypeInfoto dataclassesUse enums for internal “typeclass” and “primitive/constructed” values.
Stricter CI pipeline (including mypy and vulture)
Switch to
poetryfor packaging