destiny_sdk 0.4.1__py3-none-any.whl → 0.5.1__py3-none-any.whl

destiny_sdk/client.py

@@ -114,7 +114,7 @@ class Client:
         return RobotEnhancementBatchRead.model_validate(response.json())
 
     def poll_robot_enhancement_batch(
-        self, robot_id: UUID4, limit: int = 10
+        self, robot_id: UUID4, limit: int = 10, timeout: int = 60
     ) -> RobotEnhancementBatch | None:
         """
         Poll for a robot enhancement batch.
@@ -127,11 +127,12 @@ class Client:
         :type limit: int
         :return: The RobotEnhancementBatch object from the response, or None if no
             batches available
-        :rtype: RobotEnhancementBatch | None
+        :rtype: destiny_sdk.robots.RobotEnhancementBatch | None
         """
         response = self.session.post(
             "/robot-enhancement-batches/",
             params={"robot_id": str(robot_id), "limit": limit},
+            timeout=timeout,
         )
         # HTTP 204 No Content indicates no batches available
         if response.status_code == httpx.codes.NO_CONTENT:

destiny_sdk/enhancements.py

@@ -15,20 +15,18 @@ class EnhancementType(StrEnum):
     The type of enhancement.
 
     This is used to identify the type of enhancement in the `Enhancement` class.
-
-    **Allowed values**:
-    - `bibliographic`: Bibliographic metadata.
-    - `abstract`: The abstract of a reference.
-    - `annotation`: A free-form enhancement for tagging with labels.
-    - `locations`: Locations where the reference can be found.
-    - `full_text`: The full text of the reference. (To be implemeted)
     """
 
     BIBLIOGRAPHIC = auto()
+    """Bibliographic metadata."""
     ABSTRACT = auto()
+    """The abstract of a reference."""
     ANNOTATION = auto()
+    """A free-form enhancement for tagging with labels."""
     LOCATION = auto()
+    """Locations where the reference can be found."""
     FULL_TEXT = auto()
+    """The full text of the reference. (To be implemented)"""
 
 
 class AuthorPosition(StrEnum):
@@ -36,16 +34,14 @@ class AuthorPosition(StrEnum):
     The position of an author in a list of authorships.
 
     Maps to the data from OpenAlex.
-
-    **Allowed values**:
-    - `first`: The first author.
-    - `middle`: Any middle author
-    - `last`: The last author
     """
 
     FIRST = auto()
+    """The first author."""
     MIDDLE = auto()
+    """Any middle author."""
     LAST = auto()
+    """The last author."""
 
 
 class Authorship(BaseModel):
@@ -104,18 +100,14 @@ other works have cited this work
 
 
 class AbstractProcessType(StrEnum):
-    """
-    The process used to acquire the abstract.
-
-    **Allowed values**:
-    - `uninverted`
-    - `closed_api`
-    - `other`
-    """
+    """The process used to acquire the abstract."""
 
     UNINVERTED = auto()
+    """uninverted"""
     CLOSED_API = auto()
+    """closed_api"""
     OTHER = auto()
+    """other"""
 
 
 class AbstractContentEnhancement(BaseModel):
@@ -142,16 +134,15 @@ class AnnotationType(StrEnum):
     The type of annotation.
 
     This is used to identify the type of annotation in the `Annotation` class.
-
-    **Allowed values**:
-    - `boolean`: An annotation which is the boolean application of a label across a
-    reference.
-    - `score`: An annotation which is a score for a label across a reference,
-    without a boolean value.
     """
 
     BOOLEAN = auto()
+    """An annotation which is the boolean application of a label across a reference."""
     SCORE = auto()
+    """
+    An annotation which is a score for a label across a reference, without a boolean
+    value.
+    """
 
 
 class ScoreAnnotation(BaseModel):
@@ -227,22 +218,22 @@ class DriverVersion(StrEnum):
     The version based on the DRIVER guidelines versioning scheme.
 
     (Borrowed from OpenAlex)
-
-    Allowed values:
-    - `publishedVersion`: The document's version of record. This is the most
-    authoritative version.
-    - `acceptedVersion`: The document after having completed peer review and being
-    officially accepted for publication. It will lack publisher formatting, but the
-    content should be interchangeable with the that of the publishedVersion.
-    - `submittedVersion`: the document as submitted to the publisher by the authors, but
-    before peer-review. Its content may differ significantly from that of the accepted
-    article.
     """
 
     PUBLISHED_VERSION = "publishedVersion"
