bibliography-io 0.1.0__tar.gz

bibliography_io-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  hooks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip pre-commit
+      - run: pre-commit run --all-files
+
+  core-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[test]"
+      - run: pytest
+
+  build-and-wheel-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - run: python -m venv /tmp/bibliography-io-wheel-venv
+      - run: /tmp/bibliography-io-wheel-venv/bin/python -m pip install dist/*.whl
+      - name: Smoke-test installed wheel without optional backends
+        working-directory: /tmp
+        run: |
+          /tmp/bibliography-io-wheel-venv/bin/python - <<'PY'
+          import importlib.util
+          from importlib.metadata import entry_points
+          from pathlib import Path
+          from tempfile import TemporaryDirectory
+
+          import bibliography_io
+          from bibliography_io.exceptions import OptionalBackendUnavailableError
+
+          assert importlib.util.find_spec("colrev") is None
+          assert not entry_points().select(
+              group="bibliography_io.backends", name="markdown"
+          )
+          records = bibliography_io.loads(
+              "@article{wheel_smoke, title={Installed wheel}}", format="bib"
+          )
+          assert records["wheel_smoke"]["title"] == "Installed wheel"
+          with TemporaryDirectory() as directory:
+              path = Path(directory) / "smoke.bib"
+              bibliography_io.write_records(records, path)
+              assert bibliography_io.load_records(path) == records
+              markdown = Path(directory) / "references.md"
+              markdown.write_text("# References\n\nA reference", encoding="utf-8")
+              try:
+                  bibliography_io.load_records(markdown)
+              except OptionalBackendUnavailableError:
+                  pass
+              else:
+                  raise AssertionError("Markdown backend should not be installed")
+          PY

bibliography_io-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[docs]"
+      - run: python -m sphinx -W --keep-going -b html docs docs/_build/html
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      id-token: write
+      pages: write
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

bibliography_io-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/bibliography-io
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      # Configure this workflow as a trusted publisher in the PyPI project settings.
+      - uses: pypa/gh-action-pypi-publish@release/v1

bibliography_io-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+.venv/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+docs/_build/

bibliography_io-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: ^tests/.*/data/
+      - id: end-of-file-fixer
+        exclude: ^tests/.*/data/
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.13
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

bibliography_io-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026, Gerit Wagner and Julian Prester
+
+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.

