destiny_sdk 0.7.1__py3-none-any.whl → 0.7.3__py3-none-any.whl

destiny_sdk/client.py

@@ -1,11 +1,22 @@
 """Send authenticated requests to Destiny Repository."""
 
+import sys
 import time
 from collections.abc import Generator
 
 import httpx
-from pydantic import UUID4, HttpUrl
+from msal import (
+    ConfidentialClientApplication,
+    ManagedIdentityClient,
+    PublicClientApplication,
+    UserAssignedManagedIdentity,
+)
+from pydantic import UUID4, HttpUrl, TypeAdapter
 
+from destiny_sdk.auth import create_signature
+from destiny_sdk.core import sdk_version
+from destiny_sdk.identifiers import IdentifierLookup
+from destiny_sdk.references import Reference, ReferenceSearchResult
 from destiny_sdk.robots import (
     EnhancementRequestRead,
     RobotEnhancementBatch,
@@ -13,8 +24,10 @@ from destiny_sdk.robots import (
     RobotEnhancementBatchResult,
     RobotResult,
 )
+from destiny_sdk.search import AnnotationFilter
 
-from .auth import create_signature
+python_version = ".".join(map(str, sys.version_info[:3]))
+user_agent = f"python@{python_version}/destiny-sdk@{sdk_version}"
 
 
 class HMACSigningAuth(httpx.Auth):
@@ -53,7 +66,7 @@ class HMACSigningAuth(httpx.Auth):
         yield request
 
 
-class Client:
+class RobotClient:
     """
     Client for interaction with the Destiny API.
 
@@ -71,7 +84,10 @@ class Client:
         """
         self.session = httpx.Client(
             base_url=str(base_url).removesuffix("/").removesuffix("/v1") + "/v1",
-            headers={"Content-Type": "application/json"},
+            headers={
+                "Content-Type": "application/json",
+                "User-Agent": user_agent,
+            },
             auth=HMACSigningAuth(secret_key=secret_key, client_id=client_id),
         )
 
@@ -172,3 +188,414 @@ class Client:
             params={"lease": lease_duration} if lease_duration else None,
         )
         response.raise_for_status()
