python-re3data-v2 0.1.0__py3-none-any.whl

python_re3data_v2-0.1.0.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.5
+Name: python-re3data-v2
+Version: 0.1.0
+Summary: The Pythonic client for the re3data API (v40, schema 4.0).
+Project-URL: Changelog, https://github.com/AstrayChao/python-re3data-v2/blob/master/CHANGELOG.md
+Project-URL: Repository, https://github.com/AstrayChao/python-re3data-v2
+Project-URL: Issues, https://github.com/AstrayChao/python-re3data-v2/issues
+Author: data-sync maintainers
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,api-client,metadata,re3data,repositories,research data
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Text Processing :: Markup :: XML
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.28
+Provides-Extra: all
+Requires-Dist: typer>=0.16; extra == 'all'
+Provides-Extra: cli
+Requires-Dist: typer>=0.16; extra == 'cli'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# python-re3data-v2
+
+**The Pythonic client for the [re3data](https://www.re3data.org) API — v40 · schema 4.0 · Python 3.14+**
+
+[![PyPI version](https://img.shields.io/pypi/v/python-re3data-v2?logo=pypi&logoColor=white)](https://pypi.org/project/python-re3data-v2/)
+[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-3776ab?logo=python&logoColor=white)](pyproject.toml)
+[![Tests](https://github.com/AstrayChao/python-re3data-v2/actions/workflows/test.yml/badge.svg)](https://github.com/AstrayChao/python-re3data-v2/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-261230?logo=ruff&logoColor=white)](https://docs.astral.sh/ruff/)
+[![Original repo archived](https://img.shields.io/badge/original%20repo-archived-lightgrey?logo=github)](https://github.com/afuetterer/python-re3data)
+
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+</div>
+
+---
+
+> [!NOTE]
+> **Why this fork exists** — the original client [`python-re3data`](https://github.com/afuetterer/python-re3data)
+> by Heinz-Alexander Fütterer (MIT) has been **archived** and targets the deprecated
+> `/api/beta` endpoints (schema 2-2). This repository is an independent re-implementation,
+> built from scratch against the current **v40 REST API** and the
+> [re3data metadata schema 4.0](https://doi.org/10.48440/re3.014), keeping the familiar
+> architecture and dict conventions of the original.
+
+> [!WARNING]
+> **Not production-ready yet.** This library is young: the v40 API and schema 4.0 are new,
+> and edge cases may still exist. **Use with caution in production environments until the
+> first stable release.** 非正式发布阶段，请谨慎用于生产环境。
+
+## ✨ Highlights
+
+| | |
+|---|---|
+| 🚀 **v40 endpoints** | `GET /api/v40/repositories` · `GET /api/v40/repository/{id}` |
+| 🧬 **Typed schema 4.0 models** | Hand-written dataclasses mirroring the [official XSD](https://schema.re3data.org/4-0/re3dataV4-0.xsd) — no `xsdata` |
+| 🛡️ **Drift-tolerant parsing** | Unknown vocabulary values / malformed dates never break a parse |
+| ⚡ **Sync + async** | `Client` and `AsyncClient` on top of `httpx` |
+| 🔄 **Flexible serialization** | `dataclass` · `dict` · `json` · `xml` · `csv` · `response` |
+| 🎛️ **Facet filters** | ~30 v40 filter facets via a single `filters` mapping |
+| 🪶 **Minimal footprint** | Python 3.14+, the only runtime dependency is `httpx` |
+
+## 📦 Installation
+
+```bash
+pip install python-re3data-v2        # or: uv add python-re3data-v2
+```
+
+With the optional CLI:
+
+```bash
+pip install 'python-re3data-v2[cli]'
+```
+
+## 🚀 Quick start
+
+### Module-level manager (synchronous)
+
+```python
+import re3data
+
+summaries = re3data.repositories.list(query="UCL")
+for summary in summaries:
+    print(summary.id, summary.doi, summary.name, summary.href)
+
+repository = re3data.repositories.get("r3d100012417")
+print(repository.repositoryName.value)   # "UCL Discovery"
+print(repository.identifiers.doi)        # "https://doi.org/10.17616/R34F41"
+print(repository.subject[0].subjectId)   # "4" (DFG classification id)
+print(repository.entryDate)              # datetime.date(2017, 7, 21)
+```
+
+### Explicit clients
+
+```python
+from re3data import Client, AsyncClient
+
+client = Client()
+repository = client.repositories.get("r3d100012417")
+
+async with AsyncClient() as async_client:
+    repository = await async_client.repositories.get("r3d100012417")
+```
+
+### Return types
+
+```python
+from re3data import Client, ReturnType
+
+client = Client()
+payload = client.repositories.get("r3d100012417", return_type=ReturnType.DICT)
+```
+
+`ReturnType.DICT` reproduces the document with XML-style keys (`repositoryUrl`,
+`identifiers.re3data`, `subject[].subjectId`, …), localized elements as
+`{"value": ..., "language": ...}` and dates as ISO-8601 strings — the same
+conventions the original `python-re3data` established, so existing consumers
+keep working with minimal changes.
+
+### Facet filters
+
+The v40 list endpoint supports ~30 facet filters, serialized as repeated
+`name[]` query parameters:
+
+```python
+client.repositories.list(
+    query="climate",
+    filters={"countries": ["DEU", "NZL"], "certificates": "CoreTrustSeal"},
+)
+```
+
+### CLI
+
+```console
+$ re3data repository get r3d100012417 --return-type json
+$ re3data repository list --query "UCL" --return-type csv
+```
+
+## 🔀 Differences vs. the original `python-re3data`
+
+| Aspect | python-re3data 0.10 | python-re3data-v2 |
+|---|---|---|
+| API | `/api/beta` (deprecated) | `/api/v40` (current) |
+| Metadata schema | 2-2 | **4.0** (August 2023) |
+| Python | ≥ 3.10 | **≥ 3.14** |
+| XML binding | `xsdata` codegen | stdlib `ElementTree` + hand-written models |
+| List entry fields | id, doi, link | id, doi, **name**, link |
+| `dataframe` return type | ✅ (requires pandas) | ❌ (dropped; `csv` is built-in) |
+| Facet filters | `query` only | `query` + `filters` mapping |
+
+A complete field-by-field mapping between schema 2-2 and 4.0 is available in
+[docs/schema-mapping.md](docs/schema-mapping.md); the underlying research and
+migration notes live in [docs/research.md](docs/research.md).
+
+## ⚠️ Known upstream issues
+
+- `GET /api/v40/repositories` **without** a `query`/filter currently fails with
+  HTTP 500 server-side (the deprecated beta endpoint behaves the same). Listing
+  everything therefore requires a query or filter for now; the client surfaces
+  the error transparently.
+- The API only serves `application/xml` — there is no JSON representation.
+- Live data occasionally deviates from the XSD vocabularies (e.g.
+  `"institutional membership"` vs. `"institutionalMembership"`). Vocabulary
+  fields are typed as plain `str` and parsed verbatim, so unknown values never
+  raise.
+
+## 📚 API reference
+
+`re3data.repositories` · `re3data.Client` · `re3data.AsyncClient`
+
+| Method | Description |
+|---|---|
+| `repositories.list(query=None, filters=None, return_type=..., count=False)` | List repositories, optionally filtered |
+| `repositories.get(repository_id, return_type=...)` | Fetch one repository by its re3data id |
+
+<details>
+<summary>Reference enums exported for convenience</summary>
+
+`RepositoryType`, `ProviderType`, `DatabaseAccessType`, `DatabaseAccessRestriction`,
+`DataAccessType`, `DataAccessRestriction`, `DataUploadType`, `DataUploadRestriction`,
+`InstitutionType`, `ResponsibilityType`, `RelatedRepositoryType`, `YesNo`
+
+</details>
+
+## 🛠️ Development
+
+```bash
+uv sync --all-groups   # Python 3.14 environment
+uv run pytest          # unit + integration (offline, real v40 XML fixtures)
+uv run pytest -m e2e   # live API smoke tests
+uv run ruff check .    # lint
+```
+
+## 📄 License
+
+[MIT](LICENSE) — same as the original project. The architecture and dict
+conventions are deliberately compatible with
+[python-re3data](https://github.com/afuetterer/python-re3data) by
+Heinz-Alexander Fütterer; this repository shares no code with it.
+
+## 🙏 Credits
+
+- [python-re3data](https://github.com/afuetterer/python-re3data) — the original
+  Pythonic client this project continues, in spirit and API shape.
+- [re3data.org](https://www.re3data.org) — registry of research data
+  repositories, Karlsruhe Institute of Technology / FIZ Karlsruhe.

python_re3data_v2-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+re3data/__init__.py,sha256=mjaOvHQacouNp1kSaVmO02laplIZufDJIMlIX_QmT0w,865
+re3data/__main__.py,sha256=EQ5SBDg5guM7tneBKSCyEQHlHO4qwZ3kUQ_zur4E5OQ,116
+re3data/_cli.py,sha256=QGLWrwuQMO-JpN-UbOokiML2b81FVsWR2gybIeYOyD0,3371
+re3data/_exceptions.py,sha256=bfIiXGRChBXPuFbb4IBGjm448Abh0JpGXdhyGPUR-Cc,284
+re3data/_parser.py,sha256=McW3T9-3cNx_DwtxAZCO-4ZAfV_Ay53-W3EEH6qm7jI,17796
+re3data/_response.py,sha256=NfJxNp02RStGD5Y9Zwi6xTB3LZSpVH8JPcshJqdnx3I,942
+re3data/_serializer.py,sha256=fL0P_JUf9c6KiL7xES94K_96L11WjBWwTzdhM3B2o-0,2758
+re3data/_client/__init__.py,sha256=NMKXqeaP8dw20XHVakHq1Bgtx3Ew0K_FovPIK_VGVII,362
+re3data/_client/_async.py,sha256=JyBIkWwrFB93Et44NUf_tebvlVohhJTPN7ncQbeMZ8Q,5695
+re3data/_client/_sync.py,sha256=RahdqhYhI2u6bdpqnY3URZccVCm7vPEsP42buVs15UQ,5639
+re3data/_client/base.py,sha256=H7nUuGHwyCpzehpXF8RbLOpwklak19nl_hMjqPBWf8I,5288
+re3data/_resources/__init__.py,sha256=UfXmXRBbD1RzjGcnW0xp3rfyXZNaR0KeRT7n2Cx4Q6Y,351
+re3data/_resources/repository.py,sha256=dwVZvcE-qAxJLQl9rMCGEuo3f5bDjyqdfa5Upus8X28,18726
+re3data/_resources/repository_list.py,sha256=umH1QBcSiG1k_ZWS0V3vm7MP_kzw7wW9wpsHEHhtuB8,1753
+python_re3data_v2-0.1.0.dist-info/METADATA,sha256=FlygnealhMKCpydQLSVN5ycxRpM5fjE3B4nPH3KvALY,8455
+python_re3data_v2-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+python_re3data_v2-0.1.0.dist-info/entry_points.txt,sha256=P8OdB3PXzCCxLRMk7Seom7t36rHOk6erUlaaik3SHNo,49
+python_re3data_v2-0.1.0.dist-info/licenses/LICENSE,sha256=r4wQ3b_41L-VoaX1Hgy2FeSPtcmiuu0MPhZyO9NzaEk,1078
+python_re3data_v2-0.1.0.dist-info/RECORD,,

python_re3data_v2-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

python_re3data_v2-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+re3data = re3data.__main__:app

python_re3data_v2-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 data-sync maintainers
+
+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.

re3data/__init__.py

@@ -0,0 +1,31 @@
+"""python-re3data-v2: the Pythonic client for the re3data API (v40, schema 4.0)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__: str = version("python-re3data-v2")
+except PackageNotFoundError:  # pragma: no cover - package not installed
+    __version__ = "0.0.0"
+
+from re3data._client import AsyncClient, Client, ReturnType
+from re3data._exceptions import Re3dataError, RepositoryNotFoundError
+from re3data._resources import Link, Re3Data, Repository, RepositoryList, RepositorySummary
+from re3data._response import Response
+
+__all__ = (
+    "AsyncClient",
+    "Client",
+    "Link",
+    "Re3Data",
+    "Re3dataError",
+    "Repository",
+    "RepositoryList",
+    "RepositoryNotFoundError",
+    "RepositorySummary",
+    "Response",
+    "ReturnType",
+    "__version__",
+)
+
+_client = Client()
+repositories = _client.repositories

re3data/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point of the python-re3data-v2 CLI."""
+
+from re3data._cli import app
+
+if __name__ == "__main__":
+    app()

re3data/_cli.py

@@ -0,0 +1,114 @@
+"""python-re3data-v2 command line interface."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+from typing import Annotated
+
+from rich.console import Console
+
+import re3data
+from re3data._client import ReturnType
+from re3data._exceptions import RepositoryNotFoundError
+
+logger = logging.getLogger(__name__)
+
+try:
+    import typer
+except ImportError:  # pragma: no cover - depends on optional extra
+    logger.error("`typer` is missing. Please run 'pip install python-re3data-v2[cli]' to use the CLI.")
+    sys.exit(1)
+
+console = Console()
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+app = typer.Typer(no_args_is_help=True, context_settings=CONTEXT_SETTINGS)
+repositories_app = typer.Typer(no_args_is_help=True)
+app.add_typer(repositories_app, name="repository")
+
+
+def _version_callback(show_version: bool) -> None:
+    # Ref: https://typer.tiangolo.com/tutorial/options/version/
+    if show_version:
+        console.print(re3data.__version__)
+        raise typer.Exit(code=0)
+
+
+def _write_to_file(response: object, outfile: Path | None) -> None:
+    """Write the given response to the specified file, asking before overwriting."""
+    if outfile and outfile.exists():
+        overwrite = typer.confirm(f"{outfile} already exists. Do you want to overwrite it?")
+        if not overwrite:
+            return
+    if outfile:
+        outfile.write_text(str(response), encoding="utf-8")
+
+
+@app.callback(context_settings=CONTEXT_SETTINGS)
+def callback(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Show python-re3data-v2 version and exit.",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    """python-re3data-v2: the Pythonic client for the re3data API (v40, schema 4.0)."""
+
+
+@repositories_app.command("list")
+def list_repositories(
+    query: Annotated[
+        str | None,
+        typer.Option(
+            help="A query to filter the results. If provided, only repositories matching the query will be returned."
+        ),
+    ] = None,
+    return_type: ReturnType = ReturnType.DATACLASS,
+    count: bool = False,
+    outfile: Annotated[
+        Path | None,
+        typer.Option(
+            file_okay=True,
+            dir_okay=False,
+            writable=True,
+        ),
+    ] = None,
+) -> None:
+    """List the metadata of repositories in the re3data API."""
+    response = re3data.repositories.list(query, return_type, count)
+    _write_to_file(response, outfile)
+    console.print(response)
+
+
+@repositories_app.command("get")
+def get_repository(
+    repository_id: Annotated[
+        str,
+        typer.Argument(help="The identifier of the repository to retrieve, e.g. 'r3d100012417'."),
+    ],
+    return_type: ReturnType = ReturnType.DATACLASS,
+    outfile: Annotated[
+        Path | None,
+        typer.Option(
+            file_okay=True,
+            dir_okay=False,
+            writable=True,
+        ),
+    ] = None,
+) -> None:
+    """Get the metadata of a specific repository."""
+    try:
+        response = re3data.repositories.get(repository_id, return_type)
+    except RepositoryNotFoundError as error:
+        console.print(str(error), style="bold red")
+        raise typer.Exit(code=1) from error
+    _write_to_file(response, outfile)
+    console.print(response)

re3data/_client/__init__.py

@@ -0,0 +1,14 @@
+"""Clients for the re3data v40 API."""
+
+from re3data._client._async import AsyncClient, AsyncRepositoryManager
+from re3data._client._sync import Client, RepositoryManager
+from re3data._client.base import BASE_URL, ReturnType
+
+__all__ = (
+    "BASE_URL",
+    "AsyncClient",
+    "AsyncRepositoryManager",
+    "Client",
+    "RepositoryManager",
+    "ReturnType",
+)

re3data/_client/_async.py

@@ -0,0 +1,143 @@
+"""The asynchronous client to interact with the re3data v40 API."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Self
+
+import httpx
+
+from re3data._client.base import (
+    BaseClient,
+    Endpoint,
+    ResourceType,
+    ReturnType,
+    _dispatch_return_type,
+    build_query_params,
+    is_valid_return_type,
+)
+from re3data._exceptions import RepositoryNotFoundError
+from re3data._response import Response, _build_response
+
+if TYPE_CHECKING:
+    from re3data._resources import Repository, RepositorySummary
+
+logger = logging.getLogger(__name__)
+
+
+async def log_response(response: httpx.Response) -> None:
+    """Log method, URL and status code of an HTTP response on the debug level."""
+    logger.debug("[http] Response: %s %s - Status %s", response.request.method, response.request.url, response.status_code)
+
+
+class AsyncRepositoryManager:
+    """An async manager for interacting with the repositories endpoints."""
+
+    def __init__(self, client: AsyncClient) -> None:
+        self._client = client
+
+    async def list(
+        self,
+        query: str | None = None,
+        return_type: ReturnType = ReturnType.DATACLASS,
+        count: bool = False,
+        filters: dict[str, str | list[str] | tuple[str, ...]] | None = None,
+    ) -> list[RepositorySummary] | Response | list[dict] | str | int:
+        """List the metadata of repositories in the re3data API.
+
+        Args:
+            query: A query string to filter the results. If provided, only
+                repositories matching the query will be returned.
+            return_type: The desired return type for the API resource.
+                Defaults to `ReturnType.DATACLASS`.
+            count: Whether to return the total number of matching items
+                instead of a list of repositories.
+            filters: Optional facet filters for the v40 endpoint, e.g.
+                ``{"countries": ["DEU", "NZL"], "dataAccess": "open"}``.
+
+        Returns:
+            Depending on the `return_type`, this is a list of
+            RepositorySummary objects, an HTTP response, a dictionary/JSON/CSV
+            representation, the original XML, or the count of repositories.
+
+        Raises:
+            ValueError: If an invalid `return_type` is provided.
+            httpx.HTTPStatusError: If the server returned an error status code >= 500.
+        """
+        is_valid_return_type(return_type)
+        params = build_query_params(query, filters)
+        response = await self._client._request(Endpoint.REPOSITORY_LIST.value, params)
+        return _dispatch_return_type(response, ResourceType.REPOSITORY_LIST, return_type, count)
+
+    async def get(self, repository_id: str, return_type: ReturnType = ReturnType.DATACLASS) -> Repository | Response | dict | str:
+        """Get the metadata of a specific repository.
+
+        Args:
+            repository_id: The identifier of the repository to retrieve,
+                e.g. "r3d100012417".
+            return_type: The desired return type for the API resource.
+                Defaults to `ReturnType.DATACLASS`.
+
+        Returns:
+            Depending on the `return_type`, this is a Repository object, an
+            HTTP response, a dictionary/JSON/CSV representation or the
+            original XML.
+
+        Raises:
+            ValueError: If an invalid `return_type` is provided.
+            httpx.HTTPStatusError: If the server returned an error status code >= 500.
+            RepositoryNotFoundError: If no repository with the given ID is found.
+        """
+        is_valid_return_type(return_type)
+        response = await self._client._request(Endpoint.REPOSITORY.value.format(repository_id=repository_id))
+        if response.status_code == httpx.codes.NOT_FOUND:
+            raise RepositoryNotFoundError(f"No repository with id '{repository_id}' available at {response.url}.")
+        return _dispatch_return_type(response, ResourceType.REPOSITORY, return_type)
+
+
+class AsyncClient(BaseClient):
+    """An async client that interacts with the re3data v40 API.
+
+    Examples:
+        >>> async with AsyncClient() as client:
+        ...     await client.repositories.get("r3d100012417")
+        Repository(identifiers=Identifiers(re3data='r3d100012417', doi='https://doi.org/10.17616/R34F41'), ...)
+    """
+
+    _client: httpx.AsyncClient
+
+    def __init__(self, transport: httpx.AsyncBaseTransport | None = None) -> None:
+        """Initialize the client.
+
+        Args:
+            transport: An optional custom httpx transport, e.g. for testing.
+        """
+        super().__init__(httpx.AsyncClient, transport)
+        self._client.event_hooks["response"] = [log_response]
+        self._repository_manager: AsyncRepositoryManager = AsyncRepositoryManager(self)
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client and release connections."""
+        await self._client.aclose()
+
+    async def _request(self, path: str, query_params: list[tuple[str, str]] | None = None) -> Response:
+        """Send an HTTP GET request to the specified API endpoint.
+
+        Raises:
+            httpx.HTTPStatusError: If the server returned an error status code >= 500.
+        """
+        http_response = await self._client.get(path, params=query_params)
+        if http_response.is_server_error:
+            http_response.raise_for_status()
+        return _build_response(http_response)
+
+    @property
+    def repositories(self) -> AsyncRepositoryManager:
+        """The repository manager of this client."""
+        return self._repository_manager