pbn-client 0.1.0__tar.gz

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

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Run tests
+        run: uv run --isolated pytest -q
+      - name: Lint
+        run: uv run --isolated ruff check .

pbn_client-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+
+# Secrets / local env
+.env
+.env.*
+!.env.example
+!.env.sample
+*.pem
+*.key
+
+# IDE / editor
+.idea/
+.vscode/
+*.sublime-workspace
+
+# OS turds
+.DS_Store
+Thumbs.db
+desktop.ini
+._*

pbn_client-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
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: detect-private-key
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.0
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

pbn_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-2026 Michal Pasternak
+
+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.

pbn_client-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: pbn-client
+Version: 0.1.0
+Summary: Framework-independent client for the Polish Bibliography Network API
+Project-URL: Homepage, https://github.com/iplweb/pbn-client
+Project-URL: Repository, https://github.com/iplweb/pbn-client
+Project-URL: Issues, https://github.com/iplweb/pbn-client/issues
+Author-email: Michał Pasternak <michal.dtz@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,bibliography,pbn,polish-bibliography-network
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.15,>=3.10
+Requires-Dist: requests<3,>=2.28
+Requires-Dist: simplejson<5,>=3.19
+Description-Content-Type: text/markdown
+
+# pbn-client
+
+[![CI](https://github.com/iplweb/pbn-client/actions/workflows/ci.yml/badge.svg)](https://github.com/iplweb/pbn-client/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`pbn-client` is a framework-independent Python client for communication with
+the Polish Bibliography Network (PBN) API. It provides HTTP authentication,
+pagination, dictionary and publication endpoints, and institution-profile
+statement operations.
+
+The package does not depend on Django or an external error-reporting service.
+Projects that persist downloaded PBN data in Django should use the companion
+`django-pbn-client` package.
+
+## Installation
+
+```console
+pip install pbn-client
+```
+
+Python 3.10 through 3.14 is supported.
+
+## Basic usage
+
+```python
+from pbn_client import PBNClient, RequestsTransport
+
+transport = RequestsTransport(
+    app_id="application-id",
+    app_token="application-token",
+    base_url="https://pbn-micro-alpha.opi.org.pl",
+    user_token="user-token",
+    timeout=(30, 120),
+)
+client = PBNClient(transport)
+
+languages = list(client.get_languages())
+```
+
+Credentials should normally be supplied explicitly. The interactive command
+helpers also understand `PBN_CLIENT_APP_ID`, `PBN_CLIENT_APP_TOKEN`,
+`PBN_CLIENT_BASE_URL`, `PBN_CLIENT_USER_TOKEN`, and
+`PBN_CLIENT_HTTP_TIMEOUT`. A timeout may be a single number or a
+`connect,read` pair.
+
+## Error reporting
+
+The standalone default reporter is a no-op. An application can inject any
+object implementing `ErrorReporter` when it constructs a transport:
+
+```python
+import rollbar
+
+from pbn_client import RequestsTransport
+
+transport = RequestsTransport(
+    "application-id",
+    "application-token",
+    "https://pbn-micro-alpha.opi.org.pl",
+    reporter=rollbar,
+)
+```
+
+The reporter receives only scrubbed diagnostic metadata. Response bodies and
+authentication header values are not sent to it. `LoggingReporter`,
+`NullReporter`, and `set_default_reporter()` are also available for applications
+that prefer a process-wide policy.
+
+## Development
+
+From the repository root:
+
+```console
+uv run --isolated pytest
+uv run ruff check .
+uv build
+```
+
+## License
+
+`pbn-client` is released under the [MIT License](LICENSE).

pbn_client-0.1.0/README.md

@@ -0,0 +1,81 @@
+# pbn-client
+
+[![CI](https://github.com/iplweb/pbn-client/actions/workflows/ci.yml/badge.svg)](https://github.com/iplweb/pbn-client/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`pbn-client` is a framework-independent Python client for communication with
+the Polish Bibliography Network (PBN) API. It provides HTTP authentication,
+pagination, dictionary and publication endpoints, and institution-profile
+statement operations.
+
+The package does not depend on Django or an external error-reporting service.
+Projects that persist downloaded PBN data in Django should use the companion
+`django-pbn-client` package.
+
+## Installation
+
+```console
+pip install pbn-client
+```
+
+Python 3.10 through 3.14 is supported.
+
+## Basic usage
+
+```python
+from pbn_client import PBNClient, RequestsTransport
+
+transport = RequestsTransport(
+    app_id="application-id",
+    app_token="application-token",
+    base_url="https://pbn-micro-alpha.opi.org.pl",
+    user_token="user-token",
+    timeout=(30, 120),
+)
+client = PBNClient(transport)
+
+languages = list(client.get_languages())
+```
+
+Credentials should normally be supplied explicitly. The interactive command
+helpers also understand `PBN_CLIENT_APP_ID`, `PBN_CLIENT_APP_TOKEN`,
+`PBN_CLIENT_BASE_URL`, `PBN_CLIENT_USER_TOKEN`, and
+`PBN_CLIENT_HTTP_TIMEOUT`. A timeout may be a single number or a
+`connect,read` pair.
+
+## Error reporting
+
+The standalone default reporter is a no-op. An application can inject any
+object implementing `ErrorReporter` when it constructs a transport:
+
+```python
+import rollbar
+
+from pbn_client import RequestsTransport
+
+transport = RequestsTransport(
+    "application-id",
+    "application-token",
+    "https://pbn-micro-alpha.opi.org.pl",
+    reporter=rollbar,
+)
+```
+
+The reporter receives only scrubbed diagnostic metadata. Response bodies and
+authentication header values are not sent to it. `LoggingReporter`,
+`NullReporter`, and `set_default_reporter()` are also available for applications
+that prefer a process-wide policy.
+
+## Development
+
+From the repository root:
+
+```console
+uv run --isolated pytest
+uv run ruff check .
+uv build
+```
+
+## License
+
+`pbn-client` is released under the [MIT License](LICENSE).

pbn_client-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pbn-client"
+version = "0.1.0"
+description = "Framework-independent client for the Polish Bibliography Network API"
+readme = "README.md"
+requires-python = ">=3.10,<3.15"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Michał Pasternak", email = "michal.dtz@gmail.com" },
+]
+keywords = ["pbn", "bibliography", "polish-bibliography-network", "api-client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.28,<3",
+    "simplejson>=3.19,<5",
+]
+
+[project.urls]
+Homepage = "https://github.com/iplweb/pbn-client"
+Repository = "https://github.com/iplweb/pbn-client"
+Issues = "https://github.com/iplweb/pbn-client/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1,<10",
+    "ruff>=0.14,<1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pbn_client"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+pythonpath = ["src", "tests"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]

pbn_client-0.1.0/src/pbn_client/__init__.py

@@ -0,0 +1,53 @@
+"""Klient API PBN — czysta, niezależna od frameworka warstwa protokołu.
+
+Pakiet operuje wyłącznie na pojęciach PBN: tokeny, URL-e, PBN UID-y, JSON-y
+i flagi bool. Nie zna modelu domenowego żadnej aplikacji-hosta, więc może
+być używany przez dowolny projekt integrujący się z PBN.
+"""
+
+from .auth import OAuthMixin
+from .client import PBNClient
+from .mixins import (
+    ConferencesMixin,
+    DictionariesMixin,
+    InstitutionsMixin,
+    InstitutionsProfileMixin,
+    JournalsMixin,
+    PersonMixin,
+    PublicationsMixin,
+    PublishersMixin,
+    SearchMixin,
+)
+from .pagination import PageableResource
+from .reporting import (
+    ErrorReporter,
+    LoggingReporter,
+    NullReporter,
+    get_default_reporter,
+    set_default_reporter,
+)
+from .transport import PBNClientTransport, RequestsTransport
+from .utils import smart_content
+
+__all__ = [
+    "PBNClient",
+    "OAuthMixin",
+    "ConferencesMixin",
+    "DictionariesMixin",
+    "InstitutionsMixin",
+    "InstitutionsProfileMixin",
+    "JournalsMixin",
+    "PersonMixin",
+    "PublicationsMixin",
+    "PublishersMixin",
+    "SearchMixin",
+    "PageableResource",
+    "ErrorReporter",
+    "LoggingReporter",
+    "NullReporter",
+    "get_default_reporter",
+    "set_default_reporter",
+    "PBNClientTransport",
+    "RequestsTransport",
+    "smart_content",
+]

pbn_client-0.1.0/src/pbn_client/auth.py

@@ -0,0 +1,96 @@
+"""OAuth authentication mixin for PBN API."""
+
+from urllib.parse import parse_qs, urlparse
+
+import requests
+
+from pbn_client.conf import settings as pbn_settings
+from pbn_client.exceptions import (
+    AuthenticationConfigurationError,
+    AuthenticationResponseError,
+)
+
+
+class OAuthMixin:
+    """Mixin providing OAuth authentication functionality."""
+
+    @classmethod
+    def get_auth_url(klass, base_url, app_id, state=None):
+        url = f"{base_url}/auth/pbn/api/registration/user/token/{app_id}"
+        if state:
+            from urllib.parse import quote
+
+            url += f"?state={quote(state)}"
+        return url
+
+    @classmethod
+    def get_user_token(
+        klass,
+        base_url,
+        app_id,
+        app_token,
+        one_time_token,
+        *,
+        timeout=None,
+    ):
+        headers = {
+            "X-App-Id": app_id,
+            "X-App-Token": app_token,
+        }
+        body = {"oneTimeToken": one_time_token}
+        url = f"{base_url}/auth/pbn/api/user/token"
+        response = requests.post(
+            url=url,
+            json=body,
+            headers=headers,
+            timeout=(
+                pbn_settings.PBN_CLIENT_HTTP_TIMEOUT
+                if timeout is None
+                else pbn_settings.parse_timeout(timeout)
+            ),
+        )
+        try:
+            response.json()
+        except ValueError as e:
+            if response.content.startswith(b"Mismatched X-APP-TOKEN: "):
+                raise AuthenticationConfigurationError(
+                    "Token aplikacji PBN nieprawidłowy. Poproś administratora "
+                    "o skonfigurowanie prawidłowego tokena aplikacji PBN w "
+                    "konfiguracji aplikacji. "
+                ) from e
+
+            raise AuthenticationResponseError(response.content) from e
+
+        return response.json().get("X-User-Token")
+
+    def authorize(self, base_url, app_id, app_token):
+        if self.access_token:
+            return True
+
+        self.access_token = pbn_settings.PBN_CLIENT_USER_TOKEN
+        if self.access_token:
+            return True
+
+        auth_url = OAuthMixin.get_auth_url(base_url, app_id)
+
+        print(
+            f"""I have launched a web browser with {auth_url} ,\nplease log-in,
+             then paste the redirected URL below. \n"""
+        )
+        import webbrowser
+
+        webbrowser.open(auth_url)
+        redirect_response = input("Paste the full redirect URL here:")
+        one_time_token = parse_qs(urlparse(redirect_response).query).get("ott")[0]
+
+        # NIE wypisujemy one_time_token ani access_token — to aktywne sekrety,
+        # które zostawałyby w terminalu/CI/przechwyconych logach (uwaga #4).
+        self.access_token = OAuthMixin.get_user_token(
+            base_url,
+            app_id,
+            app_token,
+            one_time_token,
+            timeout=getattr(self, "timeout", None),
+        )
+
+        return True

pbn_client-0.1.0/src/pbn_client/client.py

@@ -0,0 +1,113 @@
+"""Czysty klient protokołu PBN.
+
+``PBNClient`` to kompozycja mixinów protokołu (słownikowo-CRUD + silnik
+oświadczeń ``StatementsMixin``). Operuje na tokenach, PBN UID-ach, JSON-ach
+i flagach bool — nie zna modelu domenowego aplikacji-hosta.
+
+Orkiestracja synchronizacji specyficzna dla aplikacji (znająca jej rekordy
+i konfigurację instytucji) powinna żyć w warstwie aplikacji, jako klasa
+dziedzicząca po ``PBNClient``.
+"""
+
+import sys
+from collections.abc import Iterable
+from pprint import pprint
+
+from .mixins import (
+    ConferencesMixin,
+    DictionariesMixin,
+    InstitutionsMixin,
+    InstitutionsProfileMixin,
+    JournalsMixin,
+    PersonMixin,
+    PublicationsMixin,
+    PublishersMixin,
+    SearchMixin,
+)
+from .statements import StatementsMixin
+from .transport import RequestsTransport
+
+
+class PBNClient(
+    ConferencesMixin,
+    DictionariesMixin,
+    InstitutionsMixin,
+    InstitutionsProfileMixin,
+    JournalsMixin,
+    PersonMixin,
+    PublicationsMixin,
+    PublishersMixin,
+    SearchMixin,
+    StatementsMixin,
+):
+    """Czysty klient protokołu PBN (bez orkiestracji specyficznej dla aplikacji)."""
+
+    _interactive = False
+
+    def __init__(self, transport: RequestsTransport):
+        self.transport = transport
+
+    def _get_command_function(self, cmd):
+        """Get function to execute from command name."""
+        try:
+            return getattr(self, cmd[0])
+        except AttributeError as e:
+            if self._interactive:
+                print(f"No such command: {cmd}")
+                return None
+            raise e
+
+    def _extract_arguments(self, lst):
+        """Extract positional and keyword arguments from command list."""
+        args = ()
+        kw = {}
+        for elem in lst:
+            if elem.find(":") >= 1:
+                k, n = elem.split(":", 1)
+                kw[k] = n
+            else:
+                args += (elem,)
+        return args, kw
+
+    def _print_non_interactive_result(self, res):
+        """Print result in non-interactive mode."""
+        import json
+
+        print(json.dumps(res))
+
+    def _print_interactive_result(self, res):
+        """Print result in interactive mode."""
+        if type(res) is dict:
+            pprint(res)
+        elif isinstance(res, Iterable):
+            if self._interactive and hasattr(res, "total_elements"):
+                print(
+                    "Incoming data: no_elements=",
+                    res.total_elements,
+                    "no_pages=",
+                    res.total_pages,
+                )
+                input("Press ENTER to continue> ")
+            for elem in res:
+                pprint(elem)
+
+    def exec(self, cmd):
+        fun = self._get_command_function(cmd)
+        if fun is None:
+            return
+
+        args, kw = self._extract_arguments(cmd[1:])
+        res = fun(*args, **kw)
+
+        if not sys.stdout.isatty():
+            self._print_non_interactive_result(res)
+        else:
+            self._print_interactive_result(res)
+
+    def interactive(self):
+        self._interactive = True
+        while True:
+            cmd = input("cmd> ")
+            if cmd == "exit":
+                break
+            self.exec(cmd.split(" "))

pbn_client-0.1.0/src/pbn_client/conf/settings.py

@@ -0,0 +1,46 @@
+"""Environment defaults for the standalone PBN client.
+
+Applications should normally pass credentials and timeouts to the transport
+constructor. These variables remain available for command-line compatibility.
+No framework settings object is imported here.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+
+from pbn_client.const import DEFAULT_BASE_URL
+
+Timeout = float | tuple[float, float]
+DEFAULT_HTTP_TIMEOUT: Timeout = (30.0, 120.0)
+
+
+def parse_timeout(
+    raw: str | float | Sequence[float] | None,
+    default: Timeout = DEFAULT_HTTP_TIMEOUT,
+) -> Timeout:
+    """Parse a requests timeout from a scalar or ``connect,read`` value."""
+
+    if raw is None:
+        return default
+    if isinstance(raw, (int, float)):
+        return float(raw)
+    if isinstance(raw, Sequence) and not isinstance(raw, str):
+        values = tuple(float(value) for value in raw)
+        return values if len(values) == 2 else default
+
+    parts = [part.strip() for part in str(raw).split(",") if part.strip()]
+    if len(parts) == 1:
+        return float(parts[0])
+    if len(parts) == 2:
+        return (float(parts[0]), float(parts[1]))
+    return default
+
+
+PBN_CLIENT_DEFAULT_BASE_URL = DEFAULT_BASE_URL
+PBN_CLIENT_APP_ID = os.getenv("PBN_CLIENT_APP_ID")
+PBN_CLIENT_APP_TOKEN = os.getenv("PBN_CLIENT_APP_TOKEN")
+PBN_CLIENT_BASE_URL = os.getenv("PBN_CLIENT_BASE_URL", DEFAULT_BASE_URL)
+PBN_CLIENT_USER_TOKEN = os.getenv("PBN_CLIENT_USER_TOKEN")
+PBN_CLIENT_HTTP_TIMEOUT = parse_timeout(os.getenv("PBN_CLIENT_HTTP_TIMEOUT"))

pbn_client-0.1.0/src/pbn_client/const.py

@@ -0,0 +1,33 @@
+DELETED = "DELETED"
+ACTIVE = "ACTIVE"
+
+PBN_POST_PUBLICATIONS_URL = "/api/v1/publications"
+
+PBN_POST_PUBLICATION_NO_STATEMENTS_URL = "/api/v1/repositorium/publications"
+
+PBN_POST_PUBLICATION_FEE_URL = "/api/v1/institutionProfile/publications/fees/{id}"
+
+PBN_GET_LANGUAGES_URL = "/api/v1/dictionary/languages"
+PBN_SEARCH_PUBLICATIONS_URL = "/api/v1/search/publications"
+
+PBN_GET_JOURNAL_BY_ID = "/api/v1/journals/{id}"
+
+DEFAULT_BASE_URL = "https://pbn-micro-alpha.opi.org.pl"
+
+NEEDS_PBN_AUTH_MSG = (
+    "W celu poprawnej autentykacji należy podać poprawny token użytkownika aplikacji."
+)
+PBN_DELETE_PUBLICATION_STATEMENT = (
+    "/api/v1/institutionProfile/publications/{publicationId}"
+)
+PBN_GET_PUBLICATION_BY_ID_URL = "/api/v1/publications/id/{id}"
+
+PBN_GET_INSTITUTION_STATEMENTS = (
+    "/api/v1/institutionProfile/publications/page/statements"
+)
+
+PBN_GET_DISCIPLINES_URL = "/api/v2/dictionary/disciplines"
+
+PBN_POST_INSTITUTION_STATEMENTS_URL = "/api/v2/institution-profile/statements"
+
+PBN_GET_INSTITUTION_PUBLICATIONS_V2 = "/api/v2/institution-profile/publications"