destiny_sdk 0.7.4__tar.gz → 0.7.6__tar.gz

{destiny_sdk-0.7.4 → destiny_sdk-0.7.6}/PKG-INFO

@@ -1,19 +1,16 @@
 Metadata-Version: 2.4
 Name: destiny_sdk
-Version: 0.7.4
+Version: 0.7.6
 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
 License-File: LICENSE
-Requires-Python: ~=3.12
+Requires-Python: <4,>=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
-Requires-Dist: pytest<9,>=8.4.0
 Requires-Dist: python-jose<4,>=3.4.0
 Provides-Extra: labs
 Description-Content-Type: text/markdown

{destiny_sdk-0.7.4 → destiny_sdk-0.7.6}/pyproject.toml

@@ -6,7 +6,10 @@ requires = ["hatchling"]
 dev = [
     "mypy>=1.15.0,<2",
     "pre-commit>=4.2.0,<5",
+    "pytest-asyncio>=1.0.0,<2",
     "pytest-env>=1.1.5,<2",
+    "pytest-httpx>=0.35.0,<0.36",
+    "pytest>=8.4.0,<9",
     "ruff>=0.11.5,<0.12",
     "uvloop>=0.21.0,<0.22",
 ]
@@ -25,17 +28,14 @@ dependencies = [
     "httpx>=0.28.1,<0.29",
     "msal>=1.34.0",
     "pydantic>=2.11.3,<3",
-    "pytest-asyncio>=1.0.0,<2",
-    "pytest-httpx>=0.35.0,<0.36",
-    "pytest>=8.4.0,<9",
     "python-jose>=3.4.0,<4",
 ]
 description = "A software development kit (sdk) to support interaction with the DESTINY repository"
 license = "Apache-2.0"
 name = "destiny_sdk"
 readme = "README.md"
-requires-python = "~=3.12"
-version = "0.7.4"
+requires-python = ">=3.12, <4"
+version = "0.7.6"
 
 [project.optional-dependencies]
 labs = []

{destiny_sdk-0.7.4 → destiny_sdk-0.7.6}/src/destiny_sdk/client.py

@@ -213,8 +213,8 @@ class OAuthMiddleware(httpx.Auth):
 
         auth = OAuthMiddleware(
             azure_client_id="client-id",
-            azure_application_id="login-url",
-            azure_tenant_id="tenant-id",
+            azure_application_id="application-id",
+            azure_login_url="login-url",
         )
 
     **Confidential Client Application (client credentials)**
@@ -260,11 +260,9 @@ class OAuthMiddleware(httpx.Auth):
         """
         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.
+        :param azure_client_id: The OAuth2 client ID.
+        :type azure_client_id: str
+        :param azure_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
@@ -479,6 +477,7 @@ class OAuthClient:
         self,
         base_url: HttpUrl | str,
         auth: httpx.Auth | None = None,
+        timeout: int = 10,
     ) -> None:
         """
         Initialize the client.
@@ -490,6 +489,8 @@ class OAuthClient:
             instance of ``OAuthMiddleware``, unless you need to create a custom auth
             class.
         :type auth: httpx.Auth | None
+        :param timeout: The timeout for requests, in seconds. Defaults to 10 seconds.
+        :type timeout: int
         """
         self._client = httpx.Client(
             base_url=str(base_url).removesuffix("/").removesuffix("/v1") + "/v1",
@@ -497,6 +498,7 @@ class OAuthClient:
                 "Content-Type": "application/json",
                 "User-Agent": user_agent,
             },
+            timeout=timeout,
         )
 
         if auth:
@@ -529,6 +531,7 @@ class OAuthClient:
         annotations: list[str | AnnotationFilter] | None = None,
         sort: str | None = None,
         page: int = 1,
+        timeout: int | None = None,
     ) -> ReferenceSearchResult:
         """
         Send a search request to the Destiny Repository API.
