models: Bibliographic data classes

Some of Relaton’s bibliographic item specifications implemented as typed dictionaries, dataclasses and Pydantic models.

They are mixed for a few reasons:


Dumping a model as a dictionary using Pydantic may not dump members that are dataclass instances. To obtain a full dictionary, use common.pydantic.unpack_dataclasses() utility.

Bibliographic data

Some of Relaton models implemented as Pydantic models.

class relaton.models.bibdata.DocID[source]

Bases: object

Typed document identifier.

May be given by publisher or issued by some third-party system.

id: str
type: str

document identifier type. Determines the format of the id field.

primary: Optional[bool] = None

If True, this identifier is considered a primary document identifier.

scope: Optional[str] = None


Clarify the meaning of scope.

class relaton.models.bibdata.BibliographicItem[source]

Bases: BaseModel

Relaton’s primary entity, bibliographic item.

Note: formattedref is exclusive with other properties. In some contexts (such as relations) bibliographic item can be specified as a “pointer”, which callers can resolve to full metadata. formattedref is that pointer. It is expected to have a shape of a primary docid.

formattedref: Optional[GenericStringValue]

A human-readable string representing this bibliographic item in a not strongly specified way.

docid: List[DocID]

A list of identifiers. The only required property.

docnumber: Optional[str]
language: Optional[Union[str, List[str]]]
type: Optional[str]
doctype: Optional[str]
script: Optional[Union[str, List[str]]]
date: Optional[Union[List[Date], Date]]
relation: Optional[List[Relation]]
version: Optional[List[VersionInfo]]
title: Optional[Union[List[Title], Title]]
edition: Optional[Edition]
abstract: Optional[Union[GenericStringValue, List[GenericStringValue]]]
fetched: Optional[date]
revdate: Optional[Union[str, date, List[Union[str, date]]]]
biblionote: Optional[Union[List[BiblioNote], BiblioNote]]
contributor: Optional[List[Contributor]]
place: Optional[Union[str, List[str]]]
series: Optional[List[Series]]
keyword: Optional[Union[str, List[str]]]
copyright: Optional[Union[List[Copyright], Copyright]]
extent: Optional[Union[LocalityStack, Locality]]
classmethod validate_revdate(v, **kwargs)[source]

Validates revdate, allowing it to be unspecific.

class relaton.models.bibdata.Relation[source]

Bases: BaseModel

Indicates a relationship from given bibliographic item to another.

type: str

Describes the relationship.

bibitem: BibliographicItem

Relationship target.

description: Optional[GenericStringValue]

Describes the relationship in more detail.

class relaton.models.bibdata.Contributor[source]

Bases: object

Anyone who helped create or publish the document.


This is equivalent of ContributionInfo model in LutaML; Contributor itself is defined as a union of Person or Organization in LutaML.

role: List[Role]
person: Optional[Person] = None
organization: Optional[Organization] = None
class relaton.models.bibdata.Series[source]

Bases: BaseModel

A series that given document belongs to.

Note: formattedref is exclusive with other properties.

formattedref: Optional[Union[GenericStringValue, str]]

References a bibliographic item via a primary ID. Exclusive with other properties.

title: Optional[Union[GenericStringValue, List[GenericStringValue]]]
abbrev: Optional[str]
place: Optional[str]
number: Optional[str]
organization: Optional[str]
run: Optional[str]
partnumber: Optional[str]
type: Optional[str]
class relaton.models.bibdata.BiblioNote[source]

Bases: object

Bibliographic note.

content: str

Note content.

type: Optional[str] = None

The class of the note associated with the bibliographic item. May be used to differentiate rendering of notes in bibliographies.


class relaton.models.copyrights.Copyright

Bases: dict

from: int
owner: List[Union[Organization, Person]]


class relaton.models.people.Forename[source]

Bases: GenericStringValue

A forename of a person

initial: Optional[str] = None

An individual initial of the person, corresponding to the given forename. Does not include final punctuation, but can include hyphens. Can be used instead of forenames, if formatted_initials are not provided (in which case each initial will be punctuated following local practice).

class relaton.models.people.Person[source]

Bases: object

Describes a person.

name: FullName
affiliation: Optional[Union[List[PersonAffiliation], PersonAffiliation]] = None
contact: Optional[List[ContactMethod]] = None

