pbn-client 0.1.0__py3-none-any.whl

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/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/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/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/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"

pbn_client/dict_utils.py

@@ -0,0 +1,48 @@
+def rename_dict_key(data, old_key, new_key):
+    """
+    Recursively rename a dictionary key in a dictionary and all nested dictionaries.
+
+    Args:
+        data: Dictionary or any data structure that may contain dictionaries
+        old_key: The key to be renamed
+        new_key: The new key name
+
+    Returns:
+        The modified data structure with renamed keys
+    """
+    if isinstance(data, dict):
+        # Create a new dictionary with renamed keys
+        new_dict = {}
+        for key, value in data.items():
+            # Rename the key if it matches
+            new_key_name = new_key if key == old_key else key
+            # Recursively process the value
+            new_dict[new_key_name] = rename_dict_key(value, old_key, new_key)
+        return new_dict
+    elif isinstance(data, list):
+        # Process each item in the list
+        return [rename_dict_key(item, old_key, new_key) for item in data]
+    else:
+        # Return the value unchanged if it's not a dict or list
+        return data
+
+
+def compare_dicts(d1, d2, path=""):
+    diffs = []
+    keys = set(d1.keys()) | set(d2.keys())
+
+    for key in keys:
+        key_path = f"{path}.{key}" if path else key
+
+        if key not in d1:
+            diffs.append(f"Key '{key_path}' missing in first dict")
+        elif key not in d2:
+            diffs.append(f"Key '{key_path}' missing in second dict")
+        else:
+            v1, v2 = d1[key], d2[key]
+            if isinstance(v1, dict) and isinstance(v2, dict):
+                diffs.extend(compare_dicts(v1, v2, key_path))
+            elif v1 != v2:
+                diffs.append(f"Value mismatch at '{key_path}': {v1!r} != {v2!r}")
+
+    return diffs

pbn_client/exceptions.py

@@ -0,0 +1,141 @@
+"""Exceptions raised by the framework-independent PBN protocol client."""
+
+import json
+
+__all__ = [
+    "AccessDeniedException",
+    "AuthenticationConfigurationError",
+    "AuthenticationResponseError",
+    "CannotDeleteStatementsException",
+    "CannotUploadPublicationFee",
+    "HttpException",
+    "NeedsPBNAuthorisationException",
+    "PBNValidationError",
+    "PraceSerwisoweException",
+    "PublicationDoesNotExistInInstitutionProfile",
+    "ResourceLockedException",
+    "SciencistDoesNotExist",
+    "StatementsResendFailedException",
+    "parse_pbn_validation_details",
+]
+
+
+class PraceSerwisoweException(Exception):
+    def __str__(self):
+        return "Po stronie PBN trwają prace serwisowe. Prosimy spróbować później. "
+
+
+class CannotDeleteStatementsException(Exception):
+    pass
+
+
+class HttpException(Exception):
+    def __init__(self, status_code, url, content):
+        self.status_code = status_code
+        self.url = url
+        self.content = content
+        try:
+            self.json = json.loads(content[:4096])
+        except (json.JSONDecodeError, ValueError, TypeError):
+            self.json = None
+
+
+class ResourceLockedException(HttpException):
+    pass
+
+
+class AccessDeniedException(Exception):
+    def __init__(self, url, content):
+        self.url = url
+        self.content = content
+
+
+class SciencistDoesNotExist(Exception):
+    """The requested scientist does not exist in PBN."""
+
+
+class AuthenticationConfigurationError(Exception):
+    pass
+
+
+class AuthenticationResponseError(Exception):
+    pass
+
+
+class NeedsPBNAuthorisationException(HttpException):
+    pass
+
+
+class CannotUploadPublicationFee(ValueError):
+    """PBN rejected a fee because the publication has no fee obligation."""
+
+
+class PublicationDoesNotExistInInstitutionProfile(ValueError):
+    """The publication is missing from the PBN institution profile."""
+
+
+class StatementsResendFailedException(Exception):
+    """Statement synchronization failed after exhausting its retry policy."""
+
+    def __init__(self, publication_pk, pbn_uid, last_error):
+        self.publication_pk = publication_pk
+        self.pbn_uid = pbn_uid
+        self.last_error = last_error
+        super().__init__(
+            f"Synchronizacja oświadczeń dla pracy pk={publication_pk} "
+            f"(PBN UID={pbn_uid}) nie powiodła się po wyczerpaniu prób: "
+            f"{last_error}"
+        )
+
+
+def parse_pbn_validation_details(parsed_json):
+    """Return deduplicated PBN validation messages or ``None``.
+
+    Recognizes both the object-shaped ``details`` response and the list-shaped
+    response containing ``message``, ``description`` or ``code`` fields.
+    Hostile values are converted to strings and malformed elements are skipped.
+    """
+
+    def _coerce(value):
+        if isinstance(value, (list, tuple)):
+            return ", ".join(str(item) for item in value)
+        return str(value)
+
+    messages = []
+    if isinstance(parsed_json, dict):
+        details = parsed_json.get("details")
+        if isinstance(details, dict) and details:
+            messages = [_coerce(value) for value in details.values()]
+    elif isinstance(parsed_json, list) and parsed_json:
+        for element in parsed_json:
+            if not isinstance(element, dict):
+                continue
+            text = (
+                element.get("message")
+                or element.get("description")
+                or element.get("code")
+            )
+            if text:
+                messages.append(_coerce(text))
+
+    if not messages:
+        return None
+    return list(dict.fromkeys(messages))
+
+
+class PBNValidationError(HttpException):
+    """PBN rejected user data with a validation response.
+
+    ``__str__`` intentionally remains the inherited ``HttpException`` form:
+    consumers that parse the original exception tuple rely on the raw
+    response body remaining available.
+    """
+
+    def __init__(self, status_code, url, content):
+        super().__init__(status_code, url, content)
+        self.messages = parse_pbn_validation_details(self.json) or []
+
+    def user_messages(self):
+        """Return deduplicated messages suitable for display to a user."""
+
+        return self.messages

