rmi-stitch-core 0.2.0.dev2__py3-none-any.whl

rmi_stitch_core-0.2.0.dev2.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.3
+Name: rmi-stitch-core
+Version: 0.2.0.dev2
+Summary: Core functionality for the Stitch platform.
+Author: Michael Barlow
+Author-email: Michael Barlow <mbarlow@rmi.org>
+Requires-Dist: pydantic>=2.14.3
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+

rmi_stitch_core-0.2.0.dev2.dist-info/RECORD

@@ -0,0 +1,12 @@
+stitch/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+stitch/core/_internal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+stitch/core/_internal/typings/__init__.py,sha256=IsOTv49ilV0cUr43mnCy6EjH7mzKfSLRgbiZ7sbmf2Y,73
+stitch/core/_internal/typings/facades.py,sha256=jEu5YGuXgOY7LblnSqzquqIT9b7F3CG_En9QdKdIEpY,1722
+stitch/core/_internal/typings/models.py,sha256=ysTRgRanmoBBkC42KhUI8XxczsQ35tD7B8-3uu9qDLs,808
+stitch/core/_internal/typings/repositories.py,sha256=oGn6WYSXDZMiM5I2vqkCQjJmhN_dzKXfUcYThJ2MPo4,543
+stitch/core/_internal/typings/resource.py,sha256=iY8uGCQuOq9MzKc5a4rCzQZLf3jTVhzMS9oKxcerJKE,598
+stitch/core/models.py,sha256=AVmPM_Ij8MNZgjaHFQZtxL9MxJ9ZfbZ4jxY56TsPMjg,3069
+stitch/core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rmi_stitch_core-0.2.0.dev2.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+rmi_stitch_core-0.2.0.dev2.dist-info/METADATA,sha256=Yak-3op6Rfl6AqGVJJe0PtASw3KqsxhkK6rlhWKQXJA,284
+rmi_stitch_core-0.2.0.dev2.dist-info/RECORD,,

rmi_stitch_core-0.2.0.dev2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.7
+Root-Is-Purelib: true
+Tag: py3-none-any

stitch/core/_internal/typings/__init__.py

@@ -0,0 +1,3 @@
+from .models import IdType, JsonValue
+
+__all__ = ["IdType", "JsonValue"]

stitch/core/_internal/typings/facades.py

@@ -0,0 +1,62 @@
+from collections.abc import Collection, Sequence
+from typing import Any, Protocol, overload
+
+from .repositories import (
+    ResourceRepository,
+    SourceRepository,
+    UserRepository,
+)
+
+type ResourceQueryParams = Any
+type SourceQueryParams = Any
+type MergeQueryParams = Any
+
+
+class PersistenceFacade[TResource, TSource, TMerge, TId](Protocol):
+    __resource_model__: type[TResource]
+    __source_model__: type[TSource]
+    _users: UserRepository
+    _resources: ResourceRepository[TResource, TId]
+    _sources: SourceRepository[TSource]
+
+    async def query_resources(
+        self, params: ResourceQueryParams, offset: int = 0, limit: int | None = None
+    ) -> Collection[TResource]:
+        pass
+
+    async def query_resource_values(self, params: ResourceQueryParams) -> Collection[TResource]:
+        """For filter options."""
+        pass
+
+    async def query_sources(
+        self, params: SourceQueryParams, offset: int = 0, limit: int | None = None
+    ) -> Collection[TSource]:
+        pass
+
+    async def query_merges(
+        self, params: MergeQueryParams, offset: int = 0, limit: int | None = None
+    ) -> Collection[TMerge]:
+        pass
+
+    async def get_resource(self, id: TId) -> TResource:
+        pass
+
+    async def get_source(self, id: TId) -> TSource:
+        pass
+
+    async def get_merge(self, id: TId) -> TMerge:
+        pass
+
+    @overload
+    async def merge_resources(self, resources: Sequence[TResource], /) -> TResource:
+        pass
+
+    @overload
+    async def merge_resources(self, ids: Sequence[TId], /) -> TResource:
+        pass
+
+    async def undo_merge(self, id: TId): ...
+
+    async def unmerge_resource(self, id: TId): ...
+
+    async def attach_source_to_resource(self): ...

stitch/core/_internal/typings/models.py

@@ -0,0 +1,28 @@
+from typing import Annotated, Protocol, runtime_checkable
+from uuid import UUID
+
+from pydantic import Field
+
+IdType = int | UUID
+type JsonValue = None | bool | int | float | str | list["JsonValue"] | dict[str, "JsonValue"]
+
+Year = Annotated[int, Field(ge=1700, le=2100)]
+FractionalPercentage = Annotated[float, Field(ge=0.0, le=100)]
+Latitude = Annotated[float, Field(ge=-90.0, le=90.0)]
+Longitude = Annotated[float, Field(ge=-180.0, le=180.0)]
+CountryCodeAlpha3 = Annotated[str, Field(pattern=r"^[A-Z]{3}$")]
+
+
+@runtime_checkable
+class Identified[TId: IdType](Protocol):
+    @property
+    def id(self) -> TId: ...
+
+
+@runtime_checkable
+class SourceRef[TId: IdType, TSrcKey: str](Identified[TId], Protocol):
+    @property
+    def source(self) -> TSrcKey: ...
+
+
+type ResourceRef[TId: IdType] = Identified[TId]

