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	str(object='') -> str

Functions

autogenerate_normalizers(→ bool)	Registers 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, ...)	Same as normalize(), but returns None if a normalizer is not found.
register_normalizer(…)	Registers a custom normalizer for the object or type; returns success, with failure resulting from a normalizer having already been 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.

Can be taken by the + or - operators.

__floor__() → int

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

The same as __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

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

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: str, /) → str

Format specification and corresponding return value: (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.types.ValidSlice, /) → tuple[int, Ellipsis]

Depending on the value of idx, corresponds to the following properties:

• 0 -> major

• 1 -> minor

• 2 -> patch

Slicing works like 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.

Of course, 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

The same as __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]

An iterator yielding 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

The same as __floor__().

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

Implemented to 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

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

compatible(other: Self, /, majtol: int | None = ..., mintol: 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.

next_major() → Self

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

next_minor() → Self

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

next_patch() → Self

The patch version following this version.

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

Another instance of this class with the specified parts.

shelve(path: asyncutils._internal.types.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.types.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.

property is_api_unstable: bool

Return whether the version is before v1.0.

property major: int

The major part of the version.

property minor: int

The minor part of the 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, in the form asyncutils --version displays.

asyncutils.version.autogenerate_normalizers() → bool

Registers 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 unnormalizable objects, in which case the comparison operators against instances of VersionInfo

will delegate to that object.

If there is fault in the normalizer (it raises an exception or returns a non-iterable), the normalizer is removed and the error 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

Same as 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

Registers a custom normalizer for the object or type; returns success, with failure resulting from a normalizer having already been 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.