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[source]¶
Bases:
object
Typed document identifier.
May be given by publisher or issued by some third-party system.
- 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.
- 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.
- abstract: Optional[Union[GenericStringValue, List[GenericStringValue]]]¶
- biblionote: Optional[Union[List[BiblioNote], BiblioNote]]¶
- contributor: Optional[List[Contributor]]¶
- class relaton.models.bibdata.Relation[source]¶
Bases:
BaseModel
Indicates a relationship from given bibliographic item to another.
- 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.
Important
This is equivalent of
ContributionInfo
model in LutaML;Contributor
itself is defined as a union ofPerson
orOrganization
in LutaML.- 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]]]¶
Copyrights¶
People¶
- 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.
- 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.
- 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)
- 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¶
Organizations¶
- class relaton.models.orgs.Organization[source]¶
Bases:
object
Describes an organization.
- name: Union[List[GenericStringValue], GenericStringValue]¶
- contact: Optional[List[ContactMethod]] = None¶
- abbreviation: Optional[GenericStringValue] = None¶
Contacts¶
Links¶
Dates¶
- class relaton.models.dates.Date[source]¶
Bases:
object
A typed date.
- 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 ofValueError
.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 theEXTRA_DATE_FORMATS
, and returns back a string fromstrftime()
.
- 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 isdatetime.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.GenericStringValue[source]¶
Bases:
FormattedContent
Roughly corresponds to a combination of Relaton’s localized & formatted string.