atdata 0.2.0a1__py3-none-any.whl → 0.2.2b1__py3-none-any.whl

atdata/promote.py

@@ -0,0 +1,199 @@
+"""Promotion workflow for migrating datasets from local to atmosphere.
+
+This module provides functionality to promote locally-indexed datasets to the
+ATProto atmosphere network. This enables sharing datasets with the broader
+federation while maintaining schema consistency.
+
+Example:
+    ::
+
+        >>> from atdata.local import LocalIndex, Repo
+        >>> from atdata.atmosphere import AtmosphereClient, AtmosphereIndex
+        >>> from atdata.promote import promote_to_atmosphere
+        >>>
+        >>> # Setup
+        >>> local_index = LocalIndex()
+        >>> client = AtmosphereClient()
+        >>> client.login("handle.bsky.social", "app-password")
+        >>>
+        >>> # Promote a dataset
+        >>> entry = local_index.get_dataset("my-dataset")
+        >>> at_uri = promote_to_atmosphere(entry, local_index, client)
+"""
+
+from typing import TYPE_CHECKING, Type
+
+if TYPE_CHECKING:
+    from .local import LocalDatasetEntry, Index as LocalIndex
+    from .atmosphere import AtmosphereClient
+    from ._protocols import AbstractDataStore, Packable
+
+
+def _find_existing_schema(
+    client: "AtmosphereClient",
+    name: str,
+    version: str,
+) -> str | None:
+    """Check if a schema with the given name and version already exists.
+
+    Args:
+        client: Authenticated atmosphere client.
+        name: Schema name to search for.
+        version: Schema version to match.
+
+    Returns:
+        AT URI of existing schema if found, None otherwise.
+    """
+    from .atmosphere import SchemaLoader
+
+    loader = SchemaLoader(client)
+    for record in loader.list_all():
+        rec_value = record.get("value", record)
+        if rec_value.get("name") == name and rec_value.get("version") == version:
+            return record.get("uri", "")
+    return None
+
+
+def _find_or_publish_schema(
+    sample_type: "Type[Packable]",
+    version: str,
+    client: "AtmosphereClient",
+    description: str | None = None,
+) -> str:
+    """Find existing schema or publish a new one.
+
+    Checks if a schema with the same name and version already exists on the
+    user's atmosphere repository. If found, returns the existing URI to avoid
+    duplicates. Otherwise, publishes a new schema record.
+
+    Args:
+        sample_type: The PackableSample subclass to publish.
+        version: Semantic version string.
+        client: Authenticated atmosphere client.
+        description: Optional schema description.
+
+    Returns:
+        AT URI of the schema (existing or newly published).
+    """
+    from .atmosphere import SchemaPublisher
+
+    schema_name = f"{sample_type.__module__}.{sample_type.__name__}"
+
+    # Check for existing schema
+    existing = _find_existing_schema(client, schema_name, version)
+    if existing:
+        return existing
+
+    # Publish new schema
+    publisher = SchemaPublisher(client)
+    uri = publisher.publish(
+        sample_type,
+        version=version,
+        description=description,
+    )
+    return str(uri)
+
+
+def promote_to_atmosphere(
+    local_entry: "LocalDatasetEntry",
+    local_index: "LocalIndex",
+    atmosphere_client: "AtmosphereClient",
+    *,
+    data_store: "AbstractDataStore | None" = None,
+    name: str | None = None,
+    description: str | None = None,
+    tags: list[str] | None = None,
+    license: str | None = None,
+) -> str:
+    """Promote a local dataset to the atmosphere network.
+
+    This function takes a locally-indexed dataset and publishes it to ATProto,
+    making it discoverable on the federated atmosphere network.
+
+    Args:
+        local_entry: The LocalDatasetEntry to promote.
+        local_index: Local index containing the schema for this entry.
+        atmosphere_client: Authenticated AtmosphereClient.
+        data_store: Optional data store for copying data to new location.
+            If None, the existing data_urls are used as-is.
+        name: Override name for the atmosphere record. Defaults to local name.
+        description: Optional description for the dataset.
+        tags: Optional tags for discovery.
+        license: Optional license identifier.
+
+    Returns:
+        AT URI of the created atmosphere dataset record.
+
+    Raises:
+        KeyError: If schema not found in local index.
+        ValueError: If local entry has no data URLs.
+
+    Example:
+        ::
+
+            >>> entry = local_index.get_dataset("mnist-train")
+            >>> uri = promote_to_atmosphere(entry, local_index, client)
+            >>> print(uri)
+            at://did:plc:abc123/ac.foundation.dataset.datasetIndex/...
+    """
+    from .atmosphere import DatasetPublisher
+    from ._schema_codec import schema_to_type
+
+    # Validate entry has data
+    if not local_entry.data_urls:
+        raise ValueError(f"Local entry '{local_entry.name}' has no data URLs")
+
+    # Get schema from local index
+    schema_ref = local_entry.schema_ref
+    schema_record = local_index.get_schema(schema_ref)
+
+    # Reconstruct sample type from schema
+    sample_type = schema_to_type(schema_record)
+    schema_version = schema_record.get("version", "1.0.0")
+
+    # Find or publish schema on atmosphere (deduplication)
+    atmosphere_schema_uri = _find_or_publish_schema(
+        sample_type,
+        schema_version,
+        atmosphere_client,
+        description=schema_record.get("description"),
+    )
+
+    # Determine data URLs
+    if data_store is not None:
+        # Copy data to new storage location
+        # Create a temporary Dataset to write through the data store
+        from .dataset import Dataset
+
+        # Build WDS URL from data_urls
+        if len(local_entry.data_urls) == 1:
+            wds_url = local_entry.data_urls[0]
+        else:
+            # Use brace notation for multiple URLs
+            wds_url = " ".join(local_entry.data_urls)
+
+        ds = Dataset[sample_type](wds_url)
+        prefix = f"promoted/{local_entry.name}"
+        data_urls = data_store.write_shards(ds, prefix=prefix)
+    else:
+        # Use existing URLs as-is
+        data_urls = local_entry.data_urls
+
+    # Publish dataset record to atmosphere
+    publisher = DatasetPublisher(atmosphere_client)
+    uri = publisher.publish_with_urls(
+        urls=data_urls,
+        schema_uri=atmosphere_schema_uri,
+        name=name or local_entry.name,
+        description=description,
+        tags=tags,
+        license=license,
+        metadata=local_entry.metadata,
+    )
+
+    return str(uri)
+
+
+__all__ = [
+    "promote_to_atmosphere",
+]

