destiny_sdk 0.5.0__tar.gz → 0.6.0__tar.gz

{destiny_sdk-0.5.0 → destiny_sdk-0.6.0}/.gitignore

@@ -15,6 +15,7 @@ downloads/
 eggs/
 .eggs/
 lib/
+!/ui/lib/
 lib64/
 parts/
 sdist/
@@ -186,6 +187,9 @@ cython_debug/
 # Mac Finder config
 .DS_Store
 
+# Include everything in ui (has its own .gitignore)
+!/ui/
+
 # delete-me working files
 tmp-scripts.sh
 infra/app/*.py
@@ -194,3 +198,8 @@ infra/app/*.py
 .certs
 
 libs/fake_data/*.jsonl
+
+.data
+.env.*
+!.env.example
+.idea/

{destiny_sdk-0.5.0 → destiny_sdk-0.6.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: destiny_sdk
-Version: 0.5.0
+Version: 0.6.0
 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>
+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
@@ -14,6 +14,7 @@ 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
@@ -34,6 +35,13 @@ pip install destiny-sdk
 uv add destiny-sdk
 ```
 
+Some labs functionality may require extra dependencies - these can be installed by:
+
+```sh
+pip install destiny-sdk[labs]
+uv add destiny-sdk --extra labs
+```
+
 ## Development
 
 ### Dependencies

{destiny_sdk-0.5.0 → destiny_sdk-0.6.0}/README.md

@@ -16,6 +16,13 @@ pip install destiny-sdk
 uv add destiny-sdk
 ```
 
+Some labs functionality may require extra dependencies - these can be installed by:
+
+```sh
+pip install destiny-sdk[labs]
+uv add destiny-sdk --extra labs
+```
+
 ## Development
 
 ### Dependencies

{destiny_sdk-0.5.0 → destiny_sdk-0.6.0}/pyproject.toml

@@ -17,6 +17,7 @@ authors = [
     {email = "andrew@futureevidence.org", name = "Andrew Harvey"},
     {email = "daniel@futureevidence.org", name = "Daniel Breves"},
     {email = "jack@futureevidence.org", name = "Jack Walmisley"},
+    {email = "tim.repke@pik-potsdam.de", name = "Tim Repke"},
 ]
 dependencies = [
     "cachetools>=5.5.2,<6",
@@ -33,7 +34,10 @@ license = "Apache-2.0"
 name = "destiny_sdk"
 readme = "README.md"
 requires-python = "~=3.12"
-version = "0.5.0"
+version = "0.6.0"
+
+[project.optional-dependencies]
+labs = []
 
 [tool.pytest.ini_options]
 addopts = ["--color=yes", "--import-mode=importlib", "--verbose"]

{destiny_sdk-0.5.0 → destiny_sdk-0.6.0}/src/destiny_sdk/__init__.py

@@ -8,6 +8,7 @@ from . import (
     imports,
     references,
     robots,
+    search,
     visibility,
 )
 
@@ -19,5 +20,6 @@ __all__ = [
     "imports",
     "references",
     "robots",
+    "search",
     "visibility",
 ]

{destiny_sdk-0.5.0 → destiny_sdk-0.6.0}/src/destiny_sdk/core.py

@@ -2,7 +2,9 @@
 
 from typing import Self
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
+
+from destiny_sdk.search import SearchResultPage, SearchResultTotal
 
 # These are non-standard newline characters that are not escaped by model_dump_json().
 # We want jsonl files to have empirical new lines so they can be streamed line by line.
@@ -47,3 +49,14 @@ class _JsonlFileInputMixIn(BaseModel):
         :rtype: Self
         """
         return cls.model_validate_json(jsonl)
+
+
+class SearchResultMixIn(BaseModel):
+    """A mixin class for models that represent search results."""
+
+    total: SearchResultTotal = Field(
+        description="The total number of results matching the search criteria.",
+    )
+    page: SearchResultPage = Field(
+        description="Information about the page of results.",
+    )

destiny_sdk-0.6.0/src/destiny_sdk/identifiers.py

@@ -0,0 +1,192 @@
+"""Identifier classes for the Destiny SDK."""
+
+import uuid
+from enum import StrEnum, auto
+from typing import Annotated, Literal, Self
+
+from pydantic import UUID4, BaseModel, Field, TypeAdapter, field_validator
+
+
+class ExternalIdentifierType(StrEnum):
+    """
+    The type of identifier used to identify a reference.
+
+    This is used to identify the type of identifier used in the `ExternalIdentifier`
+    class.
+    """
+
+    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):
+    """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%<>\[\]+&]+$",
+    )
+    identifier_type: Literal[ExternalIdentifierType.DOI] = Field(
+        ExternalIdentifierType.DOI, description="The type of identifier used."
+    )
+
+    @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://doi.org/")
+            .removeprefix("https://doi.org/")
+            .strip()
+        )
+
+
+class PubMedIdentifier(BaseModel):
+    """An external identifier representing a PubMed ID."""
+
+    identifier: int = Field(description="The PubMed ID of the reference.")
+    identifier_type: Literal[ExternalIdentifierType.PM_ID] = Field(
+        ExternalIdentifierType.PM_ID, description="The type of identifier used."
+    )
+
+
+class OpenAlexIdentifier(BaseModel):
+    """An external identifier representing an OpenAlex ID."""
+
+    identifier: str = Field(
+        description="The OpenAlex ID of the reference.", pattern=r"^W\d+$"
+    )
+    identifier_type: Literal[ExternalIdentifierType.OPEN_ALEX] = Field(
+        ExternalIdentifierType.OPEN_ALEX, description="The type of identifier used."
+    )
+
+    @field_validator("identifier", mode="before")
+    @classmethod
+    def remove_open_alex_url(cls, value: str) -> str:
+        """Remove the OpenAlex URL if it exists."""
+        return (
+            value.removeprefix("http://openalex.org/")
+            .removeprefix("https://openalex.org/")
+            .strip()
+        )
+
+
+class OtherIdentifier(BaseModel):
+    """An external identifier not otherwise defined by the repository."""
+
+    identifier: str = Field(description="The identifier of the reference.")
+    identifier_type: Literal[ExternalIdentifierType.OTHER] = Field(
+        ExternalIdentifierType.OTHER, description="The type of identifier used."
+    )
+    other_identifier_name: str = Field(
+        description="The name of the undocumented identifier type."
+    )
+
+
+#: Union type for all external identifiers.
+ExternalIdentifier = Annotated[
+    DOIIdentifier | PubMedIdentifier | OpenAlexIdentifier | OtherIdentifier,
+    Field(discriminator="identifier_type"),
+]
+
+ExternalIdentifierAdapter: TypeAdapter[ExternalIdentifier] = TypeAdapter(
+    ExternalIdentifier
+)
+
+
+class LinkedExternalIdentifier(BaseModel):
+    """An external identifier which identifies a reference."""
+
+    identifier: ExternalIdentifier = Field(
+        description="The identifier of the reference.",
+        discriminator="identifier_type",
+    )
+    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-0.6.0/src/destiny_sdk/labs/__init__.py

@@ -0,0 +1,10 @@
+"""
+Experimental DESTINY SDK.
+
+The DESTINY SDK-labs provides experimental features
+for interacting with DESTINY repository.
+"""
+
+from . import references
+
+__all__ = ["references"]

destiny_sdk-0.6.0/src/destiny_sdk/labs/references.py

@@ -0,0 +1,154 @@
+"""
+Extended Reference SDK.
+
+Extended Reference class for the Destiny SDK
+with added experimental convenience methods and properties.
+"""
+
+from collections.abc import Generator
+from typing import cast
+
+from pydantic import BaseModel, Field
+
+from destiny_sdk.enhancements import (
+    Annotation,
+    AnnotationType,
+    BibliographicMetadataEnhancement,
+    EnhancementType,
+)
+from destiny_sdk.identifiers import ExternalIdentifierType
+from destiny_sdk.references import Reference
+
+
+class LabsReference(BaseModel):
+    """Experimental presenter class for Reference with added convenience methods."""
+
+    reference: Reference = Field(
+        ...,
+        description="The core Reference object",
+    )
+
+    def _get_id(self, identifier_type: ExternalIdentifierType) -> str | int | None:
+        """Fetch an identifier matching the given identifier_type."""
+        for identifier in self.reference.identifiers or []:
+            if identifier.identifier_type == identifier_type:
+                return identifier.identifier
+        return None
+
+    @property
+    def openalex_id(self) -> str | None:
+        """Return an OpenAlex ID for the reference."""
+        return cast(
+            str | None, self._get_id(identifier_type=ExternalIdentifierType.OPEN_ALEX)
+        )
+
+    @property
+    def doi(self) -> str | None:
+        """Return a DOI for the reference."""
+        return cast(
+            str | None, self._get_id(identifier_type=ExternalIdentifierType.DOI)
+        )
+
+    @property
+    def pubmed_id(self) -> int | None:
+        """Return a pubmed ID for the reference."""
+        return cast(
+            int | None, self._get_id(identifier_type=ExternalIdentifierType.PM_ID)
+        )
+
+    @property
+    def abstract(self) -> str | None:
+        """Return an abstract for the reference."""
+        for enhancement in self.reference.enhancements or []:
+            if enhancement.content.enhancement_type == EnhancementType.ABSTRACT:
+                return enhancement.content.abstract
+        return None
+
+    @property
+    def publication_year(self) -> int | None:
+        """Return a publication year for the reference."""
+        for meta in self.it_bibliographics():
+            if meta.publication_year is not None:
+                return meta.publication_year
+        return None
+
+    @property
+    def title(self) -> str | None:
+        """The title of the reference. If multiple are present, return first one."""
+        for meta in self.it_bibliographics():
+            if meta.title is not None:
+                return meta.title
+        return None
+
+    def it_bibliographics(
+        self,
+    ) -> Generator[BibliographicMetadataEnhancement, None, None]:
+        """Iterate bibliographic enhancements."""
+        for enhancement in self.reference.enhancements or []:
+            if enhancement.content.enhancement_type == EnhancementType.BIBLIOGRAPHIC:
+                yield enhancement.content
+
+    def it_annotations(
+        self,
+        source: str | None = None,
+        annotation_type: AnnotationType | None = None,
+        scheme: str | None = None,
+        label: str | None = None,
+    ) -> Generator[Annotation, None, None]:
+        """
+        Iterate annotation enhancements for the given filters.
+
+        :param source: Optional filter for Enhancement.source
+        :param annotation_type: Optional filter for
+                                AnnotationEnhancement.annotation_type
+        :param scheme: Optional filter for Annotation.scheme
+        :param label: Optional filter for Annotation.label
+        """
+        for enhancement in self.reference.enhancements or []:
+            if enhancement.content.enhancement_type == EnhancementType.ANNOTATION:
+                if source is not None and enhancement.source != source:
+                    continue
+                for annotation in enhancement.content.annotations:
+                    if (
+                        annotation_type is not None
+                        and annotation.annotation_type != annotation_type
+                    ):
+                        continue
+                    if scheme is not None and annotation.scheme != scheme:
+                        continue
+                    if label is not None and annotation.label != label:
+                        continue
+                    yield annotation
+
+    def has_bool_annotation(
+        self,
+        source: str | None = None,
+        scheme: str | None = None,
+        label: str | None = None,
+        expected_value: bool = True,  # noqa: FBT001, FBT002
+    ) -> bool | None:
+        """
+        Check if a specific annotation exists and is true.
+
+        :param source: Optional filter for Enhancement.source
+        :param scheme: Optional filter for Annotation.scheme
+        :param label: Optional filter for Annotation.label
+        :param expected_value: Specify expected boolean annotation value
+        :return: Returns the boolean value for the first annotation matching
+                 the filters or None if nothing is found.
+        """
+        if scheme is None and label is None:
+            msg = "Please use at least one of the optional scheme or label filters."
+            raise AssertionError(msg)
+
+        found_annotation = False
+        for annotation in self.it_annotations(
+            source=source,
+            annotation_type=AnnotationType.BOOLEAN,
+            scheme=scheme,
+            label=label,
+        ):
+            if annotation.value == expected_value:
+                return True
+            found_annotation = True
+        return False if found_annotation else None

{destiny_sdk-0.5.0 → destiny_sdk-0.6.0}/src/destiny_sdk/references.py

@@ -4,7 +4,7 @@ from typing import Self
 
 from pydantic import UUID4, BaseModel, Field, TypeAdapter
 
-from destiny_sdk.core import _JsonlFileInputMixIn
+from destiny_sdk.core import SearchResultMixIn, _JsonlFileInputMixIn
 from destiny_sdk.enhancements import Enhancement, EnhancementFileInput
 from destiny_sdk.identifiers import ExternalIdentifier
 from destiny_sdk.visibility import Visibility
@@ -65,3 +65,11 @@ class ReferenceFileInput(_JsonlFileInputMixIn, BaseModel):
         default=None,
         description="A list of enhancements for the reference",
     )
+
+
+class ReferenceSearchResult(SearchResultMixIn, BaseModel):
+    """A search result for references."""
+
+    references: list[Reference] = Field(
+        description="The references returned by the search.",
+    )

destiny_sdk-0.6.0/src/destiny_sdk/search.py

@@ -0,0 +1,52 @@
+"""Models for search queries and results."""
+
+from pydantic import BaseModel, Field
+
+
+class SearchResultTotal(BaseModel):
+    """Information about the total number of search results."""
+
+    count: int = Field(
+        description="The total number of results matching the search criteria.",
+    )
+    is_lower_bound: bool = Field(
+        description="Whether the count is a lower bound (true) or exact (false).",
+    )
+
+
+class SearchResultPage(BaseModel):
+    """Information about the page of search results."""
+
+    count: int = Field(
+        description="The number of results on this page.",
+    )
+    number: int = Field(
+        description="The page number of results returned, indexed from 1.",
+    )
+
+
+class AnnotationFilter(BaseModel):
+    """An annotation filter for search queries."""
+
+    scheme: str = Field(
+        description="The annotation scheme to filter by.",
+    )
+    label: str | None = Field(
+        None,
+        description="The annotation label to filter by.",
+    )
+    score: float | None = Field(
+        None,
+        description="The minimum score for the annotation filter.",
+        ge=0.0,
+        le=1.0,
+    )
+
+    def serialize(self) -> str:
+        """Serialize the annotation filter to a string."""
+        annotation = self.scheme
+        if self.label:
+            annotation += f"/{self.label}"
+        if self.score is not None:
+            annotation += f"@{self.score}"
+        return annotation