@@ -547,6 +550,9 @@ class OAuthClient:
         :type sort: str | None
         :param page: The page number of results to retrieve.
         :type page: int
+        :param timeout: The timeout for the request, in seconds. If provided, this will override
+        the client timeout.
+        :type timeout: int | None
         :return: The response from the API.
         :rtype: libs.sdk.src.destiny_sdk.references.ReferenceSearchResult
         """  # noqa: E501
@@ -562,6 +568,7 @@ class OAuthClient:
         response = self._client.get(
             "/references/search/",
             params=params,
+            timeout=timeout or httpx.USE_CLIENT_DEFAULT,
         )
         self._raise_for_status(response)
         return ReferenceSearchResult.model_validate(response.json())
@@ -569,6 +576,7 @@ class OAuthClient:
     def lookup(
         self,
         identifiers: list[str | IdentifierLookup],
+        timeout: int | None = None,
     ) -> list[Reference]:
         """
         Lookup references by identifiers.
@@ -577,6 +585,9 @@ class OAuthClient:
 
         :param identifiers: The identifiers to look up.
         :type identifiers: list[str | libs.sdk.src.destiny_sdk.identifiers.IdentifierLookup]
+        :param timeout: The timeout for the request, in seconds. If provided, this will override
+        the client timeout.
+        :type timeout: int | None
         :return: The list of references matching the identifiers.
         :rtype: list[libs.sdk.src.destiny_sdk.references.Reference]
         """  # noqa: E501
@@ -585,6 +596,7 @@ class OAuthClient:
             params={
                 "identifier": ",".join([str(identifier) for identifier in identifiers])
             },
+            timeout=timeout or httpx.USE_CLIENT_DEFAULT,
         )
         self._raise_for_status(response)
         return TypeAdapter(list[Reference]).validate_python(response.json())

{destiny_sdk-0.7.4 → destiny_sdk-0.7.6}/src/destiny_sdk/enhancements.py

@@ -5,7 +5,7 @@ import json
 from enum import StrEnum, auto
 from typing import Annotated, Any, Literal, Self
 
-from pydantic import UUID4, BaseModel, Field, HttpUrl, model_validator
+from pydantic import UUID4, BaseModel, Field, HttpUrl, field_validator, model_validator
 
 from destiny_sdk.core import _JsonlFileInputMixIn
 from destiny_sdk.identifiers import Identifier
@@ -70,6 +70,42 @@ class Authorship(BaseModel):
     )
 
 
+class Pagination(BaseModel):
+    """
+    Pagination information for journal articles.
+
+    Maps to OpenAlex's work.biblio object. All fields are strings to match
+    OpenAlex's format, which may include non-numeric values like "Spring" or "A1".
+    """
+
+    volume: str | None = Field(
+        default=None,
+        description="The volume number of the journal/publication.",
+    )
+    issue: str | None = Field(
+        default=None,
+        description="The issue number of the journal/publication.",
+    )
+    first_page: str | None = Field(
+        default=None,
+        description="The first page number of the reference in the publication.",
+    )
+    last_page: str | None = Field(
+        default=None,
+        description="The last page number of the reference in the publication.",
+    )
+
+    @field_validator("volume", "issue", "first_page", "last_page", mode="before")
+    @classmethod
+    def normalize_pagination_string(cls, value: str | None) -> str | None:
+        """Normalize pagination strings: NBSP to space, strip, empty to None."""
+        if isinstance(value, str):
+            # Replace NBSP with space, then strip
+            value = value.replace("\u00a0", " ").strip()
+            return value if value else None
+        return value
+
+
 class BibliographicMetadataEnhancement(BaseModel):
     """
     An enhancement which is made up of bibliographic metadata.
@@ -111,6 +147,10 @@ other works have cited this work
         description="The name of the entity which published the version of record.",
     )
     title: str | None = Field(default=None, description="The title of the reference.")
