timelink.api.models package

Module for SQLAlchemy and Pydantic models of the Timelink Database.

TODO: after testing for MHK schema:

Implemente TemporalEntity with flexible dates
Check the dataclasses new mapping https://docs.sqlalchemy.org/en/20/orm/dataclasses.html#orm-declarative-native-dataclasses

Submodules

timelink.api.models.act module

Implementation of Acts in POM model

(c) Joaquim Carvalho 2023. MIT License, no warranties.

class timelink.api.models.act.Act(**kwargs)[source]

Represents an Act, i.e. a record of some event in a historical document.

Examples of acts are: baptisms, marriages, purchase deeds, wills, court records.

TODO: implement https://github.com/time-link/timelink-kleio/issues/1

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

contains: Mapped[List['Entity']]

list of Entity objects contained in this entity

Type:: list(Entity)

groupname

name of the kleio group that produced this entity

Type:: str

id: Mapped[str]

a string uniquely identifying the act

Type:: str

inside: Mapped[str | None]

id of the entity inside which this occurred.

Type:: str

loc: Mapped[str]

location of the act, eg church, notary office

Type:: str

obs: Mapped[str]: any observations or comments.

ref: Mapped[str]

archival reference

Type:: str

the_date: Mapped[str]

the date of the act in Kleio format AAAAMMDD

Type:: str

the_level

the nesting level of this entity in the source

Type:: int

the_line

line in which the entity occurred in the source

Type:: int

the_order

sequential order of this entity in the source

Type:: int

to_kleio(ident='', ident_inc=' ', show_contained=True, width=80, **kwargs) → str[source]

conver the entity to a kleio string

Parameters:

self_string – the string to be used to represent the entity
show_contained – if True, contained entities are also converted to kleio
ident – initial identation
ident_inc – identation increment
show_inrels – if False, inbound relations are not shown, default is True
kwargs – additional arguments to be passed to contained entities

updated

when this entity was updated in the database

Type:: datetime

timelink.api.models.aregister module

Mapping ‘authority-register’ to class aregister.

class aregister super entity table aregisters
      with attributes
           id column id baseclass id coltype varchar colsize 64 colprecision 0 pkey 1
        and
           date column the_date baseclass date coltype varchar colsize 24 colprecision 0 pkey 0
        and
           user column user baseclass user coltype varchar colsize 32 colprecision 0 pkey 0
        and
           name column name baseclass name coltype varchar colsize 254 colprecision 0 pkey 0
        and
           dbase column dbase baseclass dbase coltype varchar colsize 32 colprecision 0 pkey 0
      and
         mode column replace_mode baseclass mode coltype varchar colsize 64 colprecision 0 pkey 0
        and
           obs column obs baseclass obs coltype varchar colsize 16654 colprecision 0 pkey 0 .

(c) Joaquim Carvalho 2024 MIT License, no warranties.

class timelink.api.models.aregister.ARegister(**kwargs)[source]

Represent an Authorithy Register

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

contains: Mapped[List['Entity']]

list of Entity objects contained in this entity

Type:: list(Entity)

groupname

name of the kleio group that produced this entity

Type:: str

id: Mapped[str]

unique identifier for the entity

Type:: str

inside: Mapped[str | None]

id of the entity inside which this occurred.

Type:: str

the_level

the nesting level of this entity in the source

Type:: int

the_line

line in which the entity occurred in the source

Type:: int

the_order

sequential order of this entity in the source

Type:: int

to_kleio(show_contained=True, self_string=None, ident='', ident_inc=' ', width=80, **kwargs) → str[source]

conver the entity to a kleio string

Parameters:

self_string – the string to be used to represent the entity
show_contained – if True, contained entities are also converted to kleio
ident – initial identation
ident_inc – identation increment
show_inrels – if False, inbound relations are not shown, default is True
kwargs – additional arguments to be passed to contained entities

updated

when this entity was updated in the database

Type:: datetime

timelink.api.models.attribute module

class timelink.api.models.attribute.Attribute(**kwargs)[source]

represents an attribute of an entity.

Attributes have a type, a value, a date and an optional observation.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

contains: Mapped[List['Entity']]

list of Entity objects contained in this entity

Type:: list(Entity)

groupname

name of the kleio group that produced this entity

Type:: str

id: Mapped[str]

unique identifier for the entity

Type:: str

inside: Mapped[str | None]

