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

bibxml_string

relaton.serializers.bibxml.serialize(item: relaton.models.bibdata.BibliographicItem, anchor: Optional[str] = None) → xml.etree.ElementTree.Element

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

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

Parameters

anchor (str) – resulting root element anchor property.

Raises

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

Abstracts

relaton.serializers.bibxml.abstracts.get_paragraphs(val: str) → List[str]

Returns paragraphs as plain text, stripping HTML if needed.

Anchors

relaton.serializers.bibxml.anchor.get_suitable_anchor(docids: List[relaton.models.bibdata.DocID])

From a list of DocID instances, get best anchor value and return it as a string.

Ideally it’s a DocID with scope equal to “anchor”, otherwise primary identifier, otherwise any idnetifier.

Parameters

docids – a list of bib_models.bibdata.DocID instances

Returns str

a string to be used as anchor

Return type

str

Raises

ValueError – no suitable document identifier (possibly empty list)

Authors

relaton.serializers.bibxml.authors.create_author(contributor: relaton.models.bibdata.Contributor) → xml.etree.ElementTree.Element

relaton.serializers.bibxml.authors.is_author(contrib)

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.

References

relaton.serializers.bibxml.reference.create_reference(item: relaton.models.bibdata.BibliographicItem) → xml.etree.ElementTree.Element

relaton.serializers.bibxml.reference.create_referencegroup(items: List[relaton.models.bibdata.BibliographicItem]) → xml.etree.ElementTree.Element

Series

relaton.serializers.bibxml.series.extract_doi_series(docid: relaton.models.bibdata.DocID) → Optional[Tuple[str, str]]

relaton.serializers.bibxml.series.extract_rfc_series(docid: relaton.models.bibdata.DocID) → Optional[Tuple[str, str]]

relaton.serializers.bibxml.series.extract_id_series(docid: relaton.models.bibdata.DocID) → Optional[Tuple[str, str]]

relaton.serializers.bibxml.series.extract_w3c_series(docid: relaton.models.bibdata.DocID) → Optional[Tuple[str, str]]

relaton.serializers.bibxml.series.extract_3gpp_tr_series(docid: relaton.models.bibdata.DocID) → Optional[Tuple[str, str]]

relaton.serializers.bibxml.series.extract_ieee_series(docid: relaton.models.bibdata.DocID) → Optional[Tuple[str, str]]

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

relaton.serializers.bibxml.target.get_suitable_target(links: List[relaton.models.links.Link])

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: relaton.models.bibdata.BibliographicItem, **kwargs) → bytes

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.