+
+
+# Backward compatibility
+Client = RobotClient
+
+
+class OAuthMiddleware(httpx.Auth):
+    """
+    Auth middleware that handles OAuth2 token retrieval and refresh.
+
+    This is generally used in conjunction with
+    :class:`OAuthClient <libs.sdk.src.destiny_sdk.client.OAuthClient>`.
+
+    Supports three authentication flows:
+
+    **Public Client Application (human login)**
+
+    Initial login will be interactive through a browser window. Subsequent token
+    retrievals will use cached tokens and refreshes where possible, and only prompt
+    for login again if necessary.
+
+    .. code-block:: python
+
+        auth = OAuthMiddleware(
+            azure_client_id="client-id",
+            azure_application_id="login-url",
+            azure_tenant_id="tenant-id",
+        )
+
+    **Confidential Client Application (client credentials)**
+
+    Suitable for service-to-service authentication where no user interaction is
+    possible or desired. Reach out if you need help setting up a confidential client
+    application. The secret must be stored securely.
+
+    .. code-block:: python
+
+        auth = OAuthMiddleware(
+            azure_client_id="client-id",
+            azure_application_id="application-id",
+            azure_login_url="login-url",
+            azure_client_secret="your-azure-client-secret",
+        )
+
+    **Azure Managed Identity**
+
+    Suitable for Azure environments that have had API permissions provisioned for
+    their managed identity. Note that the ``azure_client_id`` here is the client ID of
+    the managed identity, not the repository.
+
+    .. code-block:: python
+
+        auth = OAuthMiddleware(
+            azure_client_id="your-managed-identity-client-id",
+            azure_application_id="application-id",
+            use_managed_identity=True,
+        )
+
+    """
+
+    def __init__(
+        self,
+        azure_client_id: str,
+        azure_application_id: str,
+        azure_login_url: HttpUrl | str | None = None,
+        azure_client_secret: str | None = None,
+        *,
+        use_managed_identity: bool = False,
+    ) -> None:
+        """
+        Initialize the auth middleware.
+
+        :param tenant_id: The OAuth2 tenant ID.
+        :type tenant_id: str
+        :param client_id: The OAuth2 client ID.
+        :type client_id: str
+        :param application_id: The application ID for the Destiny API.
+        :type application_id: str
+        :param azure_login_url: The Azure login URL.
+        :type azure_login_url: str
+        :param azure_client_secret: The Azure client secret.
+        :type azure_client_secret: str | None
+        :param use_managed_identity: Whether to use managed identity for authentication
+        :type use_managed_identity: bool
+        """
+        if use_managed_identity:
+            if (
+                any(
+                    [
+                        azure_login_url,
+                        azure_client_secret,
+                    ]
+                )
+                or not azure_client_id
+            ):
+                msg = (
+                    "azure_login_url and azure_client_secret must not be provided "
+                    "when using managed identity authentication"
+                )
+                raise ValueError(msg)
+            self._oauth_app = ManagedIdentityClient(
+                UserAssignedManagedIdentity(client_id=azure_client_id),
+                http_client=httpx.Client(),
+            )
+            self._get_token = self._get_token_from_managed_identity
+        elif azure_client_secret:
+            if not azure_login_url:
+                msg = (
+                    "azure_login_url must be provided "
+                    "when not using managed identity authentication"
+                )
+                raise ValueError(msg)
+            self._oauth_app = ConfidentialClientApplication(
+                client_id=azure_client_id,
+                authority=str(azure_login_url),
+                client_credential=azure_client_secret,
+            )
+            self._get_token = self._get_token_from_confidential_client
+        else:
+            if not azure_login_url:
+                msg = (
+                    "azure_login_url must be provided "
+                    "when not using managed identity authentication"
+                )
+                raise ValueError(msg)
+            self._oauth_app = PublicClientApplication(
+                azure_client_id,
+                authority=str(azure_login_url),
+                client_credential=None,
+            )
+            self._get_token = self._get_token_from_public_client
+
+        self._scope = f"api://{azure_application_id}/.default"
+        self._account = None
+
+    def _parse_token(self, msal_response: dict) -> str:
+        """
+        Parse the OAuth2 token from an MSAL response.
+
+        :param msal_response: The MSAL response containing the token.
+        :type msal_response: dict
+        :return: The OAuth2 token.
+        :rtype: str
+        """
+        if not msal_response.get("access_token"):
+            msg = (
+                "Failed to acquire access token: "
+                f"{msal_response.get('error', 'Unknown error')}"
+            )
+            raise RuntimeError(msg)
+
+        return msal_response["access_token"]
+
+    def _get_token_from_public_client(self, *, force_refresh: bool = False) -> str:
+        """
+        Get an OAuth2 token from a PublicClientApplication.
+
+        :param force_refresh: Whether to force a token refresh.
+        :type force_refresh: bool
+        :return: The OAuth2 token.
+        :rtype: str
+        """
+        if not isinstance(self._oauth_app, PublicClientApplication):
+            msg = "oauth_app must be a PublicClientApplication for this method"
+            raise TypeError(msg)
+
+        # Uses msal cache if possible, else interactive login
+        result = self._oauth_app.acquire_token_silent(
+            scopes=[self._scope],
+            account=self._account,
+            force_refresh=force_refresh,
+        )
+        if not result:
+            result = self._oauth_app.acquire_token_interactive(scopes=[self._scope])
+
+        access_token = self._parse_token(result)
+
+        # After first login, cache the account for silent token acquisition
+        if not self._account and (accounts := self._oauth_app.get_accounts()):
+            self._account = accounts[0]
+
+        return access_token
+
+    def _get_token_from_confidential_client(
+        self,
+        *,
+        force_refresh: bool = False,  # noqa: ARG002 MSAL will handle refreshing
+    ) -> str:
+        """
+        Get an OAuth2 token from a ConfidentialClientApplication.
+
+        :param force_refresh: Whether to force a token refresh.
+        :type force_refresh: bool
+        :return: The OAuth2 token.
+        :rtype: str
+        """
+        if not isinstance(self._oauth_app, ConfidentialClientApplication):
+            msg = "oauth_app must be a ConfidentialClientApplication for this method"
+            raise TypeError(msg)
+
+        # Uses msal cache if possible, else client credentials flow
+        result = self._oauth_app.acquire_token_for_client(scopes=[self._scope])
+
+        return self._parse_token(result)
+
+    def _get_token_from_managed_identity(
+        self,
+        *,
+        force_refresh: bool = False,  # noqa: ARG002 MSAL will handle refreshing
+    ) -> str:
+        """
+        Get an OAuth2 token from a ManagedIdentityClient.
+
+        :param force_refresh: Whether to force a token refresh.
+        :type force_refresh: bool
+        :return: The OAuth2 token.
+        :rtype: str
+        """
+        if not isinstance(self._oauth_app, ManagedIdentityClient):
+            msg = "oauth_app must be a ManagedIdentityClient for this method"
+            raise TypeError(msg)
+
+        result = self._oauth_app.acquire_token_for_client(
+            resource=self._scope.removesuffix("/.default")
+        )
+
+        return self._parse_token(result)
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response]:
+        """
+        Add OAuth2 token to request and handle token refresh on expiration.
+
+        :param request: The request to authenticate.
+        :type request: httpx.Request
+        :yield: Authenticated request with token refresh handling.
+        :rtype: Generator[httpx.Request, httpx.Response]
+        """
+        # Add initial token
+        token = self._get_token()
+        request.headers["Authorization"] = f"Bearer {token}"
+
+        response = yield request
+
+        # Check if token expired and retry once with fresh token
+        if response.status_code == httpx.codes.UNAUTHORIZED:
+            try:
+                json_response: dict = response.json()
+                error_detail: str = json_response.get("detail", {})
+            except ValueError:
+                error_detail = ""
+
+            if error_detail == "Token has expired.":
+                # Force refresh token and retry
+                token = self._get_token(force_refresh=True)
+                request.headers["Authorization"] = f"Bearer {token}"
+                yield request
+
+
+class OAuthClient:
+    """
+    Client for interaction with the Destiny API using OAuth2.
+
+    This will apply the provided authentication, usually
+    :class:`OAuthMiddleware <libs.sdk.src.destiny_sdk.client.OAuthMiddleware>`,
+    to all requests. Some API endpoints are supported directly through methods on this
+    class, while others can be accessed through the underlying ``httpx`` client.
+
+    Example usage:
+
+    .. code-block:: python
+
+        from destiny_sdk.client import OAuthClient, OAuthMiddleware
+
+        client = OAuthClient(
+            base_url="https://destiny-repository.example.com",
+            auth=OAuthMiddleware(...),
+        )
+
+        # Supported method
+        response = client.search(query="example")
+
+        # Unsupported method, use underlying httpx client
+        response = client.get_client().get("/system/healthcheck/")
+    """
+
+    def __init__(
+        self,
+        base_url: HttpUrl | str,
+        auth: httpx.Auth | None = None,
+    ) -> None:
+        """
+        Initialize the client.
+
+        :param base_url: The base URL for the Destiny Repository API.
+        :type base_url: HttpUrl
+        :param auth: The middleware for authentication. If not provided, only
+            unauthenticated requests can be made. This should almost always be an
+            instance of ``OAuthMiddleware``, unless you need to create a custom auth
+            class.
+        :type auth: httpx.Auth | None
+        """
+        self._client = httpx.Client(
+            base_url=str(base_url).removesuffix("/").removesuffix("/v1") + "/v1",
+            headers={
+                "Content-Type": "application/json",
+                "User-Agent": user_agent,
+            },
+        )
+
+        if auth:
+            self._client.auth = auth
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        """
+        Raise an error if the response status is not successful.
+
+        :param response: The HTTP response to check.
+        :type response: httpx.Response
+        :raises httpx.HTTPStatusError: If the response status is not successful.
+        """
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            msg = (
+                f"Error response {exc.response.status_code} from "
+                f"{exc.request.url}: {exc.response.text}"
+            )
+            raise httpx.HTTPStatusError(
+                msg, request=exc.request, response=exc.response
+            ) from exc
+
+    def search(  # noqa: PLR0913
+        self,
+        query: str,
+        start_year: int | None = None,
+        end_year: int | None = None,
+        annotations: list[str | AnnotationFilter] | None = None,
+        sort: str | None = None,
+        page: int = 1,
+    ) -> ReferenceSearchResult:
+        """
+        Send a search request to the Destiny Repository API.
+
+        See also: :ref:`search-procedure`.
+
+        :param query: The search query string.
+        :type query: str
+        :param start_year: The start year for filtering results.
+        :type start_year: int | None
+        :param end_year: The end year for filtering results.
+        :type end_year: int | None
+        :param annotations: A list of annotation filters to apply.
+        :type annotations: list[str | libs.sdk.src.destiny_sdk.search.AnnotationFilter] | None
+        :param sort: The sort order for the results.
+        :type sort: str | None
+        :param page: The page number of results to retrieve.
+        :type page: int
+        :return: The response from the API.
+        :rtype: libs.sdk.src.destiny_sdk.references.ReferenceSearchResult
+        """  # noqa: E501
+        params = {"q": query, "page": page}
+        if start_year:
+            params["start_year"] = start_year
+        if end_year:
+            params["end_year"] = end_year
+        if annotations:
+            params["annotation"] = [str(annotation) for annotation in annotations]
+        if sort:
+            params["sort"] = sort
+        response = self._client.get(
+            "/references/search/",
+            params=params,
+        )
+        self._raise_for_status(response)
+        return ReferenceSearchResult.model_validate(response.json())
+
+    def lookup(
+        self,
+        identifiers: list[str | IdentifierLookup],
+    ) -> list[Reference]:
+        """
+        Lookup references by identifiers.
+
+        See also: :ref:`lookup-procedure`.
+
+        :param identifiers: The identifiers to look up.
+        :type identifiers: list[str | libs.sdk.src.destiny_sdk.identifiers.IdentifierLookup]
+        :return: The list of references matching the identifiers.
+        :rtype: list[libs.sdk.src.destiny_sdk.references.Reference]
+        """  # noqa: E501
+        response = self._client.get(
+            "/references/",
+            params={
+                "identifier": ",".join([str(identifier) for identifier in identifiers])
+            },
+        )
+        self._raise_for_status(response)
+        return TypeAdapter(list[Reference]).validate_python(response.json())
+
+    def get_client(self) -> httpx.Client:
+        """
+        Get the underlying ``httpx`` client.
+
+        This can be used to make custom requests not covered by the SDK methods.
+
+        :return: The underlying ``httpx`` client with authentication attached.
+        :rtype: `httpx.Client <https://www.python-httpx.org/advanced/clients/>`_
+        """
+        return self._client

