atdata 0.2.3b1__py3-none-any.whl → 0.3.1b1__py3-none-any.whl

atdata/atmosphere/__init__.py

@@ -6,7 +6,7 @@ network.
 
 Key components:
 
-- ``AtmosphereClient``: Authentication and session management for ATProto
+- ``Atmosphere``: Authentication and session management for ATProto
 - ``SchemaPublisher``: Publish PackableSample schemas as ATProto records
 - ``DatasetPublisher``: Publish dataset index records with WebDataset URLs
 - ``LensPublisher``: Publish lens transformation records
@@ -16,13 +16,10 @@ to work unchanged. These features are opt-in for users who want to publish
 or discover datasets on the ATProto network.
 
 Examples:
-    >>> from atdata.atmosphere import AtmosphereClient, SchemaPublisher
+    >>> from atdata.atmosphere import Atmosphere
     >>>
-    >>> client = AtmosphereClient()
-    >>> client.login("handle.bsky.social", "app-password")
-    >>>
-    >>> publisher = SchemaPublisher(client)
-    >>> schema_uri = publisher.publish(MySampleType, version="1.0.0")
+    >>> atmo = Atmosphere.login("handle.bsky.social", "app-password")
+    >>> index = Index(atmosphere=atmo)
 
 Note:
     This module requires the ``atproto`` package to be installed::
@@ -32,7 +29,7 @@ Note:
 
 from typing import Iterator, Optional, Type, TYPE_CHECKING
 
-from .client import AtmosphereClient
+from .client import Atmosphere
 from .schema import SchemaPublisher, SchemaLoader
 from .records import DatasetPublisher, DatasetLoader
 from .lens import LensPublisher, LensLoader
@@ -99,38 +96,48 @@ class AtmosphereIndexEntry:
 class AtmosphereIndex:
     """ATProto index implementing AbstractIndex protocol.
 
+    .. deprecated::
+        Use ``atdata.Index(atmosphere=client)`` instead.  ``AtmosphereIndex``
+        is retained for backwards compatibility and will be removed in a
+        future release.
+
     Wraps SchemaPublisher/Loader and DatasetPublisher/Loader to provide
-    a unified interface compatible with LocalIndex.
+    a unified interface compatible with Index.
 
     Optionally accepts a ``PDSBlobStore`` for writing dataset shards as
     ATProto blobs, enabling fully decentralized dataset storage.
 
     Examples:
-        >>> client = AtmosphereClient()
-        >>> client.login("handle.bsky.social", "app-password")
+        >>> # Preferred: use unified Index
+        >>> from atdata.local import Index
+        >>> from atdata.atmosphere import AtmosphereClient
+        >>> index = Index(atmosphere=client)
         >>>
-        >>> # Without blob storage (external URLs only)
+        >>> # Legacy (deprecated)
         >>> index = AtmosphereIndex(client)
-        >>>
-        >>> # With PDS blob storage
-        >>> store = PDSBlobStore(client)
-        >>> index = AtmosphereIndex(client, data_store=store)
-        >>> entry = index.insert_dataset(dataset, name="my-data")
     """
 
     def __init__(
         self,
-        client: AtmosphereClient,
+        client: Atmosphere,
         *,
         data_store: Optional[PDSBlobStore] = None,
     ):
         """Initialize the atmosphere index.
 
         Args:
-            client: Authenticated AtmosphereClient instance.
+            client: Authenticated Atmosphere instance.
             data_store: Optional PDSBlobStore for writing shards as blobs.
                 If provided, insert_dataset will upload shards to PDS.
         """
