destiny_sdk 0.7.2__tar.gz → 0.7.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: destiny_sdk
-Version: 0.7.2
+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.2 → 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.2"
+version = "0.7.4"
 
 [project.optional-dependencies]
 labs = []

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

@@ -1,12 +1,14 @@
 """Enhancement classes for the Destiny Repository."""
 
 import datetime
+import json
 from enum import StrEnum, auto
 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
 
 
@@ -25,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()
@@ -55,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."
@@ -87,6 +95,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 +112,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."""
@@ -301,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.
@@ -332,6 +395,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[
@@ -339,6 +421,7 @@ EnhancementContent = Annotated[
     | AbstractContentEnhancement
     | AnnotationEnhancement
     | LocationEnhancement
+    | ReferenceAssociationEnhancement
     | RawEnhancement,
     Field(discriminator="enhancement_type"),
 ]

{destiny_sdk-0.7.2 → 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)