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:

• Since we don’t want to always validate every item we instantiate, we can’t use Pydantic’s models for simpler types, so we use plain dataclasses.

• Where we encounter reserved words, we use TypedDict() instantiations. They have a big drawback (no defaults on optionals), so their use is as limited as possible.

• Dataclass instantiation may cause a TypeError when given unexpected data, which is especially bad at root model level. That, and generally Pydantic’s support for dataclasses is poor—so we use regular Pydantic models at higher levels.

Important

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

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

Todo

Clarify the meaning of scope.

class relaton.models.bibdata.BibliographicItem

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

link: Optional[Union[List[Link], Link]]

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)

Validates revdate, allowing it to be unspecific.

class relaton.models.bibdata.Relation

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

Bases: object

Anyone who helped create or publish the document.

Important

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

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

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.

Copyrights

class relaton.models.copyrights.Copyright

Bases: dict

from: int

owner: List[Union[Organization, Person]]

People

class relaton.models.people.Forename

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

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

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

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

Bases: object

Affiliation of a person.

organization: Organization

Organizations

class relaton.models.orgs.Organization

Bases: object

Describes an organization.

name: Union[List[GenericStringValue], GenericStringValue]

contact: Optional[List[ContactMethod]] = None

url: Optional[str] = None

abbreviation: Optional[GenericStringValue] = None

Contacts

class relaton.models.contacts.Address

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

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

Bases: object

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

content: str

type: Optional[str] = None

Links

class relaton.models.links.Link

Bases: object

A typed link.

content: str

Typically, an URL.

type: Optional[str] = None

Dates

class relaton.models.dates.Date

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)

Validates value, allowing it to be unspecific.

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

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]

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)

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

Strings

class relaton.models.strings.FormattedContent

Bases: object

Relaton’s formatted string.

content: str

format: Optional[str] = None

class relaton.models.strings.GenericStringValue

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

Bases: GenericStringValue

Typed title.

type: Optional[str] = None