+        import warnings
+
+        warnings.warn(
+            "AtmosphereIndex is deprecated. Use atdata.Index(atmosphere=client) "
+            "instead for unified index access.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self.client = client
         self._schema_publisher = SchemaPublisher(client)
         self._schema_loader = SchemaLoader(client)
@@ -304,9 +311,13 @@ class AtmosphereIndex:
         return schema_to_type(schema)
 
 
+# Deprecated alias for backward compatibility
+AtmosphereClient = Atmosphere
+
 __all__ = [
     # Client
-    "AtmosphereClient",
+    "Atmosphere",
+    "AtmosphereClient",  # deprecated alias
     # Storage
     "PDSBlobStore",
     # Unified index (AbstractIndex protocol)

atdata/atmosphere/_types.py

@@ -20,11 +20,11 @@ class AtUri:
     AT URIs follow the format: at://<authority>/<collection>/<rkey>
 
     Examples:
-        >>> uri = AtUri.parse("at://did:plc:abc123/ac.foundation.dataset.sampleSchema/xyz")
+        >>> uri = AtUri.parse("at://did:plc:abc123/ac.foundation.dataset.schema/xyz")
         >>> uri.authority
         'did:plc:abc123'
         >>> uri.collection
-        'ac.foundation.dataset.sampleSchema'
+        'ac.foundation.dataset.schema'
         >>> uri.rkey
         'xyz'
     """
@@ -119,7 +119,7 @@ class FieldDef:
 class SchemaRecord:
     """ATProto record for a PackableSample schema.
 
-    Maps to the ``ac.foundation.dataset.sampleSchema`` Lexicon.
+    Maps to the ``ac.foundation.dataset.schema`` Lexicon.
     """
 
     name: str
@@ -143,7 +143,7 @@ class SchemaRecord:
     def to_record(self) -> dict:
         """Convert to ATProto record dict for publishing."""
         record = {
-            "$type": f"{LEXICON_NAMESPACE}.sampleSchema",
+            "$type": f"{LEXICON_NAMESPACE}.schema",
             "name": self.name,
             "version": self.version,
             "fields": [self._field_to_dict(f) for f in self.fields],

atdata/atmosphere/client.py

@@ -1,6 +1,6 @@
 """ATProto client wrapper for atdata.
 
-This module provides the ``AtmosphereClient`` class which wraps the atproto SDK
+This module provides the ``Atmosphere`` class which wraps the atproto SDK
 client with atdata-specific helpers for publishing and querying records.
 """
 
@@ -28,16 +28,15 @@ def _get_atproto_client_class():
     return _atproto_client_class
 
 
-class AtmosphereClient:
+class Atmosphere:
     """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).
 
     Examples:
-        >>> client = AtmosphereClient()
-        >>> client.login("alice.bsky.social", "app-password")
-        >>> print(client.did)
+        >>> atmo = Atmosphere.login("alice.bsky.social", "app-password")
+        >>> print(atmo.did)
         'did:plc:...'
 
     Note:
@@ -65,7 +64,63 @@ class AtmosphereClient:
 
         self._session: Optional[dict] = None
 
-    def login(self, handle: str, password: str) -> None:
+    @classmethod
+    def login(
+        cls,
+        handle: str,
+        password: str,
+        *,
+        base_url: Optional[str] = None,
+    ) -> "Atmosphere":
+        """Create an authenticated Atmosphere client.
+
+        Args:
+            handle: Your Bluesky handle (e.g., 'alice.bsky.social').
+            password: App-specific password (not your main password).
+            base_url: Optional PDS base URL. Defaults to bsky.social.
+
+        Returns:
+            An authenticated Atmosphere instance.
+
+        Raises:
+            atproto.exceptions.AtProtocolError: If authentication fails.
+
+        Examples:
+            >>> atmo = Atmosphere.login("alice.bsky.social", "app-password")
+            >>> index = Index(atmosphere=atmo)
+        """
+        instance = cls(base_url=base_url)
+        instance._login(handle, password)
+        return instance
+
+    @classmethod
+    def from_session(
+        cls,
+        session_string: str,
+        *,
+        base_url: Optional[str] = None,
+    ) -> "Atmosphere":
+        """Create an Atmosphere client from 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()``.
+            base_url: Optional PDS base URL. Defaults to bsky.social.
+
+        Returns:
+            An authenticated Atmosphere instance.
+
+        Examples:
+            >>> session = atmo.export_session()
+            >>> atmo2 = Atmosphere.from_session(session)
+        """
+        instance = cls(base_url=base_url)
+        instance._login_with_session(session_string)
+        return instance
+
+    def _login(self, handle: str, password: str) -> None:
         """Authenticate with the ATProto PDS.
 
         Args:
@@ -81,12 +136,9 @@ class AtmosphereClient:
             "handle": profile.handle,
         }
 
-    def login_with_session(self, session_string: str) -> None:
+    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()``.
         """
@@ -161,7 +213,7 @@ class AtmosphereClient:
 
         Args:
             collection: The NSID of the record collection
-                (e.g., 'ac.foundation.dataset.sampleSchema').
+                (e.g., 'ac.foundation.dataset.schema').
             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
@@ -487,7 +539,7 @@ class AtmosphereClient:
             List of schema records.
         """
         records, _ = self.list_records(
-            f"{LEXICON_NAMESPACE}.sampleSchema",
+            f"{LEXICON_NAMESPACE}.schema",
             repo=repo,
             limit=limit,
         )

atdata/atmosphere/lens.py

@@ -11,7 +11,7 @@ Note:
 
 from typing import Optional
 
-from .client import AtmosphereClient
+from .client import Atmosphere
 from ._types import (
     AtUri,
     LensRecord,
@@ -37,14 +37,13 @@ class LensPublisher:
         ... def my_lens(source: SourceType) -> TargetType:
         ...     return TargetType(field=source.other_field)
         >>>
-        >>> client = AtmosphereClient()
-        >>> client.login("handle", "password")
+        >>> atmo = Atmosphere.login("handle", "password")
         >>>
-        >>> publisher = LensPublisher(client)
+        >>> publisher = LensPublisher(atmo)
         >>> 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",
+        ...     source_schema_uri="at://did:plc:abc/ac.foundation.dataset.schema/source",
+        ...     target_schema_uri="at://did:plc:abc/ac.foundation.dataset.schema/target",
         ...     code_repository="https://github.com/user/repo",
         ...     code_commit="abc123def456",
         ...     getter_path="mymodule.lenses:my_lens",
@@ -57,11 +56,11 @@ class LensPublisher:
         records. Users must manually install and trust lens implementations.
     """
 
-    def __init__(self, client: AtmosphereClient):
+    def __init__(self, client: Atmosphere):
         """Initialize the lens publisher.
 
         Args:
-            client: Authenticated AtmosphereClient instance.
+            client: Authenticated Atmosphere instance.
         """
         self.client = client
 
@@ -195,8 +194,8 @@ class LensLoader:
     it manually.
 
     Examples:
-        >>> client = AtmosphereClient()
-        >>> loader = LensLoader(client)
+        >>> atmo = Atmosphere.login("handle", "password")
+        >>> loader = LensLoader(atmo)
         >>>
         >>> record = loader.get("at://did:plc:abc/ac.foundation.dataset.lens/xyz")
         >>> print(record["name"])
@@ -204,11 +203,11 @@ class LensLoader:
         >>> print(record.get("getterCode", {}).get("repository"))
     """
 
-    def __init__(self, client: AtmosphereClient):
+    def __init__(self, client: Atmosphere):
         """Initialize the lens loader.
 
         Args:
-            client: AtmosphereClient instance.
+            client: Atmosphere instance.
         """
         self.client = client
 

atdata/atmosphere/records.py

@@ -8,7 +8,7 @@ and loading them back. Dataset records are published as
 from typing import Type, TypeVar, Optional
 import msgpack
 
-from .client import AtmosphereClient
+from .client import Atmosphere
 from .schema import SchemaPublisher
 from ._types import (
     AtUri,
@@ -21,9 +21,10 @@ from ._types import (
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from ..dataset import PackableSample, Dataset
+    from ..dataset import Dataset
+    from .._protocols import Packable
 
-ST = TypeVar("ST", bound="PackableSample")
+ST = TypeVar("ST", bound="Packable")
 
 
 class DatasetPublisher:
@@ -35,10 +36,9 @@ class DatasetPublisher:
     Examples:
         >>> dataset = atdata.Dataset[MySample]("s3://bucket/data-{000000..000009}.tar")
         >>>
-        >>> client = AtmosphereClient()
-        >>> client.login("handle", "password")
+        >>> atmo = Atmosphere.login("handle", "password")
         >>>
-        >>> publisher = DatasetPublisher(client)
+        >>> publisher = DatasetPublisher(atmo)
         >>> uri = publisher.publish(
         ...     dataset,
         ...     name="My Training Data",
@@ -47,11 +47,11 @@ class DatasetPublisher:
         ... )
     """
 
-    def __init__(self, client: AtmosphereClient):
+    def __init__(self, client: Atmosphere):
         """Initialize the dataset publisher.
 
         Args:
-            client: Authenticated AtmosphereClient instance.
+            client: Authenticated Atmosphere instance.
         """
         self.client = client
         self._schema_publisher = SchemaPublisher(client)
@@ -267,8 +267,8 @@ class DatasetLoader:
     Python class for the sample type.
 
     Examples:
-        >>> client = AtmosphereClient()
-        >>> loader = DatasetLoader(client)
+        >>> atmo = Atmosphere.login("handle", "password")
+        >>> loader = DatasetLoader(atmo)
         >>>
         >>> # List available datasets
         >>> datasets = loader.list()
@@ -279,11 +279,11 @@ class DatasetLoader:
         >>> record = loader.get("at://did:plc:abc/ac.foundation.dataset.record/xyz")
     """
 
-    def __init__(self, client: AtmosphereClient):
+    def __init__(self, client: Atmosphere):
         """Initialize the dataset loader.
 
         Args:
-            client: AtmosphereClient instance.
+            client: Atmosphere instance.
         """
         self.client = client
 

atdata/atmosphere/schema.py

@@ -1,14 +1,14 @@
 """Schema publishing and loading for ATProto.
 
 This module provides classes for publishing PackableSample schemas to ATProto
-and loading them back. Schemas are published as ``ac.foundation.dataset.sampleSchema``
+and loading them back. Schemas are published as ``ac.foundation.dataset.schema``
 records.
 """
 
 from dataclasses import fields, is_dataclass
 from typing import Type, TypeVar, Optional, get_type_hints, get_origin, get_args
 
-from .client import AtmosphereClient
+from .client import Atmosphere
 from ._types import (
     AtUri,
     SchemaRecord,
@@ -26,9 +26,9 @@ from .._type_utils import (
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from ..dataset import PackableSample
+    from .._protocols import Packable
 
-ST = TypeVar("ST", bound="PackableSample")
+ST = TypeVar("ST", bound="Packable")
 
 
 class SchemaPublisher:
@@ -43,20 +43,19 @@ class SchemaPublisher:
         ...     image: NDArray
         ...     label: str
         ...
-        >>> client = AtmosphereClient()
-        >>> client.login("handle", "password")
+        >>> atmo = Atmosphere.login("handle", "password")
         >>>
-        >>> publisher = SchemaPublisher(client)
+        >>> publisher = SchemaPublisher(atmo)
         >>> uri = publisher.publish(MySample, version="1.0.0")
         >>> print(uri)
-        at://did:plc:.../ac.foundation.dataset.sampleSchema/...
+        at://did:plc:.../ac.foundation.dataset.schema/...
     """
 
-    def __init__(self, client: AtmosphereClient):
+    def __init__(self, client: Atmosphere):
         """Initialize the schema publisher.
 
         Args:
-            client: Authenticated AtmosphereClient instance.
+            client: Authenticated Atmosphere instance.
         """
         self.client = client
 
@@ -103,7 +102,7 @@ class SchemaPublisher:
 
         # Publish to ATProto
         return self.client.create_record(
-            collection=f"{LEXICON_NAMESPACE}.sampleSchema",
+            collection=f"{LEXICON_NAMESPACE}.schema",
             record=schema_record.to_record(),
             rkey=rkey,
             validate=False,  # PDS doesn't know our lexicon
@@ -185,20 +184,19 @@ class SchemaLoader:
     schemas from a repository.
 
     Examples:
-        >>> client = AtmosphereClient()
-        >>> client.login("handle", "password")
+        >>> atmo = Atmosphere.login("handle", "password")
         >>>
-        >>> loader = SchemaLoader(client)
-        >>> schema = loader.get("at://did:plc:.../ac.foundation.dataset.sampleSchema/...")
+        >>> loader = SchemaLoader(atmo)
+        >>> schema = loader.get("at://did:plc:.../ac.foundation.dataset.schema/...")
         >>> print(schema["name"])
         'MySample'
     """
 
-    def __init__(self, client: AtmosphereClient):
+    def __init__(self, client: Atmosphere):
         """Initialize the schema loader.
 
         Args:
-            client: AtmosphereClient instance (authentication optional for reads).
+            client: Atmosphere instance (authentication optional for reads).
         """
         self.client = client
 
@@ -217,7 +215,7 @@ class SchemaLoader:
         """
         record = self.client.get_record(uri)
 
-        expected_type = f"{LEXICON_NAMESPACE}.sampleSchema"
+        expected_type = f"{LEXICON_NAMESPACE}.schema"
         if record.get("$type") != expected_type:
             raise ValueError(
                 f"Record at {uri} is not a schema record. "

atdata/atmosphere/store.py

@@ -7,12 +7,11 @@ This enables fully decentralized dataset storage where both metadata (records)
 and data (blobs) live on the AT Protocol network.
 
 Examples:
-    >>> from atdata.atmosphere import AtmosphereClient, PDSBlobStore
+    >>> from atdata.atmosphere import Atmosphere, PDSBlobStore
     >>>
-    >>> client = AtmosphereClient()
-    >>> client.login("handle.bsky.social", "app-password")
+    >>> atmo = Atmosphere.login("handle.bsky.social", "app-password")
     >>>
-    >>> store = PDSBlobStore(client)
+    >>> store = PDSBlobStore(atmo)
     >>> urls = store.write_shards(dataset, prefix="mnist/v1")
     >>> print(urls)
     ['at://did:plc:.../blob/bafyrei...', ...]
@@ -29,7 +28,7 @@ import webdataset as wds
 if TYPE_CHECKING:
     from ..dataset import Dataset
     from .._sources import BlobSource
-    from .client import AtmosphereClient
+    from .client import Atmosphere
 
 
 @dataclass
@@ -44,7 +43,7 @@ class PDSBlobStore:
     to HTTP URLs for streaming.
 
     Attributes:
-        client: Authenticated AtmosphereClient instance.
+        client: Authenticated Atmosphere instance.
 
     Examples:
         >>> store = PDSBlobStore(client)
@@ -53,7 +52,7 @@ class PDSBlobStore:
         >>> # ['at://did:plc:abc/blob/bafyrei...', ...]
     """
 
-    client: "AtmosphereClient"
+    client: "Atmosphere"
 
     def write_shards(
         self,