destiny_sdk/core.py

@@ -1,11 +1,18 @@
 """Core classes for the Destiny SDK, not exposed to package users."""
 
+from importlib.metadata import PackageNotFoundError, version
 from typing import Self
 
 from pydantic import BaseModel, Field
 
 from destiny_sdk.search import SearchResultPage, SearchResultTotal
 
+try:
+    sdk_version = version("destiny-sdk")
+except PackageNotFoundError:
+    sdk_version = "unknown"
+
+
 # These are non-standard newline characters that are not escaped by model_dump_json().
 # We want jsonl files to have empirical new lines so they can be streamed line by line.
 # Hence we replace each occurrence with standard new lines.

destiny_sdk/enhancements.py

@@ -1,6 +1,7 @@
 """Enhancement classes for the Destiny Repository."""
 
 import datetime
+import json
 from enum import StrEnum, auto
 from typing import Annotated, Any, Literal, Self
 
@@ -87,6 +88,10 @@ other works have cited this work
     created_date: datetime.date | None = Field(
         default=None, description="The ISO8601 date this metadata record was created"
     )
+    updated_date: datetime.date | None = Field(
+        default=None,
+        description="The ISO8601 date of the last OpenAlex update to this metadata",
+    )
     publication_date: datetime.date | None = Field(
         default=None, description="The date which the version of record was published."
     )
