destiny_sdk 0.7.3__tar.gz → 0.7.5__tar.gz

{destiny_sdk-0.7.3 → destiny_sdk-0.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: destiny_sdk
-Version: 0.7.3
+Version: 0.7.5
 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

{destiny_sdk-0.7.3 → destiny_sdk-0.7.5}/pyproject.toml

@@ -35,7 +35,7 @@ license = "Apache-2.0"
 name = "destiny_sdk"
 readme = "README.md"
 requires-python = "~=3.12"
-version = "0.7.3"
+version = "0.7.5"
 
 [project.optional-dependencies]
 labs = []

{destiny_sdk-0.7.3 → destiny_sdk-0.7.5}/src/destiny_sdk/client.py

@@ -479,6 +479,7 @@ class OAuthClient:
         self,
         base_url: HttpUrl | str,
         auth: httpx.Auth | None = None,
+        timeout: int = 10,
     ) -> None:
         """
         Initialize the client.
@@ -490,6 +491,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 +500,7 @@ class OAuthClient:
                 "Content-Type": "application/json",
                 "User-Agent": user_agent,
             },
+            timeout=timeout,
         )
 
         if auth:
@@ -529,6 +533,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 +552,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 +570,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 +578,7 @@ class OAuthClient:
     def lookup(
         self,
         identifiers: list[str | IdentifierLookup],
+        timeout: int | None = None,
     ) -> list[Reference]:
         """
         Lookup references by identifiers.
@@ -577,6 +587,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 +598,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.3 → destiny_sdk-0.7.5}/src/destiny_sdk/enhancements.py

@@ -8,6 +8,7 @@ from typing import Annotated, Any, Literal, Self
 from pydantic import UUID4, BaseModel, Field, HttpUrl, model_validator
 
 from destiny_sdk.core import _JsonlFileInputMixIn
+from destiny_sdk.identifiers import Identifier
 from destiny_sdk.visibility import Visibility
 
 
@@ -26,6 +27,8 @@ class EnhancementType(StrEnum):
     """A free-form enhancement for tagging with labels."""
     LOCATION = auto()
     """Locations where the reference can be found."""
+    REFERENCE_ASSOCIATION = auto()
+    """Associations to other references."""
     RAW = auto()
     """A free form enhancement for arbitrary/unstructured data."""
     FULL_TEXT = auto()
@@ -56,7 +59,11 @@ class Authorship(BaseModel):
     for our purposes.
     """
 
-    display_name: str = Field(description="The display name of the author.")
+    display_name: str = Field(
+        description="The display name of the author. "
+        "Expected format FIRSTNAME <MIDDLENAME> LASTNAME. "
+        "Providing display_name in an unexpected format will affect search performance."
+    )
     orcid: str | None = Field(default=None, description="The ORCid of the author.")
     position: AuthorPosition = Field(
         description="The position of the author within the list of authors."
@@ -320,6 +327,43 @@ class LocationEnhancement(BaseModel):
     )
 
 
+class ReferenceAssociationType(StrEnum):
+    """
+    The type of association between references.
+
+    Direction is important: "this reference <association_type> associated reference".
+    """
+
+    CITES = auto()
+    """This reference cites the related reference."""
+    IS_CITED_BY = auto()
+    """This reference is cited by the related reference."""
+    IS_SIMILAR_TO = auto()
+    """This reference is similar to the related reference."""
+
+
+class ReferenceAssociationEnhancement(BaseModel):
+    """An enhancement for storing associations between references."""
+
+    enhancement_type: Literal[EnhancementType.REFERENCE_ASSOCIATION] = (
+        EnhancementType.REFERENCE_ASSOCIATION
+    )
+    associated_reference_ids: list[Identifier] = Field(
+        min_length=1,
+        description=(
+            "A list of Identifiers which are associated to this reference. "
+            "These can either be ExternalIdentifiers or resolved repository UUID4s."
+        ),
+    )
+    association_type: ReferenceAssociationType = Field(
+        description=(
+            "The type of association between this reference and the associated ones. "
+            "Direction is important: "
+            '"this reference <association_type> associated reference".'
+        )
+    )
+
+
 class RawEnhancement(BaseModel):
     """
     An enhancement for storing raw/arbitrary/unstructured data.
