timelink.kleio.groups package

Kleio Groups are the building blocks for transcription of historical sources.

The classes in this package can be used to generate Kleio sources from data fetched from databases or read from csv or json files.

The base classes are:

KKleio

A Kleio document. It should include a single KSource group.

KSource

A Historical Source. Can contain a variable number of KAct groups.

KAct

A historical act. Can contain a variable number of KPerson or KObject.

In normal usage the basic groups are extended for a particular context:

from timelink.kleio.groups import KKleio, KSource, KAct,
KAbstraction, KPerson, KLs, KAtr


kleio = KKleio

fonte = KSource.extend('fonte',
                        also=['tipo', 'data', 'ano', 'substitui',
                                'loc', 'ref', 'obs'])

lista = KAct.extend('lista',
                    position=['id', 'dia', 'mes', 'ano'],
                    guaranteed=['id', 'ano', 'mes', 'dia'],
                    also=['data', 'tipo', 'loc', 'obs'])

auc = KAbstraction.extend('auc', position=['name', ''], also=[
    'level', 'id'], guaranteed=['id'])

n = KPerson.extend('n', position=['nome', 'sexo'], guaranteed=[
    'id', 'nome', 'sexo'], also=['mesmo_que', 'obs'])

pai = KPerson.extend('pai', position=['nome'], guaranteed=[
    'id', 'nome'], also=['mesmo_que', 'obs'])

mae = KPerson.extend('mae', position=['nome'], guaranteed=[
    'id', 'nome'], also=['mesmo_que', 'obs'])

ls = KLs.extend('ls',
                position=['type', 'value', 'data'],
                also=['data', 'obs'])

atr = KAtr.extend(
    'atr', position=['type', 'value', 'data'], also=['data', 'obs'])

n.allow_as_part(pai)

n.allow_as_part(mae)

Submodules

timelink.kleio.groups.kabstraction module

class timelink.kleio.groups.kabstraction.KAbstraction(*args, **kwargs)

A synonym for object, used in non physical entities such as institutions.

Creates a new instance of group with setting the value of elements.

Parameters:

• *args – values for positional arguments

• **kwargs – values for optional elements.

Example

ks = KSource("s1", type="test", loc="auc", ref="alumni", obs="Nested")

Use element_check=False to turn off checking of element names

timelink.kleio.groups.kact module

class timelink.kleio.groups.kact.KAct(id, type, date[, day=, month=, year=, loc=, ref=, obs=])

An Act is a record of an event in a specific date.

Fields:

id: an unique id for this act. A string. type: type of the act (baptism, marriage, contract…). A string. date: the date of the act. A string in timelink format. day,month,year: the date expressed in individual values loc: location of the act in the archive (if different from source) ref: call number, or page number in source.

Kleio str definition:

part name=historical-act;

guaranteed=id,type,date; position=id,type,date; also=loc,ref,obs,day,month,year; arbitrary=person,object,geoentity,abstraction,ls,atr,rel

Creates a new instance of group with setting the value of elements.

Parameters:

• *args – values for positional arguments

• **kwargs – values for optional elements.

Example

ks = KSource("s1", type="test", loc="auc", ref="alumni", obs="Nested")

Use element_check=False to turn off checking of element names

timelink.kleio.groups.katr module

class timelink.kleio.groups.katr.KAtr(*args, **kwargs)

Synonym for KAttribute

Creates a new instance of group with setting the value of elements.

Parameters:

• *args – values for positional arguments

• **kwargs – values for optional elements.

Example

ks = KSource("s1", type="test", loc="auc", ref="alumni", obs="Nested")

Use element_check=False to turn off checking of element names

timelink.kleio.groups.kattribute module

class timelink.kleio.groups.kattribute.KAttribute(type, value[, date, obs=])

Time varying attribute of a person, object, or other

Attributes represent time-varying information about historical entities. Each attribute has a type (‘address’,’profession’, ‘age’), a value and a date associated with the attribute.

Elements:

type: the type of the attribute. A String value: the value of the attribute. A string. date: the date of attribute. A string in Timelink format, optional. obs: a note on the attribute. A string optional.

Kleio str definition :

part name=attribute ;

