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

atdata/atmosphere/_types.py

@@ -1,15 +1,22 @@
 """Type definitions for ATProto record structures.
 
-This module defines the data structures used to represent ATProto records
-for schemas, datasets, and lenses. These types map to the Lexicon definitions
-in the ``ac.foundation.dataset.*`` namespace.
+This module provides the ``AtUri`` utility class and the ``LEXICON_NAMESPACE``
+constant. Lexicon-mirror record types (``LexSchemaRecord``, ``LexDatasetRecord``,
+``LexLensRecord``, etc.) have moved to ``atdata.atmosphere._lexicon_types``.
+
+The old type names (``SchemaRecord``, ``DatasetRecord``, ``LensRecord``,
+``StorageLocation``, ``FieldType``, ``FieldDef``, ``CodeReference``) are
+re-exported here as deprecated aliases for backward compatibility.
 """
 
-from dataclasses import dataclass, field
-from datetime import datetime, timezone
-from typing import Optional, Literal, Any
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+from typing import Any, Literal, Optional
 
-# Lexicon namespace for atdata records
+# Canonical constant — also defined in _lexicon_types but kept here as the
+# historically authoritative location so existing imports continue to work.
 LEXICON_NAMESPACE = "ac.foundation.dataset"
 
 
@@ -39,7 +46,7 @@ class AtUri:
     """The record key within the collection."""
 
     @classmethod
