Citation

class documenteer.citations.Citation(*, title, doi=None, authors=(), publisher=None, date=None, url=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)

• doi (str | None, default: None)

• authors (tuple[PersonAuthor | OrganizationAuthor, ...], default: ())

• publisher (str | None, default: None)

• date (date | None, default: None)

• url (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.
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.
url	The work's landing page, when it is not simply the DOI's target.

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.

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.

date: date | None = None

The publication date. Only its year appears in a citation.

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; a BibtexEntryType.misc entry 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.

url: str | None = None

The work’s landing page, when it is not simply the DOI’s target.

Methods Documentation

to_bibtex(*, entry_type=BibtexEntryType.misc, key=None)

Compose the citation as a BibTeX entry.

Parameters:

• entry_type (BibtexEntryType, default: <BibtexEntryType.misc: 'misc'>) – The BibTeX entry type. Use BibtexEntryType.techreport for a technote and BibtexEntryType.misc, the default, for a dataset or a website.

• 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

The publisher is the publisher field of a BibtexEntryType.misc entry and the institution field of a BibtexEntryType.techreport one; Citation.number is a techreport field and a misc entry omits it. 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. 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