serializers: Serializing bibliographic data

Stock serializers for Relaton bibliographic items.

bibxml: BibXML element tree

Serialization of relaton.models.bibdata.BibliographicItem into BibXML (xml2rfc) format roughly per RFC 7991, with bias towards existing xml2rfc documents where differs.

Primary API is serialize().

See also


relaton.serializers.bibxml.serialize(item: BibliographicItem, anchor: Optional[str] = None) Element[source]

Converts a BibliographicItem to XML, trying to follow RFC 7991.

Returned root element is either a <reference> or a <referencegroup>.


anchor (str) – resulting root element anchor property.


ValueError – if there are different issues with given item’s structure that make it unrenderable per RFC 7991.


relaton.serializers.bibxml.abstracts.create_abstract(abstracts: List[GenericStringValue]) Element[source]

Formats an <abstract> element.


relaton.serializers.bibxml.anchor.get_suitable_anchor(item: BibliographicItem) str[source]

From a BibliographicItem instance get best anchor value and return it as a string.


item – a bib_models.bibdata.BibliographicItem instance

Returns str

a string to be used as anchor

Return type



ValueError – unable to obtain an anchor, e.g. item has no docids

relaton.serializers.bibxml.anchor.to_valid_xsid(val: str) str[source]

Transforms a string into a valid xs:id value. Transformation is lossy and irreversible.

relaton.serializers.bibxml.anchor.XSID_REGEX = re.compile('^[a-zA-Z_][-.\\w]*$')

A regular expression matching a full valid xs:id values.

relaton.serializers.bibxml.anchor.XSID_ILLEGAL = re.compile('[^-.\\w]')

A regular expression matching xs:id characters that are invalid anywhere within an xs:id string.


relaton.serializers.bibxml.authors.create_author(contributor: Contributor) Element[source]

Returns True if given Relaton contributor instance represents an author in xml2rfc domain.

relaton.serializers.bibxml.authors.AUTHOR_ROLES = {'author', 'editor', 'publisher'}

Relaton contributor roles that represent xml2rfc authors.


relaton.serializers.bibxml.reference.create_reference(item: BibliographicItem) Element[source]
relaton.serializers.bibxml.reference.create_referencegroup(items: List[BibliographicItem]) Element[source]


relaton.serializers.bibxml.series.extract_doi_series(docid: DocID) Optional[Tuple[str, str]][source]
relaton.serializers.bibxml.series.extract_rfc_series(docid: DocID) Optional[Tuple[str, str]][source]
relaton.serializers.bibxml.series.extract_id_series(docid: DocID) Optional[Tuple[str, str]][source]
relaton.serializers.bibxml.series.extract_w3c_series(docid: DocID) Optional[Tuple[str, str]][source]
relaton.serializers.bibxml.series.extract_3gpp_tr_series(docid: DocID) Optional[Tuple[str, str]][source]
relaton.serializers.bibxml.series.extract_ieee_series(docid: DocID) Optional[Tuple[str, str]][source]
relaton.serializers.bibxml.series.DOCID_SERIES_EXTRACTORS = [...]

A list of functions capable of extracting series information as 2-tuple (series name, document number) from a DocID. Each function is expected to either return a tuple or None, and not throw.

Targets List[Link])[source]

From a list of Link instances, return a string suitable to be used as value of target attribute on root XML element.

It prefers a link with type set to “src”, if not present then first available link.

bibxml_string: BibXML string

relaton.serializers.bibxml_string.serialize(item: BibliographicItem, **kwargs) bytes[source]

Passes given item and any kwargs through to relaton.serializers.bibxml.serialize(), and renders the obtained XML element as an UTF8-encoded string with pretty print.