oaipmh 3.0.0__tar.gz

oaipmh-3.0.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/
+.direnv/
+.pytest_cache/

oaipmh-3.0.0/CHANGELOG.md

@@ -0,0 +1,266 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.0.0] — 2026-04-15
+
+First release under the `oaipmh` distribution name on PyPI. This release marks the
+maintenance fork from [`infrae/pyoai`](https://github.com/infrae/pyoai) and brings the
+codebase onto modern Python packaging and tooling. The public API and the
+`from oaipmh import ...` import path are unchanged.
+
+### Breaking Changes
+
+- Renamed PyPI distribution from `pyoai` to `oaipmh`. Existing consumers must update
+  their dependency declarations; no application code changes are required.
+- Minimum supported Python version raised to 3.10. Python 2 and Python 3.9 and earlier
+  are no longer supported.
+- Removed the `six` dependency; the package now relies exclusively on native Python 3
+  APIs.
+
+### Added
+
+- PEP 621 metadata in `pyproject.toml` with [Hatchling](https://hatch.pypa.io/) as the
+  build backend.
+- `uv.lock` for reproducible dependency resolution.
+- [`uv`](https://docs.astral.sh/uv/)-based GitHub Actions CI covering Python 3.10 – 3.13.
+- GitHub Actions workflow (`publish.yml`) for automated PyPI publishing via
+  [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC; no
+  long-lived tokens stored in the repository).
+- Reproducible development environment via a [Nix](https://nixos.org/) flake and
+  [`direnv`](https://direnv.net/) integration.
+- `pytest` configuration replacing the legacy `runtests.sh` entry point.
+- `CONTRIBUTING.md` with development setup, commit conventions, and the release process.
+- `CHANGELOG.md` (this file), superseding `HISTORY.txt`.
+- `ETH Library — Data Science and Research Support <dsr@library.ethz.ch>` maintainer
+  entry alongside the existing Jaime Cardozo entry.
+
+### Changed
+
+- Build backend migrated from legacy `setup.py` / `setup.cfg` to Hatchling via
+  `pyproject.toml`.
+- Development status classifier raised from `4 - Beta` to `5 - Production/Stable`.
+- Version jumped from `2.5.2pre` to `3.0.0` to reflect the breaking distribution rename
+  and the Python version floor.
+- README rewritten and expanded; converted from reStructuredText (`README.rst`) to
+  Markdown (`README.md`).
+- License file renamed from `LICENSE.txt` to `LICENSE` and prepended with an ETH Zurich
+  copyright notice alongside the original Infrae notice.
+- Wheel and sdist contents scoped via explicit `tool.hatch.build` include/exclude
+  lists, so consumers no longer receive test fixtures or local development files.
+- Bare imports inside the package converted to relative imports.
+
+### Fixed
+
+- Replaced deprecated `datetime.utcnow()` with timezone-aware
+  `datetime.now(timezone.utc)` equivalents (Python 3.12+ deprecation).
+- Replaced `lxml.etree.XPath.evaluate()` calls with direct callable syntax for
+  compatibility with `lxml` 5.x.
+- Replaced `unicode()` with `str()` for Python 3 compatibility.
+- Replaced `pkg_resources` with `importlib.metadata` for distribution version lookup.
+- Replaced removed unittest assertion aliases dropped in Python 3.12.
+- Removed the `unittest.makeSuite` helper, which was dropped in Python 3.13.
+- Renamed the internal test helper `TestError` to `FakeRequestError` to avoid pytest's
+  `PytestCollectionWarning` on classes prefixed with `Test`.
+
+### Removed
+
+- Python 2 compatibility shims across the package and tests.
+- `six` dependency.
+- Legacy packaging files: `setup.py`, `setup.cfg`, `tox.ini`, `MANIFEST.in`, and
+  `.travis.yml`.
+- `runtests.sh` (replaced by `pytest`).
+- Non-functional Python 2 data generation scripts.
+- Outdated `doc/` directory.
+- Legacy Mercurial files.
+- `HISTORY.txt` (content migrated to this file).
+
+---
+
+## [2.5.1] — 2022-03-08
+
+### Added
+
+- Customizable client retry policy.
+- Python 3.8 compatibility.
+
+### Fixed
+
+- Do not resume `ListRecord` requests when no result was returned.
+
+## [2.5.0] — 2017-07-03
+
+### Added
+
+- Python 3 compatibility.
+- Travis CI support and badges.
+
+## [2.4.5] — 2015-12-23
+
+### Added
+
+- Client switch to force harvesting using HTTP GET.
+- Unofficial `GetMetadata` verb in server and client. `GetMetadata` is identical to
+  `GetRecord` but returns only the first element below the `oai:metadata` element,
+  without the OAI envelope.
+
+## [2.4.4] — 2010-09-30
+
+### Changed
+
+- Updated contact info.
+- Migrated code from Subversion to Mercurial.
+
+## [2.4.3] — 2010-08-19
+
+### Fixed
+
+- Convert `lxml.etree._ElementUnicodeResult` and `ElementStringResult` to normal `str`
+  and `unicode` objects to prevent errors when these objects are pickled.
+
+## [2.4.2] — 2010-05-03
+
+### Fixed
+
+- `oai_dc` and `dc` namespace declarations are now declared on the child of the
+  metadata element rather than the document root, per the OAI-PMH specification.
+
+## [2.4.1] — 2009-11-16
+
+### Fixed
+
+- When a date (not a datetime) is specified for the `until` parameter, default to
+  `23:59:59` instead of `00:00:00`.
+
+## [2.4] — 2009-05-04
+
+### Added
+
+- Support for description elements in OAI `Identify` headers, with a `toolkit`
+  description included by default.
+
+## [2.3.1] — 2009-04-24
+
+### Fixed
+
+- Raise the correct error when `from` and `until` parameters have different
+  granularities.
+
+## [2.3] — 2009-04-23
+
+### Changed
+
+- Use `buildout` to create the testrunner and environment, replacing the `test.py`
+  script.
+
+### Fixed
+
+- Handle invalid `dateTime` formats correctly: the server now responds with a
+  `BadArgument` XML error instead of a Python traceback.
+
+## [2.2.1] — 2008-04-04
+
+### Added
+
+- XML declaration to server output.
+- Pretty-printed XML output.
+- Server resumption tokens now work with POST requests.
+
+### Fixed
+
+- Compatibility with `lxml` 2.0.
+- Handle `503` responses from the server correctly in client code.
+
+## [2.2] — 2006-11-20
+
+### Added
+
+- `BatchingServer`, implementing the `IBatchingOAI` interface. Similar to `IOAI` but
+  with `cursor` and `batch_size` arguments on each method, enabling efficient batching
+  OAI servers on top of relational databases.
+- Ability to explicitly pass `None` as the `from` or `until` parameter for an OAI-PMH
+  client.
+- Extra `nsmap` argument on `Server` and `BatchingServer` to customise the namespace
+  prefix to URI mappings used in server output.
+
+### Fixed
+
+- Output encoding bug: output is now correctly encoded as UTF-8.
+
+## [2.1.5] — 2006-09-18
+
+### Fixed
+
+- Compatibility with `lxml` 1.1.
+
+## [2.1.4] — 2006-06-16
+
+### Changed
+
+- Distribute as an egg.
+
+## [2.1.3] — 2006-05-01
+
+### Added
+
+- Infrastructure to handle non-XML-compliant OAI-PMH feeds; an `XMLSyntaxError` is now
+  raised in those cases.
+- `tolerant_datestamp_to_datetime`, a more permissive alternative to
+  `datestamp_to_datetime` for handling malformed datestamps.
+
+### Changed
+
+- Split datestamp handling into a separate `datestamp` module.
+
+## [2.0] — 2006-01-26
+
+### Added
+
+- Support for day-only granularity (`YYYY-MM-DD`) in the client. Calling
+  `updateGranularity` checks with the server (via `identify()`) which granularity it
+  supports; if the server only supports day-level granularity, the client restricts
+  outgoing timestamps to `YYYY-MM-DD`.
+
+## [2.0b1] — 2005-11-21
+
+### Added
+
+- Framework for implementing OAI-PMH-compliant servers.
+- Extended testing infrastructure.
+
+### Changed
+
+- Package structure is now an `oaipmh` namespace package; client functionality moved
+  to `oaipmh.client`.
+- Refactored `oaipmh.py` to share code between the client and server.
+- Switched from the `libxml2` Python wrappers to the `lxml` binding.
+- `listRecords`, `listIdentifiers`, and `listSets` now return iterators instead of
+  lists (previously hacked via `__getitem__`). Existing call sites can wrap the result
+  in `list()` if needed.
+
+## [1.0.1]
+
+### Fixed
+
+- Typo in `oaipmh.py`.
+
+## [1.0]
+
+### Added
+
+- `encoding` parameter to the `serialize` call, fixing a Unicode bug.
+
+## [0.7.4]
+
+### Fixed
+
+- Harvested records with `<header status="deleted">` are no longer stored in the
+  catalog. Previously they could be treated as normal records even though they merely
+  indicate that the metadata set is no longer on the OAI service.
+
+## [0.7]
+
+Initial public release.

oaipmh-3.0.0/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# Contributing
+
+Thank you for your interest in contributing to `oaipmh`. Bug reports, feature proposals, and pull requests are welcome.
+
+## Local development
+
+Three setup paths are supported, in order of preference.
+
+### Option A — Nix flake with direnv (recommended)
+
+The repository ships a reproducible [Nix](https://nixos.org/) flake with [direnv](https://direnv.net/) integration. This provisions the correct Python, [`uv`](https://docs.astral.sh/uv/), and system dependencies automatically.
+
+Activate the environment the first time you enter the repository:
+
+```bash
+direnv allow
+```
+
+Run the test suite:
+
+```bash
+uv run pytest
+```
+
+### Option B — `uv` only
+
+If you have [`uv`](https://docs.astral.sh/uv/) installed directly and prefer not to use Nix.
+
+Synchronise dependencies from `uv.lock`:
+
+```bash
+uv sync
+```
+
+Run the test suite:
+
+```bash
+uv run pytest
+```
+
+### Option C — plain `pip` and `venv`
+
+Standard Python tooling works with no additional prerequisites beyond a Python 3.10+ interpreter.
+
+Create and activate a virtual environment:
+
+```bash
+python3 -m venv .venv
+```
+
+```bash
+source .venv/bin/activate
+```
+
+Install the package in editable mode together with the test dependencies:
+
+```bash
+pip install -e ".[test]"
+```
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+## Commit conventions
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). Common prefixes used in this repository:
+
+- `feat:` — a new feature.
+- `fix:` — a bug fix.
+- `docs:` — documentation-only changes.
+- `refactor:` — a code change that neither fixes a bug nor adds a feature.
+- `test:` — adding or correcting tests.
+- `build:` — changes to the build system or packaging.
+- `ci:` — changes to CI configuration.
+- `chore:` — maintenance tasks that don't fit the categories above.
+
+Keep commits atomic: one logical change per commit, with a clear message that explains the *why* rather than restating the diff.
+
+## Branching strategy
+
+This project follows a [trunk-based development](https://trunkbaseddevelopment.com/) model. All work lands on `main` through short-lived topic branches (typically merged within a few days). Long-lived branches — including release branches — are avoided because they drift from `main`, accumulate merge conflicts, and fragment CI signal.
+
+Use a short, purpose-driven prefix that matches the commit type: `feat/`, `fix/`, `docs/`, `chore/`, `ci/`.
+
+A `release/<version>` branch is only appropriate for exceptional, coordinated releases that cannot land as a single short-lived branch (for example, the initial `release/v3.0.0` that carried the fork takeover from `pyoai` to `oaipmh`). The default path for a release is a tag on `main`, not a release branch.
+
+The [Releases](#releases) section below picks up from here and walks through the tag-and-publish flow.
+
+## Pull requests
+
+External contributors should [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) `eth-library/oaipmh` on GitHub, push changes to a branch on their fork, and open a pull request from that branch. Maintainers with push access to `eth-library/oaipmh` may open branches directly on the repository.
+
+- Target the `main` branch of `eth-library/oaipmh`.
+- Keep the PR focused on a single topic; open separate PRs for unrelated changes.
+- Ensure the test suite passes locally (`uv run pytest`) before opening the PR.
+- CI must be green before a PR can be merged.
+- Provide enough context in the description for a reviewer to understand the motivation, the approach, and any trade-offs.
+
+## Releases
+
+Releases follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The release process is:
+
+1. Merge release-bound changes into `main` as individual short-lived topic branches. Do not open a long-lived release branch; cut the release from `main` once the desired commits have landed.
+2. Tag the merge commit with `vX.Y.Z` and push the tag.
+3. Create a draft GitHub Release against the tag, using the relevant `CHANGELOG.md` section as the release notes.
+4. Review the draft release; when publishing it, the `publish.yml` workflow uploads the distribution to PyPI through [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC — no tokens stored in the repository).
+
+The fork jumped directly from `2.5.2pre` (an unreleased development version under the upstream `pyoai` distribution name) to `3.0.0` because the PyPI distribution was renamed from `pyoai` to `oaipmh` and the minimum supported Python version was raised to 3.10 — both of which are breaking changes under SemVer.

oaipmh-3.0.0/LICENSE

@@ -0,0 +1,31 @@
+Copyright © 2026 ETH Zurich, Jaime Cardozo; ETH Library.
+
+Copyright (c) 2003-2006 Infrae. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+  1. Redistributions of source code must retain the above copyright
+     notice, this list of conditions and the following disclaimer.
+   
+  2. Redistributions in binary form must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in
+     the documentation and/or other materials provided with the
+     distribution.
+
+  3. Neither the name of Infrae nor the names of its contributors may
+     be used to endorse or promote products derived from this software
+     without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INFRAE OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

oaipmh-3.0.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: oaipmh
+Version: 3.0.0
+Summary: Python implementation of the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH)
+Project-URL: Repository, https://github.com/eth-library/oaipmh
+Project-URL: Original-Repository, https://github.com/infrae/pyoai
+Project-URL: Changelog, https://github.com/eth-library/oaipmh/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/eth-library/oaipmh/issues
+Author-email: Infrae <info@infrae.com>
+Maintainer-email: Jaime Cardozo <jaime.cardozo@library.ethz.ch>, ETH Library — Data Science and Research Support <dsr@library.ethz.ch>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: OAI-PMH,archive,harvesting,metadata,xml
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: lxml
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'

oaipmh-3.0.0/README.md

@@ -0,0 +1,83 @@
+# oaipmh
+
+[![PyPI version](https://img.shields.io/pypi/v/oaipmh)](https://pypi.org/project/oaipmh/)
+[![Python versions](https://img.shields.io/pypi/pyversions/oaipmh)](https://pypi.org/project/oaipmh/)
+[![CI](https://github.com/eth-library/oaipmh/actions/workflows/ci.yml/badge.svg)](https://github.com/eth-library/oaipmh/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue)](./LICENSE)
+
+A Python library for working with [OAI-PMH version 2](https://www.openarchives.org/OAI/openarchivesprotocol.html) — harvest metadata from existing repositories using the client, or expose your own repository using the server. This is a maintained fork of [`infrae/pyoai`](https://github.com/infrae/pyoai).
+
+## Installation
+
+Install the latest release from PyPI:
+
+```bash
+pip install oaipmh
+```
+
+Requires Python 3.10 or newer.
+
+## Quickstart
+
+A minimal client that lists records from an OAI-PMH endpoint using the Dublin Core metadata prefix:
+
+```python
+from oaipmh.client import Client
+from oaipmh.metadata import MetadataRegistry, oai_dc_reader
+
+URL = "http://uni.edu/ir/oaipmh"
+
+registry = MetadataRegistry()
+registry.registerReader("oai_dc", oai_dc_reader)
+client = Client(URL, registry)
+
+for record in client.listRecords(metadataPrefix="oai_dc"):
+    print(record)
+```
+
+## Migrating from pyoai
+
+If you already depend on `pyoai`, migration is a dependency swap:
+
+- Replace `pyoai` with `oaipmh` in your requirements (`pip install oaipmh`).
+- Import paths are unchanged — `from oaipmh import ...` continues to work.
+- The minimum supported Python version is 3.10.
+
+No application code changes are required beyond the dependency rename. See [Why this fork](#why-this-fork) for background.
+
+## Why this fork
+
+`oaipmh` is a maintained fork of [`infrae/pyoai`](https://github.com/infrae/pyoai), which has received no substantive changes since March 2022. The public API and import path are unchanged; only the PyPI distribution name has changed, from `pyoai` to `oaipmh`, to distinguish the maintained release from the abandoned upstream package.
+
+Maintenance since the fork has focused on bringing the codebase onto current Python infrastructure while preserving behaviour for existing consumers:
+
+- Python 3.10+ baseline; legacy Python 2 compatibility code removed.
+- Deprecated `datetime.utcnow()` replaced with timezone-aware alternatives.
+- Modern packaging using [PEP 621](https://peps.python.org/pep-0621/) metadata and the [Hatchling](https://hatch.pypa.io/) build backend.
+- CI pipeline rebuilt on [`uv`](https://docs.astral.sh/uv/), replacing the legacy `tox` configuration.
+- Reproducible development environment via a [Nix](https://nixos.org/) flake and [direnv](https://direnv.net/).
+- Test suite modernised and running green across Python 3.10 – 3.13.
+
+## Scope
+
+`oaipmh` is a maintained fork. Bug fixes and compatibility work are the primary focus; well-scoped feature proposals are welcome via GitHub Issues and Pull Requests. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for guidelines.
+
+## Contributing
+
+Issues and pull requests are welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for local development setup, branch naming, commit conventions, and the release process.
+
+## Support
+
+Bug reports and questions are accepted via [GitHub Issues](https://github.com/eth-library/oaipmh/issues). Maintenance is best-effort with no formal SLA.
+
+## Acknowledgements
+
+We are grateful to the original [`infrae/pyoai`](https://github.com/infrae/pyoai) authors at Infrae and to the many community contributors who built and maintained this library over two decades; this fork would not exist without their work.
+
+## License
+
+Distributed under the BSD-3-Clause License.  
+Copyright © 2026 ETH Zurich, Jaime Cardozo; ETH Library.  
+Based on [`infrae/pyoai`](https://github.com/infrae/pyoai) by Infrae and community contributors.
+
+See [`LICENSE`](./LICENSE) for the full license terms and [`CHANGELOG.md`](./CHANGELOG.md) for the release history.

oaipmh-3.0.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "oaipmh"
+version = "3.0.0"
+description = "Python implementation of the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH)"
+requires-python = ">=3.10"
+license = "BSD-3-Clause"
+authors = [
+    { name = "Infrae", email = "info@infrae.com" },
+]
+maintainers = [
+    { name = "Jaime Cardozo", email = "jaime.cardozo@library.ethz.ch" },
+    { name = "ETH Library — Data Science and Research Support", email = "dsr@library.ethz.ch" },
+]
+dependencies = ["lxml"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: BSD License",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Environment :: Web Environment",
+]
+keywords = ["OAI-PMH", "xml", "archive", "metadata", "harvesting"]
+
+[project.urls]
+Repository = "https://github.com/eth-library/oaipmh"
+Original-Repository = "https://github.com/infrae/pyoai"
+Changelog = "https://github.com/eth-library/oaipmh/blob/main/CHANGELOG.md"
+Issues = "https://github.com/eth-library/oaipmh/issues"
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[tool.pytest.ini_options]
+testpaths = ["src/oaipmh/tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oaipmh"]
+exclude = [
+    "src/oaipmh/tests",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/oaipmh",
+    "pyproject.toml",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+]
+exclude = [
+    "src/oaipmh/tests",
+]

oaipmh-3.0.0/src/oaipmh/__init__.py

@@ -0,0 +1 @@
+#