Citation#

class documenteer.citations.Citation(*, title, type=None, doi=None, authors=(), publisher=None, date=None, url=None, version=None, number=None)#

Bases: object

A bibliographic citation for a work, composable as plain text or BibTeX.

The fields are the DataCite mandatory metadata (creators, title, publisher, publication year, identifier) plus the landing-page URL, which is the metadata a Documenteer site can supply from its own configuration without asking a registration agency.

Parameters:

title (str)
type (CitationType | None, default: None)
doi (str | None, default: None)
authors (tuple[PersonAuthor | OrganizationAuthor, ...], default: ())
publisher (str | None, default: None)
date (PartialDate | None, default: None)
url (str | None, default: None)
version (str | None, default: None)
number (str | None, default: None)

Attributes Summary

`authors`	The work's authors, in the order they should be credited.
`bibtex_key`	The citation key that `to_bibtex` uses by default.
`date`	The publication date, at the precision its source stated.
`doi`	The work's DOI, normalized to its bare `10.NNNN/suffix` form.
`doi_url`	The DOI as a resolvable `https://doi.org` URL, or `None` when the work has no DOI.
`location`	its DOI as a resolvable URL, or its landing page when it has no DOI, or `None` when it has neither.
`number`	The work's number within its series, such as a technote's `SQR-000` handle.
`publisher`	The organization that published the work.
`title`	The title of the work.
`type`	The kind of work being cited.
`url`	The work's landing page, when it is not simply the DOI's target.
`version`	The release of the work being cited, such as a package's `12.3.0`.

Methods Summary

`to_bibtex`(*[, entry_type, key])	Compose the citation as a BibTeX entry.
`to_plain_text`()	Compose the citation as a plain-text bibliographic reference.
`to_plain_text_parts`()	Compose the citation as the two halves a linked rendering needs: the reference up to where the work is located, and that location itself.

Attributes Documentation

authors: tuple[PersonAuthor | OrganizationAuthor, ...] = ()#: The work’s authors, in the order they should be credited.

bibtex_key#

The citation key that to_bibtex uses by default.

The key is the first author, the publication year, and the first word of the title, each reduced to lowercase ASCII alphanumerics — for example sick2026citations. It is derived only from the citation’s own fields, so the same metadata always yields the same key and a bibliography that is regenerated on every build stays stable.

A leading English article is skipped when the title word is chosen, so The Vera C. Rubin Observatory Data Butler is keyed jenness2022vera rather than by the the it would otherwise share with every other title that opens with one.

Citation.version is deliberately left out of it. The key is what a reader’s \cite commands name, and folding the version in would rename every one of them each time the cited software was released.

date: PartialDate | None = None#

The publication date, at the precision its source stated.

Only its year appears in a rendered citation; the precision matters to the machine-readable metadata, which publishes the date as schema.org datePublished (see PartialDate).

doi: str | None = None#

The work’s DOI, normalized to its bare 10.NNNN/suffix form.

A DOI given in any spelling normalize_doi accepts is normalized when the citation is constructed; a value that is not a DOI raises ValueError there rather than reaching a rendered page.

doi_url#: The DOI as a resolvable https://doi.org URL, or None when the work has no DOI.

location#

its DOI as a resolvable URL, or its landing page when it has no DOI, or None when it has neither.

This is the identifier to_plain_text writes at the end of the citation, and the URL a rendered citation hyperlinks.

Type:: Where the work is found

number: str | None = None#

The work’s number within its series, such as a technote’s SQR-000 handle.

This is a BibtexEntryType.techreport field; every other entry type has nowhere to put it and omits it.

publisher: str | None = None#: The organization that published the work.

title: str = <dataclasses._MISSING_TYPE object>#: The title of the work.

type: CitationType | None = None#

The kind of work being cited.

A citation that states its type is published under the matching schema.org type, which is what makes a dataset discoverable as one. The type is unset when nothing says what the work is, and a citation composes to the same plain text and BibTeX either way.

url: str | None = None#: The work’s landing page, when it is not simply the DOI’s target.