+    pagination: Pagination | None = Field(
+        default=None,
+        description="Pagination info (volume, issue, pages).",
+    )
 
     @property
     def fingerprint(self) -> str:

{destiny_sdk-0.7.4 → destiny_sdk-0.7.6}/src/destiny_sdk/identifiers.py

@@ -1,10 +1,24 @@
 """Identifier classes for the Destiny SDK."""
 
+import re
+import unicodedata
 import uuid
 from enum import StrEnum, auto
 from typing import Annotated, Literal, Self
 
-from pydantic import UUID4, BaseModel, Field, TypeAdapter, field_validator
+from pydantic import UUID4, BaseModel, Field, PositiveInt, TypeAdapter, field_validator
+
+# Case-insensitive patterns for DOI URL prefix stripping
+_DOI_URL_PREFIX_RE = re.compile(r"^(?:https?://)?(?:dx\.)?doi\.org/", re.IGNORECASE)
+_DOI_SCHEME_RE = re.compile(r"^doi:\s*", re.IGNORECASE)
+
+# Translation table for DOI canonicalization (extensible for future characters)
+_DOI_CHAR_TRANSLATION = str.maketrans(
+    {
+        "\u00a0": " ",  # NBSP -> space
+        "\u2010": "-",  # Unicode hyphen -> ASCII hyphen
+    }
+)
 
 
 class ExternalIdentifierType(StrEnum):
@@ -24,7 +38,7 @@ class ExternalIdentifierType(StrEnum):
     PM_ID = auto()
     """A PubMed ID which is a unique identifier for a document in PubMed."""
     PRO_QUEST = auto()
-    """A ProQuest ID which is a unqiue identifier for a document in ProQuest."""
+    """A ProQuest ID which is a unique identifier for a document in ProQuest."""
     OPEN_ALEX = auto()
     """An OpenAlex ID which is a unique identifier for a document in OpenAlex."""
     OTHER = auto()