{atdata-0.2.0a1.dist-info → atdata-0.2.2b1.dist-info}/METADATA

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: atdata
-Version: 0.2.0a1
+Version: 0.2.2b1
 Summary: A loose federation of distributed, typed datasets
-Author-email: Maxine Levesque <hello@maxine.science>
+Author-email: Maxine Levesque <hello@maxine.science>, "Maxine @ Forecast Bio" <maxine@forecast.bio>
 License-File: LICENSE
 Requires-Python: >=3.12
 Requires-Dist: atproto>=0.0.65
 Requires-Dist: fastparquet>=2024.11.0
+Requires-Dist: libipld>=3.3.2
 Requires-Dist: msgpack>=1.1.2
 Requires-Dist: numpy>=2.3.4
 Requires-Dist: ormsgpack>=1.11.0
@@ -34,9 +35,13 @@ A loose federation of distributed, typed datasets built on WebDataset.
 ## Features
 
 - **Typed Samples** - Define dataset schemas using Python dataclasses with automatic msgpack serialization
+- **Schema-free Exploration** - Load datasets without defining a schema first using `DictSample`
 - **Lens Transformations** - Bidirectional, composable transformations between different dataset views
 - **Automatic Batching** - Smart batch aggregation with numpy array stacking
 - **WebDataset Integration** - Efficient storage and streaming for large-scale datasets
+- **Flexible Data Sources** - Stream from local files, HTTP URLs, or S3-compatible storage
+- **HuggingFace-style API** - `load_dataset()` with path resolution and split handling
+- **Local & Atmosphere Storage** - Index datasets locally with Redis or publish to ATProto network
 
 ## Installation
 
