marc-bibframe 0.2.1__py3-none-any.whl

marc_bibframe/__init__.py

@@ -0,0 +1,175 @@
+"""Convert MARC records to BIBFRAME RDF.
+
+A thin Python wrapper around the Library of Congress marc2bibframe2 XSLT
+(https://github.com/lcnetdev/marc2bibframe2), which is vendored in this
+package. See ``src/marc_bibframe/xsl/UPSTREAM`` for the version, and
+``patches/`` for any local changes to it.
+"""
+
+from __future__ import annotations
+
+import atexit
+import functools
+from contextlib import ExitStack
+from importlib.resources import as_file, files
+from io import BytesIO
+from typing import Any, BinaryIO
+
+import lxml.etree as ET
+import pymarc
+from pymarc.marcxml import record_to_xml
+from rdflib import Graph
+
+__all__ = [
+    "DEFAULT_BASE_URI",
+    "marc_to_graph",
+    "marc_to_marcxml",
+    "marcxml_to_graph",
+    "marcxml_to_rdfxml",
+    "upstream",
+]
+
+#: The stylesheet's own default. It is deliberately non-resolvable: URIs the
+#: transform mints for entities that MARC does not identify (agents, topics,
+#: the work and instance themselves) are built from it, and they name nothing.
+DEFAULT_BASE_URI = "http://example.org/"
+
+_MARCXML_NS = "http://www.loc.gov/MARC21/slim"
+_COLLECTION_OPEN = (
+    b'<?xml version="1.0" encoding="UTF-8"?>'
+    b'<collection xmlns="' + _MARCXML_NS.encode() + b'">'
+)
+_COLLECTION_CLOSE = b"</collection>"
+
+# The stylesheet xsl:includes ~30 siblings by relative href, so it has to be
+# resolved from a real directory rather than read out of the package as bytes.
+# Holding the ExitStack open for the life of the process keeps that directory
+# around when the package is imported from a zip.
+_files = ExitStack()
+atexit.register(_files.close)
+
+
+@functools.cache
+def _xsl_dir():
+    return _files.enter_context(as_file(files(__package__).joinpath("xsl")))
+
+
+@functools.cache
+def _transform() -> ET.XSLT:
+    """Parse and compile the stylesheet, once per process (it is not cheap)."""
+    return ET.XSLT(ET.parse(str(_xsl_dir() / "marc2bibframe2.xsl")))
+
+
+def upstream() -> dict[str, str]:
+    """The upstream marc2bibframe2 repository, tag and commit that is vendored here."""
+    text = (_xsl_dir() / "UPSTREAM").read_text()
+    return {
+        k.strip(): v.strip()
+        for k, _, v in (line.partition(":") for line in text.splitlines())
+        if k
+    }
+
+
+def _xslt_params(**kwargs: Any) -> dict[str, Any]:
+    """Build XSLT parameters, dropping any left as None so the stylesheet default wins.
+
+    Booleans become the XPath expressions true()/false() rather than string
+    literals, because every non-empty string is true in XPath -- passing "false"
+    as a string would quietly mean the opposite of what was asked for.
+    """
+    params = {}
+    for name, value in kwargs.items():
+        if value is None:
+            continue
+        params[name] = (
+            "true()"
+            if value is True
+            else "false()"
+            if value is False
+            else ET.XSLT.strparam(str(value))
+        )
+    return params
+
+
+def marc_to_marcxml(marc: bytes | BinaryIO) -> bytes:
+    """Convert binary MARC21 to a MARCXML ``<collection>`` of one or more records."""
+    handle = BytesIO(marc) if isinstance(marc, bytes) else marc
+    parts = [_COLLECTION_OPEN]
+    for i, record in enumerate(pymarc.MARCReader(handle)):
+        if record is None:
+            raise ValueError(f"Could not read MARC record at position {i}")
+        parts.append(record_to_xml(record, namespace=False))
+    parts.append(_COLLECTION_CLOSE)
+    return b"".join(parts)
+
+
+def marcxml_to_rdfxml(
+    marcxml: str | bytes,
+    *,
+    baseuri: str = DEFAULT_BASE_URI,
+    idfield: str | None = None,
+    idsource: str | None = None,
+    localfields: bool | None = None,
+    bcp47_inference: bool | None = None,
+    generation_datestamp: str | None = None,
+) -> bytes:
+    """Transform MARCXML into BIBFRAME RDF/XML.
+
+    Accepts a single ``<record>`` or a ``<collection>`` of them.
+
+    baseuri
+        Base for the URIs the transform mints. Every minted URI has the form
+        ``{baseuri}{record id}#{fragment}``, so they are scoped to the record
+        they came from and are not authority URIs -- two records describing the
+        same person yield two different agent URIs. Reconciling them against an
+        authority is the caller's job.
+    idfield
+        MARC field holding the record id, ``001`` by default. Suffix a subfield
+        code to use one, e.g. ``035a``.
+    idsource
+        URI identifying the source of the record id, e.g.
+        ``http://id.loc.gov/vocabulary/organizations/dlc``.
+    localfields
+        Convert fields LC defines locally (e.g. 859), off by default.
+    bcp47_inference
+        Omit a BCP-47 script subtag when it can be inferred from the language.
+    generation_datestamp
+        Override the timestamp recorded in the work's admin metadata, which
+        otherwise defaults to now. Set it to make the RDF/XML this function
+        returns byte-for-byte reproducible. Note that a Graph serialized by
+        rdflib still varies between runs, because rdflib mints fresh blank
+        node labels each time.
+    """
+    if isinstance(marcxml, str):
+        # Encode first: lxml refuses a str carrying an encoding declaration.
+        marcxml = marcxml.encode("utf-8")
+    params = _xslt_params(
+        baseuri=baseuri,
+        idfield=idfield,
+        idsource=idsource,
+        localfields=localfields,
+        bcp47inferrence=bcp47_inference,
+        pGenerationDatestamp=generation_datestamp,
+    )
+    result = _transform()(ET.fromstring(marcxml), **params)
+    return ET.tostring(
+        result, xml_declaration=True, encoding="UTF-8", pretty_print=True
+    )
+
+
+def marcxml_to_graph(marcxml: str | bytes, **kwargs: Any) -> Graph:
+    """Transform MARCXML into BIBFRAME as an rdflib Graph.
+
+    Takes the same keyword arguments as :func:`marcxml_to_rdfxml`.
+    """
+    graph = Graph()
+    graph.parse(data=marcxml_to_rdfxml(marcxml, **kwargs), format="xml")
+    return graph
+
+
+def marc_to_graph(marc: bytes | BinaryIO, **kwargs: Any) -> Graph:
+    """Convert binary MARC21 straight to BIBFRAME as an rdflib Graph.
+
+    Takes the same keyword arguments as :func:`marcxml_to_rdfxml`.
+    """
+    return marcxml_to_graph(marc_to_marcxml(marc), **kwargs)

