atdata 0.1.3b3__py3-none-any.whl → 0.2.0a1__py3-none-any.whl

atdata/atmosphere/client.py

@@ -0,0 +1,393 @@
+"""ATProto client wrapper for atdata.
+
+This module provides the ``AtmosphereClient`` class which wraps the atproto SDK
+client with atdata-specific helpers for publishing and querying records.
+"""
+
+from typing import Optional, Any
+
+from ._types import AtUri, LEXICON_NAMESPACE
+
+# Lazy import to avoid requiring atproto if not using atmosphere features
+_atproto_client_class: Optional[type] = None
+
+
+def _get_atproto_client_class():
+    """Lazily import the atproto Client class."""
+    global _atproto_client_class
+    if _atproto_client_class is None:
+        try:
+            from atproto import Client
+            _atproto_client_class = Client
+        except ImportError as e:
+            raise ImportError(
+                "The 'atproto' package is required for ATProto integration. "
+                "Install it with: pip install atproto"
+            ) from e
+    return _atproto_client_class
+
+
+class AtmosphereClient:
+    """ATProto client wrapper for atdata operations.
+
+    This class wraps the atproto SDK client and provides higher-level methods
+    for working with atdata records (schemas, datasets, lenses).
+
+    Example:
+        >>> client = AtmosphereClient()
+        >>> client.login("alice.bsky.social", "app-password")
+        >>> print(client.did)
+        'did:plc:...'
+
+    Note:
+        The password should be an app-specific password, not your main account
+        password. Create app passwords in your Bluesky account settings.
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        *,
+        _client: Optional[Any] = None,
+    ):
+        """Initialize the ATProto client.
+
+        Args:
+            base_url: Optional PDS base URL. Defaults to bsky.social.
+            _client: Optional pre-configured atproto Client for testing.
+        """
+        if _client is not None:
+            self._client = _client
+        else:
+            Client = _get_atproto_client_class()
+            self._client = Client(base_url=base_url) if base_url else Client()
+
+        self._session: Optional[dict] = None
+
+    def login(self, handle: str, password: str) -> None:
+        """Authenticate with the ATProto PDS.
+
+        Args:
+            handle: Your Bluesky handle (e.g., 'alice.bsky.social').
+            password: App-specific password (not your main password).
+
+        Raises:
+            atproto.exceptions.AtProtocolError: If authentication fails.
+        """
+        profile = self._client.login(handle, password)
+        self._session = {
+            "did": profile.did,
+            "handle": profile.handle,
+        }
+
+    def login_with_session(self, session_string: str) -> None:
+        """Authenticate using an exported session string.
+
+        This allows reusing a session without re-authenticating, which helps
+        avoid rate limits on session creation.
+
+        Args:
+            session_string: Session string from ``export_session()``.
+        """
+        self._client.login(session_string=session_string)
+        self._session = {
+            "did": self._client.me.did,
+            "handle": self._client.me.handle,
+        }
+
+    def export_session(self) -> str:
+        """Export the current session for later reuse.
+
+        Returns:
+            Session string that can be passed to ``login_with_session()``.
+
+        Raises:
+            ValueError: If not authenticated.
+        """
+        if not self.is_authenticated:
+            raise ValueError("Not authenticated")
+        return self._client.export_session_string()
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Check if the client has a valid session."""
+        return self._session is not None
+
+    @property
+    def did(self) -> str:
+        """Get the DID of the authenticated user.
+
+        Returns:
+            The DID string (e.g., 'did:plc:...').
+
+        Raises:
+            ValueError: If not authenticated.
+        """
+        if not self._session:
+            raise ValueError("Not authenticated")
+        return self._session["did"]
+
+    @property
+    def handle(self) -> str:
+        """Get the handle of the authenticated user.
+
+        Returns:
+            The handle string (e.g., 'alice.bsky.social').
+
+        Raises:
+            ValueError: If not authenticated.
+        """
+        if not self._session:
+            raise ValueError("Not authenticated")
+        return self._session["handle"]
+
+    def _ensure_authenticated(self) -> None:
+        """Raise if not authenticated."""
+        if not self.is_authenticated:
+            raise ValueError("Client must be authenticated to perform this operation")
+
+    # Low-level record operations
+
+    def create_record(
+        self,
+        collection: str,
+        record: dict,
+        *,
+        rkey: Optional[str] = None,
+        validate: bool = False,
+    ) -> AtUri:
+        """Create a record in the user's repository.
+
+        Args:
+            collection: The NSID of the record collection
+                (e.g., 'ac.foundation.dataset.sampleSchema').
+            record: The record data. Must include a '$type' field.
+            rkey: Optional explicit record key. If not provided, a TID is generated.
+            validate: Whether to validate against the Lexicon schema. Set to False
+                for custom lexicons that the PDS doesn't know about.
+
+        Returns:
+            The AT URI of the created record.
+
+        Raises:
+            ValueError: If not authenticated.
+            atproto.exceptions.AtProtocolError: If record creation fails.
+        """
+        self._ensure_authenticated()
+
+        response = self._client.com.atproto.repo.create_record(
+            data={
+                "repo": self.did,
+                "collection": collection,
+                "record": record,
+                "rkey": rkey,
+                "validate": validate,
+            }
+        )
+
+        return AtUri.parse(response.uri)
+
+    def put_record(
+        self,
+        collection: str,
+        rkey: str,
+        record: dict,
+        *,
+        validate: bool = False,
+        swap_commit: Optional[str] = None,
+    ) -> AtUri:
+        """Create or update a record at a specific key.
+
+        Args:
+            collection: The NSID of the record collection.
+            rkey: The record key.
+            record: The record data. Must include a '$type' field.
+            validate: Whether to validate against the Lexicon schema.
+            swap_commit: Optional CID for compare-and-swap update.
+
+        Returns:
+            The AT URI of the record.
+
+        Raises:
+            ValueError: If not authenticated.
+            atproto.exceptions.AtProtocolError: If operation fails.
+        """
+        self._ensure_authenticated()
+
+        data: dict[str, Any] = {
+            "repo": self.did,
+            "collection": collection,
+            "rkey": rkey,
+            "record": record,
+            "validate": validate,
+        }
+        if swap_commit:
+            data["swapCommit"] = swap_commit
+
+        response = self._client.com.atproto.repo.put_record(data=data)
+
+        return AtUri.parse(response.uri)
+
+    def get_record(
+        self,
+        uri: str | AtUri,
+    ) -> dict:
+        """Fetch a record by AT URI.
+
+        Args:
+            uri: The AT URI of the record.
+
+        Returns:
+            The record data as a dictionary.
+
+        Raises:
+            atproto.exceptions.AtProtocolError: If record not found.
+        """
+        if isinstance(uri, str):
+            uri = AtUri.parse(uri)
+
+        response = self._client.com.atproto.repo.get_record(
+            params={
+                "repo": uri.authority,
+                "collection": uri.collection,
+                "rkey": uri.rkey,
+            }
+        )
+
+        return response.value
+
+    def delete_record(
+        self,
+        uri: str | AtUri,
+        *,
+        swap_commit: Optional[str] = None,
+    ) -> None:
+        """Delete a record.
+
+        Args:
+            uri: The AT URI of the record to delete.
+            swap_commit: Optional CID for compare-and-swap delete.
+
+        Raises:
+            ValueError: If not authenticated.
+            atproto.exceptions.AtProtocolError: If deletion fails.
+        """
+        self._ensure_authenticated()
+
+        if isinstance(uri, str):
+            uri = AtUri.parse(uri)
+
+        data: dict[str, Any] = {
+            "repo": self.did,
+            "collection": uri.collection,
+            "rkey": uri.rkey,
+        }
+        if swap_commit:
+            data["swapCommit"] = swap_commit
+
+        self._client.com.atproto.repo.delete_record(data=data)
+
+    def list_records(
+        self,
+        collection: str,
+        *,
+        repo: Optional[str] = None,
+        limit: int = 100,
+        cursor: Optional[str] = None,
+    ) -> tuple[list[dict], Optional[str]]:
+        """List records in a collection.
+
+        Args:
+            collection: The NSID of the record collection.
+            repo: The DID of the repository to query. Defaults to the
+                authenticated user's repository.
+            limit: Maximum number of records to return (default 100).
+            cursor: Pagination cursor from a previous call.
+
+        Returns:
+            A tuple of (records, next_cursor). The cursor is None if there
+            are no more records.
+
+        Raises:
+            ValueError: If repo is None and not authenticated.
+        """
+        if repo is None:
+            self._ensure_authenticated()
+            repo = self.did
+
+        response = self._client.com.atproto.repo.list_records(
+            params={
+                "repo": repo,
+                "collection": collection,
+                "limit": limit,
+                "cursor": cursor,
+            }
+        )
+
+        records = [r.value for r in response.records]
+        return records, response.cursor
+
+    # Convenience methods for atdata collections
+
+    def list_schemas(
+        self,
+        repo: Optional[str] = None,
+        limit: int = 100,
+    ) -> list[dict]:
+        """List schema records.
+
+        Args:
+            repo: The DID to query. Defaults to authenticated user.
+            limit: Maximum number to return.
+
+        Returns:
+            List of schema records.
+        """
+        records, _ = self.list_records(
+            f"{LEXICON_NAMESPACE}.sampleSchema",
+            repo=repo,
+            limit=limit,
+        )
+        return records
+
+    def list_datasets(
+        self,
+        repo: Optional[str] = None,
+        limit: int = 100,
+    ) -> list[dict]:
+        """List dataset records.
+
+        Args:
+            repo: The DID to query. Defaults to authenticated user.
+            limit: Maximum number to return.
+
+        Returns:
+            List of dataset records.
+        """
+        records, _ = self.list_records(
+            f"{LEXICON_NAMESPACE}.record",
+            repo=repo,
+            limit=limit,
+        )
+        return records
+
+    def list_lenses(
+        self,
+        repo: Optional[str] = None,
+        limit: int = 100,
+    ) -> list[dict]:
+        """List lens records.
+
+        Args:
+            repo: The DID to query. Defaults to authenticated user.
+            limit: Maximum number to return.
+
+        Returns:
+            List of lens records.
+        """
+        records, _ = self.list_records(
+            f"{LEXICON_NAMESPACE}.lens",
+            repo=repo,
+            limit=limit,
+        )
+        return records

