timelink.kleio package

Submodules

timelink.kleio.groups module

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

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

Bases: timelink.kleio.groups.object

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

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

Bases: timelink.kleio.groups.kgroup

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

Elements:

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

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

Bases: timelink.kleio.groups.attr

Synonym for KAttribute

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

Bases: timelink.kleio.groups.kgroup

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

class timelink.kleio.groups.KElement(name: str, val: Any, comment=None, original=None)

Bases: object

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

KElement('name','Joaquim Carvalho',original='Joachim Carvº',
        comment='Family name added in the margin')

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)

comment: str = None

core: Any

is_empty()

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

name: str

original: str = None

to_dict(name=False)

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

to_dots()

to_kleio()

Return element as a kleio string: element=core#comment%original

to_tuple()

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

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

Bases: object

Abstract Kleio Group. To define a Kleio Group extend this class and set default value for _name. Define allowed elements in the default values for

_position, _guaranteed, _also (list of strings).

Use _part to list allowed enclosed groups.

For an example see timelink.kleio.groups.KPerson

classmethod all_subclasses()

classmethod allow_as_part(g: Union[str, type])

Allow g to be enclosed as part of this group.

Arguments:

g: the name of a group, or a subclass of KGroup.

A string or class.

attr(the_type: Union[str, timelink.kleio.groups.KElement, Tuple[str, str, str]], value: Union[str, timelink.kleio.groups.KElement, Tuple[str, str, str]], date: Union[str, timelink.kleio.groups.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

property dots

classmethod elements() → set

Set of Elements allowed in this Group

classmethod extend(name: str, position: Optional[Union[list, str]] = None, guaranteed: Optional[Union[list, str]] = None, also: Optional[Union[list, str]] = None, part: Optional[Union[list, str]] = None)

Create a new group extending this one fonte = KGroup.extends(‘fonte’,

also=[‘tipo’,

‘data’, ‘ano’, ‘obs’, ‘substitui’]) :type part: KGroup

property get

get_core(element_name[, default])

Returns the core value of an element

classmethod get_subclasses()

id: str = '*id*'

include(group: Type[timelink.kleio.groups.KGroup])

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

extend a class in the part list.

TODO use a ordered dict for included groups: key class

• at first include a ordered dict is created with the keys of “part” members and empty lists. - _contains = OrderedDict([(g,[]) for g in self._part])

• For each incoming group key is determined:

  k = self._contains.keys() ok = True if g.kname in k:

  self._contains[g.kname] = g

  elif type(g) in k:

  self._contains[type(g)] = g

  else: # check if it is a specialization

  ok = False for super in k:

  if super in g.mro():

  self._contains[super] = g ok = true break

  if not ok:

  raise ….

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

includes(group: Optional[Type[Union[str, Type[timelink.kleio.groups.KGroup]]]] = 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

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 tupe Return None if not allowed

classmethod is_kgroup(g)

True g is an instance of a subclass of KGroup

property kname

rel(the_type: Union[str, tuple], value: Union[str, tuple], destname: Union[str, tuple], destination: Union[str, tuple], date: Union[str, tuple], obs: Optional[str] = None)

include a relation in this KGroup

to_dict()

Return group information as a dict.

Also available as property “get” so that group.to_dict()[‘id’] == group.get[‘id’]

Format of keys:

group[element]: core value of element group[element_comment]: comment aspect of element group[element_original]: original aspect of element group[element_str] : string representation of element

(with # and % if necessary)

group[element_kleio]: kleio representation element=string

group[includes]: list of enclosed groups group[includes][subgroup]: list of enclosed groups of type subgroup

enclose subgroups can also be accessed in the plural form

if there are no name conflict with existing elements:

group[subgroup+’s’] == group[includes][subgroup]

to_dots()

to_kleio(indent='') → str

Return a kleio representation of the group.

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

Bases: timelink.kleio.groups.kgroup

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

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

Bases: timelink.kleio.groups.attr

Synonym for KAttribute

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

Bases: timelink.kleio.groups.kgroup

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

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

Bases: timelink.kleio.groups.kgroup

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

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

Bases: timelink.kleio.groups.kgroup

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. 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

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

Bases: timelink.kleio.groups.kgroup

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

timelink.kleio.utilities module

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

timelink.kleio.utilities.format_obs(obs, initial_indent='    ', indent='  ')

Not used in current implemented

timelink.kleio.utilities.kleio_escape(v: str) → str

Checks for Kleio special characters and quotes if needed:

>>> print(kleio_escape('normal string'))
normal string
>>> print(kleio_escape('oops we have a / in the middle'))
"oops we have a / in the middle"

timelink.kleio.utilities.make_element(element, value, original=None, comment=None)

timelink.kleio.utilities.make_kgroup(group_name, Entity)

timelink.kleio.utilities.quote_long_text(txt, initial_indent='    ', indent='  ', width=2048) → str

Surround long text with triple quotes, wraps and indents lines if needed. Some of the parameters are passed on to textwrap.fill().

Sphynx style markup

Parameters

• txt (str) – The text to be transformed

• initial_indent (str) – string to ident the first line of paragraphs. Default is 4 spaces. See textwrap.fill().

• indent (str) – string to ident the wrap lines of paragraphs (after the first). Default is 2 spaces. See textwrap.fill().

• width (int) – width of line for wrapping. See textwrap.fill().

Return type

str

Module contents