pixeltable 0.2.26__py3-none-any.whl → 0.5.7__py3-none-any.whl

pixeltable/share/protocol/__init__.py

@@ -0,0 +1,33 @@
+"""
+Pixeltable Core Protocol
+
+This module contains the core protocol structures for pixeltable table operations
+that can be shared between pixeltable core and cloud implementations.
+"""
+
+from .common import PxtUri, RequestBaseModel
+from .operation_types import ReplicaOperationType
+from .replica import (
+    DeleteRequest,
+    DeleteResponse,
+    FinalizeRequest,
+    FinalizeResponse,
+    PublishRequest,
+    PublishResponse,
+    ReplicateRequest,
+    ReplicateResponse,
+)
+
+__all__ = [
+    'DeleteRequest',
+    'DeleteResponse',
+    'FinalizeRequest',
+    'FinalizeResponse',
+    'PublishRequest',
+    'PublishResponse',
+    'PxtUri',
+    'ReplicaOperationType',
+    'ReplicateRequest',
+    'ReplicateResponse',
+    'RequestBaseModel',
+]

pixeltable/share/protocol/common.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import uuid
+from abc import ABC, abstractmethod
+from typing import Any
+from urllib.parse import urlparse
+from uuid import UUID
+
+from pydantic import BaseModel, model_validator
+
+# Protocol version for replica operations. Used by both client and server
+# to determine request/response format and maintain backward compatibility.
+PROTOCOL_VERSION = 1
+
+
+def is_valid_uuid(uuid_string: str) -> bool:
+    """Check if a string is a valid UUID."""
+    try:
+        uuid.UUID(uuid_string)
+        return True
+    except (ValueError, TypeError):
+        return False
+
+
+class PxtUri(BaseModel):
+    """Pixeltable URI model for pxt:// URIs with validation and parsing."""
+
+    uri: str  # The full URI string
+
+    # Parsed components
+    org: str  # Organization slug from the URI
+    db: str | None  # Database slug from the URI (optional)
+    path: str | None = None  # The table or directory path (None if using UUID)
+    id: UUID | None = None  # The table UUID (None if using path)
+    version: int | None = None  # Optional version number parsed from URI (format: identifier:<version>)
+
+    def __init__(self, uri: str | dict | None = None, **kwargs: Any) -> None:
+        # Handle dict input directly (from JSON deserialization or explicit dict)
+        if isinstance(uri, dict):
+            # Dict input goes directly to Pydantic, which will call parse_uri
+            kwargs.update(uri)
+        elif uri is not None:
+            # Validate that uri is a string when passed as positional argument
+            if not isinstance(uri, str):
+                raise ValueError(f'Invalid data type for PxtUri: expected str or dict, got {type(uri)}')
+            kwargs['uri'] = uri
+        super().__init__(**kwargs)
+
+    @model_validator(mode='before')
+    @classmethod
+    def parse_uri(cls, data: Any) -> dict:
+        # Handle case where data is already a string (from JSON deserialization)
+        if isinstance(data, str):
+            uri = data
+        elif isinstance(data, dict):
+            uri = data.get('uri')
+            if uri is None:
+                raise ValueError('URI must be provided in dict with "uri" key')
+            if not isinstance(uri, str):
+                raise ValueError(f'URI in dict must be a string, got {type(uri)}')
+        else:
+            raise ValueError(f'Invalid data type for PxtUri: expected str or dict, got {type(data)}')
+
+        return {'uri': uri, **cls._parse_and_validate_uri(uri)}
+
+    def __str__(self) -> str:
+        """Return the URI string."""
+        return self.uri
+
+    @classmethod
+    def _parse_and_validate_uri(cls, uri: str) -> dict:
+        """Parse and validate a URI string, return parsed components."""
+        if not uri.startswith('pxt://'):
+            raise ValueError('URI must start with pxt://')
+
+        parsed = urlparse(uri)
+        if parsed.scheme != 'pxt':
+            raise ValueError('URI must use pxt:// scheme')
+
+        if not parsed.netloc:
+            raise ValueError('URI must have an organization')
+
+        # Parse netloc for org and optional db
+        netloc_parts = parsed.netloc.split(':')
+        org = netloc_parts[0]
+        if not org:
+            raise ValueError('URI must have an organization')
+
+        db = netloc_parts[1] if len(netloc_parts) > 1 else None
+
+        # Allow root path (/) as valid, but reject missing path
+        if parsed.path is None:
+            raise ValueError('URI must have a path')
+
+        # Get path and remove leading slash (but keep empty string for root path)
+        # path will be '/' for root directory or '/path/to/table' for regular paths
+        path_part = parsed.path.lstrip('/') if parsed.path else ''
+
+        # Handle version parsing (format: identifier:version)
+        # For root path, path_part will be empty string after lstrip
+        if path_part and ':' in path_part:
+            parts = path_part.rsplit(':', 1)  # Split from right, only once
+            if len(parts) == 2 and parts[1].isdigit():
+                identifier, version = parts[0], int(parts[1])
+            else:
+                identifier, version = path_part, None
+        else:
+            identifier, version = path_part, None
+
+        # Parse identifier into either a path string or UUID
+        path: str | None = None
+        id: UUID | None = None
+        if identifier:
+            if is_valid_uuid(identifier):
+                # It's a UUID
+                id = UUID(identifier)
+            else:
+                # It's a path - keep as string (URI format uses / as separator)
+                # Empty string means root path
+                path = identifier or ''
+        else:
+            # Empty identifier means root path
+            path = ''
+
+        return {'org': org, 'db': db, 'path': path, 'id': id, 'version': version}
+
+    @classmethod
+    def from_components(
+        cls,
+        org: str,
+        path: str | None = None,
+        id: UUID | None = None,
+        db: str | None = None,
+        version: int | None = None,
+    ) -> PxtUri:
+        """Construct a PxtUri from its components."""
+        if path is None and id is None:
+            raise ValueError('Either path or id must be provided')
+        if path is not None and id is not None:
+            raise ValueError('Cannot specify both path and id')
+
+        # Build the URI string from components
+        netloc = org if db is None else f'{org}:{db}'
+
+        # Use path or UUID as identifier
+        if id is not None:
+            identifier = str(id)
+        elif path is not None:
+            # Path is already in URI format (slash-separated)
+            identifier = path or ''
+        else:
+            identifier = ''
+
+        path_part = f'{identifier}:{version}' if version is not None else identifier
+        uri = f'pxt://{netloc}/{path_part}'
+        return cls(uri=uri)
+
+
+class RequestBaseModel(BaseModel, ABC):
+    """Abstract base model for protocol requests that must have a PxtUri."""
+
+    @abstractmethod
+    def get_pxt_uri(self) -> PxtUri:
+        """Get the PxtUri from this request. Must be implemented by subclasses."""
+        pass

