PartialDate#

class documenteer.citations.PartialDate(year, month=None, day=None)#

Bases: object

A publication date stated to the precision its source knows.

A bibliographic source rarely states a full day. A .bib file, a journal’s front matter, and a CITATION.cff reference commonly give a year alone, and DataCite’s own mandatory metadata is a publicationYear. Carrying such a date as a datetime.date would mean inventing a month and a day — and since Documenteer publishes the date as schema.org datePublished, the invented day would then be asserted as fact on every page of a site. ISO 8601 spells reduced precision as YYYY and YYYY-MM, schema.org Date is ISO 8601, and DataCite’s crosswalk maps publicationYear onto datePublished as a bare year; this type is that spelling.

A rendered citation shows only the year at every precision, so stating a date to the year costs a reader nothing: only the machine-readable metadata tells the three precisions apart.

Parameters:

year (int)
month (int | None, default: None)
day (int | None, default: None)

Attributes Summary

`day`	The day, when the source states one.
`month`	The month, when the source states one.
`year`	The publication year.

Methods Summary

`from_date`(value)	Express a full calendar date at day precision.
`isoformat`()	Express the date as ISO 8601 at its own precision.
`parse`(value)	Read a date written as `YYYY`, `YYYY-MM`, or `YYYY-MM-DD`.
`to_date`()	Express the date as a `datetime.date`, when it states a full one.

Attributes Documentation

day: int | None = None#: The day, when the source states one.

month: int | None = None#: The month, when the source states one.

year: int = <dataclasses._MISSING_TYPE object>#: The publication year.

Methods Documentation

classmethod from_date(value)#

Express a full calendar date at day precision.

Parameters:: value (date) – The date.
Returns:: The same date, stated to the day.
Return type:: PartialDate

isoformat()#

Express the date as ISO 8601 at its own precision.

Returns:: YYYY, YYYY-MM, or YYYY-MM-DD.
Return type:: str

classmethod parse(value)#

Read a date written as YYYY, YYYY-MM, or YYYY-MM-DD.

Parameters:: value (str) – The date, in one of the three ISO 8601 precisions.
Returns:: The date at the precision the text states.
Return type:: PartialDate
Raises:: ValueError – Raised if the text is not one of the three forms, or states a month or a day outside its range.

to_date()#

Express the date as a datetime.date, when it states a full one.

Returns:: The calendar date, or None when the date is stated only to the year or the month — in which case there is no day to return, and inventing one is what this type exists to avoid.
Return type:: date | None