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: pydantic.main.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[relaton.models.strings.GenericStringValue]

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

Tends to be used, for example, when this bibliographic item is used as Relation.bibitem.

docid: Optional[Union[List[relaton.models.bibdata.DocID], relaton.models.bibdata.DocID]]

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[relaton.models.dates.Date], relaton.models.dates.Date]]

link: Optional[Union[List[relaton.models.links.Link], relaton.models.links.Link]]

relation: Optional[List[relaton.models.bibdata.Relation]]

version: Optional[relaton.models.bibdata.VersionInfo]

title: Optional[Union[List[relaton.models.strings.Title], relaton.models.strings.Title]]

edition: Optional[relaton.models.bibdata.Edition]

abstract: Optional[Union[List[relaton.models.strings.GenericStringValue], relaton.models.strings.GenericStringValue]]

fetched: Optional[datetime.date]

revdate: Optional[Union[str, datetime.date, List[Union[str, datetime.date]]]]

biblionote: Optional[Union[List[relaton.models.bibdata.BiblioNote], relaton.models.bibdata.BiblioNote]]

contributor: Optional[List[relaton.models.bibdata.Contributor]]

place: Optional[Union[str, List[str]]]

series: Optional[List[relaton.models.bibdata.Series]]

keyword: Optional[Union[str, List[str]]]

copyright: Optional[Union[List[relaton.models.copyrights.Copyright], relaton.models.copyrights.Copyright]]

classmethod validate_revdate(v, **kwargs)

Validates revdate, allowing it to be unspecific.

class relaton.models.bibdata.Relation

Bases: pydantic.main.BaseModel

Indicates a relationship from given bibliographic item to another.

type: str

Describes the relationship.

bibitem: relaton.models.bibdata.BibliographicItem

Relationship target.

description: Optional[relaton.models.strings.GenericStringValue]

Describes the relationship in more detail.

class relaton.models.bibdata.Contributor

Bases: object

Anyone who helped create or publish the document.

role: Union[List[str], str]

person: Optional[relaton.models.people.Person] = None

organization: Optional[relaton.models.orgs.Organization] = None

class relaton.models.bibdata.Series

Bases: pydantic.main.BaseModel

A series that given document belongs to.

Note: formattedref is exclusive with other properties.

formattedref: Optional[Union[relaton.models.strings.GenericStringValue, str]]

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

title: Optional[Union[List[relaton.models.strings.GenericStringValue], relaton.models.strings.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.CopyrightOwner

Bases: object

Who or which organization holds the copyright.

name: Union[List[str], str]

url: Optional[str] = None

abbreviation: Optional[str] = None

class relaton.models.copyrights.Copyright

Bases: dict

from: int

owner: List[relaton.models.copyrights.CopyrightOwner]

People

class relaton.models.people.Person

Bases: object

Describes a person.

name: relaton.models.people.PersonName

affiliation: Optional[Union[List[relaton.models.people.PersonAffiliation], relaton.models.people.PersonAffiliation]] = None

class relaton.models.people.PersonName

Bases: object

Describes a person’s name.

completename: Optional[relaton.models.strings.GenericStringValue] = None

Full name.

surname: Optional[relaton.models.strings.GenericStringValue] = None

Also known as last name or family name.

initial: Optional[List[relaton.models.strings.GenericStringValue]] = None

Initials, if any.

forename: Optional[Union[List[relaton.models.strings.GenericStringValue], relaton.models.strings.GenericStringValue]] = None

Also known as givne name or first name.

class relaton.models.people.PersonAffiliation

Bases: object

Affiliation of a person.

organization: relaton.models.orgs.Organization

Organizations

class relaton.models.orgs.Organization

Bases: object

Describes an organization.

name: Union[List[str], str]

contact: Optional[List[relaton.models.contacts.Contact]] = None

url: Optional[str] = None

abbreviation: Optional[str] = None

Contacts

class relaton.models.contacts.Contact

Bases: object

Contact information for a person or organization.

street: Optional[List[str]] = None

city: Optional[str] = None

country: Optional[str] = None

state: Optional[str] = None

postcode: 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, datetime.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[datetime.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[datetime.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: relaton.models.strings.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: relaton.models.strings.GenericStringValue

Typed title.

type: Optional[str] = None