@@ -48,9 +53,27 @@ Requires Python 3.12 or later.
 
 ## Quick Start
 
-### Defining Sample Types
+### Loading Datasets
 
-Use the `@packable` decorator to create typed dataset samples:
+The primary way to load datasets is with `load_dataset()`:
+
+```python
+from atdata import load_dataset
+
+# Load without specifying a type - returns Dataset[DictSample]
+ds = load_dataset("path/to/data.tar", split="train")
+
+# Explore the data
+for sample in ds.ordered():
+    print(sample.keys())      # See available fields
+    print(sample["text"])     # Dict-style access
+    print(sample.label)       # Attribute access
+    break
+```
+
+### Defining Typed Schemas
+
+Once you understand your data, define a typed schema with `@packable`:
 
 ```python
 import atdata
@@ -63,18 +86,21 @@ class ImageSample:
     metadata: dict
 ```
 
-### Creating Datasets
+### Loading with Types
 
 ```python
-# Create a dataset
-dataset = atdata.Dataset[ImageSample]("path/to/data-{000000..000009}.tar")
+# Load with explicit type
+ds = load_dataset("path/to/data-{000000..000009}.tar", ImageSample, split="train")
+
+# Or convert from DictSample
+ds = load_dataset("path/to/data.tar", split="train").as_type(ImageSample)
 
-# Iterate over samples in order
-for sample in dataset.ordered(batch_size=None):
+# Iterate over samples
+for sample in ds.ordered():
     print(f"Label: {sample.label}, Image shape: {sample.image.shape}")
 
 # Iterate with shuffling and batching
-for batch in dataset.shuffled(batch_size=32):
+for batch in ds.shuffled(batch_size=32):
     # batch.image is automatically stacked into shape (32, ...)
     # batch.label is a list of 32 labels
     process_batch(batch.image, batch.label)
@@ -105,9 +131,28 @@ for sample in processed_ds.ordered(batch_size=None):
 
 ## Core Concepts
 
+### DictSample
+
+The default sample type for schema-free exploration. Provides both attribute and dict-style access:
+
+```python
+ds = load_dataset("data.tar", split="train")
+
+for sample in ds.ordered():
+    # Dict-style access
+    print(sample["field_name"])
+
+    # Attribute access
+    print(sample.field_name)
+
+    # Introspection
+    print(sample.keys())
+    print(sample.to_dict())
+```
+
 ### PackableSample
 
-Base class for serializable samples. Fields annotated as `NDArray` are automatically handled:
+Base class for typed, serializable samples. Fields annotated as `NDArray` are automatically handled:
 
 ```python
 @atdata.packable
@@ -117,6 +162,8 @@ class MySample:
     regular_field: str
 ```
 
+Every `@packable` class automatically registers a lens from `DictSample`, enabling seamless conversion via `.as_type()`.
+
 ### Lens
 
 Bidirectional transformations with getter/putter semantics:
@@ -133,6 +180,25 @@ def my_lens_put(view: ViewType, source: SourceType) -> SourceType:
     return SourceType(...)
 ```
 
+### Data Sources
+
+Datasets support multiple backends via the `DataSource` protocol:
+
+```python
+# String URLs (most common) - automatically wrapped in URLSource
+dataset = atdata.Dataset[ImageSample]("data-{000000..000009}.tar")
+
+# S3 with authentication (private buckets, Cloudflare R2, MinIO)
+source = atdata.S3Source(
+    bucket="my-bucket",
+    keys=["data-000000.tar", "data-000001.tar"],
+    endpoint="https://my-account.r2.cloudflarestorage.com",
+    access_key="...",
+    secret_key="...",
+)
+dataset = atdata.Dataset[ImageSample](source)
+```
+
 ### Dataset URLs
 
 Uses WebDataset brace expansion for sharded datasets:
@@ -141,6 +207,31 @@ Uses WebDataset brace expansion for sharded datasets:
 - Multiple shards: `"data/dataset-{000000..000099}.tar"`
 - Multiple patterns: `"data/{train,val}/dataset-{000000..000009}.tar"`
 
