Skip to content

feat!: x690 2.0.0 - #20

Merged
exhuma merged 36 commits into
mainfrom
feat/version-2
Oct 27, 2026
Merged

exhuma merged 36 commits into
mainfrom
feat/version-2

Conversation

@exhuma

@exhuma exhuma commented Oct 26, 2026 •

Copy link
Copy Markdown
Owner

Everything for the 2.0.0 release (milestone 2.0.0). Current main is already breaking against the last published version, 1.0.0.post1, because of the never-released 1.1.0 changes, so this bundles the remaining breaking changes into one major release. docs/changelog.rst has the full 2.0.0 notes.

Breaking changes

  • Context-specific tags per enclosing type (Resolve context-specific tags relative to their enclosing type #6). Context-class types are no longer registered globally. A constructed type lists its children in CHILD_TYPES; decode(..., types=[...]) covers the top level; Explicit[Inner] describes explicitly tagged values. Application and private types stay global but can be overridden per structure, or kept local with register=False. A subclass is registered only if it sets its own TYPECLASS, TAG or NATURE.
  • Python values for more universal types (Convert more universal types to Python values #7). Text types → str, UtcTime/GeneralizedTime → datetime, Enumerated → int, RelativeOid → str, Real → float (all X.690 forms decoded, base-2 encoded, bit-exact), BitString → new Bits value type, Set → list of values like Sequence. Six rarely used types stay raw bytes, with the reason documented.
  • raw_bytes and detach() (Release the input buffer once a value has been read #14). raw_bytes of a decoded value is its own bytes; the shared buffer and bounds are private; detach() copies a value's bytes so a kept value no longer holds the whole input. Decoding stays no-copy.
  • repr() of Sequence subclasses (repr() of Sequence subclasses shows Sequence #19) shows the subclass name.
  • Equality: values compare equal only within the same class; all types except ObjectIdentifier are unhashable.

Documentation review (library kit)

Reviewed against the Quartermaster library guidance and fixed:

  • API reference: no private bases or internal sentinel in signatures (the sentinel is now the public Uninitialised), intersphinx for the standard library, section labels and type hints in the build, methods of private bases shown under the public classes, and CI builds with sphinx-build -n -W so dead references fail (64 were hidden before).
  • Every public class and function has a docstring with parameters, return values and errors.
  • A compatibility section states the SemVer, breaking-change and deprecation policy; guides are titled by task; glossary terms are linked; all example lines fit the code column.
  • cspell runs in pre-commit, including the changelog; typos fixed.
  • Two fixes found on the way: a truncated ObjectIdentifier raises ValueError instead of StopIteration, and the raw-bytes string types are annotated as bytes.

Logging (library kit)

Reconciled with the logging guidance for libraries:

  • x690 logs only at DEBUG, on the x690.types logger, and never configures logging. The records cover decisions that were invisible before: unknown types (including context tags missing from CHILD_TYPES), child types overriding registered types, lenient decoding (bit-string padding, characters outside the PrintableString/NumericString alphabet), saturated Real values and dropped or truncated time fractions. Values go into namespaced attributes (x690.*); decoded content is never logged.
  • No spans: x690 is pure computation.
  • New Observability page lists the logger, every message and its attributes; logger names and messages are part of the public interface.
  • Ruff now checks logging use (G, LOG, TRY400, T20); .quartermaster.toml pins the structured logging kit to v2.
  • Benchmark: no measurable cost with logging disabled (interleaved runs, full document of 1,000,000 records: before 24.0 / 24.2 s, after 23.8 / 23.7 s).

Fixes

Release prep

Version 2.0.0; the unpublished 1.1.0 notes and the unreleased entries are merged into one 2.0.0 section; status wording updated.

Review and verification

  • One commit per item, each green on its own, followed by an integration review across all of them, whose findings are fixed in the last commits (one equality rule, one error type for malformed content, shared text and integer bases, registry isolation for every test, behavioural tests only).
  • pytest: 796 passed, coverage 99.8 %. mypy --strict, pre-commit (incl. cspell), sphinx-build -n -W: clean.
  • Benchmark (x690, 1,000,000 records, small machine): full 22.5 s / 8 MB, partial 1.7 s / 8 MB, indexed 23.4 s / 8 MB, stream 21.7 s. That is within a few percent of the reports in benchmarks/results/.

Points to review

  • Registration rule: a subclass that only overrides methods (for example class MyReal(Real): def decode_raw…) no longer replaces the registered type; it must set TAG again. Without this, a structure class that only declares CHILD_TYPES would replace Sequence everywhere.
  • Types are declared by tag, not position. Two children with the same tag in one structure (for example the two leading sequences of an X.509 certificate) get the same class. Positional declarations belong with Named access to sequence components #9.
  • Not handled: the constructed (segmented) form of string, time and BitString values. UtcTime encoding drops microseconds.

After merging

Tag v2.0.0 on the merge commit and push the tag; CI checks it against the version and publishes to PyPI.

Closes #6
Closes #7
Closes #12
Closes #13
Closes #14
Closes #19

🤖 Generated with Claude Code

exhuma and others added 15 commits October 26, 2026 16:54
decode(..., strict=True) compared the next index with len(data) - 1, so
exactly one trailing byte was accepted.

Closes #12

Co-Authored-By: Claude <noreply@anthropic.com>
GraphicString decoded its bytes to str but had no matching encode_raw,
so bytes(GraphicString("abc")) raised TypeError.

Closes #13

Co-Authored-By: Claude <noreply@anthropic.com>
Sequence.__repr__ hard-coded "Sequence", so a subclass such as an SNMP
GetRequest printed as Sequence([...]).

BREAKING CHANGE: repr() of Sequence subclasses now starts with the
subclass name.

Closes #19

Co-Authored-By: Claude <noreply@anthropic.com>
A decoded value's raw_bytes returned the whole input buffer, and the
public bounds attribute located the value inside it. A value kept from
a large document therefore kept the whole document alive.

raw_bytes is now the value's own content bytes. The shared buffer and
its bounds are private. detach() copies a value's own bytes and drops
the reference to the input, so applications can keep a few values from
a large document without keeping the document. Decoding stays no-copy.

BREAKING CHANGE: raw_bytes of a decoded value is its own content bytes
instead of the whole input buffer, and the bounds attribute is gone.

Closes #14

Co-Authored-By: Claude <noreply@anthropic.com>
A constructed type now lists the types of its children in the class
attribute CHILD_TYPES. While decoding, the tag of each item is looked up
there first and then in the global registry, so the same context tag can
mean a different type in every structure. Each value uses the
declarations of its own class, and decode() takes the same list as
types= for a value at the top level. The new Explicit base class models
explicitly tagged values such as X.509 "version [0] EXPLICIT Version".

Universal, application and private types stay globally registered. A
subclass is registered only when its class body sets TYPECLASS, TAG or
NATURE, so a structure class such as "class Message(Sequence)" no longer
replaces Sequence, and register=False keeps a type local to the
structures that list it.

BREAKING CHANGE: context-specific types are no longer registered
globally. List them in CHILD_TYPES of the enclosing type, or pass them
to decode() as types=, instead of relying on the class definition alone.
A subclass that should replace a registered type must set its TAG again.

Closes #6

Co-Authored-By: Claude <noreply@anthropic.com>
Utf8String, NumericString, PrintableString, IA5String, VisibleString,
ObjectDescriptor, BmpString and UniversalString now hold a str.
UtcTime and GeneralizedTime hold a datetime, and Enumerated holds an
int. RelativeOid holds a dotted str.

UtcTime reads two-digit years 50-99 as 19xx and 00-49 as 20xx, and
encodes only timezone-aware datetimes in 1950-2049, as UTC. A
GeneralizedTime without a zone is a naive datetime and encodes without
a zone. NumericString and PrintableString decode any ASCII but check
their alphabet on encode. Only the primitive encoding is supported.

BREAKING CHANGE: the value of Utf8String, NumericString,
PrintableString, IA5String, VisibleString, ObjectDescriptor, BmpString,
UniversalString, UtcTime, GeneralizedTime, Enumerated and RelativeOid is
now a str, datetime or int instead of bytes.

Refs #7

Co-Authored-By: Claude <noreply@anthropic.com>
Real decodes every form of X.690 section 8.5: zero, the special values,
binary in base 2, 8 or 16 with a scaling factor and any exponent length,
and decimal in the ISO 6093 forms NR1, NR2 and NR3. It encodes in base 2
with an odd mantissa and the shortest exponent, so every finite float
survives a round trip bit for bit.

BitString holds the new Bits value type, which keeps the octets and the
number of unused bits. It offers len() in bits, indexing and iteration as
bool in ASN.1 bit order, is_set() for named bit lists, from_bin() and
str() for strings of "0" and "1", and bytes() for keys and signatures.

Set shares the lazy item access of Sequence through a common private
base class, but is not a Sequence.

BREAKING CHANGE: the value of Real is a float, the value of BitString is
a Bits instead of bytes, and Set holds a list of x690 values instead of
bytes.

Closes #7

Co-Authored-By: Claude <noreply@anthropic.com>
Set the version to 2.0.0 and turn the never-published 1.1.0 notes and
the unreleased entries into one 2.0.0 section that starts with the
breaking changes.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Equality is defined once in X690Type (exactly the same class and the
same value) and once in _Structure and Explicit (the same class and the
same content bytes). The per-type copies are gone. Real keeps its
NaN and -0.0 handling, UnknownType also compares its tag, and
ObjectIdentifier keeps its hash.

BREAKING CHANGE: values compare equal only when they are of the same
class and hold the same value. The types converted to Python values now
compare by value and, like Integer and OctetString, cannot be hashed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
@exhuma exhuma added this to the 2.0.0 milestone Oct 26, 2026
@exhuma exhuma self-assigned this Oct 26, 2026
exhuma and others added 13 commits October 26, 2026 19:09
Group the notes by what users need to change, what is new, what is
faster, fixes and documentation, and drop implementation details such
as __slots__, registry internals, packaging metadata and CI.

Co-Authored-By: Claude <noreply@anthropic.com>
Value-based hashing was never available apart from ObjectIdentifier, so
there is no change to announce.

Co-Authored-By: Claude <noreply@anthropic.com>
Rename the private sentinel type to the public, documented
Uninitialised with a readable repr, drop private bases from the
"Bases:" lines and document the TWrappedPyType TypeVar.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Give the twelve public classes that lacked a docstring one (Boolean, Null,
OctetString, Integer, External, EmbeddedPdv, VideotexString, GeneralString,
CharacterString, EOC, TypeClass, TypeNature), naming the tag, the Python
value type and, for the raw-bytes types, why they hold raw bytes.

Add :param:, :returns: and :raises: fields to every public callable with
parameters in x690.types, x690.util and x690.exc, including the decode_raw
overrides, the private-base helpers and the constructors that take
arguments. Add docstrings to the LengthInfo and ValueMetaData fields, correct
the description of X690Type.decode, and add doctested examples for get,
validate, decode, decode_large_value, encode_large_value, parentof and
childof. No behaviour or signature changes.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
VideotexString, GeneralString and CharacterString hold the raw content
octets, so they are X690Type[bytes], like External and EmbeddedPdv.

Co-Authored-By: Claude <noreply@anthropic.com>
exhuma and others added 8 commits October 27, 2026 08:20
A truncated last arc leaked StopIteration from ObjectIdentifier.decode_raw.
Raise ValueError, as RelativeOid already does.

Co-Authored-By: Claude <noreply@anthropic.com>
Correct the spelling in older release entries so the changelog passes
the spell check, which now covers it too, and add the 2.0.0 entries for
the truncated object identifier, the raw-bytes type hints and the
documentation policy.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Enable the G, LOG, TRY400 and T20 rules. The benchmark scripts print
their reports by design, so T201 is allowed there.

Co-Authored-By: Claude <noreply@anthropic.com>
Log unknown types, child types that override a registered type,
lenient decoding of bit strings and text strings, saturated REAL
values and dropped time fractions on the x690.types logger. The
records sit in rare branches, so decoding a common document pays
for one extra dict lookup per child of a type with CHILD_TYPES at
most. No decoded content is logged.

Co-Authored-By: Claude <noreply@anthropic.com>
Describe the x690.types logger, each DEBUG record with its attributes,
how to enable them and that they are part of the public interface.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
@exhuma
exhuma merged commit 2083ec2 into main Oct 27, 2026
22 checks passed
@exhuma
exhuma deleted the feat/version-2 branch October 27, 2026 13:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant