marc-bibframe 0.2.1__tar.gz

marc_bibframe-0.2.1/.github/workflows/dependency-updates.yml

@@ -0,0 +1,143 @@
+name: Weekly Dependency Updates
+
+on:
+  schedule:
+    - cron: '0 9 * * 1'  # Every Monday at 9 AM UTC
+  workflow_dispatch: # Enables the "Run workflow" button in GitHub
+
+jobs:
+  update-dependencies:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # The lowest supported version, which is the one most likely to catch
+        # an incompatibility. The pull request this opens runs the full matrix.
+        python-version: [3.12]
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Update dependencies
+        run: uv lock --upgrade
+
+      - name: Check for dependency changes
+        id: check_changes
+        run: |
+          if git diff --quiet uv.lock; then
+            echo "changed=false" >> $GITHUB_OUTPUT
+          else
+            echo "changed=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Install dependencies
+        if: steps.check_changes.outputs.changed == 'true'
+        run: uv sync
+
+      # The same checks CI runs, in the same order. A dependency bump can break
+      # formatting or typing as easily as it breaks a test -- ruff and ty are
+      # themselves dependencies here.
+      - name: Format
+        if: steps.check_changes.outputs.changed == 'true'
+        run: uv run ruff format --diff
+
+      - name: Lint
+        if: steps.check_changes.outputs.changed == 'true'
+        run: uv run ruff check
+
+      - name: Types
+        if: steps.check_changes.outputs.changed == 'true'
+        run: uv run ty check
+
+      - name: Run tests
+        if: steps.check_changes.outputs.changed == 'true'
+        env:
+          # The upstream-version test calls the GitHub API. Without a token the
+          # anonymous limit is 60/hour per IP, which shared runners share, and
+          # the test skips instead of checking anything.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: uv run pytest
+
+      - name: Bump patch version
+        id: bump_version
+        if: steps.check_changes.outputs.changed == 'true'
+        run: |
+          NEW_VERSION=$(python3 -c "
+          import re
+          with open('pyproject.toml') as f:
+              content = f.read()
+          m = re.search(r'version = \"(\d+)\.(\d+)\.(\d+)\"', content)
+          major, minor, patch = m.groups()
+          print(f'{major}.{minor}.{int(patch) + 1}')
+          ")
+          sed -i "s/^version = \"[0-9]*\.[0-9]*\.[0-9]*\"/version = \"$NEW_VERSION\"/" pyproject.toml
+          echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
+
+      - name: Sync lockfile with bumped version
+        if: steps.check_changes.outputs.changed == 'true'
+        run: uv lock
+
+      - name: Create Pull Request
+        id: create_pr
+        if: steps.check_changes.outputs.changed == 'true' && success()
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: dependency-updates
+          base: main
+          title: 'Weekly dependency updates (${{ steps.bump_version.outputs.new_version }})'
+          body: |
+            Weekly automated dependency updates.
+
+            - Updated `uv.lock` via `uv lock --upgrade`
+            - Bumped patch version to `${{ steps.bump_version.outputs.new_version }}`
+
+            Publishing happens on release, so merging this prepares the next
+            version rather than releasing it.
+
+            Note this updates the Python dependencies only. The vendored LC
+            stylesheets track upstream separately, via `./scripts/vendor.py`.
+          commit-message: 'Update dependencies and bump patch version to ${{ steps.bump_version.outputs.new_version }}'
+          labels: dependencies
+
+      # Skipped rather than failed when no webhook is configured.
+      - name: Notify Slack
+        if: steps.check_changes.outputs.changed == 'true' && success()
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+          PR_URL: ${{ steps.create_pr.outputs.pull-request-url }}
+          NEW_VERSION: ${{ steps.bump_version.outputs.new_version }}
+          REPO_NAME: ${{ github.event.repository.name }}
+        run: |
+          if [ -z "$SLACK_WEBHOOK_URL" ]; then
+            echo "No SLACK_WEBHOOK_URL configured, skipping."
+            exit 0
+          fi
+          curl -X POST -H 'Content-type: application/json' \
+            --data "{\"text\": \"$REPO_NAME dependency update PR opened: <$PR_URL|v$NEW_VERSION>\"}" \
+            "$SLACK_WEBHOOK_URL"
+
+      - name: Notify Slack on failure
+        if: steps.check_changes.outputs.changed == 'true' && failure()
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+          REPO_NAME: ${{ github.event.repository.name }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          if [ -z "$SLACK_WEBHOOK_URL" ]; then
+            echo "No SLACK_WEBHOOK_URL configured, skipping."
+            exit 0
+          fi
+          curl -X POST -H 'Content-type: application/json' \
+            --data "{\"text\": \"$REPO_NAME dependency update failed: <$RUN_URL|view run>\"}" \
+            "$SLACK_WEBHOOK_URL"

marc_bibframe-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+# Requires this repo to be registered as a trusted publisher on PyPI, so no
+# API token is needed: https://docs.pypi.org/trusted-publishers/
+
+on:
+  release:
+    types:
+      published
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/marc-bibframe
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      # Don't publish something that doesn't pass its own tests.
+      - name: Check
+        env:
+          # The upstream-version test calls the GitHub API. Without a token the
+          # anonymous limit is 60/hour per IP, which shared runners share, and
+          # the test skips instead of checking anything.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          uv run ruff format --diff
+          uv run ruff check
+          uv run ty check
+          uv run pytest
+
+      # The vendored stylesheets are the whole point of the package, so make
+      # sure a release ships upstream-plus-patches and not a hand-edited tree.
+      - name: Vendored stylesheets match upstream plus patches
+        run: |
+          uv run ./scripts/vendor.py "$(grep '^tag:' src/marc_bibframe/xsl/UPSTREAM | cut -d' ' -f2)"
+          git diff --exit-code -- src/marc_bibframe/xsl
+
+      - name: Publish
+        run: |
+          uv build
+          uv publish

marc_bibframe-0.2.1/.github/workflows/test.yml

@@ -0,0 +1,44 @@
+name: Test
+on:
+  - push
+  - pull_request
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+
+      - name: checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Formatting
+        run: uv run ruff format --diff
+
+      - name: Linting
+        run: uv run ruff check
+
+      - name: Type Checking
+        run: uv run ty check
+
+      - name: Tests
+        env:
+          # The upstream-version test calls the GitHub API. Without a token the
+          # anonymous limit is 60/hour per IP, which shared runners share, and
+          # the test skips instead of checking anything.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: uv run pytest
+
+      - name: Vendored stylesheets match upstream plus patches
+        run: |
+          uv run ./scripts/vendor.py "$(grep '^tag:' src/marc_bibframe/xsl/UPSTREAM | cut -d' ' -f2)"
+          git diff --exit-code -- src/marc_bibframe/xsl

marc_bibframe-0.2.1/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage

marc_bibframe-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blue Core
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

marc_bibframe-0.2.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: marc-bibframe
+Version: 0.2.1
+Summary: Convert MARC records to BIBFRAME RDF using the Library of Congress marc2bibframe2 XSLT
+Project-URL: Homepage, https://github.com/blue-core-lod/marc-bibframe
+Project-URL: Issues, https://github.com/blue-core-lod/marc-bibframe/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bibframe,libraries,marc,marc2bibframe2,marcxml,rdf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup :: XML
+Requires-Python: >=3.12
+Requires-Dist: lxml>=6.0.2
+Requires-Dist: pymarc>=5.2.0
+Requires-Dist: rdflib>=7.1.3
+Description-Content-Type: text/markdown
+
+# marc-bibframe
+
+[![Test](https://github.com/blue-core-lod/marc-bibframe/actions/workflows/test.yml/badge.svg)](https://github.com/blue-core-lod/marc-bibframe/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/marc-bibframe)](https://pypi.org/project/marc-bibframe/)
+
+Convert MARC records to BIBFRAME RDF in Python, using the Library of Congress
+[marc2bibframe2](https://github.com/lcnetdev/marc2bibframe2) XSLT.
+
+The stylesheet is vendored in this package, so there is nothing to install
+alongside it and no Java or Saxon involved, just `lxml`, `pymarc` and
+`rdflib`.
+
+## Install
+
+```
+pip install marc-bibframe
+```
+
+## Command line
+
+You can use it from the command line:
+
+```
+$ marc-bibframe record.mrc
+$ marc-bibframe record.xml --format json-ld --baseuri https://example.edu/catalog/
+$ yaz-marcdump -o marcxml big.mrc | marc-bibframe -f nt -o big.nt
+```
+
+Binary MARC21 and MARCXML are both accepted and told apart by their content,
+so there is no flag for it. With no filename it reads standard input.
+
+`--format` takes `turtle` (the default), `json-ld`, `ntriples`, `xml`, or
+`rdfxml`. The last is the stylesheet's own output passed through without a
+parse into rdflib, which is faster and keeps the transform's exact shape.
+
+`marc-bibframe --help` lists the stylesheet parameters, which are also
+available as flags.
+
+## Use as a library
+
+Or you can use it as a function in your own Python programs:
+
+```python
+from marc_bibframe import marc_to_graph
+
+with open("record.mrc", "rb") as fh:
+    graph = marc_to_graph(fh, baseuri="https://example.edu/catalog/")
+
+print(graph.serialize(format="turtle"))
+```
+
+MARCXML is accepted directly, and RDF/XML is available if you would rather not
+pay for a parse into an rdflib.Graph:
+
+```python
+from marc_bibframe import marc_to_marcxml, marcxml_to_graph, marcxml_to_rdfxml
+
+marcxml = marc_to_marcxml(open("record.mrc", "rb").read())
+graph = marcxml_to_graph(marcxml)
+rdfxml = marcxml_to_rdfxml(marcxml)
+```
+
+All four functions accept the stylesheet's parameters as keyword arguments —
+`baseuri`, `idfield`, `idsource`, `localfields`, `bcp47_inference` and
+`generation_datestamp`. See the docstring on `marcxml_to_rdfxml` for what each
+one does.
+
+## A note on the URIs it mints
+
+MARC does not identify most of what it describes, so the transform invents
+URIs for them, built from `baseuri` and the record's own id:
+
+```
+https://example.edu/catalog/99123456#Work
+https://example.edu/catalog/99123456#Instance
+https://example.edu/catalog/99123456#Agent100-3
+https://example.edu/catalog/99123456#Topic650-5
+```
+
+These are **not** authority URIs. They are scoped to the record they came
+from, so two records describing the same person produce two different agent
+URIs. If you need them reconciled against an authority (LC, Wikidata, your
+own store) that happens after this library hands you the graph.
+
+For the same reason the default `baseuri` is `http://example.org/`, matching
+the stylesheet's own. Pick something under your control, and prefer a
+namespace that cannot be mistaken for an authority's: minting
+`http://id.loc.gov/resources/99123456#Agent100-3` produces URIs that look like
+LC's but are not.
+
+## Keeping up with upstream
+
+`src/marc_bibframe/xsl/` is a copy of the LC stylesheets — see
+[`UPSTREAM`](src/marc_bibframe/xsl/UPSTREAM) for the tag and commit. Local
+changes are not edited in place; they live as patches in
+[`patches/`](patches/) and are reapplied on every re-vendor:
+
+```
+./scripts/vendor.py v3.2.0
+```
+
+If a patch stops applying the script says so and stops, which is usually the
+signal that it was fixed upstream and can be deleted. The aim is to keep
+`patches/` empty; anything in there should also be reported to LC.
+
+The test suite checks the vendored tag against LC's latest release and fails
+when there is a newer one, with the command to run. It skips rather than fails
+if the GitHub API is unreachable.
+
+The stylesheets are [CC0](src/marc_bibframe/xsl/LICENSE). This wrapper is
+[MIT](LICENSE).
+
+## Reproducible output
+
+The transform stamps the current time into the work's admin metadata.
+`generation_datestamp` (`--datestamp`) overrides it, which makes the RDF/XML
+byte-for-byte reproducible. The other serializations still vary between runs:
+rdflib mints fresh blank node labels every time it serializes.
+
+## Development
+
+```
+uv sync
+uv run pytest
+```

marc_bibframe-0.2.1/README.md

@@ -0,0 +1,125 @@
+# marc-bibframe
+
+[![Test](https://github.com/blue-core-lod/marc-bibframe/actions/workflows/test.yml/badge.svg)](https://github.com/blue-core-lod/marc-bibframe/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/marc-bibframe)](https://pypi.org/project/marc-bibframe/)
+
+Convert MARC records to BIBFRAME RDF in Python, using the Library of Congress
+[marc2bibframe2](https://github.com/lcnetdev/marc2bibframe2) XSLT.
+
+The stylesheet is vendored in this package, so there is nothing to install
+alongside it and no Java or Saxon involved, just `lxml`, `pymarc` and
+`rdflib`.
+
+## Install
+
+```
+pip install marc-bibframe
+```
+
+## Command line
+
+You can use it from the command line:
+
+```
+$ marc-bibframe record.mrc
+$ marc-bibframe record.xml --format json-ld --baseuri https://example.edu/catalog/
+$ yaz-marcdump -o marcxml big.mrc | marc-bibframe -f nt -o big.nt
+```
+
+Binary MARC21 and MARCXML are both accepted and told apart by their content,
+so there is no flag for it. With no filename it reads standard input.
+
+`--format` takes `turtle` (the default), `json-ld`, `ntriples`, `xml`, or
+`rdfxml`. The last is the stylesheet's own output passed through without a
+parse into rdflib, which is faster and keeps the transform's exact shape.
+
+`marc-bibframe --help` lists the stylesheet parameters, which are also
+available as flags.
+
+## Use as a library
+
+Or you can use it as a function in your own Python programs:
+
+```python
+from marc_bibframe import marc_to_graph
+
+with open("record.mrc", "rb") as fh:
+    graph = marc_to_graph(fh, baseuri="https://example.edu/catalog/")
+
+print(graph.serialize(format="turtle"))
+```
+
+MARCXML is accepted directly, and RDF/XML is available if you would rather not
+pay for a parse into an rdflib.Graph:
+
+```python
+from marc_bibframe import marc_to_marcxml, marcxml_to_graph, marcxml_to_rdfxml
+
+marcxml = marc_to_marcxml(open("record.mrc", "rb").read())
+graph = marcxml_to_graph(marcxml)
+rdfxml = marcxml_to_rdfxml(marcxml)
+```
+
+All four functions accept the stylesheet's parameters as keyword arguments —
+`baseuri`, `idfield`, `idsource`, `localfields`, `bcp47_inference` and
+`generation_datestamp`. See the docstring on `marcxml_to_rdfxml` for what each
+one does.
+
+## A note on the URIs it mints
+
+MARC does not identify most of what it describes, so the transform invents
+URIs for them, built from `baseuri` and the record's own id:
+
+```
+https://example.edu/catalog/99123456#Work
+https://example.edu/catalog/99123456#Instance
+https://example.edu/catalog/99123456#Agent100-3
+https://example.edu/catalog/99123456#Topic650-5
+```
+
+These are **not** authority URIs. They are scoped to the record they came
+from, so two records describing the same person produce two different agent
+URIs. If you need them reconciled against an authority (LC, Wikidata, your
+own store) that happens after this library hands you the graph.
+
+For the same reason the default `baseuri` is `http://example.org/`, matching
+the stylesheet's own. Pick something under your control, and prefer a
+namespace that cannot be mistaken for an authority's: minting
+`http://id.loc.gov/resources/99123456#Agent100-3` produces URIs that look like
+LC's but are not.
+
+## Keeping up with upstream
+
+`src/marc_bibframe/xsl/` is a copy of the LC stylesheets — see
+[`UPSTREAM`](src/marc_bibframe/xsl/UPSTREAM) for the tag and commit. Local
+changes are not edited in place; they live as patches in
+[`patches/`](patches/) and are reapplied on every re-vendor:
+
+```
+./scripts/vendor.py v3.2.0
+```
+
+If a patch stops applying the script says so and stops, which is usually the
+signal that it was fixed upstream and can be deleted. The aim is to keep
+`patches/` empty; anything in there should also be reported to LC.
+
+The test suite checks the vendored tag against LC's latest release and fails
+when there is a newer one, with the command to run. It skips rather than fails
+if the GitHub API is unreachable.
+
+The stylesheets are [CC0](src/marc_bibframe/xsl/LICENSE). This wrapper is
+[MIT](LICENSE).
+
+## Reproducible output
+
+The transform stamps the current time into the work's admin metadata.
+`generation_datestamp` (`--datestamp`) overrides it, which makes the RDF/XML
+byte-for-byte reproducible. The other serializations still vary between runs:
+rdflib mints fresh blank node labels every time it serializes.
+
+## Development
+
+```
+uv sync
+uv run pytest
+```

marc_bibframe-0.2.1/patches/0001-bcp47-require-nonempty-script.patch

@@ -0,0 +1,28 @@
+Subject: Don't infer a BCP-47 script subtag when no script was detected
+
+In utils.xsl's language-tag handling, the $bcp47inferrence branch compares the
+language's expected script against $vScript without first checking that
+$vScript is non-empty. When a record yields no script, the comparison
+"expected != ''" succeeds and the transform emits a bogus tag such as "ru-"
+instead of plain "ru".
+
+Requiring $vScript != '' makes the branch fall through to the plain language
+code, which is the correct output.
+
+Upstream status: not yet reported to lcnetdev/marc2bibframe2.
+Origin: blue-core-lod/bluecore_api "Fix language tag bug" (2026-08-28).
+
+diff --git a/src/marc_bibframe/xsl/utils.xsl b/src/marc_bibframe/xsl/utils.xsl
+index 13b8f95..9f136e3 100644
+--- a/src/marc_bibframe/xsl/utils.xsl
++++ b/src/marc_bibframe/xsl/utils.xsl
+@@ -93,7 +93,8 @@
+         </xsl:variable>
+         <xsl:choose>
+           <xsl:when test="$vLang = 'en' and $vScript != '' and $vScript != 'latn'"><xsl:value-of select="concat('und-',$vScript)"/></xsl:when>
+-          <xsl:when test="$bcp47inferrence and 
++          <xsl:when test="$bcp47inferrence and
++                          $vScript != '' and
+                           $code-to-script-map/code-to-script-map/entry[@key=$vLang] and
+                           $code-to-script-map/code-to-script-map/entry[@key=$vLang]/value != $vScript">
+             <xsl:value-of select="concat($vLang,'-',$vScript)"/>

marc_bibframe-0.2.1/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "marc-bibframe"
+version = "0.2.1"
+description = "Convert MARC records to BIBFRAME RDF using the Library of Congress marc2bibframe2 XSLT"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+keywords = ["marc", "bibframe", "marcxml", "rdf", "marc2bibframe2", "libraries"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Text Processing :: Markup :: XML",
+]
+dependencies = [
+    "lxml>=6.0.2",
+    "pymarc>=5.2.0",
+    "rdflib>=7.1.3",
+]
+
+[project.scripts]
+marc-bibframe = "marc_bibframe.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/blue-core-lod/marc-bibframe"
+Issues = "https://github.com/blue-core-lod/marc-bibframe/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "ruff>=0.9.6",
+    # ty resolves lxml through these; without them lxml.etree is unresolved.
+    "lxml-stubs>=0.5.1",
+    # Declared so CI resolves the same checker as a local `uv run ty check`,
+    # rather than whatever happens to be on PATH.
+    "ty>=0.0.1a1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/marc_bibframe"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+addopts = "-v"