asyncutils.version

A versioning scheme for asyncutils. Inspired by torch.torch_version, but with quite some differences.

asyncutils uses a subset of SemVer.

Classes

VersionDelta
VersionInfo	A class representing a version of asyncutils.

Functions

autogenerate_normalizers(→ bool)	Register normalizers for decimal.Decimal and fractions.Fraction. Return whether both normalizers were successfully registered, including re-registration of the same normalizer.
dispatch_normalizer(…)	Return the normalizer to be used for the object or type.
normalize(→ tuple[int, int, int])
normalize_allow_unimplemented(→ tuple[int, int, ...)	Like normalize(), but returns None if a normalizer is not found.
register_normalizer(…)	Register a custom normalizer for the object or type; return whether the normalizer was newly registered.
unregister_normalizer(…)	Unregister the normalizer for the object or type and return it if any.

Module Contents

class asyncutils.version.VersionDelta

Bases: NamedTuple

A named tuple-like class representing the difference between versions.

Not actually created by collections.namedtuple(), but implements its methods.

Accepted by the + or - operators.

__floor__() → int

Return the major part of the delta.

__neg__() → Self

Return the negative of the delta. Additions and subtractions taking the return value correspond to subtractions and additions taking the original delta respectively.

__replace__(*, major: int = ..., minor: int = ..., patch: int = ...) → Self

Alias for _replace().

__trunc__() → int

Identical to __floor__().

major: int = Ellipsis

The major part of the version.

minor: int = Ellipsis

The minor part of the version.

patch: int = Ellipsis

The patch part of the version.

class asyncutils.version.VersionInfo

Bases: str

A class representing a version of asyncutils.

Initialize self. See help(type(self)) for accurate signature.

__add__(n: int, /) → Self

__add__(delta: VersionDelta, /) → Self

Return this version incremented by n patches or the delta delta.

__ceil__() → int

Return the major version, adding one if there is a minor or patch version.

__eq__(other: object, /) → bool

Whether this version is the same as the other.

__float__() → float

Assumes minor and patch are less than 100.

__floor__() → int

Return the major version.

__format__(

format_spec: Literal['x', 'hex', 'o', 'oct', 'b', 'bin', 'd', 'dec', '0', 'major', 'maj', '1', 'minor', 'min', '2', 'patch', 's', 'short', 'l', 'long', 'a', 'ascii', 'c', 'chars', 't', 'tuple', 'h', 'hash', 'n', 'majmin'],

/,

) → str

Format the version. See the return values below, using version 123.4.0 as example.

• x, hex: '0x7b0400'

• o, oct: '0o36602000'

• b, bin: '0b11110110000010000000000'

• d, dec: '8061952'

• 0, major, maj: '123'

• 1, minor, min: '4'

• 2, patch: '0'

• s, short: '123.4'

• l, long: 'asyncutils version 123.4.0'

• a, ascii: '{\x04\x00'

• c, chars: '{\x04\x00'

• t, tuple: '(123, 4, 0)'

• h, hash: '116380397'

• n, majmin: '123.4'

__ge__(other: object, /) → bool

Whether this version succeeds or is equal to the other as a version.

__getitem__(idx: Literal[0, 1, 2], /) → int

__getitem__(idx: asyncutils._internal.prots.ValidSlice, /) → tuple[int, Ellipsis]

Return a property depending on the value of idx.

• 0: major

• 1: minor

• 2: patch

Slicing works as if the version object is a tuple of these three items, which is also accessible as parts.

__gt__(other: object, /) → bool

Whether this version succeeds the other as a version.

__hash__() → int

A perfect hash function for versions! May produce larger integers than __int__() in some cases, and may also produce negative integers.

Since hash() returns the output of __hash__() modulo 0x1FFFFFFFFFFFFFFF (largest Mersenne prime within 64 bits), the reasonable limit for versions that can be hashed and unhashed losslessly lies around VersionInfo(46340, 41707, 2147483645).

__index__() → int

Identical to __int__().

__int__() → int

Assuming minor and patch are less than 256, pack the parts into an integer, which can be larger than 24 bits to fit the major version. OverflowError is raised if not possible.

__iter__() → collections.abc.Iterator[int]

Yield major, minor, patch sequentially.

__le__(other: object, /) → bool

Whether this version precedes or is equal to the other as a version.

__len__() → Literal[3]

len((major, minor, patch)) == 3.

__lt__(other: object, /) → bool

Whether this version precedes the other as a version.

__ne__(other: object, /) → bool

Whether this version is different than the other.

__radd__(n: int, /) → Self

__radd__(delta: VersionDelta, /) → Self

Return this version incremented by n patches or the delta delta.

__reduce__() → tuple[type[Self], tuple[int, int, int]]

Support for pickling.

__replace__(major: int = ..., minor: int = ..., patch: int = ...) → Self

__round__(ndigits: int, /) → NoReturn

__round__(ndigits: Literal[1, 2, 3] | None = ..., /) → Self

Support for rounding.

__setattr__(name: str, value: object, /) → NoReturn

Disallow modifying attributes of the object.

__sub__(n: int, /) → Self

__sub__(delta: VersionDelta, /) → Self

__sub__(other: Self, /) → VersionDelta

Return this version decremented by n patches or the delta delta, or the delta between self and other.

__trunc__() → int

Identical to __floor__().

_replace(major: int = ..., minor: int = ..., patch: int = ...) → Self

Satisfy the named tuple interface.

assert_valid() → None

Signify an error if the user messed something up in this object, likely intentionally.

change_sep(sep: str) → str

Return this version as a string with the specified separator instead of a dot between parts.

compatible(other: Self, /, maj_tol: int | None = ..., min_tol: int | None = ...) → bool

Whether this version is compatible with the other, given the major and minor tolerances.

classmethod from_hash(hashed: int) → Self

Reconstruct the version from its hash.

classmethod from_rep(rep: str) → Self

Parse the string representation of a version to get the version back.

classmethod get_current_version() → Self

Return the current version number of asyncutils; equivalent to asyncutils.__version__.

is_current_version() → bool

Whether this version is the same as the current version of asyncutils.

replace_parts(*, major: int = ..., minor: int = ..., patch: int = ...) → Self

Another instance of this class with the specified parts.

shelve(path: asyncutils._internal.prots.Openable, /, key: int = ...) → None

Store this version into the specified path, non-cryptographically transforming the bytes with key, which can be any integer.

to_complex() → complex

Loses the patch version. Since this class is a str subclass, an implementation of __complex__() will not be recognized.

classmethod unshelve(path: asyncutils._internal.prots.Openable, /, key: int = ...) → Self

Recover a stored version from path. A wrong key would usually raise an error, and even if it doesn’t, the version would be wrong.

DEFAULT_KEY: Final[int]

The default value of the shelving and unshelving key.

property major: int

The major part of the version.

property minor: int

The minor part of the version.

property next_major: Self

The major version following this version, with minor and patch 0.

property next_minor: Self

The minor version following this version, with a patch of 0.

property next_patch: Self

The patch version following this version.

property parts: tuple[int, int, int]

The tuple (major, minor, patch).

property patch: int

The patch part of the version.

property representation: str

String representation of the version for pretty printing, used by asyncutils -v.

asyncutils.version.autogenerate_normalizers() → bool

Register normalizers for decimal.Decimal and fractions.Fraction. Return whether both normalizers were successfully registered, including re-registration of the same normalizer.

asyncutils.version.dispatch_normalizer[T](o: type[T], /) → collections.abc.Callable[[T], collections.abc.Iterable[int]] | None

asyncutils.version.dispatch_normalizer(o: T, /) → collections.abc.Callable[[T], collections.abc.Iterable[int]] | None

Return the normalizer to be used for the object or type.

asyncutils.version.normalize(o: object, /) → tuple[int, int, int]

Return a tuple of three integers (major, minor, patch) from the information provided by the object as extracted by registered normalizers.

A normalizer can return None for an unnormalizable object, in which case the comparison operators against instances of VersionInfo will delegate to the object itself.

If the normalizer raises an exception or returns a non-iterable, it is removed and the error is propagated.

Note

Normalization logic is hardcoded for exact instances of str, complex, int, and float. This takes precedence over any registered normalizers, but those can still be accessed with dispatch_normalizer().

Note

For iterables, the default behaviour is to take the first three items and pad zeros behind if necessary.

asyncutils.version.normalize_allow_unimplemented(o: object, /) → tuple[int, int, int] | None

Like normalize(), but returns None if a normalizer is not found.

asyncutils.version.register_normalizer[T](o: type[T], f: collections.abc.Callable[[T], collections.abc.Iterable[int]], /) → bool

asyncutils.version.register_normalizer(o: T, f: collections.abc.Callable[[T], collections.abc.Iterable[int]], /) → bool

Register a custom normalizer for the object or type; return whether the normalizer was newly registered.

asyncutils.version.unregister_normalizer[T](o: type[T], /) → collections.abc.Callable[[T], collections.abc.Iterable[int]] | None

asyncutils.version.unregister_normalizer(o: T, /) → collections.abc.Callable[[T], collections.abc.Iterable[int]] | None

Unregister the normalizer for the object or type and return it if any.