chariots.versioning¶

The versioning module provides all the types the Chariot’s versioning logic is built around. If you want to know more about the way semantic versioning is handled in Chariots, you can go check out the guiding principles.

This module is built around the VersionableMeta metaclass. This is a very simple metaclas that adds the __version__ class attribute whenever a new versionable class is created:

>>> class MyVersionedClass(metaclass=VersionableMeta):
...     pass
>>> MyVersionedClass.__version__
<Version, major:da39a, minor: da39a, patch: da39a>

to control the version of your class, you can use VersionedField descriptors:

..doctest:

>>> class MyVersionedClass(metaclass=VersionableMeta):
...     foo = VersionedField(3, VersionType.MINOR)
>>> MyVersionedClass.__version__
<Version, major:94e72, minor: 36d3c, patch: 94e72>
>>> MyVersionedClass.foo
3

and if in a future version of your code, the class attribute changes, the subsequent version will be changed:

..doctest:

>>> class MyVersionedClass(metaclass=VersionableMeta):
...     foo = VersionedField(5, VersionType.MINOR)
>>> MyVersionedClass.__version__
<Version, major:94e72, minor: 72101, patch: 94e72>
>>> MyVersionedClass.foo
5

but this version change only happen when the class is created and not when you change the value of this class attribute during the lifetime of your class:

>>> MyVersionedClass.foo = 7
>>> MyVersionedClass.__version__
<Version, major:94e72, minor: 72101, patch: 94e72>
>>> MyVersionedClass.foo
7

This module also provides a helper for creating versioned dict (where each value of the dict acts as a VersionedField) with the VersionedFieldDict descriptors:

>>> class MyVersionedClass(metaclass=VersionableMeta):
...     versioned_dict = VersionedFieldDict(VersionType.PATCH,{
...         'foo': 1,
...         'bar': 2,
...         'blu': VersionedField(3, VersionType.MAJOR)
...     })
>>> MyVersionedClass.__version__
<Version, major:ddf7a, minor: 1b365, patch: 68722>
>>> MyVersionedClass.versioned_dict['foo']
1
>>> class MyVersionedClass(metaclass=VersionableMeta):
...     versioned_dict = VersionedFieldDict(VersionType.PATCH,{
...         'foo': 10,
...         'bar': 2,
...         'blu': VersionedField(3, VersionType.MAJOR)
...     })
>>> MyVersionedClass.__version__
<Version, major:ddf7a, minor: 1b365, patch: 18615>
>>> MyVersionedClass.versioned_dict['foo']
10
>>> class MyVersionedClass(metaclass=VersionableMeta):
...     versioned_dict = VersionedFieldDict(VersionType.PATCH,{
...         'foo': 1,
...         'bar': 2,
...         'blu': VersionedField(10, VersionType.MAJOR)
...     })
>>> MyVersionedClass.__version__
<Version, major:d5abf, minor: 1b365, patch: 68722>
>>> MyVersionedClass.versioned_dict['blu']
10

this is for instance used for the model_parameters attribute of the sci-kit learn ops

class chariots.versioning.Version(major: Union[_hashlib.HASH, str, None] = None, minor: Union[_hashlib.HASH, str, None] = None, patch: Union[_hashlib.HASH, str, None] = None, creation_time: Optional[float] = None)[source]¶

Bases: object

Type of all the different versions used throughout the Chariots framework.

A Chariots version has three subversions (major, minor, patch) each subversion is the hexadecimal representation of the VersionedFields of this version.

two versions are considered equal if all their subversions are the same. A version is considered greater than the other of the other if one or more of it’s subversions is different and it has been created later.

you can use the + operation between two version to create a new version. this new version will NOT be the same as creating the new version from the same VersionedFields as the two versions: version(foo) + version(bar) != version(foo, bar)

__init__(major: Union[_hashlib.HASH, str, None] = None, minor: Union[_hashlib.HASH, str, None] = None, patch: Union[_hashlib.HASH, str, None] = None, creation_time: Optional[float] = None)[source]¶

ONLY PROVIDE ARGUMENTS IF YOU ARE PARSING A VALID VERSION

Parameters

major – the starting hash of the major version
minor – the starting hash of the minor version
patch – the starting hash of the patch version
creation_time – the starting creation time of the version

property creation_time¶: the time stamp of the creation time of the version

property major¶: the hash of the major subversion

property minor¶: the hash of the minor subversion

classmethod parse(version_string: str) → chariots.versioning._version.Version[source]¶

parses a string representation of a saved version and returns a valid Version object

Parameters: version_string – the version string to parse (this must come from str(my_version) and not repr(my_version)
Returns: the version represented by the version string

property patch¶: the hash of the patch subversion

update(version_type: chariots.versioning._version_type.VersionType, input_bytes: bytes) → chariots.versioning._version.Version[source]¶

updates the corresponding subversion of this version with some bytes

Parameters

version_type – the subversion to update
input_bytes – the bytes to update the subversion with

Returns

the updated version

update_major(input_bytes: bytes) → chariots.versioning._version.Version[source]¶

updates the major subversion with some bytes

Parameters: input_bytes – bytes to update the major subversion with
Returns: the updated version

update_minor(input_bytes: bytes) → chariots.versioning._version.Version[source]¶

updates the minor subversion with some bytes

Parameters: input_bytes – bytes to update the minor subversion with
Returns: the updated version

update_patch(input_bytes: bytes) → chariots.versioning._version.Version[source]¶

updates the patch subversion with some bytes

Parameters: input_bytes – bytes to update the patch subversion with
Returns: the updated version

class chariots.versioning.VersionType[source]¶

Bases: enum.Enum

am enum to give the three subversion types used in the chariots framework

MAJOR = 'major'¶

MINOR = 'minor'¶

PATCH = 'patch'¶

class chariots.versioning.VersionedField(value: Any, affected_version: chariots.versioning._version_type.VersionType)[source]¶

Bases: object

a descriptor to mark that a certain class attribute has to be incorporated in a subversion a versioned field is used as a normal class attribute (when gotten it returns the inner value) but is used to generate the version of the class it is used on when said class is created (at import time)

>>> class MyVersionedClass(metaclass=VersionableMeta):
...     foo = VersionedField(3, VersionType.MINOR)
>>> MyVersionedClass.foo
3

Parameters

value – the inner value to be given the field whcih will be returned when you try to get the class attribute
affected_version – the subversion this class attribute has to affect

__init__(value: Any, affected_version: chariots.versioning._version_type.VersionType)[source]¶: Initialize self. See help(type(self)) for accurate signature.

class chariots.versioning.VersionedFieldDict(default_version=<VersionType.MAJOR: 'major'>, *args, **kwargs)[source]¶

Bases: collections.abc.MutableMapping

a versioned field dict acts as a normal dictionary but the values as interpreted as versioned fields when it is a VersionedClass class attribute

__init__(default_version=<VersionType.MAJOR: 'major'>, *args, **kwargs)[source]¶: Initialize self. See help(type(self)) for accurate signature.

property version_dict¶: property to retrieve the name of the fields and the Versions associated to each of them :return: the mapping with the key and the version of the value

class chariots.versioning.VersionableMeta(clsname, superclasses, attributedict)[source]¶

Bases: type

metaclass for all versioned objects in the library. When a new class using this metaclas is created, it will have a __version__ class attribute that sets all the subversions of the class depending on the VersionedFields the class was created with

__init__(clsname, superclasses, attributedict)[source]¶: Initialize self. See help(type(self)) for accurate signature.