timelink.api.models package

Module for SQLAlchemy and Pydantic models of the Timelink Database.

TODO: after testing for MHK schema:

1. Implemente TemporalEntity with flexible dates

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

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

indexed

when this entity was added to the full text index

Type:

datetime

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

updated

when this entity was updated in the database

Type:

datetime

timelink.api.models.attribute module

class timelink.api.models.attribute.Attribute(**kwargs)

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

indexed

when this entity was added to the full text index

Type:

datetime

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

timelink.api.models.base_class module

class timelink.api.models.base_class.Base(**kwargs: Any)

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.

metadata: ClassVar[MetaData] = MetaData()

Refers to the _schema.MetaData collection that will be used for new _schema.Table objects.

See also

orm_declarative_metadata

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

timelink.api.models.entity module

class timelink.api.models.entity.Entity(**kwargs)

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)

TODO: specialize in 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.

contains: Mapped[List[Entity]]

list of Entity objects contained in this entity

Type:

list(Entity)

classmethod get_entity(id: str, session=None)

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

classmethod get_orm_entities_classes()

Currently defined ORM classes that extend Entity

(including Entity itself)

Returns:

List of ORM classes

Return type:

list

classmethod get_orm_for_pom_class("act")

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

classmethod get_orm_for_table("acts")

will return the ORM class handling the “acts” table

classmethod get_som_mapper_ids()

Ids of SomPomMapper references by orm classes

Returns:

List of strings

Return type:

List[str]

classmethod get_som_mapper_to_orm_as_dict()

Return a dict with pom_class id as key and ORM class as value

classmethod get_subclasses()

Get the subclasses of Entity

classmethod get_tables_to_orm_as_dict()

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

indexed

when this entity was added to the full text index

Type:

datetime

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

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

class timelink.api.models.object.Object(**kwargs)

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

indexed

when this entity was added to the full text index

Type:

datetime

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)

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

indexed

when this entity was added to the full text index

Type:

datetime

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.get_person(id: str | None = None, db=None, sql_echo: bool = False) → Person

Fetch a person from the database

timelink.api.models.person.pperson(id: str)

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)

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)

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

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:

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

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

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

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

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

contains: Mapped[List['Entity']]

list of Entity objects contained in this entity

Type:

list(Entity)

element_class_to_column(eclass: str) → str

Return the column name corresponding to a group element class :param eclass: the class of an element (included in the export file :return: the name of the column corresponding to this element in the mapped table.

classmethod ensure_all_mappings(session)

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)

Ensure that a table exists to support this SOM Mapping and an ORM class is created to represent data of objects from this mapping.

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_pom_class(pom_class_id: String, session)

Return the pom_class object for a given pom_class_id.

See also Entity.get_orm_for_pom_class

Parameters:

pom_class_id – the id of a pom_class

classmethod get_pom_class_from_group(group: KGroup, session=None)

Returns the PomSomMapper for a given group

classmethod get_pom_class_ids(session)

Return all the pom_som_class ids as a list :return:

classmethod get_pom_classes(session) → List[PomSomMapper] | None

Get the pom_classes from database data.

Note that this method does not ensure that a ORM mapper is created for each class. Use pom_class.ensure_mapping() method to dynamically produce the ORM class

Returns:

A list of SomPomMappers object for each class in the db

groupname

name of the kleio group that produced this entity

Type:

str

id: Mapped[str]

unique identifier for the entity

Type:

str

indexed

when this entity was added to the full text index

Type:

datetime

inside: Mapped[str | None]

id of the entity inside which this occurred.

Type:

str

classmethod kgroup_to_entity(group: KGroup, session=None, with_pom=None) → Entity

Store a Kleio Group in the database.

Parameters:

• group – a Kleio Group

• with_pom – id of a PomSom class to handle storing this group

Returns:

An ORM object that can store this group in the database

To produce the ORM-POM representation of a group we need to find the PomSomMapper specific to that group, using the following:

• if with_pom is given with a PomSomMapper id we fetch that

• if the group was imported it should have _pom_class_id

• if neither then we search for a PomSom mapper with “groupname”

  equal to the name of the group.

classmethod store_KGroup(group: KGroup, session, with_pom=None)

Store a Kleio Group in the database

Will recursively store all the groups included in this group.

If the group is already in the database it will be deleted, as well as all included groups.

This is the main method that import Kleio transcripts into the database.

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

class timelink.api.models.relation.Relation(**kwargs)

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

indexed

when this entity was added to the full text index

Type:

datetime

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

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

class timelink.api.models.source.Source(**kwargs)

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

indexed

when this entity was added to the full text index

Type:

datetime

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

Models for system tables

Tables defined here:

• syspar: system parameters

• syslog: system log

class timelink.api.models.system.KleioImportedFile(**kwargs)

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, imported_string: str)

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

str date of import as string

Type:

imported_string

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'from_attributes': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'error_rpt': FieldInfo(annotation=Union[str, NoneType], required=True), 'imported': FieldInfo(annotation=datetime, required=True), 'imported_string': FieldInfo(annotation=str, required=True), 'name': FieldInfo(annotation=str, required=True), 'nerrors': FieldInfo(annotation=int, required=True), 'nwarnings': FieldInfo(annotation=int, required=True), 'path': FieldInfo(annotation=str, required=True), 'structure': FieldInfo(annotation=str, required=True), 'translation_date': FieldInfo(annotation=datetime, required=True), 'translator': FieldInfo(annotation=str, required=True), 'warning_rpt': FieldInfo(annotation=Union[str, NoneType], required=True)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

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)

Log level

Fields:

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

class timelink.api.models.system.ParTypeSchema(value)

Parameter type

Fields:

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

class timelink.api.models.system.SysLog(**kwargs)

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)

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_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'from_attributes': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'level': FieldInfo(annotation=LogLevel, required=True), 'message': FieldInfo(annotation=str, required=True), 'origin': FieldInfo(annotation=str, required=True)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

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

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_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'from_attributes': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'level': FieldInfo(annotation=LogLevel, required=True), 'message': FieldInfo(annotation=str, required=True), 'origin': FieldInfo(annotation=str, required=True), 'seq': FieldInfo(annotation=int, required=True), 'time': FieldInfo(annotation=datetime, required=True)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

class timelink.api.models.system.SysPar(**kwargs)

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)

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_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'from_attributes': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'obs': FieldInfo(annotation=str, required=True), 'pname': FieldInfo(annotation=str, required=True), 'ptype': FieldInfo(annotation=ParTypeSchema, required=True), 'pvalue': FieldInfo(annotation=str, required=True)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.