atdata 0.3.0b1__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
@@ -122,14 +119,14 @@ class AtmosphereIndex:
 
     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.
         """
@@ -314,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,
@@ -36,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",
@@ -48,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)
@@ -268,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()
@@ -280,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,
@@ -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,

atdata/cli/__init__.py

@@ -1,12 +1,12 @@
 """Command-line interface for atdata.
 
-This module provides CLI commands for managing local development infrastructure,
+This module provides CLI commands for managing development infrastructure,
 inspecting datasets, and diagnosing configuration issues.
 
 Commands:
-    atdata local up      Start Redis and MinIO containers for local development
-    atdata local down    Stop local development containers
-    atdata local status  Show status of local infrastructure
+    atdata infra up      Start Redis and MinIO containers for development
+    atdata infra down    Stop development containers
+    atdata infra status  Show status of infrastructure
     atdata diagnose      Check Redis configuration and connectivity
     atdata inspect       Show dataset summary information
     atdata schema show   Display dataset schema
@@ -30,12 +30,12 @@ app = typer.Typer(
     no_args_is_help=True,
 )
 
-local_app = typer.Typer(
-    name="local",
-    help="Manage local development infrastructure.",
+infra_app = typer.Typer(
+    name="infra",
+    help="Manage development infrastructure.",
     no_args_is_help=True,
 )
-app.add_typer(local_app, name="local")
+app.add_typer(infra_app, name="infra")
 
 schema_app = typer.Typer(
     name="schema",
@@ -101,11 +101,11 @@ def diagnose(
 
 
 # ---------------------------------------------------------------------------
-# local sub-commands
+# infra sub-commands
 # ---------------------------------------------------------------------------
 
 
-@local_app.command()
+@infra_app.command()
 def up(
     redis_port: int = typer.Option(6379, help="Redis port."),
     minio_port: int = typer.Option(9000, help="MinIO API port."),
@@ -115,7 +115,7 @@ def up(
     ),
 ) -> None:
     """Start Redis and MinIO containers."""
-    from .local import local_up
+    from .infra import local_up
 
     code = local_up(
         redis_port=redis_port,
@@ -126,23 +126,23 @@ def up(
     raise typer.Exit(code=code)
 
 
-@local_app.command()
+@infra_app.command()
 def down(
     volumes: bool = typer.Option(
         False, "--volumes", "-v", help="Also remove volumes (deletes all data)."
     ),
 ) -> None:
     """Stop local development containers."""
-    from .local import local_down
+    from .infra import local_down
 
     code = local_down(remove_volumes=volumes)
     raise typer.Exit(code=code)
 
 
-@local_app.command()
+@infra_app.command()
 def status() -> None:
-    """Show status of local infrastructure."""
-    from .local import local_status
+    """Show status of infrastructure."""
+    from .infra import local_status
 
     code = local_status()
     raise typer.Exit(code=code)

atdata/cli/diagnose.py

@@ -51,7 +51,7 @@ def diagnose_redis(host: str = "localhost", port: int = 6379) -> int:
         _print_status("Connection", False, str(e))
         print()
         print("Cannot connect to Redis. Make sure Redis is running:")
-        print("  atdata local up")
+        print("  atdata infra up")
         return 1
 
     # Check Redis version
@@ -162,7 +162,7 @@ def diagnose_redis(host: str = "localhost", port: int = 6379) -> int:
         print("  maxmemory-policy noeviction")
         print()
         print("  # Or use atdata's preconfigured local setup:")
-        print("  atdata local up")
+        print("  atdata infra up")
         return 1
     else:
         print("All checks passed. Redis is properly configured for atdata.")

atdata/cli/{local.py → infra.py}

@@ -1,6 +1,6 @@
-"""Local infrastructure management for atdata.
+"""Infrastructure management for atdata.
 
-This module provides commands to start and stop local development infrastructure:
+This module provides commands to start and stop development infrastructure:
 - Redis: For index storage and metadata
 - MinIO: S3-compatible object storage for dataset files
 
@@ -179,7 +179,7 @@ def local_up(
     if not _check_docker():
         return 1
 
-    print("Starting atdata local infrastructure...")
+    print("Starting atdata infrastructure...")
 
     compose_content = _get_compose_file(redis_port, minio_port, minio_console_port)
     command = ["up"]
@@ -202,7 +202,7 @@ def local_up(
 
     # Show status
     print()
-    print("Local infrastructure started:")
+    print("Infrastructure started:")
     print(f"  Redis:        localhost:{redis_port}")
     print(f"  MinIO API:    http://localhost:{minio_port}")
     print(f"  MinIO Console: http://localhost:{minio_console_port}")
@@ -210,7 +210,7 @@ def local_up(
     print("MinIO credentials: minioadmin / minioadmin")
     print()
     print("Example usage:")
-    print("  from atdata.local import Index, S3DataStore")
+    print("  from atdata.stores import S3DataStore")
     print("  ")
     print("  store = S3DataStore.from_credentials({")
     print(f"      'AWS_ENDPOINT': 'http://localhost:{minio_port}',")
@@ -234,7 +234,7 @@ def local_down(remove_volumes: bool = False) -> int:
     if not _check_docker():
         return 1
 
-    print("Stopping atdata local infrastructure...")
+    print("Stopping atdata infrastructure...")
 
     # Use default ports for compose file (actual ports don't matter for down)
     compose_content = _get_compose_file(6379, 9000, 9001)
@@ -252,7 +252,7 @@ def local_down(remove_volumes: bool = False) -> int:
         print(f"Error: {e}", file=sys.stderr)
         return 1
 
-    print("Local infrastructure stopped.")
+    print("Infrastructure stopped.")
     return 0
 
 
@@ -268,16 +268,16 @@ def local_status() -> int:
     redis_running = _container_running(REDIS_CONTAINER)
     minio_running = _container_running(MINIO_CONTAINER)
 
-    print("atdata local infrastructure status:")
+    print("atdata infrastructure status:")
     print()
     print(f"  Redis ({REDIS_CONTAINER}):  {'running' if redis_running else 'stopped'}")
     print(f"  MinIO ({MINIO_CONTAINER}):  {'running' if minio_running else 'stopped'}")
 
     if redis_running or minio_running:
         print()
-        print("To stop: atdata local down")
+        print("To stop: atdata infra down")
     else:
         print()
-        print("To start: atdata local up")
+        print("To start: atdata infra up")
 
     return 0