atlas-python 0.10.0__tar.gz → 0.12.0__tar.gz

{atlas_python-0.10.0 → atlas_python-0.12.0}/Cargo.lock

@@ -28,9 +28,9 @@ checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 
 [[package]]
 name = "array-format"
-version = "0.10.0"
+version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a637a3b5f23ba45eb53f09e643b363163114f0e94d0f6f05f330134cb86d381b"
+checksum = "f894cd59132aa6a00c360fef55469100c39da19c556bbf44a46bd647f7252fae"
 dependencies = [
  "bytes",
  "futures",
@@ -71,7 +71,7 @@ dependencies = [
 
 [[package]]
 name = "atlas-python"
-version = "0.10.0"
+version = "0.12.0"
 dependencies = [
  "atlas-rust",
  "ndarray",
@@ -86,7 +86,7 @@ dependencies = [
 
 [[package]]
 name = "atlas-rust"
-version = "0.10.0"
+version = "0.12.0"
 dependencies = [
  "array-format",
  "chrono",

{atlas_python-0.10.0 → atlas_python-0.12.0}/Cargo.toml

@@ -5,7 +5,7 @@ members = ["atlas-python"]
 # Registry name on crates.io (`atlas` is taken). The library is still
 # imported as `atlas` — see `[lib]` below.
 name = "atlas-rust"
-version = "0.10.0"
+version = "0.12.0"
 edition = "2024"
 description = "Directory-based store for thousands of N-dimensional datasets local or remote using object storage."
 license = "Apache-2.0"
@@ -22,7 +22,7 @@ all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
 
 [dependencies]
-array-format = "0.10.0"
+array-format = "0.11.0"
 object_store = "0.13"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

{atlas_python-0.10.0 → atlas_python-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atlas-python
-Version: 0.10.0
+Version: 0.12.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
@@ -179,8 +179,8 @@ picklable, so call `.compute()` before handing off to distributed/multiprocessin
 | Item | How it's stored |
 | --- | --- |
 | Each coord / data variable | A separate array, with `dims` mapped 1:1. |
-| Dataset attrs | Dataset attributes, plain keys. |
-| Per-variable attrs | Flattened as `{var}.{attr}` at the dataset attr level. |
+| Dataset attrs | Dataset-level (global) attributes, plain keys. |
+| Per-variable attrs | Real per-variable attributes on each variable's array. |
 | Per-variable `_FillValue` | Consumed by `define_array` as a typed fill value (source `Dataset.attrs` is not mutated). See [Missing data](#missing-data). |
 | Coord vs data_var distinction | JSON list in the internal `_pyatlas_coords` attr. |
 | Non-scalar attr values (list, ndarray) | JSON-encoded string with a `json:` prefix marker. |
@@ -261,8 +261,10 @@ handle instead of a local path. The path-based local-filesystem API works withou
 | `delete_array(name)` | Tombstone the array within this dataset. |
 | `array_meta(name) -> dict \| None` | `{"dtype", "shape", "chunk_shape", "dimension_names"}`. |
 | `array_stats(name) -> dict \| None` | `{"row_count", "null_count", "min", "max"}` — populated after `flush()`. |
-| `set_attribute(key, value, dtype=None)` | Type inferred from the Python value; pass `dtype` to override (e.g. `"int8"`, `"float32"`, `"timestamp_nanoseconds"`). On disk: bool, int64, float64, string, timestamp_nanoseconds. |
-| `get_attribute(key)` / `attributes()` | Single attribute or dict of all. |
+| `set_attribute(key, value, dtype=None)` | Set a dataset-level (global) attribute. Type inferred from the Python value; pass `dtype` to override (e.g. `"int8"`, `"float32"`, `"timestamp_nanoseconds"`). Values are stored in the `_global` `.af` file. |
+| `get_attribute(key)` / `attributes()` | Single global attribute or dict of all. |
+| `set_array_attribute(array, key, value, dtype=None)` | Set a per-variable attribute on `array` (e.g. `units`); `KeyError` if the array isn't defined. |
+| `get_array_attribute(array, key)` / `array_attributes(array)` | Single per-variable attribute or dict of all, for `array`. |
 
 `DatasetView` does **not** expose its own `flush` / `compact` — both go through the parent `Atlas`.
 

{atlas_python-0.10.0 → atlas_python-0.12.0}/README.md

@@ -21,26 +21,30 @@ A directory-based store for thousands of named datasets, each holding N-dimensio
 
 `atlas` is designed for workloads where you have a large collection of similarly-shaped datasets — such as one dataset per time step, sensor station, or simulation run — and you want to query a single variable (e.g. `temperature`) across all of them efficiently.
 
-Each dataset is a named group of N-dimensional arrays with typed per-dataset attributes. Datasets that share an array name (e.g. every `jan_2024`, `feb_2024`, … all have `temperature`) are stored together in the same physical file, keyed by dataset name inside the file.
+Each dataset is a named group of N-dimensional arrays with typed attributes — both dataset-level (global) attributes and per-variable attributes. Datasets that share an array name (e.g. every `jan_2024`, `feb_2024`, … all have `temperature`) are stored together in the same physical file, keyed by dataset name inside the file.
 
 ```text
 my_store/
-├── atlas.json               ← dataset registry and per-dataset attributes (JSON)
+├── atlas.json               ← interned per-dataset schema + attribute-key namespace (JSON)
+├── _global/
+│   └── data.af         ← dataset-level (global) attribute values, one entry per dataset
 ├── temperature/
-│   └── data.af         ← one ArrayFile holding temperature for every dataset
+│   └── data.af         ← one ArrayFile: temperature + its per-variable attributes, per dataset
 ├── pressure/
 │   └── data.af
 └── time/
     └── data.af
 ```
 
+`atlas.json` holds only the **schema** of the collection. Attribute **values** live in the `.af` files: per-variable attributes on the variable's own file, and dataset-level attributes in the reserved `_global` file.
+
 ---
 
 ## Durability model
 
-`atlas.json` is read **once** when the store is opened or created. Every subsequent mutation — `create_dataset`, `define_array`, `set_attribute`, `delete_array`, `delete_dataset` — only touches the in-memory `StoreMeta`; writes to `ArrayFile`s buffer inside the per-array in-memory layer. **Nothing reaches disk until `Atlas::flush()` (or `Atlas::close()`).** Dropping an `Atlas` without flushing abandons every pending in-memory write.
+`atlas.json` is read **once** when the store is opened or created. Every subsequent mutation — `create_dataset`, `define_array`, `set_attribute`, `set_array_attribute`, `delete_array`, `delete_dataset` — only touches in-memory state; array writes buffer inside the per-array in-memory layer and attribute writes buffer in a pending-attribute map. **Nothing reaches disk until `Atlas::flush()` (or `Atlas::close()`).** Dropping an `Atlas` without flushing abandons every pending in-memory write.
 
-A single `Atlas::flush()` walks every cached `ArrayFile` (writing deltas + stats) and then serialises the in-memory `StoreMeta` to `atlas.json`. This gives one durability boundary for the whole store: N datasets ⇒ one delta file per touched array name (not one per dataset) and one `atlas.json` rewrite (not N).
+A single `Atlas::flush()` drains the buffered attributes into their `.af` files, walks every cached `ArrayFile` (writing deltas + stats), and then serialises the in-memory schema to `atlas.json`. This gives one durability boundary for the whole store: N datasets ⇒ one delta file per touched array name (not one per dataset) and one `atlas.json` rewrite (not N).
 
 `DatasetView` is a borrowed handle into the atlas's shared meta — it has no `flush()` of its own.
 
@@ -50,14 +54,25 @@ A single `Atlas::flush()` walks every cached `ArrayFile` (writing deltas + stats
 
 ### `atlas.json`
 
-The registry is a plain JSON file written on `Atlas::flush()` / `Atlas::close()`. It stores:
+The schema is a plain JSON file written on `Atlas::flush()` / `Atlas::close()`. It stores:
+
+- **Store version** — for format upgrades. The current version is `2`; stores written by an older atlas are rejected on open (re-export to upgrade).
+- **Interned schema pool** — each *distinct* per-dataset schema is stored once and referenced by index. A dataset's schema is its array schemas (per array: dtype, shape, chunk shape, named dimensions, codec) plus its **attribute-key namespace** (the names of its global and per-variable attribute keys). A collection of thousands of homogeneous datasets stores its schema a single time.
+- **Dataset registry** — a map of dataset name → schema-pool index.
+- **Merged schema** — a collection-wide summary listing every unique array (with its dtype widened across all datasets, its dimensions, and its per-variable attribute types) and every global attribute type. Descriptive only — reads always use each dataset's own schema — but handy for tools that want one view of "what's in here." Also exposed programmatically via `Atlas::merged_schema()`.
+
+When the same array name (or attribute key) appears in more than one dataset with different types, the merged type is **widened**. Widening is allowed only within numeric types (e.g. `int16` ∪ `int32` → `int32`; `int32` ∪ `float32` → `float64`) or between `string` and `timestamp` (→ `string`).
+
+Any other combination — e.g. an `int32` array in one dataset and a `string` array under the same name in another — can't merge. The dataset is **still stored** under its own type (each dataset keeps the type it declared, and its data reads back normally); the merged schema simply keeps the **first-seen** type. Whether that's reported as a warning or an error is set by `StoreConfig::on_type_mismatch`:
+
+| `TypeMismatchPolicy` | Behaviour |
+| --- | --- |
+| `Warn` (default) | Logs a `tracing` warning and carries on — an ingest of many heterogeneous files won't abort because one disagrees. |
+| `Error` | `define_array` / `set_attribute` / `set_array_attribute` return `Error::TypeMismatch`. |
 
-- **Store version** — for future format upgrades.
-- **Dataset names** — the complete list of datasets in the store.
-- **Per-dataset attributes** — typed key-value pairs serialized as plain JSON values: bool, 64-bit integer, 64-bit float, UTF-8 string, or an RFC 3339 nanosecond-precision timestamp string (e.g. `"2023-11-15T07:33:20.123456789Z"`). Atlas's `Attr` enum has five variants (`Bool`/`Int64`/`Float64`/`String`/`TimestampNanoseconds`); there are no narrow integer/float types on disk.
-- **Array schemas** — per array: dtype, shape, chunk shape, named dimensions, and the codec used when the array was first written.
+The policy is a **per-session** choice, not an on-disk property: pass it to `Atlas::create`, or to `Atlas::open_with_config` / `Atlas::open_path_with_config` when opening an existing collection (plain `open` / `open_path` use the default). Note that these open variants honour only `on_type_mismatch` — the codec and metadata format are always detected from disk.
 
-Because `atlas.json` is human-readable and self-describing, you can inspect or audit the store contents with any JSON tool without needing the library.
+Attribute **values** are **not** in `atlas.json` — only their key names are (as part of the schema). Values live in the `.af` files and are read via the `array-format` attribute API. Because `atlas.json` is human-readable and self-describing, you can still inspect or audit the collection's schema with any JSON tool without needing the library.
 
 ### `<array_name>/data.af`
 
@@ -67,6 +82,7 @@ Each array variable gets its own subdirectory with a single `data.af` binary fil
 - **Chunked layout** — arrays are split into chunks of a user-specified shape, so partial reads and writes touch only the relevant blocks.
 - **Configurable compression** — each block is compressed with the codec set when the store was created (default: Zstd; also LZ4 and uncompressed). The codec is persisted in `atlas.json` and restored automatically on `open` — no need to pass it again. Block target size is 8 MiB.
 - **Per-array fill value** — `define_array` accepts an optional `FillValue` (one of `Bool`/`Int`/`UInt`/`Float`/`String`). Unwritten cells read back as the fill value, and any *written* cell equal to it is counted as a null in the persisted stats (see below). Fill values are stored in the per-array footer; `atlas.json` is not extended.
+- **Attribute values** — per-variable attributes (e.g. `units`) are stored in the footer of the variable's own `data.af`, keyed by dataset. Dataset-level (global) attributes live the same way in the reserved `_global/data.af`. Atlas's `Attr` type mirrors `array-format`'s `AttributeValue` (bool, sized ints/uints, `f32`/`f64`, string, binary, and typed lists) plus a nanosecond timestamp variant stored as an RFC 3339 string.
 - **Persisted statistics** — on `Atlas::flush()`, min, max, null count, and row count are computed per array per dataset and stored alongside the data. Cells equal to the array's fill value are tallied in `null_count` and excluded from `min`/`max` (NaN fills match NaN cells by bit pattern). Statistics survive store reopening.
 - **In-memory caches** — a 256 MiB decoded block cache and a 64 MiB raw I/O cache sit in front of the object store for repeated reads.
 

{atlas_python-0.10.0 → atlas_python-0.12.0}/atlas-python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "atlas-python"
-version = "0.10.0"
+version = "0.12.0"
 edition = "2021"
 readme = "README.md"
 

{atlas_python-0.10.0 → atlas_python-0.12.0}/atlas-python/README.md

@@ -147,8 +147,8 @@ picklable, so call `.compute()` before handing off to distributed/multiprocessin
 | Item | How it's stored |
 | --- | --- |
 | Each coord / data variable | A separate array, with `dims` mapped 1:1. |
-| Dataset attrs | Dataset attributes, plain keys. |
-| Per-variable attrs | Flattened as `{var}.{attr}` at the dataset attr level. |
+| Dataset attrs | Dataset-level (global) attributes, plain keys. |
+| Per-variable attrs | Real per-variable attributes on each variable's array. |
 | Per-variable `_FillValue` | Consumed by `define_array` as a typed fill value (source `Dataset.attrs` is not mutated). See [Missing data](#missing-data). |
 | Coord vs data_var distinction | JSON list in the internal `_pyatlas_coords` attr. |
 | Non-scalar attr values (list, ndarray) | JSON-encoded string with a `json:` prefix marker. |
@@ -229,8 +229,10 @@ handle instead of a local path. The path-based local-filesystem API works withou
 | `delete_array(name)` | Tombstone the array within this dataset. |
 | `array_meta(name) -> dict \| None` | `{"dtype", "shape", "chunk_shape", "dimension_names"}`. |
 | `array_stats(name) -> dict \| None` | `{"row_count", "null_count", "min", "max"}` — populated after `flush()`. |
-| `set_attribute(key, value, dtype=None)` | Type inferred from the Python value; pass `dtype` to override (e.g. `"int8"`, `"float32"`, `"timestamp_nanoseconds"`). On disk: bool, int64, float64, string, timestamp_nanoseconds. |
-| `get_attribute(key)` / `attributes()` | Single attribute or dict of all. |
+| `set_attribute(key, value, dtype=None)` | Set a dataset-level (global) attribute. Type inferred from the Python value; pass `dtype` to override (e.g. `"int8"`, `"float32"`, `"timestamp_nanoseconds"`). Values are stored in the `_global` `.af` file. |
+| `get_attribute(key)` / `attributes()` | Single global attribute or dict of all. |
+| `set_array_attribute(array, key, value, dtype=None)` | Set a per-variable attribute on `array` (e.g. `units`); `KeyError` if the array isn't defined. |
+| `get_array_attribute(array, key)` / `array_attributes(array)` | Single per-variable attribute or dict of all, for `array`. |
 
 `DatasetView` does **not** expose its own `flush` / `compact` — both go through the parent `Atlas`.
 

atlas_python-0.12.0/atlas-python/docs/guides/attributes.md

@@ -0,0 +1,115 @@
+# Attributes
+
+Each [`DatasetView`](../reference/dataset-view.md) carries typed attributes at
+two levels: **dataset-level** (global) attributes and **per-variable**
+attributes on individual arrays. Attribute *values* are stored in the `.af`
+files — global values in a reserved `_global` file, per-variable values on the
+variable's own file. Only the attribute *key names* are recorded in
+`atlas.json` (as part of the schema), so listing which attributes exist is
+cheap and doesn't load any array bytes.
+
+## Dataset-level (global) attributes
+
+```python
+ds = atlas.create_dataset("jan_2024")
+
+ds.set_attribute("month", 1)            # inferred int
+ds.set_attribute("station", "KNMI")     # inferred str
+ds.set_attribute("calibrated", True)    # inferred bool
+
+ds.get_attribute("month")               # -> 1
+ds.get_attribute("missing")             # -> None
+ds.attributes()                         # -> {"month": 1, "station": "KNMI", "calibrated": True}
+```
+
+## Per-variable attributes
+
+Attributes can also attach to a specific array (e.g. `units` on `temperature`):
+
+```python
+ds.define_array("temperature", dtype="float32", dims=["lat", "lon"], shape=[4, 8])
+ds.set_array_attribute("temperature", "units", "degC")
+ds.set_array_attribute("temperature", "valid_range", [-40.0, 60.0], dtype="f64")
+
+ds.get_array_attribute("temperature", "units")   # -> "degC"
+ds.array_attributes("temperature")               # -> {"units": "degC", "valid_range": [...]}
+```
+
+`set_array_attribute` raises `KeyError` if the array isn't defined in the
+dataset.
+
+## Durability
+
+Attribute writes are buffered in memory and only reach disk on
+[`atlas.flush()`](durability.md) (or leaving a `with atlas:` block), together
+with the array data. The reserved `_global/data.af` file is created lazily —
+only once a dataset actually sets a global attribute.
+
+## The on-disk type system
+
+Atlas's `Attr` type mirrors the underlying `array-format` `AttributeValue`:
+
+| On-disk type | Python type returned on read |
+|---|---|
+| `bool` | `bool` |
+| `int8` / `int16` / `int32` / `int64` | `int` |
+| `uint8` / `uint16` / `uint32` / `uint64` | `int` |
+| `float32` / `float64` | `float` |
+| `string` | `str` |
+| `binary` | `bytes` |
+| `timestamp_nanoseconds` | `int` (nanoseconds; stored as an RFC 3339 string) |
+| any of the above as a list | `list` |
+
+Type is inferred from the Python value by default — `int` → `int64`,
+`float` → `float64`, `str` → `string`, `bytes` → `binary`, `bool` → `bool`.
+
+## Overriding inferred types
+
+Pass `dtype=` to narrow or force a specific type (works on both
+`set_attribute` and `set_array_attribute`):
+
+```python
+ds.set_attribute("sensor_id", 7, dtype="int8")          # stored as int8, range-checked
+ds.set_attribute("ratio", 0.5, dtype="float32")         # stored as float32
+ds.set_attribute("observed_at",
+                 np.datetime64("2024-01-15T10:00", "ns").astype("int64").item(),
+                 dtype="timestamp_nanoseconds")
+```
+
+Unlike earlier versions, width hints now preserve the storage type: `dtype="int8"`
+stores an 8-bit integer, not a widened `int64`. A `timestamp_nanoseconds`
+attribute is stored as an RFC 3339 string and restored to a timestamp on read.
+
+## Per-variable xarray attributes
+
+When you write an `xr.Dataset` via `atlas.add_xarray_dataset(ds, name)`, each
+variable's `attrs` are stored as **real per-variable attributes** on that
+variable's array, and the dataset's own `attrs` become dataset-level
+attributes:
+
+```python
+ds = xr.Dataset(
+    data_vars={"temperature": xr.DataArray(arr, dims=["lat", "lon"],
+                                            attrs={"units": "C"})},
+    attrs={"station": "KNMI"},
+)
+atlas.add_xarray_dataset(ds, "jan_2024")
+
+view = atlas.open_dataset("jan_2024")
+view.attributes()                        # {"station": "KNMI"}
+view.array_attributes("temperature")     # {"units": "C"}
+```
+
+On read, `atlas.open_as_xarray_dataset("jan_2024")` puts each variable's attrs
+back on the right `DataArray` and the global attrs back on the Dataset.
+
+See [xarray integration](xarray.md) for the full storage convention.
+
+## JSON-encoded "complex" attributes
+
+xarray attribute values are sometimes nested dicts or other structures that
+don't map to atlas's on-disk types. The xarray bridge JSON-encodes those and
+prefixes the string with `json:`, decoding transparently on read. You generally
+don't need to think about this, but it's why some values come back as strings
+starting with `json:` if you read them through the raw attribute API. Simple
+lists of scalars are stored natively as typed-list attributes.

{atlas_python-0.10.0 → atlas_python-0.12.0}/atlas-python/docs/guides/datasets-and-arrays.md

@@ -4,18 +4,24 @@
 
 An [`Atlas`](../reference/atlas.md) is a directory-backed handle. It owns:
 
-1. An in-memory **`StoreMeta`** — every dataset, every array schema, every
-   attribute. Loaded once at `open`/`create`, mutated by every write,
-   persisted on `flush()`.
+1. An in-memory **`StoreMeta`** — the collection's schema: every dataset and
+   every array schema, plus the attribute-key namespace (which global and
+   per-variable attribute keys exist). Distinct dataset schemas are interned,
+   so thousands of identical schemas cost one copy. Loaded once at
+   `open`/`create`, mutated by every schema write, persisted to `atlas.json`
+   on `flush()`.
 2. A set of **array file caches** — one buffer per array name across the
-   whole store. Pending writes accumulate here until `flush()`.
+   whole store. Pending array writes accumulate here until `flush()`.
+3. A **pending-attribute buffer** — attribute *values* set via `set_attribute`
+   / `set_array_attribute`, drained into the `.af` files on `flush()`.
 
 A [`DatasetView`](../reference/dataset-view.md) is a typed handle into a
 single logical dataset. It exposes the per-dataset array schemas, the
-per-array statistics, and the per-dataset attribute dict. Mutations through
-the view (`define_array`, `write_array`, `set_attribute`, …) update the
-parent atlas's in-memory state; nothing reaches disk until you flush the
-*atlas*.
+per-array statistics, dataset-level (global) attributes, and per-variable
+attributes. Mutations through the view (`define_array`, `write_array`,
+`set_attribute`, `set_array_attribute`, …) update the parent atlas's in-memory
+state; attribute *values* live in the `.af` files, and nothing reaches disk
+until you flush the *atlas*.
 
 ```text
 Atlas ── StoreMeta (in-memory) ─┬─ DatasetView "jan_2024"
@@ -142,3 +148,40 @@ jan.delete_array("temperature")    # tombstone within this dataset
 
 The array's bytes inside the shared physical file are tombstoned; reclaim
 the space with [`atlas.compact()`](durability.md).
+
+## Merged schema and type widening
+
+`atlas.json` also carries a collection-wide **merged schema** — every unique
+array (with its dtype, dimensions, and per-variable attribute types) and every
+global attribute type, folded across all datasets. Read it with
+`atlas.merged_schema()`:
+
+```python
+merged = store.merged_schema()
+merged["arrays"]["temperature"]["dtype"]        # widened dtype across datasets
+merged["arrays"]["temperature"]["attributes"]   # {attr_key: dtype}
+merged["global_attributes"]                     # {attr_key: dtype}
+```
+
+When the same array name or attribute key appears in multiple datasets with
+different types, the merged type is **widened** — but only within numeric types
+(`int16` ∪ `int32` → `int32`, `int32` ∪ `float32` → `float64`) or between
+`string` and `timestamp` (→ `string`).
+
+Anything else can't merge (e.g. an `int32` array in one dataset and a `string`
+array under the same name in another). The dataset is **still stored** under its
+own type and reads back normally; the merged schema just keeps the
+**first-seen** type. `on_type_mismatch` decides how that's reported:
+
+```python
+# "warn" (default): stored, logs a warning, merged keeps the first type
+store = atlas.Atlas.create("/tmp/store")
+store = atlas.Atlas.open("/tmp/store")
+
+# "error": the mismatching define_array / set_attribute raises ValueError
+store = atlas.Atlas.create("/tmp/store", on_type_mismatch="error")
+store = atlas.Atlas.open("/tmp/store", on_type_mismatch="error")
+```
+
+It's a per-session choice — it isn't stored in `atlas.json`, so pass it each
+time you open the collection.

atlas_python-0.12.0/atlas-python/src/attr.rs

@@ -0,0 +1,95 @@
+use atlas::Attr;
+use pyo3::exceptions::PyValueError;
+use pyo3::prelude::*;
+use pyo3::types::{PyBool, PyBytes, PyFloat, PyInt, PyList, PyString};
+
+pub fn py_to_attr(value: &Bound<'_, PyAny>, dtype_hint: Option<&str>) -> PyResult<Attr> {
+    if let Some(hint) = dtype_hint {
+        return py_to_attr_typed(value, hint);
+    }
+
+    if let Ok(b) = value.downcast::<PyBool>() {
+        return Ok(Attr::Bool(b.is_true()));
+    }
+    if value.downcast::<PyString>().is_ok() {
+        return Ok(Attr::String(value.extract::<String>()?));
+    }
+    if value.downcast::<PyBytes>().is_ok() {
+        return Ok(Attr::Binary(value.extract::<Vec<u8>>()?));
+    }
+    if value.downcast::<PyInt>().is_ok() {
+        return Ok(Attr::Int64(value.extract::<i64>()?));
+    }
+    if value.downcast::<PyFloat>().is_ok() {
+        return Ok(Attr::Float64(value.extract::<f64>()?));
+    }
+    Err(PyValueError::new_err(format!(
+        "unsupported attribute type: {:?}",
+        value.get_type().name()?
+    )))
+}
+
+fn py_to_attr_typed(value: &Bound<'_, PyAny>, dtype: &str) -> PyResult<Attr> {
+    Ok(match dtype.to_ascii_lowercase().as_str() {
+        "bool" => Attr::Bool(value.extract()?),
+        // Width-precise integer hints so the on-disk attribute keeps its type.
+        // Python `int.extract::<T>()` raises OverflowError on overflow, which
+        // surfaces as a PyErr.
+        "i8" | "int8" => Attr::Int8(value.extract()?),
+        "i16" | "int16" => Attr::Int16(value.extract()?),
+        "i32" | "int32" => Attr::Int32(value.extract()?),
+        "i64" | "int64" => Attr::Int64(value.extract()?),
+        "u8" | "uint8" => Attr::UInt8(value.extract()?),
+        "u16" | "uint16" => Attr::UInt16(value.extract()?),
+        "u32" | "uint32" => Attr::UInt32(value.extract()?),
+        "u64" | "uint64" => Attr::UInt64(value.extract()?),
+        "f32" | "float32" => Attr::Float32(value.extract()?),
+        "f64" | "float64" => Attr::Float64(value.extract()?),
+        "string" | "str" => Attr::String(value.extract()?),
+        "binary" | "bytes" => Attr::Binary(value.extract()?),
+        "timestamp_ns" | "timestamp_nanoseconds" | "datetime64[ns]" => {
+            Attr::TimestampNanoseconds(value.extract()?)
+        }
+        other => {
+            return Err(PyValueError::new_err(format!(
+                "unknown attribute dtype: {other:?}"
+            )))
+        }
+    })
+}
+
+pub fn attr_to_py(py: Python<'_>, attr: &Attr) -> PyResult<Py<PyAny>> {
+    use pyo3::IntoPyObjectExt;
+    match attr {
+        Attr::Bool(v) => (*v).into_py_any(py),
+        Attr::Int8(v) => (*v).into_py_any(py),
+        Attr::Int16(v) => (*v).into_py_any(py),
+        Attr::Int32(v) => (*v).into_py_any(py),
+        Attr::Int64(v) => (*v).into_py_any(py),
+        Attr::UInt8(v) => (*v).into_py_any(py),
+        Attr::UInt16(v) => (*v).into_py_any(py),
+        Attr::UInt32(v) => (*v).into_py_any(py),
+        Attr::UInt64(v) => (*v).into_py_any(py),
+        Attr::Float32(v) => (*v).into_py_any(py),
+        Attr::Float64(v) => (*v).into_py_any(py),
+        Attr::String(v) => v.clone().into_py_any(py),
+        Attr::Binary(v) => PyBytes::new(py, v).into_py_any(py),
+        Attr::TimestampNanoseconds(v) => (*v).into_py_any(py),
+        Attr::BoolList(v) => PyList::new(py, v)?.into_py_any(py),
+        Attr::Int8List(v) => PyList::new(py, v)?.into_py_any(py),
+        Attr::Int16List(v) => PyList::new(py, v)?.into_py_any(py),
+        Attr::Int32List(v) => PyList::new(py, v)?.into_py_any(py),
+        Attr::Int64List(v) => PyList::new(py, v)?.into_py_any(py),
+        Attr::UInt8List(v) => PyList::new(py, v)?.into_py_any(py),
+        Attr::UInt16List(v) => PyList::new(py, v)?.into_py_any(py),
+        Attr::UInt32List(v) => PyList::new(py, v)?.into_py_any(py),
+        Attr::UInt64List(v) => PyList::new(py, v)?.into_py_any(py),
+        Attr::Float32List(v) => PyList::new(py, v)?.into_py_any(py),
+        Attr::Float64List(v) => PyList::new(py, v)?.into_py_any(py),
+        Attr::StringList(v) => PyList::new(py, v)?.into_py_any(py),
+        Attr::BinaryList(v) => {
+            let items: Vec<Bound<'_, PyBytes>> = v.iter().map(|b| PyBytes::new(py, b)).collect();
+            PyList::new(py, items)?.into_py_any(py)
+        }
+    }
+}

{atlas_python-0.10.0 → atlas_python-0.12.0}/atlas-python/src/dataset.rs

@@ -71,10 +71,13 @@ impl PyDatasetView {
             .collect()
     }
 
-    /// Returns a dict of attribute name -> Python value.
+    /// Returns a dict of dataset-level (global) attribute name -> Python value.
     fn attributes<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyDict>> {
+        let attrs = py
+            .detach(|| runtime().block_on(self.inner.attributes()))
+            .map_err(to_py_err)?;
         let dict = PyDict::new(py);
-        for (k, v) in &self.inner.meta().attributes {
+        for (k, v) in &attrs {
             dict.set_item(k, attr_to_py(py, v)?)?;
         }
         Ok(dict)
@@ -88,15 +91,58 @@ impl PyDatasetView {
         dtype: Option<&str>,
     ) -> PyResult<()> {
         let attr = py_to_attr(value, dtype)?;
-        self.inner.set_attribute(key, attr);
-        Ok(())
+        self.inner.set_attribute(key, attr).map_err(to_py_err)
     }
 
     fn get_attribute(&self, py: Python<'_>, key: &str) -> PyResult<Option<Py<PyAny>>> {
+        let attr = py
+            .detach(|| runtime().block_on(self.inner.get_attribute(key)))
+            .map_err(to_py_err)?;
+        attr.map(|attr| attr_to_py(py, &attr)).transpose()
+    }
+
+    /// Set a per-variable (per-array) attribute, e.g. `units` on `temperature`.
+    #[pyo3(signature = (array, key, value, dtype=None))]
+    fn set_array_attribute(
+        &mut self,
+        array: &str,
+        key: &str,
+        value: &Bound<'_, PyAny>,
+        dtype: Option<&str>,
+    ) -> PyResult<()> {
+        let attr = py_to_attr(value, dtype)?;
         self.inner
-            .get_attribute(key)
-            .map(|attr| attr_to_py(py, &attr))
-            .transpose()
+            .set_array_attribute(array, key, attr)
+            .map_err(to_py_err)
+    }
+
+    /// Get a per-variable attribute on `array`, or `None` if unset.
+    fn get_array_attribute(
+        &self,
+        py: Python<'_>,
+        array: &str,
+        key: &str,
+    ) -> PyResult<Option<Py<PyAny>>> {
+        let attr = py
+            .detach(|| runtime().block_on(self.inner.get_array_attribute(array, key)))
+            .map_err(to_py_err)?;
+        attr.map(|attr| attr_to_py(py, &attr)).transpose()
+    }
+
+    /// Returns a dict of per-variable attribute name -> Python value for `array`.
+    fn array_attributes<'py>(
+        &self,
+        py: Python<'py>,
+        array: &str,
+    ) -> PyResult<Bound<'py, PyDict>> {
+        let attrs = py
+            .detach(|| runtime().block_on(self.inner.array_attributes(array)))
+            .map_err(to_py_err)?;
+        let dict = PyDict::new(py);
+        for (k, v) in &attrs {
+            dict.set_item(k, attr_to_py(py, v)?)?;
+        }
+        Ok(dict)
     }
 
     /// Returns `{"dtype", "shape", "chunk_shape", "dimension_names"}` for

{atlas_python-0.10.0 → atlas_python-0.12.0}/atlas-python/src/error.rs

@@ -21,6 +21,9 @@ pub fn to_py_err(err: atlas::Error) -> PyErr {
             PyValueError::new_err(format!("invalid name: {name}"))
         }
         atlas::Error::StoreNotFound => PyFileNotFoundError::new_err("store not found at path"),
+        e @ (atlas::Error::UnsupportedVersion { .. } | atlas::Error::TypeMismatch { .. }) => {
+            PyValueError::new_err(e.to_string())
+        }
         atlas::Error::Io(e) => PyOSError::new_err(e.to_string()),
         e @ (atlas::Error::ObjectStore(_)
         | atlas::Error::ArrayFormat(_)