id of the entity inside which this occurred.

Type:: str

the_level

the nesting level of this entity in the source

Type:: int

the_line

line in which the entity occurred in the source

Type:: int

the_order

sequential order of this entity in the source

Type:: int

to_kleio(ident='', ident_inc=' ', self_string=None, show_contained=False, **kwargs)[source]

conver the entity to a kleio string

Parameters:

self_string – the string to be used to represent the entity
show_contained – if True, contained entities are also converted to kleio
ident – initial identation
ident_inc – identation increment
show_inrels – if False, inbound relations are not shown, default is True
kwargs – additional arguments to be passed to contained entities

to_markdownn(**kwargs)[source]: Convert the attribute to a markdown representation.

updated

when this entity was updated in the database

Type:: datetime

timelink.api.models.base module

timelink.api.models.base_class module

Base class, all modules must import this to share Metadata

for 2.0 migration see: https://docs.sqlalchemy.org/en/20/changelog/whatsnew_20.html#whatsnew-20-orm-declarative-typing

class timelink.api.models.base_class.Base(**kwargs: Any)[source]

Base class, all modules must import this to share Metadata

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

registry: ClassVar[_RegistryType] = <sqlalchemy.orm.decl_api.registry object>: Refers to the _orm.registry in use where new _orm.Mapper objects will be associated.

timelink.api.models.base_class.get_all_base_subclasses(cls=None)[source]

Get all base subclasses

This function returns all ORM classes that inherit from Base, and so share the same metadata.

timelink.api.models.base_mappings module

These mappings are needed to boostrap a new database.

They are used by TimelinkDatabase to initialize a new database.

Mappings as these can be generated from existing Timelink/MHK databases with:

pom_classes = session.query(PomSomMapper)
                     .where(Entity.pom_clas == 'class').all()
for pom_class in pom_classes:
     print(f"'{pom_class.id}': [")
     print(repr(pom_class),',')
     for cattr in pom_class.class_attributes:
         print(repr(cattr),',')
     print('],')

Note that the order of the mappings is important. If a mapping extends another mapping with ‘super_class’, the super class mapping must be defined before the subclass mapping.

Originally these mappings are generated by the Kleio translator when processing kleio source files and generating data for the Timelink database.