pbn_client/mixins/__init__.py

@@ -0,0 +1,22 @@
+"""API endpoint mixins for PBN client."""
+
+from .conferences import ConferencesMixin
+from .dictionaries import DictionariesMixin
+from .institutions import InstitutionsMixin, InstitutionsProfileMixin
+from .journals import JournalsMixin
+from .person import PersonMixin
+from .publications import PublicationsMixin
+from .publishers import PublishersMixin
+from .search import SearchMixin
+
+__all__ = [
+    "ConferencesMixin",
+    "DictionariesMixin",
+    "InstitutionsMixin",
+    "InstitutionsProfileMixin",
+    "JournalsMixin",
+    "PersonMixin",
+    "PublicationsMixin",
+    "PublishersMixin",
+    "SearchMixin",
+]

pbn_client/mixins/conferences.py

@@ -0,0 +1,20 @@
+"""Conferences API mixin."""
+
+
+class ConferencesMixin:
+    """Mixin providing conference-related API methods."""
+
+    def get_conferences(self, *args, **kw):
+        return self.transport.get_pages("/api/v1/conferences/page", *args, **kw)
+
+    def get_conferences_mnisw(self, *args, **kw):
+        return self.transport.get_pages("/api/v1/conferences/mnisw/page", *args, **kw)
+
+    def get_conference(self, id):
+        return self.transport.get(f"/api/v1/conferences/{id}")
+
+    def get_conference_editions(self, id):
+        return self.transport.get(f"/api/v1/conferences/{id}/editions")
+
+    def get_conference_metadata(self, id):
+        return self.transport.get(f"/api/v1/conferences/{id}/metadata")

pbn_client/mixins/dictionaries.py

@@ -0,0 +1,16 @@
+"""Dictionaries API mixin."""
+
+from pbn_client.const import PBN_GET_DISCIPLINES_URL, PBN_GET_LANGUAGES_URL
+
+
+class DictionariesMixin:
+    """Mixin providing dictionary-related API methods."""
+
+    def get_countries(self):
+        return self.transport.get("/api/v1/dictionary/countries")
+
+    def get_disciplines(self):
+        return self.transport.get(PBN_GET_DISCIPLINES_URL)
+
+    def get_languages(self):
+        return self.transport.get(PBN_GET_LANGUAGES_URL)