linkahead.common.versioning module

Versioning module for anything related to entity versions.

Currently this module defines nothing but a single class, Version.

Bases: object

The version of an entity.

An entity version has a version id (string), a date (UTC timestamp), a list of predecessors and a list of successors.

Parameters:

id (str, optional) – See attribute id. Default: None
date (str, optional) – See attribute date. Default: None
username (str, optional) – See attribute username. Default: None
realm (str, optional) – See attribute realm. Default: None
predecessors (list of Version, optional) – See attribute predecessors. Default: empty list.
successors (list of Version, optional) – See attribute successors. Default: empty list.
is_head (bool) – See attribute is_head. Default: False
is_complete_history (bool) – See attribute is_complete_history. Default: False

id

Version ID (not the entity’s id).

Type:: str

date

UTC Timestamp of the version, i.e. the date and time when the entity of this version has been inserted or modified.

Type:: str

username

The username of the user who inserted or updated this version.

Type:: str

realm

The realm of the user who inserted or updated this version.

Type:: str

predecessors

Predecessors are the older entity versions which have been modified into this version. Usually, there is only one predecessor. However, this API allows for entities to be merged into one entity, which would result in more than one predecessor.

Type:: list of Version

successors

Successors are newer versions of this entity. If there are successors, this version is not the latest version of this entity. Usually, there is only one successor. However, this API allows that a single entity may co-exist in several versions (e.g. several proposals for the next entity status). That would result in more than one successor.

Type:: list of Version

is_head

If true, this indicates that this version is the HEAD if true. Otherwise it is not known whether this is the head or not. Any string matching “true” (case-insensitively) is regarded as True. Nota bene: This property should typically be set if the server response indicated that this is the head version.

Type:: bool or string

is_complete_history

If true, this indicates that this version contains the full version history. That means, that the predecessors and successors have their respective predecessors and successors attached as well and the tree is completely available. Any string matching “true” (case-insensitively) is regarded as True. Nota bene: This property should typically be set if the server response indicated that the full version history is included in its response.

Type:: bool or string

static from_xml(xml: _Element) → Version

Parse a version object from a ‘Version’ xml element.

Parameters:: xml (etree.Element) – A ‘Version’ xml element, with ‘id’, possibly ‘date’, username, realm, and head attributes as well as ‘Predecessor’ and ‘Successor’ child elements.
Returns:: version – a new version instance
Return type:: Version

get_history() → List[Version]

Returns a flat list of Version instances representing the history of the entity.

The list items are ordered by the relation between the versions, starting with the oldest version.

The items in the list have no predecessors or successors attached.

Note: This method only returns reliable results if self.is_complete_history is True and it will not retrieve the full version history if it is not present.

Return type:: list of Version

to_xml(tag: str = 'Version') → _Element

Serialize this version to xml.

The tag name is ‘Version’ per default. But since this method is called recursively for the predecessors and successors as well, the tag name can be configured.

The resulting xml element contains attributes ‘id’ and ‘date’ and ‘Predecessor’ and ‘Successor’ child elements.

Parameters:: tag (str, optional) – The name of the returned xml element. Defaults to ‘Version’.
Returns:: xml
Return type:: etree.Element