guaranteed=type,value ; also=obs,date ; position=type,value,date

Creates a new instance of group with setting the value of elements.

Parameters:

• *args – values for positional arguments

• **kwargs – values for optional elements.

Example

ks = KSource("s1", type="test", loc="auc", ref="alumni", obs="Nested")

Use element_check=False to turn off checking of element names

after_include(group)

Method called after a new group is included in this one through KGroup.include(KGroup).

before_include(container_group)

Method called before a new group is included in this one through KGroup.include(KGroup).

timelink.kleio.groups.kelement module

class timelink.kleio.groups.kelement.KClass(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for the class of a group

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KDate(date: Any | None = None, core=None, comment=None, original=None, element_class=None)

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KDay(day: Any | None = None, core=None, comment=None, original=None, element_class=None)

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KDescription(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Similar to name, for objects

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KDestId(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for destination id in relations

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KDestName(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for destination names in relations

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KElement(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Represents an Element in Kleio language.

While Groups represent historical entities (people, objects, events) Elements encapsulate basic items of information (name, gender, date).

The value of an Element can have three possible “aspects”:

1. “core”: the actual information for the element

2. “original” (optional), the original wording when relevant

3. “comment” (optional), a comment of the value.

Example in Kleio notation:

person$Joaquim Carvalho%Joachim Carvº#Family name added in the margin

Can be generated by

n = KElement('name','Joaquim Carvalho',original='Joachim Carvº',
        comment='Family name added in the margin')
id = KElement('id','p-jrc')
person = KPerson(id=id,name=n)

TODO: does not deal with multiple values in elements. Check KElement in MHK where core, comment and original are Vectors better to create a KAspect class.

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

classmethod all_subclasses()

List of all the subclasses of this KElement

property element_class

This return _element_class if existing or name if not.

classmethod extend(name: str)

Creates a new KElement class that extends this one. This allows creating new KElement names for different languages and keep the behaviour of a specific element type (e.g. mapping “tipo” elements behave like “type” elements).

When an element of a group is set with an atomic value or a tuple, a new KElement of the class with the same name of the element in the group is used to store the group.

Parameters:

name

Returns:

extends(name: str)

True if name is in the the classes this element inherits from

classmethod get_class_for(name: str)

Search in KElement subclasses and return the one with the same element name as the argument.

if more than one apply return the more specialized (longer __mro__)

If not found return None

Parameters:

name – name of an element

Returns:

KElement or a subclass

classmethod get_classes_for(name: str)

Search in Element subclass and return all that have the same element name as the argument

see KElement.get_class_for(name) for getting the more specialized

classmethod get_subclasses()

Generator for subclasses of this KElement

inherited_names()

Return the list of names in the KElement subclasses this element inherits from including its own

is_empty()

True if all aspects of the element are None or empty string

to_dict(name=False)

Return Element as a dict {core:_, comment:_, original:_} add name=True to add name to dictionary: {name:_, core:_, comment:_, original:_}

to_kleio(name=True, force_show=False)

Return element as a kleio string: element=core#comment%original To avoid rendering the element name set name=False :param name: if True(default) prefix value with self.name= :return: a valid Kleio representation of this element value

to_tuple()

Return Element as a tuple (core,comment,original)

class timelink.kleio.groups.kelement.KEntityInAttribute(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KGroupName(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for groupname of a group

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KId(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Represents an unique id for a group.

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KInside(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for id of the enclosing group

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KKleiofile(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for the name of the file from which the source was imported

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KLevel(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for nesting level in imported groups

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KLine(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for line number in imported groups

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KLoc(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for location (in a document, e.g. page) in some groups

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KMonth(month: Any | None = None, core=None, comment=None, original=None, element_class=None)

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KName(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Name of person

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KObs(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for “obs” normally observations or notes

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KOrder(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for group order in imported groups

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KOriginInRel(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KRef(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for reference number (e.g. a call number in an archive)

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KReplace(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Represents the id of a group to be replaced.

Example

source$new-id/replace=old-id

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KReplaceSourceId(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for id of source being replaced in source groups

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KSameAs(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Represents the id of a group that describes the same real world entity has the one with this element.

Used in the same file. Translators should check if the id corresponds to a group in the same file and file an error otherwise

Examples:

person$Bob Dylan/id=bob-dylan

person$Robert Allan Zimmerman/sameas=bob-dylan

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KSex(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

male / female …

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KStructure(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for structure name in sources

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KSummary(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element for summaries (long texts)

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KType(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Represents a type of object or abstraction

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KUndef(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Element of undefined class (generated by the kleio translator)

This is generated when the translator finds an element for which the is no mapping POM_SOM in any class. An example if the elements for day,month,year that are used for input but are stored as a single value YYYYMMDD and so are not present in the mapping information for database storage.

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KValue(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Represents a general purpose value

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KXSameAs(name: str | None = None, core: Any | None = None, comment=None, original=None, element_class=None)

Same meaning as KSameAs used when id is not in the file.

The difference between KSameAs and KXSameAs is just for error checking during translation. Translators will raise error if a KSameAs id is not found in the same file, but only a warning for KXSameAs.

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

class timelink.kleio.groups.kelement.KYear(year: Any | None = None, core=None, comment=None, original=None)

Represents a year.

To have value checking do KYear.set_limits((lower,upper)) !!!!

Parameters:

• name – name of the Element. If None then self._name is used.

• core – the core aspect of the Element. Must have __str__ or a tuple (core,comment,original). If a tuple optional arguments are disregarded.

• comment – Optional; The comment aspect of the Element.

• original – Optional; The original aspect of the Element.

• element_class – Optional; in groups from kleio translations this is set by the translator from the the source=parameter. of the str file. If absent it is set here equal to the name of the element.

timelink.kleio.groups.kelement.KleioNoShow

alias of invisible_

timelink.kleio.groups.kgeoentity module

class timelink.kleio.groups.kgeoentity.KGeoentity(name, type, id=, obs=, same_as=, xsame_as=)

A geographic entity. Flags an Entity as a geographic entity. No specific fields are defined for this class.

Elements:

name: the name of the object. A string. type: the . A string. id: an unique id for this person. A string, optional. obs: a note on the person. A string, optional. same_as: id of another instance of this object in the same file. xsame_as: id of another instance of this object in another file.

Kleio str definition:

part name=geoentity;

position=name; guaranteed=name; also=type,id,obs,same_as,xsame_as; part=ls,atr,rel

Creates a new instance of group with setting the value of elements.

Parameters:

• *args – values for positional arguments

• **kwargs – values for optional elements.

Example

ks = KSource("s1", type="test", loc="auc", ref="alumni", obs="Nested")

Use element_check=False to turn off checking of element names

timelink.kleio.groups.kgroup module

class timelink.kleio.groups.kgroup.KGroup(*positional_elements, **more_elements)

Abstract Kleio Group.

To define a Kleio Group extend this class and set default value for _name, or use extend(name,position, guaranteed, also).

Define allowed elements in the default values for _position, _guaranteed, _also (list of strings) or call allowed_as_element .

Use _part to list allowed enclosed groups, or call allow_as_part

For an example see timelink.kleio.groups.KPerson

Class Methods:

• extend: Create a new group definition by extending this one.

• get_subclasses: Generator for subclasses of this group.

• all_subclasses: List of all the subclasses of this group.

• is_kgroup: Check if an object is an instance of a subclass of KGroup.

• elements_allowed: Get the set of elements allowed in this group.

• allow_as_element: Add element(s) to the list of allowed elements for this group.

• allow_as_part: Allow a group to be enclosed as part of this group.

• inc_sequence: Increment and return the global sequence count.

• inc_line: Increment and return the global line count.

Instance Methods:

• include: Include a group within this group.

• before_include: Method called before this group is included into another.

• after_include: Method called after a new group is included in this one.

• is_allowed_as_part: Test if a group can be included in the current one.

• is_allowed_as_element: Test if an element is allowed in this group.

• contains: Returns included groups, optionally filtered by group name.

• elements: Returns elements in this group.

• element_names: Returns the names of elements in this group

• attr: Utility function to include a KAttribute in this KGroup.

• rel: Include a relation in this KGroup.

• to_kleio: Return a kleio representation of the group.

• to_dict: Return group information as a dictionary.

• to_json: Return group information as a JSON string.

• to_dots: Return group information as a Box object for easy referencing.

• __str__: Return a string representation of the group.

• __getitem__: Get an element by name.

• __setitem__: Set an element by name.

• pack_as_kelement: Pack a value as a KElement with a given name.

• unpack_from_kelement: Unpack the core value from a KElement.

• get_core: Get the core value of an element.

• get_id: Return the id of the group.

• get_element_by_name_or_class: Return the value of an element by name or class.

Creates a new instance of group with setting the value of elements.

Parameters:

• *args – values for positional arguments

• **kwargs – values for optional elements.

Example

ks = KSource("s1", type="test", loc="auc", ref="alumni", obs="Nested")

Use element_check=False to turn off checking of element names

after_include(group)

Method called after a new group is included in this one through KGroup.include(KGroup).

classmethod all_subclasses()

List of all the subclasses of this group

classmethod allow_as_element(ename: str | List[str], guaranteed=False, also=True, position=None)

Add element or list to list of allowed elements for this group. Optionally define if element(s) is positional, required (guaranteed) or optional :param ename: name of element :param guaranteed: if True this element is added to list of required elements. :param also: if True this element is optional (default) :param position: int, this is a positional element, at this position (0 = first position) :return: List of allowed elements

classmethod allow_as_part(g: str | type)

Allow g to be enclosed as part of this group.

Parameters:

g – the name of a group, or a subclass of KGroup. A string or class.

attr(the_type: str | KElement | Tuple[str, str, str], value: str | KElement | Tuple[str, str, str], date: str | KElement | Tuple[str, str, str], obs=None)

Utility function to include a KAttribute in this KGroup

The call:

KGroup.attr('age','25','2021-08-08',obs='in May')

is short hand for:

KGroup.include(KAttr('age','25','2021-08-08',obs='in May'))

Params google style

Parameters:

• the_type (str or tuple) – core or (core,org,comment)

• value (str or tuple) – core or (core,org,comment)

• date (str) – date as string in Kleio format, or (date,org,comment)

• obs (str) – options observation field

before_include(container_group)

Method called before this group is included into another through KGroup.include(KGroup).

contains(group: Type[str | Type[KGroup]] | None = None) → list

Returns included groups.

Groups are returned by the order in _pars.

Todo:

this would better be a generator, yield instead of extend.

Parameters:

group (str) – filter by group name

property dots

Allows easy referencing of the dictionary representation of the group.

It is very usefull in list comprehensiona, e.g.:

>> ‘Diamantina’ in [ls.value for ls in person.dots.lss

if ls.type == ‘nome-geografico’]

>> [ls.value for ls in person.dots.lss

if ls.type == ‘nome-geografico’]

Returns:

element_names() → list

Returns a list of all element names in the group.

elements() → list

Returns a list of all elements in the group.

classmethod elements_allowed() → set

Set of Elements allowed in this Group

classmethod extend(name: str, position: list | str | None = None, guaranteed: list | str | None = None, also: list | str | None = None, part: list | str | None = None, synonyms: Tuple[str, str] | None = None)

Create a new group definition by extending this one

Parameters:

• name – name of the new group

• position – list of positional elements

• guaranteed – list of required elements

• also – list of optional elements

• part – list of groups that can be included in this one

• synonyms – list of tuples defining synonym for elements e,g, [(“ano”,”year”),…]

Returns:

new group class

get_core(element_name[, default])

Returns the core value of an element

get_element_by_name_or_class(element_spec, default=None)

Return the value of an element with a given name or that inherits from an element of the given name.

An element matches a element_spec if its name is equal to the element_spec name or if it is an instance of KElement subclass with the name equal to element_spec.

Parameters:

• element_spec – name of column, or name of POMClassAttributes

• default – default value if not element found

Returns:

KElement, or whatever in default.

get_id()

Return the id of the group

classmethod get_subclasses()

Generator for subclasses of this group

include(group: Type[KGroup])

Include a group. group, or its class, must in _part list or

extend a class in the part list.

Returns self so it is possible to chain: g.include(g2).include(g3)

includes(*args, **kargs) → list

Deprecated. Use contains instead.

is_allowed_as_element(element_name)

Test if this element is allowed in this group.

For an element to be allowed one the following must be true:

1. part of KGroup._builtin

2. part of position list

3. part of guarenteed list

4. part of also list

Note that this function is unaffected by self._element_check

Parameters:

element_name – name of element to check

Returns:

True if element allowed False otherwise

is_allowed_as_part(group)

Test if a group can be included in the current one.

For a group to be allowed for inclusion one of 3 conditions necessary:

1. the kname of the group is in self._pars

2. the type of the group is in self._pars

3. the type of the group inherits from a type in self._pars

Return key under which the group is allowed (kname, type or super type) Return None if not allowed

classmethod is_kgroup(g)

True g is an instance of a subclass of KGroup

property kname

The kleio name of this group, used in the to_kleio() method

pack_as_kelement(arg, value, element_class=None)

Packs value as a KElement with name arg

Parameters:

• arg – name of element

• value – value of element; can be a KElement, a tuple (core, cooment, original) or a value

• element_class – class of element as string; if none arg is used to find class

TODO: the question is what is the class of the KElement to be stored if value is a KElement then it already has a class

rel(the_type: str | tuple, value: str | tuple, destname: str | tuple, destination: str | tuple, date: str | tuple | None = None, obs: str | None = None)

include a relation in this KGroup

to_dict(allow_none: bool = False, include_str: bool = False, include_kleio: bool = False, redundant_keys: bool = True, include_builtin: bool = True)

Return group information as a dict.

Params:

allow_none bool = Include null values (default False)

param allow_none:

Include null values (default False)

param include_str:

include a string represention of each element with keys [elementname]_str, the value will include # and % if necessary

param include_kleio:

include a kleio representation of each element with keys [elementname]_kleio; this is similar to include_str but the value also contains the element name

param redundant_keys:

include redundant keys (see bellow)

param include_builtin:

include also elements like line,level,… etc…

return:

a dictionary with the structure bellow

Keys of returned dict

group[element]:

core value of element; also group[element_core]

group[element_comment]:

comment aspect of element

group[element_original]:

original aspect of element

group[element_str]:

if include_str=True, a string representation of elementm(with # and % if necessary);

group[element_kleio]:

if include_kleio=True, a kleio representation in the form element=string

group[includes]:

list of enclosed groups

group[includes][subgroup]:

list of enclosed groups of type subgroup

If redundant_keys=True enclosed subgroups can also be accessed in the plural form, if no name conflict with existing elements:

group['persons'] == group['includes']['persons']
group['person']['id1'] ==
        [p for p in group['includes']['persons']
        if p.id='id1'][0]

Todo:

add first(), last() where includes is allowed:: group[‘first’][‘person’] = group[‘includes’][‘person’][0]

to_kleio(indent='') → str

Return a kleio representation of the group.

unpack_from_kelement(value)

if value is a KElement return core if not return value as is.

Useful to obtain the core value in elements that normally have no comment or original.

Parameters:

value

Returns:

timelink.kleio.groups.kkleio module

class timelink.kleio.groups.kkleio.KKleio(structure, prefix=, obs=, translations=, translator=)

Kleio notation document. Represents a file in Kleio notation.

Elements:

structure: The path to a Kleio structure file (default gacto2.str) prefix: Prefix to be added to all ids generated from this file translations: number of times this file was translated translator: name of the translator to be used (currently not used) obs: observations

TODO: Could keep a list of the name of the groups included, at all levels

Creates a new instance of group with setting the value of elements.

Parameters:

• *args – values for positional arguments

• **kwargs – values for optional elements.

Example

ks = KSource("s1", type="test", loc="auc", ref="alumni", obs="Nested")

Use element_check=False to turn off checking of element names

timelink.kleio.groups.kls module

class timelink.kleio.groups.kls.KLs(*args, **kwargs)

Synonym for KAttribute

Creates a new instance of group with setting the value of elements.

Parameters:

• *args – values for positional arguments

• **kwargs – values for optional elements.

Example

ks = KSource("s1", type="test", loc="auc", ref="alumni", obs="Nested")

Use element_check=False to turn off checking of element names

timelink.kleio.groups.kobject module

class timelink.kleio.groups.kobject.KObject(name, type, id=, obs=, same_as=, xsame_as=)

An object in a historical source. Object groups represent physical entities like houses, pieces of land, movable objects

Elements:

name: the name of the object. A string. type: the . A string. id: an unique id for this person. A string, optional. obs: a note on the person. A string, optional. same_as: id of another instance of this object in the same file. xsame_as: id of another instance of this object in another file.

Kleio str definition:

part name=object;

guaranteed=name; position=name,type; also=obs,id,same_as,xsame_as; arbitrary=atr,ls,rel

Creates a new instance of group with setting the value of elements.

Parameters:

• *args – values for positional arguments

• **kwargs – values for optional elements.

Example

ks = KSource("s1", type="test", loc="auc", ref="alumni", obs="Nested")

Use element_check=False to turn off checking of element names

timelink.kleio.groups.kperson module

class timelink.kleio.groups.kperson.KPerson(name, sex, id, obs=, same_as=, xsame_as=)

Person in a historical source

Elements:

name: the name of the person. A string. sex: the gender of the person. A string. id: an unique id for this person. A string, optional. obs: a note on the person. A string, optional. same_as: id of another instance of this person in the same file. xsame_as: id of another instance of this person in another file.

Kleio str definition:

part name=person ;

guaranteed=name,sex; also=id,obs,same_as; position=name,sex,id,same_as; arbitrary=atr,rel,ls

Creates a new instance of group with setting the value of elements.

Parameters:

• *args – values for positional arguments

• **kwargs – values for optional elements.

Example

ks = KSource("s1", type="test", loc="auc", ref="alumni", obs="Nested")

Use element_check=False to turn off checking of element names

timelink.kleio.groups.krelation module

class timelink.kleio.groups.krelation.KRelation(type, value, destname, destination[, date=, obs=])

A relation between historical entities.

Relations have a type, a value, a date and a destination. The origin of the relation is the entity represented by the group that includes the relation.

Elements:

type: the type of the relation. A String value: the value of the relation. A string. origin: the id of the origin of the destination. A string destination: the id of the destination of the relation. A string. destname: the name of the destination of the relation. A string date: the date of relation. A string in Timelink format, optional. obs: a note on the attribute. A string optional.

Kleio stru definition:

part name=relation ;

position=type,value,destname,destination; guaranteed=type,value,destname,destination ; also=obs,date

Creates a new instance of group with setting the value of elements.

Parameters:

• *args – values for positional arguments

• **kwargs – values for optional elements.

Example

ks = KSource("s1", type="test", loc="auc", ref="alumni", obs="Nested")

Use element_check=False to turn off checking of element names

after_include(group)

Method called after a new group is included in this one through KGroup.include(KGroup).

before_include(container_group)

Method called before a new krelation is included

in a group with container_group.include(KGroup).

It sets the origin of the relation to the id of the container group.

Parameters:

container_group (KGroup) – the group that includes the relation

Returns:

True if the relation can be included in the group, False otherwise.

timelink.kleio.groups.ksource module

class timelink.kleio.groups.ksource.KSource(*args, **kwargs)

Represents an Historical Source. Sources contain KAct and may contain KAttribute.

Elements

id

An unique id for this source.

type

The type of the source (e.g. baptisms, marriages); optional.

loc

Location (name of archive, library, collection); optional.

ref

The call reference (“cota”) of the source in the location; optional.

date

The date of the source. A string in timelink format; optional.

• 1582

• 1582-05-04

• 1582:1609

• >1582:<1702

year

A single year. A number. Deprecated, use date instead

obs

Observations on the source (can be long and multiline); optional.

replace

Id of source to be replaced. A string; optional. The source with this id is removed before importing this one. Used when changing the id of a file, old id should go here.

Kleio str definition:

part name=historical-source;
     guaranteed=id;
     also=type,date,year,loc,ref,obs,replace;
     position=id,year,type,ref;
     part=historical-act

Creates a new instance of group with setting the value of elements.

Parameters:

• *args – values for positional arguments

• **kwargs – values for optional elements.

Example

ks = KSource("s1", type="test", loc="auc", ref="alumni", obs="Nested")

Use element_check=False to turn off checking of element names