+### HuggingFace-style API
+
+Load datasets with a familiar interface:
+
+```python
+from atdata import load_dataset
+
+# Load without type for exploration (returns Dataset[DictSample])
+ds = load_dataset("./data/train-*.tar", split="train")
+
+# Load with explicit type
+ds = load_dataset("./data/train-*.tar", ImageSample, split="train")
+
+# Load from S3 with brace notation
+ds = load_dataset("s3://bucket/data-{000000..000099}.tar", ImageSample, split="train")
+
+# Load all splits (returns DatasetDict)
+ds_dict = load_dataset("./data", ImageSample)
+train_ds = ds_dict["train"]
+test_ds = ds_dict["test"]
+
+# Convert DictSample to typed schema
+ds = load_dataset("./data/train.tar", split="train").as_type(ImageSample)
+```
+
 ## Development
 
 ### Setup
@@ -157,13 +248,13 @@ uv sync
 
 ```bash
 # Run all tests with coverage
-pytest
+uv run pytest
 
 # Run specific test file
-pytest tests/test_dataset.py
+uv run pytest tests/test_dataset.py
 
 # Run single test
-pytest tests/test_lens.py::test_lens
+uv run pytest tests/test_lens.py::test_lens
 ```
 
 ### Building

atdata-0.2.2b1.dist-info/RECORD

@@ -0,0 +1,28 @@
+atdata/__init__.py,sha256=TH-HoeLOdDJL42HqcrcR4pAoizI21CTUffdBlnEQZzM,2451
+atdata/_cid.py,sha256=aLH4Iov6oQsxFt4pj2-0SwcfBMQsIFtBDADQekQRtEw,4083
+atdata/_helpers.py,sha256=RvA-Xlj3AvgSWuiPdS8YTBp8AJT-u32BaLpxsu4PIIA,1564
+atdata/_hf_api.py,sha256=D4-2-3bhO9yO6G_wMBlNHO_Pcj-USsUUErJNgPbdK5w,23113
+atdata/_protocols.py,sha256=qHZDas6jOOWWEJYwZU4zPsB9RcX1WgwnOLNsvMek9rg,16055
+atdata/_schema_codec.py,sha256=5kKCYy2F4Tg_6wpcw2lxvKFUZrMmZsTBAuBqMvuthrw,14430
+atdata/_sources.py,sha256=w3nSqvd74T68vDv_xFZzx4myaFilFWXvFX7OoAT6vBU,16820
+atdata/_stub_manager.py,sha256=rTyxlf5LeEcs4SHdXI-xnthhboOjK9uWIAzyXj5w9MA,19150
+atdata/_type_utils.py,sha256=yKx_imuYpZkJZOQRBuneoVm7HNVIXnLZ3SbLQA7OeFw,2891
+atdata/dataset.py,sha256=HTWKBXc7nKB4iaYBRMzRhxQ3iN7DZGTSPPlpcxPIdoc,36113
+atdata/lens.py,sha256=fKt07rKFgwmtr10ArzhvtxJw8krcs4qJHIMc9Hbe544,9907
+atdata/local.py,sha256=Wg7ynRMmpup83Plh9EgHrshgiJfznzWvt0aXnxT0jfU,57547
+atdata/promote.py,sha256=DdjgrbUSOrtPau_fyGdELMwkVM8kM0bTBH8ojpcJXtc,6385
+atdata/atmosphere/__init__.py,sha256=DgBGgGN6AmRnq6Csm5kbxu24KBmp41QvVOvG0ewyOB8,9863
+atdata/atmosphere/_types.py,sha256=TK08Skpy2mLEgyiQmeYF4Pl_V0YfOiHI2zlClAdFvv4,9604
+atdata/atmosphere/client.py,sha256=cZQMJKJQ49CC99WYFsUw71iZD3tA9cRwGWpvcYjM1p8,16174
+atdata/atmosphere/lens.py,sha256=8papN5AK8Id-1LxNaHLyvpR_YYIkt5ifMd-47-QFJt4,9377
+atdata/atmosphere/records.py,sha256=aC1oaAyIUid56CGkFEiZe5-jGkmkVgcQKzzFauM9yso,16003
+atdata/atmosphere/schema.py,sha256=IBbssMT8mXJbJ7otW5ZJXj9eZUCwI1VsYagjeEQPwCI,7767
+atdata/atmosphere/store.py,sha256=dEVGJtIUfxWZhD4NraUNGjD8Umh3CugrDCZONn-i7r0,6366
+atdata/cli/__init__.py,sha256=fLnG7-Nra0IEOK140c4RoSSRvah1uXIDKpl6uW31acc,5698
+atdata/cli/diagnose.py,sha256=q6wj4Skl-KwEAnwD9Bnhk_Gr8EEnrsNkSxwKtk54LaM,5455
+atdata/cli/local.py,sha256=xNItYhEYOGQd30_eJ39s8IQfIfrozMxblsPc29hY-rE,8046
+atdata-0.2.2b1.dist-info/METADATA,sha256=QrVdfUO-0PrI2UI113lZw16cHh_Bgdqirx-xrSZ9_bg,7270
+atdata-0.2.2b1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+atdata-0.2.2b1.dist-info/entry_points.txt,sha256=6-iQr1veSTq-ac94bLyfcyGHprrZWevPEd12BWX37tQ,39
+atdata-0.2.2b1.dist-info/licenses/LICENSE,sha256=Pz2eACSxkhsGfW9_iN60pgy-enjnbGTj8df8O3ebnQQ,16726
+atdata-0.2.2b1.dist-info/RECORD,,