-    def parse(cls, uri: str) -> "AtUri":
+    def parse(cls, uri: str) -> AtUri:
         """Parse an AT URI string into components.
 
         Args:
@@ -71,261 +78,82 @@ class AtUri:
         return f"at://{self.authority}/{self.collection}/{self.rkey}"
 
 
-@dataclass
-class FieldType:
-    """Schema field type definition.
+# ---------------------------------------------------------------------------
+# Deprecated re-exports (will be removed in a future version)
+# ---------------------------------------------------------------------------
+# These names existed in this module before the lexicon-mirror types were
+# split into _lexicon_types.py.  They are re-exported here so that existing
+# imports like ``from atdata.atmosphere._types import SchemaRecord`` continue
+# to work during the migration period.
+
+
+def __getattr__(name: str) -> Any:
+    _DEPRECATED_ALIASES: dict[str, tuple[str, str]] = {
+        # old name → (new module attribute, import path in _lexicon_types)
+        "FieldType": ("FieldType", "atdata.atmosphere._lexicon_types"),
+        "FieldDef": ("FieldDef", "atdata.atmosphere._lexicon_types"),
+        "SchemaRecord": ("LexSchemaRecord", "atdata.atmosphere._lexicon_types"),
+        "DatasetRecord": ("LexDatasetRecord", "atdata.atmosphere._lexicon_types"),
+        "LensRecord": ("LexLensRecord", "atdata.atmosphere._lexicon_types"),
+        "StorageLocation": ("StorageLocation", "atdata.atmosphere._lexicon_types"),
+        "CodeReference": ("LexCodeReference", "atdata.atmosphere._lexicon_types"),
+    }
+    if name in _DEPRECATED_ALIASES:
+        new_name, mod_path = _DEPRECATED_ALIASES[name]
+        warnings.warn(
+            f"{name} has been moved. Import {new_name} from {mod_path} instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from . import _lexicon_types
 
-    Represents a type in the schema type system, supporting primitives,
-    ndarrays, and references to other schemas.
-    """
+        # For StorageLocation, provide a lightweight shim
+        if name == "StorageLocation":
+            return _StorageLocationShim
+        # FieldType / FieldDef don't exist in _lexicon_types; they were
+        # internal-only types used by the old SchemaRecord.  Return them
+        # from the shim definitions below.
+        if name in ("FieldType", "FieldDef"):
+            return _FIELD_SHIMS[name]
+        return getattr(_lexicon_types, new_name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
-    kind: Literal["primitive", "ndarray", "ref", "array"]
-    """The category of type."""
 
-    primitive: Optional[str] = None
-    """For kind='primitive': one of 'str', 'int', 'float', 'bool', 'bytes'."""
+# Lightweight shims for types that have no direct equivalent in _lexicon_types
 
-    dtype: Optional[str] = None
-    """For kind='ndarray': numpy dtype string (e.g., 'float32')."""
 
-    shape: Optional[list[int | None]] = None
-    """For kind='ndarray': shape constraints (None for any dimension)."""
+@dataclass
+class _FieldTypeShim:
+    """Deprecated: schema field type used by the old SchemaRecord."""
 
+    kind: Literal["primitive", "ndarray", "ref", "array"]
+    primitive: Optional[str] = None
+    dtype: Optional[str] = None
+    shape: Optional[list[int | None]] = None
     ref: Optional[str] = None
-    """For kind='ref': AT URI of referenced schema."""
-
-    items: Optional["FieldType"] = None
-    """For kind='array': type of array elements."""
+    items: Optional[_FieldTypeShim] = None
 
 
 @dataclass
-class FieldDef:
-    """Schema field definition."""
+class _FieldDefShim:
+    """Deprecated: schema field definition used by the old SchemaRecord."""
 
     name: str
-    """Field name."""
-
-    field_type: FieldType
-    """Type of this field."""
-
+    field_type: _FieldTypeShim
     optional: bool = False
-    """Whether this field can be None."""
-
-    description: Optional[str] = None
-    """Human-readable description."""
-
-
-@dataclass
-class SchemaRecord:
-    """ATProto record for a PackableSample schema.
-
-    Maps to the ``ac.foundation.dataset.schema`` Lexicon.
-    """
-
-    name: str
-    """Human-readable schema name."""
-
-    version: str
-    """Semantic version string (e.g., '1.0.0')."""
-
-    fields: list[FieldDef]
-    """List of field definitions."""
-
     description: Optional[str] = None
-    """Human-readable description."""
-
-    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
-    """When this record was created."""
-
-    metadata: Optional[dict] = None
-    """Arbitrary metadata as msgpack-encoded bytes."""
-
-    def to_record(self) -> dict:
-        """Convert to ATProto record dict for publishing."""
-        record = {
-            "$type": f"{LEXICON_NAMESPACE}.schema",
-            "name": self.name,
-            "version": self.version,
-            "fields": [self._field_to_dict(f) for f in self.fields],
-            "createdAt": self.created_at.isoformat(),
-        }
-        if self.description:
-            record["description"] = self.description
-        if self.metadata:
-            record["metadata"] = self.metadata
-        return record
-
-    def _field_to_dict(self, field_def: FieldDef) -> dict:
-        """Convert a field definition to dict."""
-        result = {
-            "name": field_def.name,
-            "fieldType": self._type_to_dict(field_def.field_type),
-            "optional": field_def.optional,
-        }
-        if field_def.description:
-            result["description"] = field_def.description
-        return result
-
-    def _type_to_dict(self, field_type: FieldType) -> dict:
-        """Convert a field type to dict."""
-        result: dict = {"$type": f"{LEXICON_NAMESPACE}.schemaType#{field_type.kind}"}
-
-        if field_type.kind == "primitive":
-            result["primitive"] = field_type.primitive
-        elif field_type.kind == "ndarray":
-            result["dtype"] = field_type.dtype
-            if field_type.shape:
-                result["shape"] = field_type.shape
-        elif field_type.kind == "ref":
-            result["ref"] = field_type.ref
-        elif field_type.kind == "array":
-            if field_type.items:
-                result["items"] = self._type_to_dict(field_type.items)
-
-        return result
 
 
 @dataclass
-class StorageLocation:
-    """Dataset storage location specification."""
+class _StorageLocationShim:
+    """Deprecated: use StorageHttp / StorageS3 / StorageBlobs instead."""
 
     kind: Literal["external", "blobs"]
-    """Storage type: external URLs or ATProto blobs."""
-
     urls: Optional[list[str]] = None
-    """For kind='external': WebDataset URLs with brace notation."""
-
     blob_refs: Optional[list[dict]] = None
-    """For kind='blobs': ATProto blob references."""
-
-
-@dataclass
-class DatasetRecord:
-    """ATProto record for a dataset index.
-
-    Maps to the ``ac.foundation.dataset.record`` Lexicon.
-    """
-
-    name: str
-    """Human-readable dataset name."""
-
-    schema_ref: str
-    """AT URI of the schema record."""
-
-    storage: StorageLocation
-    """Where the dataset data is stored."""
-
-    description: Optional[str] = None
-    """Human-readable description."""
-
-    tags: list[str] = field(default_factory=list)
-    """Searchable tags."""
-
-    license: Optional[str] = None
-    """SPDX license identifier."""
-
-    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
-    """When this record was created."""
-
-    metadata: Optional[bytes] = None
-    """Arbitrary metadata as msgpack-encoded bytes."""
-
-    def to_record(self) -> dict:
-        """Convert to ATProto record dict for publishing."""
-        record = {
-            "$type": f"{LEXICON_NAMESPACE}.record",
-            "name": self.name,
-            "schemaRef": self.schema_ref,
-            "storage": self._storage_to_dict(),
-            "createdAt": self.created_at.isoformat(),
-        }
-        if self.description:
-            record["description"] = self.description
-        if self.tags:
-            record["tags"] = self.tags
-        if self.license:
-            record["license"] = self.license
-        if self.metadata:
-            record["metadata"] = self.metadata
-        return record
-
-    def _storage_to_dict(self) -> dict:
-        """Convert storage location to dict."""
-        if self.storage.kind == "external":
-            return {
-                "$type": f"{LEXICON_NAMESPACE}.storageExternal",
-                "urls": self.storage.urls or [],
-            }
-        else:
-            return {
-                "$type": f"{LEXICON_NAMESPACE}.storageBlobs",
-                "blobs": self.storage.blob_refs or [],
-            }
-
 
-@dataclass
-class CodeReference:
-    """Reference to lens code in a git repository."""
-
-    repository: str
-    """Git repository URL."""
-
-    commit: str
-    """Git commit hash."""
-
-    path: str
-    """Path to the code file/function."""
-
-
-@dataclass
-class LensRecord:
-    """ATProto record for a lens transformation.
 
-    Maps to the ``ac.foundation.dataset.lens`` Lexicon.
-    """
-
-    name: str
-    """Human-readable lens name."""
-
-    source_schema: str
-    """AT URI of the source schema."""
-
-    target_schema: str
-    """AT URI of the target schema."""
-
-    description: Optional[str] = None
-    """What this transformation does."""
-
-    getter_code: Optional[CodeReference] = None
-    """Reference to getter function code."""
-
-    putter_code: Optional[CodeReference] = None
-    """Reference to putter function code."""
-
-    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
-    """When this record was created."""
-
-    def to_record(self) -> dict:
-        """Convert to ATProto record dict for publishing."""
-        record: dict[str, Any] = {
-            "$type": f"{LEXICON_NAMESPACE}.lens",
-            "name": self.name,
-            "sourceSchema": self.source_schema,
-            "targetSchema": self.target_schema,
-            "createdAt": self.created_at.isoformat(),
-        }
-        if self.description:
-            record["description"] = self.description
-        if self.getter_code:
-            record["getterCode"] = {
-                "repository": self.getter_code.repository,
-                "commit": self.getter_code.commit,
-                "path": self.getter_code.path,
-            }
-        if self.putter_code:
-            record["putterCode"] = {
-                "repository": self.putter_code.repository,
-                "commit": self.putter_code.commit,
-                "path": self.putter_code.path,
-            }
-        return record
+_FIELD_SHIMS: dict[str, type] = {
+    "FieldType": _FieldTypeShim,
+    "FieldDef": _FieldDefShim,
+}

atdata/atmosphere/lens.py

@@ -9,18 +9,11 @@ Note:
     implementations.
 """
 
-from typing import Optional
+from typing import Optional, TYPE_CHECKING
 
 from .client import Atmosphere
-from ._types import (
-    AtUri,
-    LensRecord,
-    CodeReference,
-    LEXICON_NAMESPACE,
-)
-
-# Import for type checking only
-from typing import TYPE_CHECKING
+from ._types import AtUri, LEXICON_NAMESPACE
+from ._lexicon_types import LexLensRecord, LexCodeReference
 
 if TYPE_CHECKING:
     from ..lens import Lens
@@ -70,59 +63,58 @@ class LensPublisher:
         name: str,
         source_schema_uri: str,
         target_schema_uri: str,
+        code_repository: str,
+        code_commit: str,
+        getter_path: str,
+        putter_path: 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,
+        language: Optional[str] = None,
+        metadata: Optional[dict] = None,
         rkey: Optional[str] = None,
     ) -> AtUri:
         """Publish a lens transformation record to ATProto.
 
+        Code references are required by the ATProto lexicon. Each lens must
+        point to a getter and putter implementation in a git repository.
+
         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').
+            description: What this transformation does.
+            language: Programming language (e.g., 'python').
+            metadata: Arbitrary metadata dictionary.
             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(
+        getter_code = LexCodeReference(
+            repository=code_repository,
+            commit=code_commit,
+            path=getter_path,
+        )
+        putter_code = LexCodeReference(
+            repository=code_repository,
+            commit=code_commit,
+            path=putter_path,
+        )
+
+        lens_record = LexLensRecord(
             name=name,
             source_schema=source_schema_uri,
             target_schema=target_schema_uri,
-            description=description,
             getter_code=getter_code,
             putter_code=putter_code,
+            description=description,
+            language=language,
+            metadata=metadata,
         )
 
         return self.client.create_record(
@@ -142,6 +134,8 @@ class LensPublisher:
         code_repository: str,
         code_commit: str,
         description: Optional[str] = None,
+        language: Optional[str] = None,
+        metadata: Optional[dict] = None,
         rkey: Optional[str] = None,
     ) -> AtUri:
         """Publish a lens record from an existing Lens object.
@@ -157,16 +151,16 @@ class LensPublisher:
             code_repository: Git repository URL.
             code_commit: Git commit hash.
             description: What this transformation does.
+            language: Programming language (e.g., 'python').
+            metadata: Arbitrary metadata dictionary.
             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__", "")
 
@@ -177,11 +171,13 @@ class LensPublisher:
             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,
+            description=description,
+            language=language,
+            metadata=metadata,
             rkey=rkey,
         )
 
@@ -234,6 +230,18 @@ class LensLoader:
 
         return record
 
+    def get_typed(self, uri: str | AtUri) -> LexLensRecord:
+        """Fetch a lens record and return as a typed object.
+
+        Args:
+            uri: The AT URI of the lens record.
+
+        Returns:
+            LexLensRecord instance.
+        """
+        record = self.get(uri)
+        return LexLensRecord.from_record(record)
+
     def list_all(
         self,
         repo: Optional[str] = None,