destiny_sdk 0.7.3__tar.gz → 0.7.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: destiny_sdk
-Version: 0.7.3
+Version: 0.7.4
 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.4}/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.4"
 
 [project.optional-dependencies]
 labs = []

{destiny_sdk-0.7.3 → destiny_sdk-0.7.4}/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.4}/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.4}/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,
+        )