So the mappings bellow have the same information as the Kleio source files. They are needed for situations where the Kleio source files are not available and Kleio groups are generated programmatically, like in the case of importing from other data files. See the tests in tests(test_api_models_db.py for examples.

timelink.api.models.entity module

class timelink.api.models.entity.Entity(**kwargs)[source]

ORM Model root of the object hierarchy.

All entities in a Timelink/MHK database have an entry in this table. Each entity is associated with a class that allow access to a specialization table with more columns for that class.

This corresponds to the model described as “Joined Table Inheritance” in sqlalchemy (see https://docs.sqlalchemy.org/en/14/orm/inheritance.html)

This class also provides methods to manage the association between groups and ORM classes. This is needed because the ORM classes are created dynamically based on the mappings defined in the PomSomMapper class and during import diferent Kleio groups are imported associated with different classes.

TODO: specialize TemporalEntity to implement https://github.com/time-link/timelink-kleio/issues/1: Acts, Sources, Attributes and Relations are TemporalEntities

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

add_attribute(attribute)[source]: Add an attribute to the entity

add_relation(relation)[source]: Add a relation to the entity

classmethod clear_group_models_cache()[source]: Clear cached association between groups and ormclass

contains: Mapped[List[Entity]]

list of Entity objects contained in this entity

Type:: list(Entity)

dated_bio() → dict[source]

Return the atributes and relations of the entity grouped by date

Returns a dictionary with the date as key and a list of attributes and relations as value

description_elements()[source]: Return a list of elements to be used in the description of the entity

for_kleio(element: str, named=False, prefix='', skip_if_empty=False)[source]

Render a specific attribute/column/element of the entity for kleio.

Check which attribute is requested and return the value Checks for extra information for this attribute.

Extra information can be “comment” or “original”

if the attribute has a comment, #comment is appended to the value if the attribute has an original wording, %original is appended to the value

get_column_for_element(element: str)[source]: Get the column name for a group element

get_description(default=None) → str[source]

Return a descritive name for the entity

Uses list of description elements to get the first non-empty element. If no element is found, returns the default value. If no default is provided, returns the pom_class.

classmethod get_dynamic_models()[source]

Dynamically defined ORM classes that extend Entity

Dynamic models are models that are created during the import of Kleio groups.

Returns:: List of ORM classes
Return type:: list

classmethod get_dynamic_orm_table_names()[source]: Return the names of tables associated with ORM models

get_element_for_column(column: str)[source]: Get the kleio element name for a column

get_element_names()[source]: Get the names of the elements for this entity

classmethod get_entity(eid: str, session)[source]: Get an Entity from the database. The object returned will be of the ORM class defined by mappings. :param id: id of the entity :param session: current session :return: an Entity object of the proper class for the mapping

get_extra_info() → tuple[str, dict][source]

Return a dictionatry with extra information about this entity or None

This method checks if there is extra information about the entity. This is needed because in the source oriented notation each value can have a comment and the original wording of the value, and also multiple values for a single element/field.

The way this is managed in the relational database (person oriented model) is to store the information as a Json object in the ‘extra_info’ field. A legacy pattern was to store the information in the ‘obs’ field.

if an entity has an ‘obs’ field and that field contains the string ‘extra_info:’ then the rest of the field is considered a json representation of extra information about the entity. Extra information can be comments and original wording of field values.

This method returns a tuple with the extra information as dict and, in the case that the obs field contains extra information, a new obs string (withou the extra_info part).

Currently the dictionary has the following structure:

{‘field_name’:

{‘comment’: text_of_comment,
‘original’: original_wording}}

classmethod get_group_models() → dict[source]

Return a dictionary of group models

The keys are group names and the values are ORM Models.

classmethod get_groups_for_orm(orm: str)[source]

get the list of groups that map to this model

Parameters:: orm (str) – id of a orm model

classmethod get_orm_for_group("acts")[source]: will return the ORM class handling a given group

classmethod get_orm_for_pom_class("act")[source]: will return the ORM class corresponding to the pom_class “act”

classmethod get_orm_for_table("acts")[source]: will return the ORM class handling the “acts” table

classmethod get_orm_models()[source]

Currently defined ORM classes that extend Entity (including Entity itself)

Returns:: List of ORM classes
Return type:: list

classmethod get_orm_table_names()[source]: Return the names of tables associated with ORM models

classmethod get_orm_tables()[source]: Return the table objects associated with ORM models

classmethod get_som_mapper_ids()[source]

Ids of PomSomMapper references by orm classes

Returns:: List of strings
Return type:: List[str]

classmethod get_som_mapper_to_orm_as_dict()[source]: Return a dict with pom_class id as key and ORM class as value

classmethod get_subclasses()[source]: Get the subclasses of Entity

classmethod get_tables_to_dynamic_orm_as_dict()[source]: Return a dict with table name as key and ORM class as value

classmethod get_tables_to_orm_as_dict()[source]: Return a dict with table name as key and ORM class as value

groupname

name of the kleio group that produced this entity

Type:: str

id: Mapped[str]

unique identifier for the entity

Type:: str

inside: Mapped[str | None]

id of the entity inside which this occurred.

Type:: str

classmethod is_dynamic()[source]

Return True if this class was created by a dynamic mapping

Dynamic mappings are mappings that are created during the import of a Kleio group.

is_inbound_relation(relation)[source]

Check if the relation is inbound to this entity.

Override in real entities or other special cases

render_id()[source]

Return the id of the entity in a kleio format

Does not return the id if it starts with an underscore

classmethod reset_cache()[source]: Reset the group_models and group_elements_to_columns cache

classmethod set_as_dynamic()[source]: Set this class as dynamic Dynamic mappings are mappings that are created during the import of a Kleio group.

the_level

the nesting level of this entity in the source

Type:: int

the_line

line in which the entity occurred in the source

Type:: int

the_order

sequential order of this entity in the source

Type:: int

to_kleio(self_string=None, show_contained=True, ident='', ident_inc=' ', show_inrels=True, **kwargs)[source]

conver the entity to a kleio string

Parameters:

self_string – the string to be used to represent the entity
show_contained – if True, contained entities are also converted to kleio
ident – initial identation
ident_inc – identation increment
show_inrels – if False, inbound relations are not shown, default is True
kwargs – additional arguments to be passed to contained entities

update_group_elements_to_columns()[source]: Update the element to column mappings for the Group of this Entity

updated

when this entity was updated in the database

Type:: datetime

with_extra_info()[source]

Returns a copy of the entity with field values rendered with extra information

Extra_info is current stored as json in the obs field of the entity, or in the extra_info field of the entity. The extra_info field is a json field.

timelink.api.models.geoentity module

(c) Joaquim Carvalho 2021. MIT License, no warranties.

class timelink.api.models.geoentity.Geoentity(**kwargs)[source]

represents a geographical entity.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

contains: Mapped[List['Entity']]

list of Entity objects contained in this entity

Type:: list(Entity)

groupname

name of the kleio group that produced this entity

Type:: str

id: Mapped[str]

unique identifier for the entity

Type:: str

inside: Mapped[str | None]

id of the entity inside which this occurred.

Type:: str

the_level

the nesting level of this entity in the source

Type:: int

the_line

line in which the entity occurred in the source

Type:: int

the_order

sequential order of this entity in the source

Type:: int

to_kleio(self_string=None, show_contained=False, ident='', ident_inc=' ', width=80, **kwargs) → str[source]

conver the entity to a kleio string

Parameters:

self_string – the string to be used to represent the entity
show_contained – if True, contained entities are also converted to kleio
ident – initial identation
ident_inc – identation increment
show_inrels – if False, inbound relations are not shown, default is True
kwargs – additional arguments to be passed to contained entities

updated

when this entity was updated in the database

Type:: datetime

timelink.api.models.object module

(c) Joaquim Carvalho 2021. MIT License, no warranties.

class timelink.api.models.object.Object(**kwargs)[source]

Represent an object in the database. Objects are entities that are not people.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

contains: Mapped[List['Entity']]

list of Entity objects contained in this entity

Type:: list(Entity)

groupname

name of the kleio group that produced this entity

Type:: str

id: Mapped[str]

unique identifier for the entity

Type:: str

inside: Mapped[str | None]

id of the entity inside which this occurred.

Type:: str

the_level

the nesting level of this entity in the source

Type:: int

the_line

line in which the entity occurred in the source

Type:: int

the_order

sequential order of this entity in the source

Type:: int

updated

when this entity was updated in the database

Type:: datetime

timelink.api.models.person module

class timelink.api.models.person.Person(**kwargs)[source]

Represents a person in a historical source

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

contains: Mapped[List['Entity']]

list of Entity objects contained in this entity

Type:: list(Entity)

groupname

name of the kleio group that produced this entity

Type:: str

id: Mapped[str]

unique identifier for the entity

Type:: str

inside: Mapped[str | None]

id of the entity inside which this occurred.

Type:: str

the_level

the nesting level of this entity in the source

Type:: int

the_line

line in which the entity occurred in the source

Type:: int

the_order

sequential order of this entity in the source

Type:: int

to_kleio(self_string='', ident='', ident_inc=' ', show_contained=True, width=80, **kwargs) → str[source]

conver the entity to a kleio string

Parameters:

self_string – the string to be used to represent the entity
show_contained – if True, contained entities are also converted to kleio
ident – initial identation
ident_inc – identation increment
show_inrels – if False, inbound relations are not shown, default is True
kwargs – additional arguments to be passed to contained entities

updated

when this entity was updated in the database

Type:: datetime

timelink.api.models.person.get_person(id: str | None = None, db=None, session=None, sql_echo: bool = False) → Person[source]: Fetch a person from the database

timelink.api.models.person.pperson(id: str, session=None)[source]: Prints a person in kleio notation

timelink.api.models.pom_som_mapper module

Mapping between Kleio Groups and relational database tables

class timelink.api.models.pom_som_mapper.PomClassAttributes(**kwargs)[source]

Attribute of a PomClass. Maps kleio group element to table columns

the_class: id of the PomSomClass this attribute is attached to. name : name of of the attribute colname : name of the column in the corresponding table colclass : class of the column (element source if different from colname) coltype : type of the column colsize : size of the column, int colprecision: precision of the column (if decimal), int pkey : if > 0 order of this column in the primary key of the table

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class timelink.api.models.pom_som_mapper.PomSomMapper(**kwargs)[source]

Represents a mapping between a Kleio Group in the Source Oriented Model (Som) and a relational database entity in the Person Oriented Model (Pom). This class corresponds to the table “classes” in a Timelink-MHK database, and the associated “class_attributes” table. Together the two tables describe a Som-Pom mapping, that define how Kleio groups are stored in the relational database.

This class can generate tables and ORM objects that can store a Kleio Group in the database.

Fields

Id:: name of this PomSomMapper, singular form
Table_name:: name of the table in Pom, plural form
Group_name:: name of Som group that maps to this table
Super_class:: name of PomSom class extended by this one
Orm_class:: ORM class that maps to this table
Pom_classes:: dictionary of all PomSomMappers (id, PomSomMapper)
Group_orm_models:: dictionary of ORM classes for each group name

For the core kleio groups (source,act,person,object, relation,attribute) the mapping information is predefined at database creation time and the ‘classes’ and ‘class_attributes’ populated accordingly.

The Kleio translator can provide new mappings for new groups that are created for specific sources. The mapping information between new groups and the database is embedded in the translator output of new sources in the form of data for the tables mapped to the PomSomMapper.

For a mapping between a Som Group and a Pom table to be fully operational it is necessary that:

The tables “classes” and “class_attributes” contain the mapping information, normally populated during the initialization process of the database (timelink.api.models.basemappings.py) and updated during import, as new sources define new mappings dynamically.
A table for storing the elements of the Som Group. This is either a basic core table (persons,objects,acts,sources,…) or a table that extends a basic core table with extra columns.
An ORM sqlalchemy model that represents the Pom model and joins the information of the inheritance hierarchy, by mapping to the necessary tables.

The name of the table for a given group and the correspondence between group elements and table columns is handled by the PomSomMapper. If the group adds extra information then a new table is created that “extends” an existing core table, by what is called a “joined inheritance hierarchy” (see https://docs.sqlalchemy.org/en/14/orm/inheritance.html)

To ensure that all the three dimensions exist in a given context it is necessary that:

1. When creating a new database, the core Pom tables should be created using sqlalchemy metadata.create_all(bind=engine). Then the tables “classes” and “class_attributes” must be populated with the mapping of the core Som and Pom groups and entities.

See timelink.api.models.base_mappings.py for the core data for bootstrapping of the mapping information.

Both steps are ensured by TimelinkDatabase.__init__ method.

When importing new sources, if a new mapping was generated at the translation step, it is necessary first to populate “classes” and “class_attributes” with the mapping information, included in the translation source, then generate the table for the group information (if it does not exist) and the ORM mapping. This step is done by the method PomSomMapper.ensure_mapping(session) which must be called during the import process.
When connecting to a database created by a legacy version of MHK, it is necessary to ensure that all the ORM mappings are created, by examining the information in the “classes” table and checking if the ORM mapping and table representations exist. This is done by the PomClass.ensure_all_mappings() method.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

column_to_class_attribute(colname: str, session: None) → PomClassAttributes[source]

Return the class attribute corresponding to a column name.

Parameters:: colname (str) – The name of a column in the mapped table.

contains: Mapped[List['Entity']]

list of Entity objects contained in this entity

Type:: list(Entity)

element_class_to_column(eclass: str, session: None) → str[source]

Return the column name corresponding to a group element class.

Parameters:: eclass (str) – The class of an element (included in the export file).
Returns:: The name of the column corresponding to this element in the mapped table.
Return type:: str

element_name_to_column(ename: str, session: None) → str[source]

Return the column name corresponding to a group element name.

Parameters:: ename (str) – The name of an element (included in the export file).
Returns:: The name of the column corresponding to this element in the mapped table.
Return type:: str

classmethod ensure_all_mappings(session)[source]

Ensures that every class currently defined in the database has a python table object and a python ORM object

Returns:: None

ensure_mapping(session=None)[source]

Ensure that a table and ORM model exist to support this PomSom mappings

Checks if there is a table definition to support this mapping. If not a new table definition is created with information from the class attributes.

A new ORM class is also created for mapping the new table. The new ORM class will extend the superclass ORM mapping.

classmethod get_orm_for_group(groupname: str)[source]

PomSomMapper.get_orm_for_groupname(“act”)

will return the ORM class corresponding to the groupname “act”

classmethod get_pom_class(pom_class_id: String, session)[source]

Return the pom_class object for a given pom_class_id.

timelink.api.models.relation module

class timelink.api.models.relation.Relation(**kwargs)[source]

represents a relation between two entities.

Relations have a type, a value, a date and an optional observation.

Parameters:

id (str) – the id of the relation
origin (str) – the id of the origin entity
destination (str) – the id of the destination entity
the_type (str) – the type of the relation
the_value (str) – the value of the relation
the_date (str) – the date of the relation
obs (str) – an observation about the relation

Also, for the entity super class:: groupname (str): the name of the group inside (str): the id of the containing entity the_line (str): the line of the entity in the source the_level (str): the level of the entity in the source the_order (str): the order of the entity in the source

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

contains: Mapped[List['Entity']]

list of Entity objects contained in this entity

Type:: list(Entity)

groupname

name of the kleio group that produced this entity

Type:: str

id: Mapped[str]

unique identifier for the entity

Type:: str

inside: Mapped[str | None]

id of the entity inside which this occurred.

Type:: str

the_level

the nesting level of this entity in the source

Type:: int

the_line

line in which the entity occurred in the source

Type:: int

the_order

sequential order of this entity in the source

Type:: int

to_kleio(ident='', **kwargs)[source]

conver the entity to a kleio string

Parameters:

self_string – the string to be used to represent the entity
show_contained – if True, contained entities are also converted to kleio
ident – initial identation
ident_inc – identation increment
show_inrels – if False, inbound relations are not shown, default is True
kwargs – additional arguments to be passed to contained entities

to_markdown(**kwargs)[source]: Convert the relation to a markdown representation.

updated

when this entity was updated in the database

Type:: datetime

timelink.api.models.rentity module

class timelink.api.models.rentity.BLink(**kwargs)[source]

Table to store backups of the links table.

This is used when links are removed temporalily so that new links with the same occurrences can recover a previous real id. Check REntity.same_as for more details.

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class timelink.api.models.rentity.Link(**kwargs)[source]

Represents the link between a real entity and an entity.

The link between a real entity and an entity is maintained in this table.

Fields:: rid: id of the real entity entity: id of the entity (occurrence) rule: rule used to link the entity to the real entity user: user that linked the entity to the real entity status: status of the link source: id of source of the link when same_as or x_same_as aregister: id of source of the link when same_as or x_same

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

classmethod missing_occurrences(session=None)[source]: Find link rows where the entity is missing in the Entity table

class timelink.api.models.rentity.LinkStatus(value)[source]

Status of a real entity.

The following statuses are possible:

Unlinked: unlinked entity, assumed as a real entity. Automatic: linked automatically by enetity resolution algorithms. Source: linked by the user in the source with same_as or x_same_as. Manual: linked manually by the user in the database after import. Valid: validated by the user (whatever the origin). N: legacy status, linked in MHK (considered valid). For importing data from MHK.

Note that in SQLAlchemy what is persisted is the name of the enum “UNLINKED”, “AUTOMATIC”, “SOURCE”, “MANUAL”, “VALID”, “MHK” etc…

Note that changes to this list will require changes to the database schema in postgresql directly in the database.

See: https://stackoverflow.com/questions/43519096/: after-updating-enum-with-a-new-value-that-value-cannot-be-inserted-with-psycopg

exception timelink.api.models.rentity.OccurenceTypeError[source]: Error raised when an attempot is made to link two entities of different types

exception timelink.api.models.rentity.OccurrenceMissingError[source]: Error raised when an occurrence is missing in the database and an attempt is made to link it to a real entity

class timelink.api.models.rentity.REntity(**kwargs)[source]

Represents Real Entities in the database.

Real entities are the result of entity resolution. They aggregate the information of several entities in the database that are believed to represent the same real-world entity.

The representation supports reversing the entity resolution process. A mapping between the real entity and the entities that compose is maintained in the links table.

We use the term “REntity” to avoid confusion with the term “entity”, and often use to unlinked entities as “occurrences”.

Note that it is possible for an occurrence to be linked to more than one real entity. This can happen when the different users have different opinions about the identity of the entities.

Fields:: id: id of the real entity user: user that identified this real entity description: description of the real entity status: status of the real entity obs: observations about the real entity links: list of links to the entities that compose the real entity

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

classmethod already_real(occurrence: str, user='user', session=None)[source]: Check if an occurrence is already linked to a real entity for a given user

attach_occurrence(occ_id: str, user='user', status=LinkStatus.MANUAL, rule=None, aregister=None) → REntity[source]

Attach an occurrence to a real entity

Parameters:

occ_id – id of the occurrence
user – user that linked the occurrence
status – status of the link
rule – rule used to link the occurrence
aregister – id of the source of the link (normally an identifications source)

property contains

classmethod delete(rentity_id: str, silent=True, session=None)[source]

Delete a real entity from the database

If sucessfull returns the id of the deleted real entity if the rentity does not exist and silent=True returns None otherwise raises an exception

classmethod generate_id(length=6, session=None)[source]: Generate a random n digit id for a real entity

classmethod get(rentity_id: str, session=None)[source]: Get a real entity from the database

get_description()[source]: Get the description of the real entity

get_obs()[source]: Get the observations about the real entity

get_occurrences()[source]: Get the occurrences of the real entity

classmethod get_real_entity(occurrence: str, user='user', session=None)[source]: Get the real entity of an occurrence TODO: this should be an instance method of Entity

classmethod get_rentity_brief(rentity_id: str, session=None, db=None)[source]: Fetch a real entity from the database

classmethod get_rentity_full(rentity_id: str, session=None, db=None)[source]

Fetch a real entity from the database with all the attributes, relationships and contained objects of the occurrences of the real entity.

I think this corresponds to an eager fetch in SQLAlchemy

get_status()[source]: Get the status of the real entity

get_user()[source]: Get the user that identified this real entity

groupname

name of the kleio group that produced this entity

Type:: str

id: Mapped[str]

unique identifier for the entity

Type:: str

inside: Mapped[str | None]

id of the entity inside which this occurred.

Type:: str

is_inbound_relation(relation)[source]: Check if the relation is inbound to this real entity.

classmethod make_real(id1: str, user='user', status=LinkStatus.MANUAL, real_id=None, real_id_prefix=None, description=None, rule=None, source=None, session=None) → REntity[source]

Make an entity a real entity

This creates a real entity from a single occurence

Parameters:

id1 – id of the occurrence
user – user that linked the occurrence
status – status of the link
real_id – id of the real entity
real_id_prefix – prefix of the generated real entity id
description – description of the real entity
rule – rule used to link the occurrence
source – id of the source of the link (normally an identifications source)
session – database session

Returns:

The real entity created

classmethod recover_rentity(occ: str, user='user', session=None)[source]

Recover a real entity from an occurrence

This method is used to recover a real entity an occurrence that were previously linked to the real entity. It is used to avoid the creation of a new real entity when occurrences were temporarlily unlinked and then linked again, which is a common operation when reimporting data from a source.

This method uses the blinks table, which are backed up links saved before a source is reimported.

If the occurence was previously linked to a real entity and currently the real entity has no links to entities then the id of the real entity is returned

Parameters:

id1 – id of the first occurrence
user – user that linked the occurrences
session – database session

Returns:

The real entity id if the occurrence was linked to the real entity in the past and the real entity is not linked to any other entity

property rels_in: Relations having this real entity as destination

property rels_out: Relations having this real entity as source

classmethod same_as(id1: str, id2: str, user='user', status=None, real_id=None, real_id_prefix=None, description=None, rule=None, source=None, session=None) → REntity[source]

Returns a real entity id linking id1 and id2.

Parameters:

id1 – id of the first entity
id2 – id of the second entity
user – user that linked the entities
status – status of the link (default M)
real_id – id of the real entity (if none a random id is generated)
real_id_prefix – prefix of the generated real entity id
description – description of the real entity (defaults to description or name of first entity)
rule – rule used to link the entities
source – id of the source with the link (same_as or x_same_as)
session – database session

Notes

if id1 and id2 are both unlinked occurrences then a new real entity is created associated with user. If real_id is not given a random id is generated.
if id1 is a real entity and id2 is not, then id2 is added to id1 and id1 returned
if id2 is a real entity and id1 is not, swap and do as above.
if both id1 and id2 are real entities, merge them and keep the id of the real entity with higher status V->M->S->A->U
in all the cases linking two id2 of different types or inheriting from a common type not equal to Entity is an error.

set_description(description)[source]: Set the description of the real entity

set_obs(obs)[source]: Set the observations about the real entity

set_status(status)[source]: Set the status of the real entity

set_user(user)[source]: Set the user that identified this real entity

the_level

the nesting level of this entity in the source

Type:: int

the_line

line in which the entity occurred in the source

Type:: int

the_order

sequential order of this entity in the source

Type:: int

updated

when this entity was updated in the database

Type:: datetime

exception timelink.api.models.rentity.RealEntityIdChangeError[source]: Error raised when an attempt is made to change the id of a real entity

exception timelink.api.models.rentity.RealEntityIdExists[source]: Error raised when an attempt is made to create a real entity with an existing id

exception timelink.api.models.rentity.RealEntityMissingError[source]: Error raised when a Real Entity required for an opperation is missing

timelink.api.models.source module

(c) Joaquim Carvalho 2023. MIT License, no warranties.

class timelink.api.models.source.Source(**kwargs)[source]

Represent an historical source

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

contains: Mapped[List['Entity']]

list of Entity objects contained in this entity

Type:: list(Entity)

groupname

name of the kleio group that produced this entity

Type:: str

id: Mapped[str]

unique identifier for the entity

Type:: str

inside: Mapped[str | None]

id of the entity inside which this occurred.

Type:: str

the_level

the nesting level of this entity in the source

Type:: int

the_line

line in which the entity occurred in the source

Type:: int

the_order

sequential order of this entity in the source

Type:: int

to_kleio(ident='', ident_inc=' ', show_contained=True, width=80, **kwargs) → str[source]

conver the entity to a kleio string

Parameters:

self_string – the string to be used to represent the entity
show_contained – if True, contained entities are also converted to kleio
ident – initial identation
ident_inc – identation increment
show_inrels – if False, inbound relations are not shown, default is True
kwargs – additional arguments to be passed to contained entities

updated

when this entity was updated in the database

Type:: datetime

timelink.api.models.system module

Models for system tables

Tables defined here:

syspar: system parameters

syslog: system log

class timelink.api.models.system.KleioImportedFile(**kwargs)[source]

Represents a Kleio file imported in the database

Fields:: path: path of the file name: name of the file structure: structure name translator: translator name translation_date: date of translation nerrors: number of errors nwarnings: number of warnings error_rpt: error report warning_rpt: warning report

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

path: Mapped[str]

str

Type:: name

class timelink.api.models.system.KleioImportedFileSchema(*, path: str, name: str, structure: str, translator: str, translation_date: datetime, nerrors: int, nwarnings: int, error_rpt: str | None, warning_rpt: str | None, imported: datetime | None, imported_string: str | None)[source]

Represents a Kleio file imported in the database

Objects of this class contain the same fields as the KleioImportedFile class.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

error_rpt: str | None

str warning report

Type:: warning_rpt

imported: datetime | None

str date of import as string

Type:: imported_string

model_config: ClassVar[ConfigDict] = {'from_attributes': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

str structure used to translate the file

Type:: structure

nerrors: int

int number of warnings in the translation

Type:: nwarnings

nwarnings: int

str error report

Type:: error_rpt

path: str

str

Type:: name

structure: str

str name of the translator

Type:: translator

translation_date: datetime

int number of errors in the translation

Type:: nerrors

translator: str

datetime date of translation

Type:: translation_date

warning_rpt: str | None

datetime date of import

Type:: imported

class timelink.api.models.system.LogLevel(value)[source]

Log level

Fields:: debug: debug info: info warning: warning error: error critical: critical

class timelink.api.models.system.ParTypeSchema(value)[source]

Parameter type

Fields:: string: string integer: integer float: float date: date boolean: boolean list: list

class timelink.api.models.system.SysLog(**kwargs)[source]

System log table

Fields:: seq: sequence number time: time of log entry level: log level origin: origin of log entry message: log message

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class timelink.api.models.system.SysLogCreateSchema(*, level: LogLevel, origin: str, message: str)[source]

System log create in the Timelink app

Fields:: level: log level origin: origin of log entry message: log message

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {'from_attributes': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class timelink.api.models.system.SysLogSchema(*, seq: int, time: datetime, level: LogLevel, origin: str, message: str)[source]

System log in the Timelink app

Fields:: seq: sequence number time: time of log entry level: log level origin: origin of log entry message: log message

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {'from_attributes': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class timelink.api.models.system.SysPar(**kwargs)[source]

System parameters table

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class timelink.api.models.system.SysParSchema(*, pname: str, pvalue: str, ptype: ParTypeSchema, obs: str)[source]

System parameters in the Timelink app

Fields:: pname: parameter name pvalue: parameter value ptype: parameter type obs: parameter description

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config: ClassVar[ConfigDict] = {'from_attributes': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].