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: BibliographicItem, anchor: Optional[str] = None) → 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.create_abstract(abstracts: List[GenericStringValue]) → Element

Formats an <abstract> element.

Anchors

relaton.serializers.bibxml.anchor.get_suitable_anchor(item: BibliographicItem) → str

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

Parameters

item – a bib_models.bibdata.BibliographicItem instance

Returns str

a string to be used as anchor

Return type

str

Raises

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

relaton.serializers.bibxml.anchor.to_valid_xsid(val: str) → str

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.

Authors

relaton.serializers.bibxml.authors.create_author(contributor: Contributor) → 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: BibliographicItem) → Element

relaton.serializers.bibxml.reference.create_referencegroup(items: List[BibliographicItem]) → Element

Series

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

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

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

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

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

relaton.serializers.bibxml.series.extract_ieee_series(docid: 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[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: 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.