version: str | None = None#

The release of the work being cited, such as a package’s 12.3.0.

FORCE11’s software citation principles list the version among the elements a software citation has to carry, because software is the kind of work whose behavior changes between releases: a citation that names only the project says which code was run no more precisely than naming the language would. A dataset has the same need whenever it is released more than once, so the field is not restricted to software — only the entry types that have somewhere to put it are (see to_bibtex).

It is deliberately absent from bibtex_key, so that a reader’s .bib file keeps working across releases of the site that composed it.

Methods Documentation

to_bibtex(*, entry_type=None, key=None)#

Compose the citation as a BibTeX entry.

Parameters:

entry_type (BibtexEntryType | None, default: None) – The BibTeX entry type, overriding the one the work’s own type implies. Defaults to None, which composes the entry as the type BIBTEX_ENTRY_TYPES maps Citation.type onto — @dataset for a dataset, @techreport for a report, and @misc for a work whose type is unstated.
key (str | None, default: None) – The entry’s citation key. Defaults to bibtex_key.

Returns:

The BibTeX entry, without a trailing newline. Fields appear in a fixed order, so regenerating the entry from unchanged metadata never churns a file that stores it.

Return type:

str

Notes

A date stated to the month or finer writes a month field after the year, as the English month name — the form BibTeX, biblatex, and lsst.bib all read. A day never becomes a field of its own, because BibTeX has none to put it in.

The publisher is the institution field of a BibtexEntryType.techreport entry and the publisher field of every other entry type; Citation.number is a techreport field alone, and any other entry omits it. Citation.version is written only for the entry types biblatex defines a version field on — @software and @dataset, see BIBTEX_VERSIONED_TYPES — and is omitted for every other, which has nowhere to put it. No other field varies with the entry type, because the model carries no field — no journal or volume — that only one type has a home for. The url field is the work’s own landing page when it has one, falling back to the DOI URL; doi and url are written verbatim rather than LaTeX-escaped, matching what DataCite, Crossref, and Zenodo export, since a style’s \url macro takes its argument literally.

An optional field whose value reduces to nothing once collapsed and escaped is omitted, rather than written as an empty pair of braces. The required title field is always written, so that a blank title shows up as an entry to fix rather than as a silently missing field.

to_plain_text()#

Compose the citation as a plain-text bibliographic reference.

Returns:: The citation in DataCite’s recommended display format: Creators (PublicationYear). Title. Publisher. Identifier, with a version — when the work states one — qualifying the title. Creators are separated by semicolons because a person’s name itself contains a comma, and the identifier is the DOI URL when the work has a DOI and its landing page otherwise. A segment with no value — including one that is only whitespace — is dropped rather than left as empty punctuation.
Return type:: str

Notes

A dataset citation credited to an organization composes as:

Vera C. Rubin Observatory (2025). Data Preview 2.
Vera C. Rubin Observatory. https://doi.org/10.71929/rubin/2570308

A surface that hyperlinks the identifier reads the same reference pre-split from to_plain_text_parts instead, rather than slicing this text.

to_plain_text_parts()#

Compose the citation as the two halves a linked rendering needs: the reference up to where the work is located, and that location itself.

Return type:

tuple[str, str | None]

Returns:

lead (str) – The citation up to its trailing location, ending in the single space that separates the two. It is the whole reference when the work has no location, and empty when the citation is nothing but one.
location (str or None) – Where the work is found — see location — or None when the citation has neither a DOI nor a landing page to name.

Notes

Joining the halves reproduces to_plain_text exactly: that method is written in terms of this one, so the invariant holds structurally rather than by two implementations agreeing.

The split exists because a displayed citation ends in a hyperlink to the work, and a surface that writes the lead as text and the location as a link must not compose either half itself. Every such surface reads the split from here — the guide’s footer and citation card through GuideCitation.to_html_context, and the technote’s article footer through its TechnoteCitation.plain_text_lead — which is what keeps them from disagreeing about where the text ends and the link begins.