@@ -377,6 +421,7 @@ EnhancementContent = Annotated[
     | AbstractContentEnhancement
     | AnnotationEnhancement
     | LocationEnhancement
+    | ReferenceAssociationEnhancement
     | RawEnhancement,
     Field(discriminator="enhancement_type"),
 ]

{destiny_sdk-0.7.3 → destiny_sdk-0.7.5}/src/destiny_sdk/identifiers.py

@@ -165,6 +165,9 @@ ExternalIdentifier = Annotated[
     Field(discriminator="identifier_type"),
 ]
 
+#: Any identifier including external identifiers and repository UUID4s.
+Identifier = Annotated[ExternalIdentifier | UUID4, Field()]
+
 ExternalIdentifierAdapter: TypeAdapter[ExternalIdentifier] = TypeAdapter(
     ExternalIdentifier
 )
@@ -245,7 +248,7 @@ class IdentifierLookup(BaseModel):
         )
 
     @classmethod
-    def from_identifier(cls, identifier: ExternalIdentifier | UUID4) -> Self:
+    def from_identifier(cls, identifier: Identifier) -> Self:
         """Create an IdentifierLookup from an ExternalIdentifier or UUID4."""
         if isinstance(identifier, uuid.UUID):
             return cls(identifier=str(identifier), identifier_type=None)
@@ -255,7 +258,7 @@ class IdentifierLookup(BaseModel):
             other_identifier_name=getattr(identifier, "other_identifier_name", None),
         )
 
-    def to_identifier(self) -> ExternalIdentifier | UUID4:
+    def to_identifier(self) -> Identifier:
         """Convert into an ExternalIdentifier or UUID4 if it has no identifier_type."""
         if self.identifier_type is None:
             return UUID4(self.identifier)

{destiny_sdk-0.7.3 → destiny_sdk-0.7.5}/tests/unit/test_enhancements.py

@@ -173,3 +173,54 @@ def test_empty_location_enhancement_errors():
             enhancement_type=destiny_sdk.enhancements.EnhancementType.LOCATION,
             locations=[],
         )
+
+
+def test_association_enhancement_valid():
+    # Create valid association content
+    association_content = destiny_sdk.enhancements.ReferenceAssociationEnhancement(
+        enhancement_type=destiny_sdk.enhancements.EnhancementType.REFERENCE_ASSOCIATION,
+        associated_reference_ids=[
+            uuid.uuid4(),
+            destiny_sdk.identifiers.OpenAlexIdentifier(
+                identifier="https://openalex.org/W1234567890",
+                identifier_type=destiny_sdk.identifiers.ExternalIdentifierType.OPEN_ALEX,
+            ),
+        ],
+        association_type=destiny_sdk.enhancements.ReferenceAssociationType.CITES,
+    )
+    enhancement = destiny_sdk.enhancements.Enhancement(
+        id=uuid.uuid4(),
+        source="test_source",
+        visibility="public",
+        robot_version="1.0",
+        enhancement_type=destiny_sdk.enhancements.EnhancementType.REFERENCE_ASSOCIATION,
+        content=association_content,
+        reference_id=uuid.uuid4(),
+    )
+    assert (
+        enhancement.content.association_type
+        == destiny_sdk.enhancements.ReferenceAssociationType.CITES
+    )
+    assert enhancement.content.associated_reference_ids[1].identifier == "W1234567890"
+
+
+def test_association_enhancement_empty_associated_reference_ids_errors():
+    # Test that an empty associated_reference_ids list raises a validation error
+    with pytest.raises(ValidationError):
+        destiny_sdk.enhancements.ReferenceAssociationEnhancement(
+            enhancement_type=destiny_sdk.enhancements.EnhancementType.REFERENCE_ASSOCIATION,
+            associated_reference_ids=[],
+            association_type=destiny_sdk.enhancements.ReferenceAssociationType.CITES,
+        )
+
+
+def test_association_enhancement_invalid_identifier_type_errors():
+    # Test that an invalid identifier type raises a validation error
+    with pytest.raises(ValidationError):
+        destiny_sdk.enhancements.ReferenceAssociationEnhancement(
+            enhancement_type=destiny_sdk.enhancements.EnhancementType.REFERENCE_ASSOCIATION,
+            associated_reference_ids=[
+                "random-string",
+            ],
+            association_type=destiny_sdk.enhancements.ReferenceAssociationType.CITES,
+        )