linkahead.common.versioning module

Versioning module for anything related to entity versions.

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

class linkahead.common.versioning.Version(id=None, date=None, username=None, realm=None, predecessors=None, successors=None, is_head=False, is_complete_history=False)

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)

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()

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='Version')

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