Contact information.

class relaton.models.people.FullName[source]

Bases: object

Describes a person’s name.

prefix: Optional[GenericStringValue] = None

Name prefix.

given: Optional[GivenName] = None
surname: Optional[GenericStringValue] = None

Also known as last name or family name.

completename: Optional[GenericStringValue] = None

Full name. Expected to be mutually exclusive with other properties.

addition: Optional[GenericStringValue] = None

Addition to the name.

class relaton.models.people.GivenName[source]

Bases: object

GivenName(forename: Union[List[relaton.models.people.Forename], relaton.models.people.Forename, NoneType] = None, formatted_initials: Optional[relaton.models.strings.GenericStringValue] = None)

forename: Optional[Union[List[Forename], Forename]] = None

Also known as given name or first name.

formatted_initials: Optional[GenericStringValue] = None

The initials of the person, as a formatted string, including punctuation, dropping punctuation as desired, and including hyphens where necessary. For example, the initial set for Jean-Paul would be J, P; the formatted initials would be “J.-P.” or “J-P.”. Can be used instead of forenames.

class relaton.models.people.PersonAffiliation[source]

Bases: object

Affiliation of a person.

organization: Organization


class relaton.models.orgs.Organization[source]

Bases: object

Describes an organization.

name: Union[List[GenericStringValue], GenericStringValue]
contact: Optional[List[ContactMethod]] = None
url: Optional[str] = None
abbreviation: Optional[GenericStringValue] = None


class relaton.models.contacts.Address[source]

Bases: object

Address information for a contact.

street: Optional[List[str]] = None
city: Optional[str] = None
country: Optional[str] = None
state: Optional[str] = None
postcode: Optional[str] = None
class relaton.models.contacts.ContactMethod[source]

Bases: object

Address information for a person or organization.

address: Optional[Address] = None
phone: Optional[Phone] = None
email: Optional[str] = None
uri: Optional[str] = None
class relaton.models.contacts.Phone[source]

Bases: object

Phone(content: str, type: Optional[str] = None)

content: str
type: Optional[str] = None


class relaton.models.dates.Date[source]

Bases: object

A typed date.

value: Optional[Union[str, date]]

Date value.

Can either be a fully-formed date, or a low-specificity date like YYYY or YYYY-MM.

type: str
classmethod validate_value(v, **kwargs)[source]

Validates value, allowing it to be unspecific.

relaton.models.dates.parse_relaxed_date(v: str) Union[None, Tuple[date, str, str]][source]

Parses a relaxed date and returns a 3-tuple containing date, formatted string, and specificity (“month” or “year”).

relaton.models.dates.parse_date_pydantic(v) Optional[date][source]

Parses given date or string using Pydantic’s parse_date(), which must return a date or raise a subclass of ValueError.

It’s considered failed if the obtained date is the epoch (which is one of Pydantic parser’s failure modes).

relaton.models.dates.validate_relaxed_date(v, optional=False)[source]

To be used as validator on bibliographic item’s pydantic models wherever very approximate dates (no day) are possible.

Tries pydantic’s own validation, which is considered failed if returned date is the epoch.

Then tries strptime() on each of the EXTRA_DATE_FORMATS, and returns back a string from strftime().

relaton.models.dates.EXTRA_DATE_FORMATS: List[Tuple[str, str, str]] = [('%Y-%m', '%B %Y', 'month'), ('%B %Y', '%B %Y', 'month'), ('%Y', '%Y', 'year')]

A list of approximate formats as 3-tuples, first string of each is datetime.datetime.strptime() to parse, second is datetime.datetime.strftime() to format, third is specificity (“month” or “year”).

Formats should be in order of decreasing specificity.

Used by parse_relaxed_date().


class relaton.models.strings.FormattedContent[source]

Bases: object

Relaton’s formatted string.

content: str
format: Optional[str] = None
class relaton.models.strings.GenericStringValue[source]

Bases: FormattedContent

Roughly corresponds to a combination of Relaton’s localized & formatted string.

script: Optional[Union[str, List[str]]] = None
language: Optional[Union[str, List[str]]] = None
class relaton.models.strings.Title[source]

Bases: GenericStringValue

Typed title.

type: Optional[str] = None