@@ -35,8 +49,13 @@ class DOIIdentifier(BaseModel):
     """An external identifier representing a DOI."""
 
     identifier: str = Field(
-        description="The DOI of the reference.",
-        pattern=r"^10\.\d{4,9}/[-._;()/:a-zA-Z0-9%<>\[\]+&]+$",
+        description=(
+            "The DOI of the reference. "
+            "Format: '10.<registrant>/<suffix>' where registrant is 4-9 digits "
+            "and suffix is any non-whitespace characters. "
+            "Examples: 10.1000/journal.pone.0001, 10.18730/9WQ$D, 10.1000/édition"
+        ),
+        pattern=r"^10\.\d{4,9}/\S+$",
     )
     identifier_type: Literal[ExternalIdentifierType.DOI] = Field(
         ExternalIdentifierType.DOI, description="The type of identifier used."
@@ -44,23 +63,33 @@ class DOIIdentifier(BaseModel):
 
     @field_validator("identifier", mode="before")
     @classmethod
-    def remove_doi_url(cls, value: str) -> str:
-        """Remove the URL part of the DOI if it exists."""
-        return (
-            value.removeprefix("http://")
-            .removeprefix("https://")
-            .removeprefix("doi.org/")
-            .removeprefix("dx.doi.org/")
-            .removeprefix("doi:")
-            .strip()
-        )
+    def canonicalize_doi(cls, value: str) -> str:
+        """
+        Canonicalize DOI: strip URL prefixes and normalize Unicode.
+
+        - NFC Unicode normalization
+        - Translate special characters (NBSP, Unicode hyphen) via translation table
+        - Case-insensitive URL/scheme prefix stripping
+        """
+        # NFC normalization first
+        value = unicodedata.normalize("NFC", str(value))
+        # Translate special characters and strip
+        value = value.translate(_DOI_CHAR_TRANSLATION).strip()
+        # Strip URL prefixes (case-insensitive)
+        value = _DOI_URL_PREFIX_RE.sub("", value)
+        value = _DOI_SCHEME_RE.sub("", value)
+        return value.strip()
 
 
 class ProQuestIdentifier(BaseModel):
     """An external identifier representing a ProQuest ID."""
 
     identifier: str = Field(
-        description="The ProQuest id of the reference", pattern=r"[0-9]+$"
+        description=(
+            "The ProQuest ID of the reference. "
+            "Format: numeric digits only. Example: 12345678"
+        ),
+        pattern=r"[0-9]+$",
     )
     identifier_type: Literal[ExternalIdentifierType.PRO_QUEST] = Field(
         ExternalIdentifierType.PRO_QUEST, description="The type of identifier used."
@@ -84,12 +113,16 @@ class ERICIdentifier(BaseModel):
     """
     An external identifier representing an ERIC Number.
 
-    An ERIC Number is defined as a unqiue identifiying number preceeded by
-    EJ (for a journal article) or ED (for a non-journal document).
+    An ERIC Number is defined as a unique identifying number preceded by
+    ED (for a non-journal document) or EJ (for a journal article).
     """
 
     identifier: str = Field(
-        description="The ERIC Number of the reference.", pattern=r"E[D|J][0-9]+$"
+        description=(
+            "The ERIC Number. "
+            "Format: 'ED' or 'EJ' followed by digits. Example: ED123456 or EJ789012"
+        ),
+        pattern=r"E[D|J][0-9]+$",
     )
     identifier_type: Literal[ExternalIdentifierType.ERIC] = Field(
         ExternalIdentifierType.ERIC, description="The type of identifier used."
@@ -112,7 +145,9 @@ class ERICIdentifier(BaseModel):
 class PubMedIdentifier(BaseModel):
     """An external identifier representing a PubMed ID."""
 
-    identifier: int = Field(description="The PubMed ID of the reference.")
+    identifier: PositiveInt = Field(
+        description="The PubMed ID (PMID) of the reference. Example: 12345678",
+    )
     identifier_type: Literal[ExternalIdentifierType.PM_ID] = Field(
         ExternalIdentifierType.PM_ID, description="The type of identifier used."
     )
@@ -122,7 +157,11 @@ class OpenAlexIdentifier(BaseModel):
     """An external identifier representing an OpenAlex ID."""
 
     identifier: str = Field(
-        description="The OpenAlex ID of the reference.", pattern=r"^W\d+$"
+        description=(
+            "The OpenAlex ID of the reference. "
+            "Format: 'W' followed by digits. Example: W2741809807"
+        ),
+        pattern=r"^W\d+$",
     )
     identifier_type: Literal[ExternalIdentifierType.OPEN_ALEX] = Field(
         ExternalIdentifierType.OPEN_ALEX, description="The type of identifier used."

{destiny_sdk-0.7.4 → destiny_sdk-0.7.6}/tests/unit/test_enhancements.py

@@ -8,7 +8,13 @@ from pydantic import ValidationError
 
 
 def test_bibliographic_metadata_enhancement_valid():
-    # Create valid bibliographic content
+    # Create valid bibliographic content with pagination
+    pagination = destiny_sdk.enhancements.Pagination(
+        volume="42",
+        issue="7",
+        first_page="495",
+        last_page="512",
+    )
     bibliographic = destiny_sdk.enhancements.BibliographicMetadataEnhancement(
         enhancement_type=destiny_sdk.enhancements.EnhancementType.BIBLIOGRAPHIC,
         authorship=[],
@@ -19,6 +25,7 @@ def test_bibliographic_metadata_enhancement_valid():
         publication_year=2020,
         publisher="Test Publisher",
         title="Test Title",
+        pagination=pagination,
     )
     enhancement = destiny_sdk.enhancements.Enhancement(
         id=uuid.uuid4(),
@@ -33,6 +40,27 @@ def test_bibliographic_metadata_enhancement_valid():
         enhancement.content.enhancement_type
         == destiny_sdk.enhancements.EnhancementType.BIBLIOGRAPHIC
     )
+    assert enhancement.content.pagination.volume == "42"
+    assert enhancement.content.pagination.issue == "7"
+    assert enhancement.content.pagination.first_page == "495"
+    assert enhancement.content.pagination.last_page == "512"
+
+
+def test_bibliographic_metadata_enhancement_non_numeric_pagination_fields():
+    """Test that non-numeric pagination fields are accepted (per OpenAlex spec)."""
+    bibliographic = destiny_sdk.enhancements.BibliographicMetadataEnhancement(
+        title="Test Title",
+        pagination=destiny_sdk.enhancements.Pagination(
+            volume="Spring",
+            issue="Special Issue",
+            first_page="A1",
+            last_page="A15",
+        ),
+    )
+    assert bibliographic.pagination.volume == "Spring"
+    assert bibliographic.pagination.issue == "Special Issue"
+    assert bibliographic.pagination.first_page == "A1"
+    assert bibliographic.pagination.last_page == "A15"
 
 
 def test_abstract_content_enhancement_valid():
@@ -224,3 +252,28 @@ def test_association_enhancement_invalid_identifier_type_errors():
             ],
             association_type=destiny_sdk.enhancements.ReferenceAssociationType.CITES,
         )
+
+
+def test_pagination_empty_string_to_none():
+    """Test that empty pagination strings are converted to None."""
+    pagination = destiny_sdk.enhancements.Pagination(
+        volume="", issue="  ", first_page=None, last_page="42"
+    )
+    assert pagination.volume is None
+    assert pagination.issue is None
+    assert pagination.first_page is None
+    assert pagination.last_page == "42"
+
+
+def test_pagination_nbsp_normalized():
+    """Test that NBSP (U+00A0) is replaced with space and stripped."""
+    pagination = destiny_sdk.enhancements.Pagination(
+        volume="\u00a042\u00a0",  # NBSP padding
+        issue="7\u00a0",  # Trailing NBSP
+        first_page="\u00a0",  # Only NBSP -> should become None
+        last_page="100",
+    )
+    assert pagination.volume == "42"
+    assert pagination.issue == "7"
+    assert pagination.first_page is None
+    assert pagination.last_page == "100"

{destiny_sdk-0.7.4 → destiny_sdk-0.7.6}/tests/unit/test_identifiers.py

@@ -30,6 +30,59 @@ def test_doi_url_removed():
     assert obj.identifier == "10.1000/xyz123"
 
 
+@pytest.mark.parametrize(
+    "doi",
+    [
+        # DataCite GLIS characters: = ~ * $
+        # Crossref/legacy: #
+        "10.18730/9WQ$D",  # Dollar sign
+        "10.18730/9WQ*D",  # Asterisk
+        "10.18730/9WQ~D",  # Tilde
+        "10.18730/9WQ=D",  # Equals
+        "10.18730/9WQ#D",  # Hash
+        "10.18730/9WQ$~*=#D",  # Multiple special characters
+        # Latin Extended characters (accented letters)
+        "10.1000/journalÉdition",  # É (U+00C9)
+        "10.1000/café",  # é (U+00E9)
+        "10.1000/naïve",  # ï (U+00EF)
+        "10.1000/Müller",  # ü (U+00FC)
+        "10.1000/señor",  # ñ (U+00F1)
+    ],
+)
+def test_valid_doi_with_special_characters(doi: str):
+    """Test that DOIs with DataCite GLIS and Latin Extended characters are valid."""
+    obj = destiny_sdk.identifiers.DOIIdentifier(
+        identifier_type=destiny_sdk.identifiers.ExternalIdentifierType.DOI,
+        identifier=doi,
+    )
+    assert obj.identifier == doi
+
+
+@pytest.mark.parametrize(
+    ("doi_input", "expected"),
+    [
+        # Unicode hyphen → ASCII hyphen
+        ("10.1000/abc\u2010def", "10.1000/abc-def"),
+        # NBSP stripped (leading/trailing)
+        ("\u00a010.1000/xyz123", "10.1000/xyz123"),
+        ("10.1000/xyz123\u00a0", "10.1000/xyz123"),
+        # Case-insensitive URL prefix stripping
+        ("HTTP://DOI.ORG/10.1000/xyz123", "10.1000/xyz123"),
+        ("HTTPS://DOI.ORG/10.1000/xyz123", "10.1000/xyz123"),
+        ("https://DX.DOI.ORG/10.1000/xyz123", "10.1000/xyz123"),
+        ("DOI:10.1000/xyz123", "10.1000/xyz123"),
+        ("doi: 10.1000/xyz123", "10.1000/xyz123"),
+    ],
+)
+def test_doi_canonicalization(doi_input: str, expected: str):
+    """Test DOI canonicalization: Unicode normalization and URL prefix stripping."""
+    obj = destiny_sdk.identifiers.DOIIdentifier(
+        identifier_type=destiny_sdk.identifiers.ExternalIdentifierType.DOI,
+        identifier=doi_input,
+    )
+    assert obj.identifier == expected
+
+
 def test_valid_eric_identifier():
     obj = destiny_sdk.identifiers.ERICIdentifier(
         identifier_type=destiny_sdk.identifiers.ExternalIdentifierType.ERIC,

{destiny_sdk-0.7.4 → destiny_sdk-0.7.6}/uv.lock

@@ -1,5 +1,5 @@
 version = 1
-revision = 2
+revision = 3
 requires-python = ">=3.12, <4"
 
 [[package]]
@@ -233,7 +233,7 @@ wheels = [
 
 [[package]]
 name = "destiny-sdk"
-version = "0.6.0"
+version = "0.7.6"
 source = { editable = "." }
 dependencies = [
     { name = "cachetools" },
@@ -241,9 +241,6 @@ dependencies = [
     { name = "httpx" },
     { name = "msal" },
     { name = "pydantic" },
-    { name = "pytest" },
-    { name = "pytest-asyncio" },
-    { name = "pytest-httpx" },
     { name = "python-jose" },
 ]
 
@@ -251,7 +248,10 @@ dependencies = [
 dev = [
     { name = "mypy" },
     { name = "pre-commit" },
+    { name = "pytest" },
+    { name = "pytest-asyncio" },
     { name = "pytest-env" },
+    { name = "pytest-httpx" },
     { name = "ruff" },
     { name = "uvloop" },
 ]
@@ -263,9 +263,6 @@ requires-dist = [
     { name = "httpx", specifier = ">=0.28.1,<0.29" },
     { name = "msal", specifier = ">=1.34.0" },
     { name = "pydantic", specifier = ">=2.11.3,<3" },
-    { name = "pytest", specifier = ">=8.4.0,<9" },
-    { name = "pytest-asyncio", specifier = ">=1.0.0,<2" },
-    { name = "pytest-httpx", specifier = ">=0.35.0,<0.36" },
     { name = "python-jose", specifier = ">=3.4.0,<4" },
 ]
 provides-extras = ["labs"]
@@ -274,7 +271,10 @@ provides-extras = ["labs"]
 dev = [
     { name = "mypy", specifier = ">=1.15.0,<2" },
     { name = "pre-commit", specifier = ">=4.2.0,<5" },
+    { name = "pytest", specifier = ">=8.4.0,<9" },
+    { name = "pytest-asyncio", specifier = ">=1.0.0,<2" },
     { name = "pytest-env", specifier = ">=1.1.5,<2" },
+    { name = "pytest-httpx", specifier = ">=0.35.0,<0.36" },
     { name = "ruff", specifier = ">=0.11.5,<0.12" },
     { name = "uvloop", specifier = ">=0.21.0,<0.22" },
 ]