marc_bibframe/cli.py

@@ -0,0 +1,150 @@
+"""Command line interface: MARC in, BIBFRAME out."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from marc_bibframe import (
+    DEFAULT_BASE_URI,
+    marc_to_marcxml,
+    marcxml_to_graph,
+    marcxml_to_rdfxml,
+    upstream,
+)
+
+# rdflib's name for each, except rdfxml, which we serve from the transform
+# directly rather than round-tripping it through a parse.
+FORMATS = {
+    "turtle": "turtle",
+    "ttl": "turtle",
+    "json-ld": "json-ld",
+    "jsonld": "json-ld",
+    "ntriples": "nt",
+    "nt": "nt",
+    "xml": "xml",
+    "rdfxml": None,
+}
+
+
+def looks_like_marcxml(data: bytes) -> bool:
+    return data.lstrip().lstrip(b"\xef\xbb\xbf").startswith(b"<")
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="marc-bibframe",
+        description="Convert MARC records to BIBFRAME RDF.",
+        epilog="Binary MARC21 and MARCXML are both accepted; the format is "
+        "detected from the content. With no INPUT, reads standard input.",
+    )
+    parser.add_argument(
+        "input",
+        nargs="?",
+        default="-",
+        help="MARC file to convert, or - for standard input (the default)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        help="write to this file instead of standard output",
+    )
+    parser.add_argument(
+        "-f",
+        "--format",
+        default="turtle",
+        choices=sorted(FORMATS),
+        help="output serialization (default: turtle). rdfxml is the "
+        "stylesheet's own output, passed through unparsed",
+    )
+    parser.add_argument(
+        "-b",
+        "--baseuri",
+        default=DEFAULT_BASE_URI,
+        metavar="URI",
+        help="base for the URIs the transform mints, which are NOT authority "
+        f"URIs -- see the README (default: {DEFAULT_BASE_URI})",
+    )
+    parser.add_argument(
+        "--idfield",
+        metavar="FIELD",
+        help="MARC field holding the record id, 001 by default. Suffix a "
+        "subfield code to use one, e.g. 035a",
+    )
+    parser.add_argument(
+        "--idsource",
+        metavar="URI",
+        help="URI identifying the source of the record id, e.g. "
+        "http://id.loc.gov/vocabulary/organizations/dlc",
+    )
+    parser.add_argument(
+        "--local-fields",
+        action="store_true",
+        default=None,
+        help="convert fields the Library of Congress defines locally, e.g. 859",
+    )
+    parser.add_argument(
+        "--no-bcp47-inference",
+        dest="bcp47_inference",
+        action="store_false",
+        default=None,
+        help="keep the script subtag in BCP-47 codes even when the language implies it",
+    )
+    parser.add_argument(
+        "--datestamp",
+        metavar="TIMESTAMP",
+        help="override the timestamp in the work's admin metadata. With "
+        "-f rdfxml this makes output byte-for-byte reproducible; other "
+        "formats still vary, as rdflib renames blank nodes on each run",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"marc-bibframe, marc2bibframe2 {upstream()['tag']}",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+
+    if args.input == "-":
+        data = sys.stdin.buffer.read()
+    else:
+        path = Path(args.input)
+        if not path.exists():
+            sys.exit(f"marc-bibframe: {path}: no such file")
+        data = path.read_bytes()
+
+    if not data.strip():
+        sys.exit("marc-bibframe: no input")
+
+    marcxml = data if looks_like_marcxml(data) else marc_to_marcxml(data)
+
+    params = {
+        "baseuri": args.baseuri,
+        "idfield": args.idfield,
+        "idsource": args.idsource,
+        "localfields": args.local_fields,
+        "bcp47_inference": args.bcp47_inference,
+        "generation_datestamp": args.datestamp,
+    }
+
+    rdflib_format = FORMATS[args.format]
+    if rdflib_format is None:
+        out = marcxml_to_rdfxml(marcxml, **params)
+    else:
+        out = marcxml_to_graph(marcxml, **params).serialize(
+            format=rdflib_format, encoding="utf-8"
+        )
+
+    if args.output:
+        Path(args.output).write_bytes(out)
+    else:
+        sys.stdout.buffer.write(out)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())