stitch/core/_internal/typings/repositories.py

@@ -0,0 +1,25 @@
+from collections.abc import Collection
+from typing import Any, Protocol
+
+
+class UserRepository(Protocol): ...
+
+
+type Params = Any
+
+
+class ResourceRepository[T, TId](Protocol):
+    async def create(self) -> T: ...
+
+    async def get_one(self, id: TId) -> T: ...
+
+    async def get_many(self, id: TId) -> Collection[T]: ...
+
+    async def query(
+        self, params: Params, limit: int = 0, offset: int | None = None
+    ) -> Collection[T]: ...
+
+    async def update(self, id: TId, item: T) -> T: ...
+
+
+class SourceRepository[T](Protocol): ...

stitch/core/_internal/typings/resource.py

@@ -0,0 +1,31 @@
+from typing import Literal, Protocol
+
+
+class IResource[TId](Protocol):
+    @classmethod
+    def model_class(cls): ...
+
+    @property
+    def model(self): ...
+
+    @property
+    def stored(self) -> bool: ...
+
+    @property
+    def id_type(self) -> type[TId]: ...
+
+
+class FreeResource[TId](IResource[TId], Protocol):
+    @property
+    def stored(self) -> Literal[False]: ...
+
+
+class PersistedResource[TId](IResource[TId], Protocol):
+    @property
+    def id(self) -> TId: ...
+
+    @property
+    def stored(self) -> Literal[True]: ...
+
+
+type Resource[TId] = FreeResource[TId] | PersistedResource[TId]

stitch/core/models.py

@@ -0,0 +1,102 @@
+from collections.abc import Sequence
+from datetime import datetime
+from typing import (
+    ClassVar,
+    NamedTuple,
+)
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ._internal.typings import IdType, JsonValue
+
+__all__ = [
+    "Resource",
+    "Source",
+    "SourcePayload",
+    "SourceRecord",
+    "SourceRefTuple",
+    "SourceView",
+]
+
+
+class SourceRecord(BaseModel):
+    record_id: str | None = None
+    run_id: str | None = None
+    observed_at: datetime
+    producer: str
+    payload: JsonValue
+
+
+class Source[TId: IdType, TSrcKey: str](BaseModel):
+    """Base class for dependent, canonical `Source` data declarations.
+
+    Used for creational patterns and to handle use cases where identifiers should NOT be present.
+
+    Attributes:
+        source: key for identifying the data source
+    """
+
+    id: TId | None = None
+    source: TSrcKey
+    source_record: SourceRecord
+
+    # we set `from_attributes=True` to accommodate ORM or other object mappings
+    model_config: ClassVar[ConfigDict] = ConfigDict(from_attributes=True, extra="ignore")
+
+
+class SourceView[TId: IdType, TSrcKey: str](Source[TId, TSrcKey]):
+    source_record: SourceRecord | None = Field(default=None, exclude=True)  # ty: ignore[invalid-attribute-override]
+
+
+class SourcePayload(BaseModel):
+    """Base for domain-specific source payload containers.
+
+    Subclass and declare attributes that hold collections (for example, mappings)
+    of :class:`Source` instances keyed and structured as appropriate for your domain.
+    """
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(from_attributes=True)
+
+
+class SourceRefTuple[TId: IdType, TKey: str](NamedTuple):
+    id: TId
+    source: TKey
+
+
+class Resource[TResId: IdType, TSrc: Source](BaseModel):
+    id: TResId | None = None
+    source_data: Sequence[TSrc] = Field(default_factory=list)
+    repointed_to: TResId | None = Field(default=None)
+    constituents: frozenset[TResId] = Field(default_factory=frozenset)
+
+    model_config = ConfigDict(extra="forbid")
+
+    @model_validator(mode="after")
+    def _no_self_reference(self):
+        if self.id is not None:
+            if self.id in self.constituents:
+                raise ValueError("A resource cannot be a constituent of itself")
+            if self.repointed_to == self.id:
+                raise ValueError("A resource cannot be repointed to itself")
+        return self
+
+
+class Resource_[
+    TResId: IdType,
+    TPayload: SourcePayload,
+](BaseModel):
+    id: TResId | None = None
+    source_data: TPayload
+    repointed_to: TResId | None = Field(default=None)
+    constituents: frozenset[TResId] = Field(default_factory=frozenset)
+
+    model_config = ConfigDict(extra="ignore")
+
+    @model_validator(mode="after")
+    def _no_self_reference(self):
+        if self.id is not None:
+            if self.id in self.constituents:
+                raise ValueError("A resource cannot be a constituent of itself")
+            if self.repointed_to == self.id:
+                raise ValueError("A resource cannot be repointed to itself")
+        return self