atdata/atmosphere/lens.py

@@ -0,0 +1,280 @@
+"""Lens transformation publishing for ATProto.
+
+This module provides classes for publishing Lens transformation records to
+ATProto. Lenses are published as ``ac.foundation.dataset.lens`` records.
+
+Note:
+    For security reasons, lens code is stored as references to git repositories
+    rather than inline code. Users must manually install and import lens
+    implementations.
+"""
+
+from typing import Optional, Callable
+
+from .client import AtmosphereClient
+from ._types import (
+    AtUri,
+    LensRecord,
+    CodeReference,
+    LEXICON_NAMESPACE,
+)
+
+# Import for type checking only
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from ..lens import Lens
+
+
+class LensPublisher:
+    """Publishes Lens transformation records to ATProto.
+
+    This class creates lens records that reference source and target schemas
+    and point to the transformation code in a git repository.
+
+    Example:
+        >>> @atdata.lens
+        ... def my_lens(source: SourceType) -> TargetType:
+        ...     return TargetType(field=source.other_field)
+        >>>
+        >>> client = AtmosphereClient()
+        >>> client.login("handle", "password")
+        >>>
+        >>> publisher = LensPublisher(client)
+        >>> uri = publisher.publish(
+        ...     name="my_lens",
+        ...     source_schema_uri="at://did:plc:abc/ac.foundation.dataset.sampleSchema/source",
+        ...     target_schema_uri="at://did:plc:abc/ac.foundation.dataset.sampleSchema/target",
+        ...     code_repository="https://github.com/user/repo",
+        ...     code_commit="abc123def456",
+        ...     getter_path="mymodule.lenses:my_lens",
+        ...     putter_path="mymodule.lenses:my_lens_putter",
+        ... )
+
+    Security Note:
+        Lens code is stored as references to git repositories rather than
+        inline code. This prevents arbitrary code execution from ATProto
+        records. Users must manually install and trust lens implementations.
+    """
+
+    def __init__(self, client: AtmosphereClient):
+        """Initialize the lens publisher.
+
+        Args:
+            client: Authenticated AtmosphereClient instance.
+        """
+        self.client = client
+
+    def publish(
+        self,
+        *,
+        name: str,
+        source_schema_uri: str,
+        target_schema_uri: str,
+        description: Optional[str] = None,
+        code_repository: Optional[str] = None,
+        code_commit: Optional[str] = None,
+        getter_path: Optional[str] = None,
+        putter_path: Optional[str] = None,
+        rkey: Optional[str] = None,
+    ) -> AtUri:
+        """Publish a lens transformation record to ATProto.
+
+        Args:
+            name: Human-readable lens name.
+            source_schema_uri: AT URI of the source schema.
+            target_schema_uri: AT URI of the target schema.
+            description: What this transformation does.
+            code_repository: Git repository URL containing the lens code.
+            code_commit: Git commit hash for reproducibility.
+            getter_path: Module path to the getter function
+                (e.g., 'mymodule.lenses:my_getter').
+            putter_path: Module path to the putter function
+                (e.g., 'mymodule.lenses:my_putter').
+            rkey: Optional explicit record key.
+
+        Returns:
+            The AT URI of the created lens record.
+
+        Raises:
+            ValueError: If code references are incomplete.
+        """
+        # Build code references if provided
+        getter_code: Optional[CodeReference] = None
+        putter_code: Optional[CodeReference] = None
+
+        if code_repository and code_commit:
+            if getter_path:
+                getter_code = CodeReference(
+                    repository=code_repository,
+                    commit=code_commit,
+                    path=getter_path,
+                )
+            if putter_path:
+                putter_code = CodeReference(
+                    repository=code_repository,
+                    commit=code_commit,
+                    path=putter_path,
+                )
+
+        lens_record = LensRecord(
+            name=name,
+            source_schema=source_schema_uri,
+            target_schema=target_schema_uri,
+            description=description,
+            getter_code=getter_code,
+            putter_code=putter_code,
+        )
+
+        return self.client.create_record(
+            collection=f"{LEXICON_NAMESPACE}.lens",
+            record=lens_record.to_record(),
+            rkey=rkey,
+            validate=False,
+        )
+
+    def publish_from_lens(
+        self,
+        lens_obj: "Lens",
+        *,
+        name: str,
+        source_schema_uri: str,
+        target_schema_uri: str,
+        code_repository: str,
+        code_commit: str,
+        description: Optional[str] = None,
+        rkey: Optional[str] = None,
+    ) -> AtUri:
+        """Publish a lens record from an existing Lens object.
+
+        This method extracts the getter and putter function names from
+        the Lens object and publishes a record referencing them.
+
+        Args:
+            lens_obj: The Lens object to publish.
+            name: Human-readable lens name.
+            source_schema_uri: AT URI of the source schema.
+            target_schema_uri: AT URI of the target schema.
+            code_repository: Git repository URL.
+            code_commit: Git commit hash.
+            description: What this transformation does.
+            rkey: Optional explicit record key.
+
+        Returns:
+            The AT URI of the created lens record.
+        """
+        # Extract function names from the lens
+        getter_name = lens_obj._getter.__name__
+        putter_name = lens_obj._putter.__name__
+
+        # Get module info if available
+        getter_module = getattr(lens_obj._getter, "__module__", "")
+        putter_module = getattr(lens_obj._putter, "__module__", "")
+
+        getter_path = f"{getter_module}:{getter_name}" if getter_module else getter_name
+        putter_path = f"{putter_module}:{putter_name}" if putter_module else putter_name
+
+        return self.publish(
+            name=name,
+            source_schema_uri=source_schema_uri,
+            target_schema_uri=target_schema_uri,
+            description=description,
+            code_repository=code_repository,
+            code_commit=code_commit,
+            getter_path=getter_path,
+            putter_path=putter_path,
+            rkey=rkey,
+        )
+
+
+class LensLoader:
+    """Loads lens records from ATProto.
+
+    This class fetches lens transformation records. Note that actually
+    using a lens requires installing the referenced code and importing
+    it manually.
+
+    Example:
+        >>> client = AtmosphereClient()
+        >>> loader = LensLoader(client)
+        >>>
+        >>> record = loader.get("at://did:plc:abc/ac.foundation.dataset.lens/xyz")
+        >>> print(record["name"])
+        >>> print(record["sourceSchema"])
+        >>> print(record.get("getterCode", {}).get("repository"))
+    """
+
+    def __init__(self, client: AtmosphereClient):
+        """Initialize the lens loader.
+
+        Args:
+            client: AtmosphereClient instance.
+        """
+        self.client = client
+
+    def get(self, uri: str | AtUri) -> dict:
+        """Fetch a lens record by AT URI.
+
+        Args:
+            uri: The AT URI of the lens record.
+
+        Returns:
+            The lens record as a dictionary.
+
+        Raises:
+            ValueError: If the record is not a lens record.
+        """
+        record = self.client.get_record(uri)
+
+        expected_type = f"{LEXICON_NAMESPACE}.lens"
+        if record.get("$type") != expected_type:
+            raise ValueError(
+                f"Record at {uri} is not a lens record. "
+                f"Expected $type='{expected_type}', got '{record.get('$type')}'"
+            )
+
+        return record
+
+    def list_all(
+        self,
+        repo: Optional[str] = None,
+        limit: int = 100,
+    ) -> list[dict]:
+        """List lens records from a repository.
+
+        Args:
+            repo: The DID of the repository. Defaults to authenticated user.
+            limit: Maximum number of records to return.
+
+        Returns:
+            List of lens records.
+        """
+        return self.client.list_lenses(repo=repo, limit=limit)
+
+    def find_by_schemas(
+        self,
+        source_schema_uri: str,
+        target_schema_uri: Optional[str] = None,
+        repo: Optional[str] = None,
+    ) -> list[dict]:
+        """Find lenses that transform between specific schemas.
+
+        Args:
+            source_schema_uri: AT URI of the source schema.
+            target_schema_uri: Optional AT URI of the target schema.
+                If not provided, returns all lenses from the source.
+            repo: The DID of the repository to search.
+
+        Returns:
+            List of matching lens records.
+        """
+        all_lenses = self.list_all(repo=repo, limit=1000)
+
+        matches = []
+        for lens_record in all_lenses:
+            if lens_record.get("sourceSchema") == source_schema_uri:
+                if target_schema_uri is None:
+                    matches.append(lens_record)
+                elif lens_record.get("targetSchema") == target_schema_uri:
+                    matches.append(lens_record)
+
+        return matches