@@ -100,6 +105,20 @@ other works have cited this work
     )
     title: str | None = Field(default=None, description="The title of the reference.")
 
+    @property
+    def fingerprint(self) -> str:
+        """
+        The fingerprint of this bibliographic metadata enhancement.
+
+        Excludes updated_at from the fingerprint calculation, meaning
+        that two raw enhancements with identical data but different export dates
+        will be considered the same.
+        """
+        return json.dumps(
+            self.model_dump(mode="json", exclude={"updated_date"}, exclude_none=True),
+            sort_keys=True,
+        )
+
 
 class AbstractProcessType(StrEnum):
     """The process used to acquire the abstract."""
@@ -332,6 +351,25 @@ class RawEnhancement(BaseModel):
             raise ValueError(msg)
         return self
 
+    @property
+    def fingerprint(self) -> str:
+        """
+        The unique fingerprint of this raw enhancement.
+
+        Excludes the source_export_date from the fingerprint calculation, meaning
+        that two raw enhancements with identical data but different export dates
+        will be considered the same.
+
+        Unstructured data in `data` and `metadata` is included in the fingerprint,
+        sorted by key.
+        """
+        return json.dumps(
+            self.model_dump(
+                mode="json", exclude={"source_export_date"}, exclude_none=True
+            ),
+            sort_keys=True,
+        )
+
 
 #: Union type for all enhancement content types.
 EnhancementContent = Annotated[

destiny_sdk/identifiers.py

@@ -260,3 +260,11 @@ class IdentifierLookup(BaseModel):
         if self.identifier_type is None:
             return UUID4(self.identifier)
         return ExternalIdentifierAdapter.validate_python(self.model_dump())
+
+    def __repr__(self) -> str:
+        """Serialize the identifier lookup to a string."""
+        return self.serialize()
+
+    def __str__(self) -> str:
+        """Serialize the identifier lookup to a string."""
+        return self.serialize()

destiny_sdk/search.py

@@ -51,3 +51,7 @@ class AnnotationFilter(BaseModel):
         if self.score is not None:
             annotation += f"@{self.score}"
         return annotation
+
+    def __str__(self) -> str:
+        """Serialize the annotation filter to a string."""
+        return repr(self)

{destiny_sdk-0.7.1.dist-info → destiny_sdk-0.7.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: destiny_sdk
-Version: 0.7.1
+Version: 0.7.3
 Summary: A software development kit (sdk) to support interaction with the DESTINY repository
 Author-email: Adam Hamilton <adam@futureevidence.org>, Andrew Harvey <andrew@futureevidence.org>, Daniel Breves <daniel@futureevidence.org>, Jack Walmisley <jack@futureevidence.org>, Tim Repke <tim.repke@pik-potsdam.de>
 License-Expression: Apache-2.0
@@ -9,6 +9,7 @@ Requires-Python: ~=3.12
 Requires-Dist: cachetools<6,>=5.5.2
 Requires-Dist: fastapi<0.116,>=0.115.12
 Requires-Dist: httpx<0.29,>=0.28.1
+Requires-Dist: msal>=1.34.0
 Requires-Dist: pydantic<3,>=2.11.3
 Requires-Dist: pytest-asyncio<2,>=1.0.0
 Requires-Dist: pytest-httpx<0.36,>=0.35.0

{destiny_sdk-0.7.1.dist-info → destiny_sdk-0.7.3.dist-info}/RECORD

@@ -1,21 +1,21 @@
 destiny_sdk/__init__.py,sha256=NdSlsPQyDF3TW30_JzbvYMRBRA9iT677iTRWWCMdYOA,382
 destiny_sdk/auth.py,sha256=bY72ywZEcG_67YBd9PrwgWTXkCf58rhLvVEXrtXbWtA,6247
-destiny_sdk/client.py,sha256=LoXEBPxekbT-Y8eiTt_Gfy4G5RPj1tURZHuH-V9CLXs,6247
-destiny_sdk/core.py,sha256=PYCYpY72MHXo7iQMHtnXcnCOGn6CUsbYoykHvtQl4Oc,1857
-destiny_sdk/enhancements.py,sha256=-4jLm3R0T5UpgCt09CgUfPcnzPOyjdhUZCT1zhEP6sQ,12838
-destiny_sdk/identifiers.py,sha256=r2dFBIv2vtOK-C5lvHryEOqQBQ6_Odehipc6YgMZVBk,9482
+destiny_sdk/client.py,sha256=nKvS5rRkIpBqv8dVIB57Xsop0UvVz3i875RQxfVSMao,21306
+destiny_sdk/core.py,sha256=E0Wotu9psggK1JRJxbvx3Jc7WEGE6zaz2R2awvRrLz8,2023
+destiny_sdk/enhancements.py,sha256=P_kH59WoWuYq444xjV05HNXlTGfB-lE0ffKYwpAY7z8,14118
+destiny_sdk/identifiers.py,sha256=I9Q2I35Lg8oyl3uytq1gCGOUu92F9sZSSwzLoCXBJi4,9727
 destiny_sdk/imports.py,sha256=b-rh-dt3NsyLGxqmVzIzKaHiXhbw-3wtAaBN-ZW-i1E,5940
 destiny_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 destiny_sdk/references.py,sha256=3Y8gBMTSyZY35S3pB1bnVHMai9RRiGeoGZysNvSo7kk,2553
 destiny_sdk/robots.py,sha256=I_ZvMxwST52e8ovhv0-gPbOB3P9tptbRG0LrkNNOqKo,13463
-destiny_sdk/search.py,sha256=RAmUBS2KE2fmzLTxB0jV5R3AeuBrOJAWqieGv4GgFAo,1474
+destiny_sdk/search.py,sha256=QWQBNEJJnH2o6CGapChKUp6kOZl2Uq3Pxqg1kcu9x-4,1590
 destiny_sdk/visibility.py,sha256=8D44Q868YdScAt6eAFgXXrhonozXnv_Qa5w5yEGMPX8,577
 destiny_sdk/labs/__init__.py,sha256=H4RFPyeelqZ56PagnWPX-JZeWlxPnCZoYHtr4c9SU9Q,180
 destiny_sdk/labs/references.py,sha256=iZisRgGZ5c7X7uTFoe6Q0AwwFMa4yJbIoPUVv_hvOiU,5589
 destiny_sdk/parsers/__init__.py,sha256=d5gS--bXla_0I7e_9wTBnGWMXt2U8b-_ndeprTPe1hk,149
 destiny_sdk/parsers/eppi_parser.py,sha256=_1xnAT0F0o1HKpMWOGQbVS3VPOrhPqyzHDWR3CosWwk,9484
 destiny_sdk/parsers/exceptions.py,sha256=0Sc_M4j560Nqh4SjeP_YrgOUVagdIwWwRz24E6YlZ1k,573
-destiny_sdk-0.7.1.dist-info/METADATA,sha256=w_3Zbj91oWcz1uCgSN1JLYVTisV1m3PJBio2g9AtopY,2657
-destiny_sdk-0.7.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-destiny_sdk-0.7.1.dist-info/licenses/LICENSE,sha256=6QURU4gvvTjVZ5rfp5amZ6FtFvcpPhAGUjxF5WSZAHI,9138
-destiny_sdk-0.7.1.dist-info/RECORD,,
+destiny_sdk-0.7.3.dist-info/METADATA,sha256=2z_JjoZa-UMvOaPefJoYAc1ILx39gT0IWIqfYljbS1g,2685
+destiny_sdk-0.7.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+destiny_sdk-0.7.3.dist-info/licenses/LICENSE,sha256=6QURU4gvvTjVZ5rfp5amZ6FtFvcpPhAGUjxF5WSZAHI,9138
+destiny_sdk-0.7.3.dist-info/RECORD,,