bibliography_io-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: bibliography-io
+Version: 0.1.0
+Summary: Loading and writing bibliographic records across formats
+Project-URL: Homepage, https://github.com/CoLRev-Environment/bibliography-io
+Project-URL: Repository, https://github.com/CoLRev-Environment/bibliography-io
+Project-URL: Issues, https://github.com/CoLRev-Environment/bibliography-io/issues
+Project-URL: Changelog, https://github.com/CoLRev-Environment/bibliography-io/releases
+Project-URL: Documentation, https://colrev-environment.github.io/bibliography-io/
+Author: Gerit Wagner
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.10
+Requires-Dist: openpyxl>=3.1.2
+Requires-Dist: pandas<3,>=2.2
+Requires-Dist: xlrd>=2.0.1
+Provides-Extra: all
+Requires-Dist: colrev; extra == 'all'
+Requires-Dist: requests>=2.31; extra == 'all'
+Provides-Extra: colrev
+Requires-Dist: colrev; extra == 'colrev'
+Provides-Extra: docs
+Requires-Dist: sphinx-copybutton>=0.5.2; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=3.0; extra == 'docs'
+Requires-Dist: sphinx<9,>=7.3; extra == 'docs'
+Provides-Extra: requests
+Requires-Dist: requests>=2.31; extra == 'requests'
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# bibliography-io
+
+[![PyPI - Version](https://img.shields.io/pypi/v/bibliography-io?color=blue)](https://pypi.org/project/bibliography-io/)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/bibliography-io)
+[![License](https://img.shields.io/github/license/CoLRev-Environment/bibliography-io)](https://github.com/CoLRev-Environment/bibliography-io/blob/main/LICENSE)
+[![GitHub Actions](https://img.shields.io/github/actions/workflow/status/CoLRev-Environment/bibliography-io/ci.yml?label=tests)](https://github.com/CoLRev-Environment/bibliography-io/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/github/actions/workflow/status/CoLRev-Environment/bibliography-io/docs.yml?label=docs)](https://github.com/CoLRev-Environment/bibliography-io/actions/workflows/docs.yml)
+
+</div>
+
+`bibliography-io` provides standalone loading and writing of bibliographic
+records. Its core API does not require CoLRev or GROBID.
+
+## Installation
+
+Install the base package with:
+
+```shell
+pip install bibliography-io
+```
+
+The optional `colrev` extra is for legacy compatibility modules. It is not
+needed by the core file and string APIs. Markdown reference-list parsing has no
+released optional backend yet.
+
+## Usage
+
+```python
+from bibliography_io import load_records, write_records
+
+records = load_records("references.bib")
+write_records(records, "references.ris")
+```
+
+File APIs infer the format from recognized suffixes; an explicit `format` can
+override inference. String APIs always require `format`:
+
+```python
+from bibliography_io import dumps, loads
+
+records = loads("@article{example, title={An example}}", format="bib")
+text = dumps(records, format="bib")
+```
+
+### Format support
+
+| Format | Read files | Write files | String APIs |
+| --- | --- | --- | --- |
+| BibTeX | Yes | Yes | `loads` / `dumps` |
+| RIS | Yes | Yes | `loads` / `dumps` |
+| CSV | Yes | Yes | `loads` / `dumps` |
+| Excel | `.xls`, `.xlsx` | `.xlsx` | File APIs only |
+| ENL / EndNote | `.enl`, `.txt` | No | `loads` only |
+| NBIB | Yes | No | `loads` only |
+| JSON | Yes | No | `loads` only |
+| Markdown table | No | Yes | `dumps` |
+| Markdown reference list | Pending optional backend | No | Pending optional backend |
+
+Markdown table serialization is built into the core. Markdown reference-list
+parsing is a separate optional feature; its backend and installation extra are
+not finalized. Requesting Markdown input without a registered backend raises
+``OptionalBackendUnavailableError``.
+
+Historical root aliases (``load``, ``write``, ``write_file``, ``to_string``,
+``load_df``, and ``get_nr_records``) are deprecated immediately and will be
+removed in a future release.
+
+See the [documentation](https://colrev-environment.github.io/bibliography-io/)
+for installation details, usage examples, and the generated API reference.
+
+## Development
+
+Install the package's test extra and run the standalone test suite. The tests
+use the package API and do not require CoLRev:
+
+```shell
+pip install -e ".[test]"
+pip install build pre-commit
+pre-commit install
+pre-commit run --all-files
+pytest
+```
+
+Build the documentation locally with:
+
+```shell
+pip install -e ".[docs]"
+python -m sphinx -W --keep-going -b html docs docs/_build/html
+```
+
+See [RELEASING.md](RELEASING.md) for the package build and publication process.
+
+## License
+
+This project is distributed under the [MIT License](LICENSE).

bibliography_io-0.1.0/README.md

@@ -0,0 +1,97 @@
+<div align="center">
+
+# bibliography-io
+
+[![PyPI - Version](https://img.shields.io/pypi/v/bibliography-io?color=blue)](https://pypi.org/project/bibliography-io/)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/bibliography-io)
+[![License](https://img.shields.io/github/license/CoLRev-Environment/bibliography-io)](https://github.com/CoLRev-Environment/bibliography-io/blob/main/LICENSE)
+[![GitHub Actions](https://img.shields.io/github/actions/workflow/status/CoLRev-Environment/bibliography-io/ci.yml?label=tests)](https://github.com/CoLRev-Environment/bibliography-io/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/github/actions/workflow/status/CoLRev-Environment/bibliography-io/docs.yml?label=docs)](https://github.com/CoLRev-Environment/bibliography-io/actions/workflows/docs.yml)
+
+</div>
+
+`bibliography-io` provides standalone loading and writing of bibliographic
+records. Its core API does not require CoLRev or GROBID.
+
+## Installation
+
+Install the base package with:
+
+```shell
+pip install bibliography-io
+```
+
+The optional `colrev` extra is for legacy compatibility modules. It is not
+needed by the core file and string APIs. Markdown reference-list parsing has no
+released optional backend yet.
+
+## Usage
+
+```python
+from bibliography_io import load_records, write_records
+
+records = load_records("references.bib")
+write_records(records, "references.ris")
+```
+
+File APIs infer the format from recognized suffixes; an explicit `format` can
+override inference. String APIs always require `format`:
+
+```python
+from bibliography_io import dumps, loads
+
+records = loads("@article{example, title={An example}}", format="bib")
+text = dumps(records, format="bib")
+```
+
+### Format support
+
+| Format | Read files | Write files | String APIs |
+| --- | --- | --- | --- |
+| BibTeX | Yes | Yes | `loads` / `dumps` |
+| RIS | Yes | Yes | `loads` / `dumps` |
+| CSV | Yes | Yes | `loads` / `dumps` |
+| Excel | `.xls`, `.xlsx` | `.xlsx` | File APIs only |
+| ENL / EndNote | `.enl`, `.txt` | No | `loads` only |
+| NBIB | Yes | No | `loads` only |
+| JSON | Yes | No | `loads` only |
+| Markdown table | No | Yes | `dumps` |
+| Markdown reference list | Pending optional backend | No | Pending optional backend |
+
+Markdown table serialization is built into the core. Markdown reference-list
+parsing is a separate optional feature; its backend and installation extra are
+not finalized. Requesting Markdown input without a registered backend raises
+``OptionalBackendUnavailableError``.
+
+Historical root aliases (``load``, ``write``, ``write_file``, ``to_string``,
+``load_df``, and ``get_nr_records``) are deprecated immediately and will be
+removed in a future release.
+
+See the [documentation](https://colrev-environment.github.io/bibliography-io/)
+for installation details, usage examples, and the generated API reference.
+
+## Development
+
+Install the package's test extra and run the standalone test suite. The tests
+use the package API and do not require CoLRev:
+
+```shell
+pip install -e ".[test]"
+pip install build pre-commit
+pre-commit install
+pre-commit run --all-files
+pytest
+```
+
+Build the documentation locally with:
+
+```shell
+pip install -e ".[docs]"
+python -m sphinx -W --keep-going -b html docs docs/_build/html
+```
+
+See [RELEASING.md](RELEASING.md) for the package build and publication process.
+
+## License
+
+This project is distributed under the [MIT License](LICENSE).

bibliography_io-0.1.0/RELEASING.md

@@ -0,0 +1,75 @@
+# Releasing
+
+The initial release version proposed for this project is `0.1.0`. Confirm the
+version and package name with the maintainers before publishing.
+
+## Required pre-release checks
+
+1. Ensure the CI test job passes for the supported Python versions. It installs
+   `bibliography-io` and its test extra without CoLRev or GROBID, then runs the
+   complete standalone test suite:
+
+   ```shell
+   python -m pip install -e ".[test]"
+   pytest
+   ```
+
+   The test suite exercises the public bibliography-io API and repository data
+   fixtures without importing CoLRev.
+2. Build and validate the release artifacts, then install the wheel into a clean
+   environment without optional extras:
+
+   ```shell
+   python -m pip install --upgrade build twine
+   python -m build
+   python -m twine check dist/*
+   python -m venv /tmp/bibliography-io-wheel-smoke
+   /tmp/bibliography-io-wheel-smoke/bin/python -m pip install dist/*.whl
+   ```
+
+   From outside the source checkout, smoke-test imports and a BibTeX file
+   round-trip with the installed wheel. The wheel test must not install the
+   `colrev`, `requests`, or Markdown backend extras.
+3. Markdown table output is part of core testing. Markdown reference-list
+   parsing is pending an optional backend; test it separately after the backend
+   package, entry-point protocol, and installation extra are finalized.
+4. Update `project.version` in `pyproject.toml`, add release notes, and keep the
+   version in the Git tag synchronized with package metadata.
+
+## TestPyPI verification
+
+Upload the built artifacts and test installation of the core package without
+optional extras:
+
+```shell
+python -m twine upload --repository testpypi dist/*
+python -m venv /tmp/bibliography-io-testpypi
+/tmp/bibliography-io-testpypi/bin/python -m pip install \
+    --index-url https://test.pypi.org/simple/ \
+    --extra-index-url https://pypi.org/simple/ \
+    "bibliography-io==0.1.0"
+```
+
+Repeat the installed-wheel smoke test against the TestPyPI installation. The
+`--extra-index-url` allows runtime dependencies not mirrored on TestPyPI to
+resolve from PyPI.
+
+## PyPI publication with GitHub Actions
+
+`.github/workflows/publish.yml` builds distributions and publishes them to PyPI
+when a GitHub Release is published. Before using it:
+
+1. Create the `bibliography-io` project on PyPI and configure a Trusted
+   Publisher for this repository, the `publish.yml` workflow, and the `pypi`
+   environment.
+2. Create the matching GitHub `pypi` environment and configure any required
+   protection rules.
+3. Publish only after CI and TestPyPI verification pass. Use a `v<version>` tag
+   matching `project.version` (for example, `v0.1.0`).
+
+## Compatibility status
+
+The standalone bibliography-io API and its format-specific data fixtures are
+covered without CoLRev or GROBID. Historical CoLRev-facing compatibility
+wrappers are outside the standalone test suite. Markdown reference-list parsing
+is optional and remains unverified until its backend is finalized and tested.

bibliography_io-0.1.0/docs/Makefile

@@ -0,0 +1,14 @@
+# Minimal makefile for Sphinx documentation.
+
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = .
+BUILDDIR = _build
+
+.PHONY: help Makefile
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

bibliography_io-0.1.0/docs/api.rst

@@ -0,0 +1,21 @@
+API reference
+=============
+
+The strict standalone public API is:
+
+File operations infer formats from filename suffixes unless an explicit
+``format`` is provided. String operations require ``format``. See
+:doc:`usage` for the read/write format matrix, including the distinction
+between core Markdown table output and pending optional reference-list parsing.
+
+.. autofunction:: bibliography_io.load_records
+
+.. autofunction:: bibliography_io.loads
+
+.. autofunction:: bibliography_io.write_records
+
+.. autofunction:: bibliography_io.dumps
+
+The historical names ``load``, ``write``, ``write_file``, ``to_string``,
+``load_df``, and ``get_nr_records`` are deprecated immediately. They remain
+available during migration and will be removed in a future release.

bibliography_io-0.1.0/docs/conf.py

@@ -0,0 +1,23 @@
+from datetime import datetime
+from importlib.metadata import version as distribution_version
+
+project = "bibliography-io"
+author = "Gerit Wagner"
+copyright = f"{datetime.now().year}, {author}"
+release = distribution_version("bibliography-io")
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx_copybutton",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+autodoc_member_order = "bysource"
+autodoc_typehints = "description"
+
+html_theme = "sphinx_rtd_theme"
+html_title = "bibliography-io documentation"
+html_baseurl = "https://colrev-environment.github.io/bibliography-io/"

bibliography_io-0.1.0/docs/index.rst

@@ -0,0 +1,47 @@
+bibliography-io
+===============
+
+``bibliography-io`` provides standalone APIs for loading and writing
+bibliographic records. Core use does not require CoLRev or GROBID.
+
+Installation
+------------
+
+Install the core package with:
+
+.. code-block:: console
+
+   python -m pip install bibliography-io
+
+The optional ``colrev`` extra is for legacy compatibility modules, not the
+standalone core API. Markdown reference-list parsing is pending an optional
+backend; Markdown table writing is included in the core.
+
+Quick example
+-------------
+
+.. code-block:: python
+
+   from bibliography_io import load_records, write_records
+
+   records = load_records("references.bib")
+   write_records(records, "references.ris")
+
+File APIs infer formats from recognized filename suffixes. String APIs require
+an explicit format:
+
+.. code-block:: python
+
+   from bibliography_io import dumps, loads
+
+   records = loads("@article{example, title={An example}}", format="bib")
+   bibtex = dumps(records, format="bib")
+
+See :doc:`usage` for supported formats and :doc:`api` for the public interface.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Documentation
+
+   usage
+   api

bibliography_io-0.1.0/docs/make.bat

@@ -0,0 +1,21 @@
+@ECHO OFF
+
+pushd %~dp0
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure Sphinx is installed.
+	echo.
+	popd
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+popd