atdata-0.2.0a1.dist-info/RECORD

@@ -1,16 +0,0 @@
-atdata/__init__.py,sha256=6RYvy9GJwqtSQbCS81HaQyOyAVgLxm63kBt0SH5Qapo,1642
-atdata/_helpers.py,sha256=RvA-Xlj3AvgSWuiPdS8YTBp8AJT-u32BaLpxsu4PIIA,1564
-atdata/dataset.py,sha256=O2j1_ABvTFcs83_y-GGDRROD9zRe-237O2OiI1NhySg,24173
-atdata/lens.py,sha256=lFFVeuKXa17KYjfz3VFqE9Xf0vy3C6puSiF78hyIaAI,9673
-atdata/local.py,sha256=IdNOTA0nvszG-XRkRMkT_zkMivIx93WKh3bpgIx_u_o,15458
-atdata/atmosphere/__init__.py,sha256=8tPDziazrQWdyvetWTVV1eWRt6JBy86WfnvAeyh8iJE,1743
-atdata/atmosphere/_types.py,sha256=0606wb2c8Ty7cmZWTh5mb_qwJmAwYf5oaJU_wk9moa8,9564
-atdata/atmosphere/client.py,sha256=tihVBlhPCz3TZBHs_Ce7uYwE70IzKyeXNpDKsN_qc5U,11358
-atdata/atmosphere/lens.py,sha256=BzUdagItYsyzYHtK1jqppJJ1VUHJVQRw0hi7LuvJG5Q,9267
-atdata/atmosphere/records.py,sha256=-9hhSLsr6sDHkzCVWDudZtxTMHXcVyUHeVojlNcGdL4,10672
-atdata/atmosphere/schema.py,sha256=6gQMGSRjgESaXZzBYMfO51qL9JMiyNGrqJe4iWarO7w,9872
-atdata-0.2.0a1.dist-info/METADATA,sha256=EBwfarL5lmzP2lMdn7Z9yfZBjP6TwTalnTDC8cc7cdY,4471
-atdata-0.2.0a1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-atdata-0.2.0a1.dist-info/entry_points.txt,sha256=6-iQr1veSTq-ac94bLyfcyGHprrZWevPEd12BWX37tQ,39
-atdata-0.2.0a1.dist-info/licenses/LICENSE,sha256=Pz2eACSxkhsGfW9_iN60pgy-enjnbGTj8df8O3ebnQQ,16726
-atdata-0.2.0a1.dist-info/RECORD,,