sphinxcontrib_bibtex_urn.styles¶

Pybtex style mixin and pre-built styles with URN field support.

Attributes¶

`URN_RESOLVER_URL`
`NBN_RESOLVERS`
`logger`

Classes¶

`UrnStyleMixin`	Mixin that adds a `urn` BibTeX field to any pybtex formatting style.
`PlainUrn`	`plain` style with URN support.
`UnsrtUrn`	`unsrt` style with URN support.
`AlphaUrn`	`alpha` style with URN support.
`UnsrtAlphaUrn`	`unsrtalpha` style with URN support.

Functions¶

resolve_urn(→ tuple[str, str] | None)

Return (url, display_text) for a URN value.

Module Contents¶

sphinxcontrib_bibtex_urn.styles.URN_RESOLVER_URL: str = 'https://nbn-resolving.org/'¶

sphinxcontrib_bibtex_urn.styles.NBN_RESOLVERS: dict[str, str]¶

sphinxcontrib_bibtex_urn.styles.logger¶

sphinxcontrib_bibtex_urn.styles.resolve_urn(raw: str) → tuple[str, str] | None¶

Return (url, display_text) for a URN value.

Handles both bare identifiers (e.g., URN:NBN:…) and full resolver URLs.

Supports country-specific NBN resolvers for: AT, CZ, FI, HR, HU, IT, NL, NO, SE, SI. Other NBNs (URN:NBN:…) resolve via https://nbn-resolving.org/.

Args:: raw: The raw URN value, either as a bare identifier or a full URL.
Returns:: A tuple of (url, display_text), or None if the URN type is not supported.

class sphinxcontrib_bibtex_urn.styles.UrnStyleMixin¶

Mixin that adds a urn BibTeX field to any pybtex formatting style.

When an entry contains a urn field the mixin appends a hyperlinked URN identifier to the formatted reference. Supported URN namespaces include:

URN:NBN:fi:... - Finnish NBNs (resolves via https://urn.fi/).
URN:NBN:<CC>:... - Country-specific NBNs (e.g. AT, CZ, HR, HU, IT, NL, NO, SE, SI).
URN:NBN:... - Other NBNs (resolves via https://nbn-resolving.org/).

Note: only URN:NBN identifiers are officially supported. Other URN types will log a warning.

The Sphinx extension (sphinxcontrib_bibtex_urn) dynamically wraps your configured style at build time, so it works with any pybtex formatting style, including third-party ones.

If the entry also carries a url field whose value points at the same resolver URL the redundant URL is suppressed automatically. The comparison is case-insensitive per RFC 8141.

format_entry(label: str, entry: pybtex.database.Entry) → pybtex.style.FormattedEntry¶

Format an entry, appending a URN hyperlink when the field exists.

Args:: label: The entry label. entry: The BibTeX entry to format.
Returns:: The formatted entry with URN support.

class sphinxcontrib_bibtex_urn.styles.PlainUrn(label_style=None, name_style=None, sorting_style=None, abbreviate_names=False, min_crossrefs=2, **kwargs)¶

Bases: UrnStyleMixin, pybtex.style.formatting.plain.Style

plain style with URN support.

class sphinxcontrib_bibtex_urn.styles.UnsrtUrn(label_style=None, name_style=None, sorting_style=None, abbreviate_names=False, min_crossrefs=2, **kwargs)¶

Bases: UrnStyleMixin, pybtex.style.formatting.unsrt.Style

unsrt style with URN support.

class sphinxcontrib_bibtex_urn.styles.AlphaUrn(label_style=None, name_style=None, sorting_style=None, abbreviate_names=False, min_crossrefs=2, **kwargs)¶

Bases: UrnStyleMixin, pybtex.style.formatting.alpha.Style

alpha style with URN support.

class sphinxcontrib_bibtex_urn.styles.UnsrtAlphaUrn(label_style=None, name_style=None, sorting_style=None, abbreviate_names=False, min_crossrefs=2, **kwargs)¶

Bases: UrnStyleMixin, pybtex.style.formatting.unsrtalpha.Style

unsrtalpha style with URN support.