+    """The document's version of record. This is the most authoritative version."""
     ACCEPTED_VERSION = "acceptedVersion"
+    """
+    The document after having completed peer review and being officially accepted for
+    publication. It will lack publisher formatting, but the content should be
+    interchangeable with that of the publishedVersion.
+    """
     SUBMITTED_VERSION = "submittedVersion"
+    """
+    The document as submitted to the publisher by the authors, but before peer-review.
+    Its content may differ significantly from that of the accepted article."""
     OTHER = "other"
+    """Other version."""
 
 
 class Location(BaseModel):
@@ -360,7 +351,6 @@ class EnhancementFileInput(BaseModel):
     visibility: Visibility = Field(
         description="The level of visibility of the enhancement"
     )
-    enhancement_type: EnhancementType = Field(description="The type of enhancement.")
     robot_version: str | None = Field(
         default=None,
         description="The version of the robot that generated the content.",

destiny_sdk/identifiers.py

@@ -1,9 +1,10 @@
 """Identifier classes for the Destiny SDK."""
 
+import uuid
 from enum import StrEnum, auto
-from typing import Annotated, Literal
+from typing import Annotated, Literal, Self
 
-from pydantic import UUID4, BaseModel, Field, field_validator
+from pydantic import UUID4, BaseModel, Field, TypeAdapter, field_validator
 
 
 class ExternalIdentifierType(StrEnum):
@@ -12,19 +13,16 @@ class ExternalIdentifierType(StrEnum):
 
     This is used to identify the type of identifier used in the `ExternalIdentifier`
     class.
-    **Allowed values**:
-    - `doi`: A DOI (Digital Object Identifier) which is a unique identifier for a
-    document.
-    - `pmid`: A PubMed ID which is a unique identifier for a document in PubMed.
-    - `openalex`: An OpenAlex ID which is a unique identifier for a document in
-    OpenAlex.
-    - `other`: Any other identifier not defined. This should be used sparingly.
     """
 
     DOI = auto()
+    """A DOI (Digital Object Identifier) which is a unique identifier for a document."""
     PM_ID = auto()
+    """A PubMed ID which is a unique identifier for a document in PubMed."""
     OPEN_ALEX = auto()
+    """An OpenAlex ID which is a unique identifier for a document in OpenAlex."""
     OTHER = auto()
+    """Any other identifier not defined. This should be used sparingly."""
 
 
 class DOIIdentifier(BaseModel):
@@ -97,6 +95,10 @@ ExternalIdentifier = Annotated[
     Field(discriminator="identifier_type"),
 ]
 
+ExternalIdentifierAdapter: TypeAdapter[ExternalIdentifier] = TypeAdapter(
+    ExternalIdentifier
+)
+
 
 class LinkedExternalIdentifier(BaseModel):
     """An external identifier which identifies a reference."""
@@ -108,3 +110,83 @@ class LinkedExternalIdentifier(BaseModel):
     reference_id: UUID4 = Field(
         description="The ID of the reference this identifier identifies."
     )
+
+
+class IdentifierLookup(BaseModel):
+    """An external identifier lookup."""
+
+    identifier: str = Field(description="The identifier value.")
+    identifier_type: ExternalIdentifierType | None = Field(
+        description="The type of identifier used. If not provided, it is assumed to"
+        " be a DESTINY identifier.",
+    )
+    other_identifier_name: str | None = Field(
+        default=None,
+        description="The name of the undocumented identifier type.",
+    )
+
+    def serialize(self) -> str:
+        """Serialize the identifier lookup to a string."""
+        if self.identifier_type is None:
+            return self.identifier
+        if self.identifier_type == ExternalIdentifierType.OTHER:
+            return f"other:{self.other_identifier_name}:{self.identifier}"
+        return f"{self.identifier_type.value.lower()}:{self.identifier}"
+
+    @classmethod
+    def parse(cls, identifier_lookup_string: str, delimiter: str = ":") -> Self:
+        """Parse an identifier string into an IdentifierLookup."""
+        if delimiter not in identifier_lookup_string:
+            try:
+                UUID4(identifier_lookup_string)
+            except ValueError as exc:
+                msg = (
+                    f"Invalid identifier lookup string: {identifier_lookup_string}. "
+                    "Must be UUIDv4 if no identifier type is specified."
+                )
+                raise ValueError(msg) from exc
+            return cls(
+                identifier=identifier_lookup_string,
+                identifier_type=None,
+            )
+        identifier_type, identifier = identifier_lookup_string.split(delimiter, 1)
+        if identifier_type == ExternalIdentifierType.OTHER:
+            if delimiter not in identifier:
+                msg = (
+                    f"Invalid identifier lookup string: {identifier_lookup_string}. "
+                    "Other identifier type must include other identifier name."
+                )
+                raise ValueError(msg)
+            other_identifier_type, identifier = identifier.split(delimiter, 1)
+            return cls(
+                identifier=identifier,
+                identifier_type=ExternalIdentifierType.OTHER,
+                other_identifier_name=other_identifier_type,
+            )
+        if identifier_type not in ExternalIdentifierType:
+            msg = (
+                f"Invalid identifier lookup string: {identifier_lookup_string}. "
+                f"Unknown identifier type: {identifier_type}."
+            )
+            raise ValueError(msg)
+        return cls(
+            identifier=identifier,
+            identifier_type=ExternalIdentifierType(identifier_type),
+        )
+
+    @classmethod
+    def from_identifier(cls, identifier: ExternalIdentifier | UUID4) -> Self:
+        """Create an IdentifierLookup from an ExternalIdentifier or UUID4."""
+        if isinstance(identifier, uuid.UUID):
+            return cls(identifier=str(identifier), identifier_type=None)
+        return cls(
+            identifier=str(identifier.identifier),
+            identifier_type=identifier.identifier_type,
+            other_identifier_name=getattr(identifier, "other_identifier_name", None),
+        )
+
+    def to_identifier(self) -> ExternalIdentifier | UUID4:
+        """Convert into an ExternalIdentifier or UUID4 if it has no identifier_type."""
+        if self.identifier_type is None:
+            return UUID4(self.identifier)
+        return ExternalIdentifierAdapter.validate_python(self.model_dump())

destiny_sdk/imports.py

@@ -13,90 +13,52 @@ from pydantic import (
 
 
 class ImportRecordStatus(StrEnum):
-    """
-    Describes the status of an import record.
-
-    - `created`: Created, but no processing has started.
-    - `started`: Processing has started on the batch.
-    - `completed`: Processing has been completed.
-    """
+    """Describes the status of an import record."""
 
     CREATED = auto()
+    """Created, but no processing has started."""
     STARTED = auto()
+    """Processing has started on the batch."""
     COMPLETED = auto()
+    """Processing has been completed."""
 
 
 class ImportBatchStatus(StrEnum):
-    """
-    Describes the status of an import batch.
-
-    - `created`: Created, but no processing has started.
-    - `started`: Processing has started on the batch.
-    - `failed`: Processing has failed.
-    - `partially_failed`: Some references succeeded while others failed.
-    - `completed`: Processing has been completed.
-    """
+    """Describes the status of an import batch."""
 
     CREATED = auto()
+    """Created, but no processing has started."""
     STARTED = auto()
+    """Processing has started on the batch."""
     FAILED = auto()
+    """Processing has failed."""
     PARTIALLY_FAILED = auto()
+    """Some references succeeded while others failed."""
     COMPLETED = auto()
-
-
-class CollisionStrategy(StrEnum):
-    """
-    The strategy to use when an identifier collision is detected.
-
-    Identifier collisions are detected on ``identifier_type`` and ``identifier``
-    (and ``other_identifier_name`` where relevant) already present in the database.
-
-    Enhancement collisions are detected on an entry with matching ``enhancement_type``
-    and ``source`` already being present on the collided reference.
-
-    - `discard`: Do nothing with the incoming reference.
-    - `fail`: Do nothing with the incoming reference and mark it as failed. This
-      allows the importing process to "follow up" on the failure.
-    - `merge_aggressive`: Prioritize the incoming reference's identifiers and
-      enhancements in the merge.
-    - `merge_defensive`: Prioritize the existing reference's identifiers and
-      enhancements in the merge.
-    - `append`: Performs an aggressive merge of identifiers, and an append of
-      enhancements.
-    - `overwrite`: Performs an aggressive merge of identifiers, and an overwrite of
-      enhancements (deleting existing and recreating what is imported). This should
-      be used sparingly and carefully.
-    """
-
-    DISCARD = auto()
-    FAIL = auto()
-    MERGE_AGGRESSIVE = auto()
-    MERGE_DEFENSIVE = auto()
-    APPEND = auto()
-    OVERWRITE = auto()
+    """Processing has been completed."""
 
 
 class ImportResultStatus(StrEnum):
-    """
-    Describes the status of an import result.
-
-    - `created`: Created, but no processing has started.
-    - `started`: The reference is currently being processed.
-    - `completed`: The reference has been created.
-    - `partially_failed`: The reference was created but one or more enhancements or
-      identifiers failed to be added. See the result's `failure_details` field for
-      more information.
-    - `failed`: The reference failed to be created. See the result's `failure_details`
-      field for more information.
-    - `retrying`: Processing has failed, but is being retried.
-    """
+    """Describes the status of an import result."""
 
     CREATED = auto()
+    """Created, but no processing has started."""
     STARTED = auto()
+    """The reference is currently being processed."""
     COMPLETED = auto()
+    """The reference has been created."""
     PARTIALLY_FAILED = auto()
+    """
+    The reference was created but one or more enhancements or identifiers failed to
+    be added. See the result's `failure_details` field for more information.
+    """
     FAILED = auto()
+    """
+    The reference failed to be created. See the result's `failure_details` field for
+    more information.
+    """
     RETRYING = auto()
+    """Processing has failed, but is being retried."""
 
 
 class _ImportRecordBase(BaseModel):
@@ -162,13 +124,6 @@ class ImportRecordRead(_ImportRecordBase):
 class _ImportBatchBase(BaseModel):
     """The base class for import batches."""
 
-    collision_strategy: CollisionStrategy = Field(
-        default=CollisionStrategy.FAIL,
-        description="""
-The strategy to use for each reference when an identifier collision occurs.
-Default is `fail`, which allows the importing process to "follow up" on the collision.
-        """,
-    )
     storage_url: HttpUrl = Field(
         description="""
 The URL at which the set of references for this batch are stored. The file is a jsonl
@@ -176,11 +131,6 @@ with each line formatted according to
 :class:`ReferenceFileInput <libs.sdk.src.destiny_sdk.references.ReferenceFileInput>`.
     """,
     )
-    callback_url: HttpUrl | None = Field(
-        default=None,
-        deprecated=True,
-        description="This field is currently a no-op.",
-    )
 
 
 class ImportBatchIn(_ImportBatchBase):

destiny_sdk/parsers/eppi_parser.py

@@ -157,7 +157,6 @@ class EPPIParser:
                     source=parser_source,
                     visibility=Visibility.PUBLIC,
                     content=content,
-                    enhancement_type=content.enhancement_type,
                     robot_version=robot_version,
                 )
                 for content in enhancement_contents

destiny_sdk/robots.py

@@ -159,32 +159,28 @@ If the URL expires, a new one can be generated using
 
 
 class EnhancementRequestStatus(StrEnum):
-    """
-    The status of an enhancement request.
-
-    **Allowed values**:
-    - `received`: Enhancement request has been received by the repo.
-    - `accepted`: Enhancement request has been accepted by the robot.
-    - `processing`: Enhancement request is being processed by the robot.
-    - `rejected`: Enhancement request has been rejected by the robot.
-    - `partial_failed`: Some enhancements failed to create.
-    - `failed`: All enhancements failed to create.
-    - `importing`: Enhancements have been received by the repo and are being imported.
-    - `indexing`: Enhancements have been imported and are being indexed.
-    - `indexing_failed`: Enhancements have been imported but indexing failed.
-    - `completed`: All enhancements have been created.
-    """
+    """The status of an enhancement request."""
 
     RECEIVED = auto()
+    """Enhancement request has been received by the repo."""
     ACCEPTED = auto()
+    """Enhancement request has been accepted by the robot."""
     PROCESSING = auto()
+    """Enhancement request is being processed by the robot."""
     REJECTED = auto()
+    """Enhancement request has been rejected by the robot."""
     PARTIAL_FAILED = auto()
+    """Some enhancements failed to create."""
     FAILED = auto()
+    """All enhancements failed to create."""
     IMPORTING = auto()
+    """Enhancements have been received by the repo and are being imported."""
     INDEXING = auto()
+    """Enhancements have been imported and are being indexed."""
     INDEXING_FAILED = auto()
+    """Enhancements have been imported but indexing failed."""
     COMPLETED = auto()
+    """All enhancements have been created."""
 
 
 class _EnhancementRequestBase(BaseModel):
@@ -334,10 +330,6 @@ class _RobotBase(BaseModel):
     model_config = ConfigDict(extra="forbid")  # Forbid extra fields on robot models
 
     name: str = Field(description="The name of the robot, must be unique.")
-    base_url: HttpUrl = Field(
-        description="The base url of the robot. The robot must implement endpoint"
-        "base_url/batch for batch enhancements of references.",
-    )
     description: str = Field(
         description="Description of the enhancement the robot provides."
     )

destiny_sdk/visibility.py

@@ -9,16 +9,11 @@ class Visibility(StrEnum):
 
     This is used to manage whether information should be publicly available or
     restricted (generally due to copyright constraints from publishers).
-
-    TODO: Implement data governance layer to manage this.
-
-    **Allowed values**:
-
-    - `public`: Visible to the general public without authentication.
-    - `restricted`: Requires authentication to be visible.
-    - `hidden`: Is not visible, but may be passed to data mining processes.
     """
 
     PUBLIC = auto()
+    """Visible to the general public without authentication."""
     RESTRICTED = auto()
+    """Requires authentication to be visible."""
     HIDDEN = auto()
+    """Is not visible, but may be passed to data mining processes."""

{destiny_sdk-0.4.1.dist-info → destiny_sdk-0.5.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: destiny_sdk
-Version: 0.4.1
+Version: 0.5.1
 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>
 License-Expression: Apache-2.0

destiny_sdk-0.5.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+destiny_sdk/__init__.py,sha256=gmmrceJX84T4msk_GSm_OjTQvCpHFZRjnlUK5_7IODE,356
+destiny_sdk/auth.py,sha256=bY72ywZEcG_67YBd9PrwgWTXkCf58rhLvVEXrtXbWtA,6247
+destiny_sdk/client.py,sha256=fTBtuq5emT8ieNtCuCY8Y6xAKZJDLq8sG1WOvmjLz-I,4971
+destiny_sdk/core.py,sha256=_FwDaczKTSaUSV_qfcnLhkBbZagh4ayFpN0qUwJ03-o,1448
+destiny_sdk/enhancements.py,sha256=SkIlIlWKBN7Z-aXpQiy22SXrU7zVnKxaRb4F5yaFsO8,11503
+destiny_sdk/identifiers.py,sha256=1N2cszBmnQoUeKm54-7MUTO-zTDuvW8U9OjTeAmhWvo,7182
+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=Dx-WKcv9gNJkKU9n52AYoEey7siTHR5_wBVBKSHND6Q,2321
+destiny_sdk/robots.py,sha256=I_ZvMxwST52e8ovhv0-gPbOB3P9tptbRG0LrkNNOqKo,13463
+destiny_sdk/visibility.py,sha256=8D44Q868YdScAt6eAFgXXrhonozXnv_Qa5w5yEGMPX8,577
+destiny_sdk/parsers/__init__.py,sha256=d5gS--bXla_0I7e_9wTBnGWMXt2U8b-_ndeprTPe1hk,149
+destiny_sdk/parsers/eppi_parser.py,sha256=rEOtt_5Kp3oktFlzRTLZ2x4_7aQ9-ba3FYpkaEnpnvs,5521
+destiny_sdk-0.5.1.dist-info/METADATA,sha256=eKznxYvVJhW-IVlA16LHzJ2QtpzfG3RyBKk9e-x_o8w,2440
+destiny_sdk-0.5.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+destiny_sdk-0.5.1.dist-info/licenses/LICENSE,sha256=6QURU4gvvTjVZ5rfp5amZ6FtFvcpPhAGUjxF5WSZAHI,9138
+destiny_sdk-0.5.1.dist-info/RECORD,,

destiny_sdk-0.4.1.dist-info/RECORD

@@ -1,17 +0,0 @@
-destiny_sdk/__init__.py,sha256=gmmrceJX84T4msk_GSm_OjTQvCpHFZRjnlUK5_7IODE,356
-destiny_sdk/auth.py,sha256=bY72ywZEcG_67YBd9PrwgWTXkCf58rhLvVEXrtXbWtA,6247
-destiny_sdk/client.py,sha256=8l-UdKKdKgSSFZKg2AMhmyegIRD_wLjp8AtxtSuUMf0,4904
-destiny_sdk/core.py,sha256=_FwDaczKTSaUSV_qfcnLhkBbZagh4ayFpN0qUwJ03-o,1448
-destiny_sdk/enhancements.py,sha256=_S_anq194qdaEGklgycSG1qLEJeWzKe1u3oyXNxAg54,11800
-destiny_sdk/identifiers.py,sha256=9CFEaPhZr2IHfL4RSAzOvidXhhzKLDPXiSKddBMWzwM,3606
-destiny_sdk/imports.py,sha256=PG1rNNPdOxTeVI3-8sXFfRYi9BkCVZmr_jqr0Q9mxiU,7845
-destiny_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-destiny_sdk/references.py,sha256=Dx-WKcv9gNJkKU9n52AYoEey7siTHR5_wBVBKSHND6Q,2321
-destiny_sdk/robots.py,sha256=Okkveik2tFG4JtchnUMbrHcKGglBrR30fiNdtLP00IA,13777
-destiny_sdk/visibility.py,sha256=nDLqnWuSZSk0vG3ynzDpHAvaALsbk8cuEZujTsqf6no,684
-destiny_sdk/parsers/__init__.py,sha256=d5gS--bXla_0I7e_9wTBnGWMXt2U8b-_ndeprTPe1hk,149
-destiny_sdk/parsers/eppi_parser.py,sha256=aSTqmm8N2WK1gnkj38XvfWaEXsaf0y6je6h9qN0xvFA,5584
-destiny_sdk-0.4.1.dist-info/METADATA,sha256=6gCDo23pk4zxjAyADhY6gs3E3l8TWW0zJkpLbbrpTgI,2440
-destiny_sdk-0.4.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-destiny_sdk-0.4.1.dist-info/licenses/LICENSE,sha256=6QURU4gvvTjVZ5rfp5amZ6FtFvcpPhAGUjxF5WSZAHI,9138
-destiny_sdk-0.4.1.dist-info/RECORD,,