pixeltable/share/protocol/operation_types.py

@@ -0,0 +1,33 @@
+"""
+Replica operation types for pixeltable table replica operations.
+
+This module defines the replica operation types that are shared between
+pixeltable core and cloud implementations.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ReplicaOperationType(str, Enum):
+    """Replica operation types for table replica operations."""
+
+    # Table replica operations
+    PUBLISH_REPLICA = 'publish_replica'
+    FINALIZE_REPLICA = 'finalize_replica'
+    CLONE_REPLICA = 'clone_replica'
+    DELETE_REPLICA = 'delete_replica'
+
+    def is_replica_operation(self) -> bool:
+        """Check if operation is a replica operation."""
+        return self in REPLICA_OPERATIONS
+
+
+# Define the operation sets as module-level constants
+REPLICA_OPERATIONS: set[ReplicaOperationType] = {
+    ReplicaOperationType.PUBLISH_REPLICA,
+    ReplicaOperationType.FINALIZE_REPLICA,
+    ReplicaOperationType.CLONE_REPLICA,
+    ReplicaOperationType.DELETE_REPLICA,
+}

pixeltable/share/protocol/replica.py

@@ -0,0 +1,119 @@
+"""
+Core table protocol for pixeltable operations.
+
+This module contains the core table protocol structures that can be shared
+between pixeltable core and cloud implementations.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+from uuid import UUID
+
+from pydantic import AnyUrl, BaseModel, field_validator
+
+from pixeltable.catalog.table_version import TableVersionMd
+from pixeltable.utils.object_stores import StorageTarget
+
+from .common import PxtUri, RequestBaseModel
+from .operation_types import ReplicaOperationType
+
+
+class PublishRequest(RequestBaseModel):
+    """Request to publish or push table replica."""
+
+    operation_type: Literal[ReplicaOperationType.PUBLISH_REPLICA] = ReplicaOperationType.PUBLISH_REPLICA
+    table_uri: PxtUri  # If PxtUri#id is not None then it's considered a push replica request
+    pxt_version: str
+    pxt_md_version: int
+    md: list[TableVersionMd]
+    is_public: bool = False
+    bucket_name: str | None = None  # Optional bucket name, falls back to org's default bucket if not provided
+
+    def get_pxt_uri(self) -> PxtUri:
+        """Get the PxtUri from this request."""
+        return self.table_uri
+
+    @field_validator('md')
+    @classmethod
+    def validate_md_not_empty(cls, v: list[TableVersionMd]) -> list[TableVersionMd]:
+        """Ensure md list has at least one element."""
+        if len(v) == 0:
+            raise ValueError('md list must contain at least one element')
+        return v
+
+
+class PublishResponse(BaseModel):
+    """Response from publishing a table replica."""
+
+    upload_id: UUID | None = None
+    destination: StorageTarget | None = None
+    destination_uri: AnyUrl | None = None
+    max_size: int | None = None  # Maximum size that can be used by this replica, used for R2 home buckets
+    table_uri: PxtUri | None = None  # If replica already exists, return the uri for it
+
+
+class FinalizeRequest(RequestBaseModel):
+    """Request to finalize a table replica."""
+
+    operation_type: Literal[ReplicaOperationType.FINALIZE_REPLICA] = ReplicaOperationType.FINALIZE_REPLICA
+    table_uri: PxtUri  # Use same table_uri that was given during publish replica request
+    upload_id: UUID
+    size: int
+    sha256: str
+    datafile: str
+    row_count: int
+    preview_header: dict[str, str]
+    preview_data: list[list[Any]]
+
+    def get_pxt_uri(self) -> PxtUri:
+        """Get the PxtUri from this request."""
+        return self.table_uri
+
+
+class FinalizeResponse(BaseModel):
+    """Response from finalizing a table replica."""
+
+    confirmed_table_uri: PxtUri
+    version: int | None = None  # Version that was pushed to replica
+
+
+class DeleteRequest(RequestBaseModel):
+    """Request to delete a table replica."""
+
+    operation_type: Literal[ReplicaOperationType.DELETE_REPLICA] = ReplicaOperationType.DELETE_REPLICA
+    table_uri: PxtUri
+    version: int | None = None  # Delete a version in replica
+
+    def get_pxt_uri(self) -> PxtUri:
+        """Get the PxtUri from this request."""
+        return self.table_uri
+
+
+class DeleteResponse(BaseModel):
+    """Response from deleting a table replica."""
+
+    table_uri: PxtUri
+    version: int | None = None
+
+
+class ReplicateRequest(RequestBaseModel):
+    """Request to clone a table replica."""
+
+    operation_type: Literal[ReplicaOperationType.CLONE_REPLICA] = ReplicaOperationType.CLONE_REPLICA
+    table_uri: PxtUri
+
+    def get_pxt_uri(self) -> PxtUri:
+        """Get the PxtUri from this request."""
+        return self.table_uri
+
+
+class ReplicateResponse(BaseModel):
+    """Response from cloning a table replica."""
+
+    table_uri: PxtUri
+    pxt_md_version: int
+    destination: StorageTarget
+    destination_uri: AnyUrl
+    md: list[TableVersionMd]
+    version: int | None = None