atlas-python 0.16.0__tar.gz → 0.16.2__tar.gz

{atlas_python-0.16.0 → atlas_python-0.16.2}/Cargo.lock

@@ -71,7 +71,7 @@ dependencies = [
 
 [[package]]
 name = "atlas-python"
-version = "0.16.0"
+version = "0.16.2"
 dependencies = [
  "atlas-rust",
  "ndarray",
@@ -86,7 +86,7 @@ dependencies = [
 
 [[package]]
 name = "atlas-rust"
-version = "0.16.0"
+version = "0.16.2"
 dependencies = [
  "array-format",
  "async-trait",

{atlas_python-0.16.0 → atlas_python-0.16.2}/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.16.0"
+version = "0.16.2"
 edition = "2024"
 description = "Single-file immutable store for thousands of N-dimensional datasets, local or on object storage."
 license = "Apache-2.0"

{atlas_python-0.16.0 → atlas_python-0.16.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atlas-python
-Version: 0.16.0
+Version: 0.16.2
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
@@ -39,11 +39,14 @@ pip install atlas-python
 ```bash
 atlas create /data/nc /data/collection
 atlas ls     /data/collection
-atlas show   /data/collection 2024-01
+atlas show   /data/collection 2024-01.nc
 atlas info   /data/collection
-atlas rm     /data/collection 2024-02 2024-03
+atlas rm     /data/collection 2024-02.nc 2024-03.nc
 ```
 
+`python -m atlas` runs the same command without a PATH lookup, for a shell that
+cannot find `atlas`.
+
 | Extra | Install | Adds |
 |---|---|---|
 | cloud | `pip install "atlas-python[cloud]"` | S3 / GCS / Azure / HTTP via [obstore](https://github.com/developmentseed/obstore) |
@@ -58,10 +61,10 @@ The same five as a library:
 import atlas
 
 atlas.create("/data/nc", "/data/collection")   # from a directory of NetCDF files
-atlas.list_datasets("/data/collection")        # ['2024-01', '2024-02', '2024-03']
-atlas.describe("/data/collection", "2024-01")  # types, shapes, attrs, statistics
+atlas.list_datasets("/data/collection")        # ['2024-01.nc', '2024-02.nc', '2024-03.nc']
+atlas.describe("/data/collection", "2024-01.nc")  # types, shapes, attrs, statistics
 atlas.info("/data/collection")                 # counts, size, codec, statistics
-atlas.remove("/data/collection", ["2024-02"])  # updates the mask
+atlas.remove("/data/collection", ["2024-02.nc"])  # updates the mask
 ```
 
 Every one takes a local path, a URL, or an obstore handle:
@@ -94,8 +97,8 @@ request.
 ## What `show` gives you
 
 ```text
-$ atlas show /data/collection 2024-01
-dataset 2024-01 {
+$ atlas show /data/collection 2024-01.nc
+dataset 2024-01.nc {
 dimensions:
 	lat = 4 ;
 	lon = 6 ;
@@ -120,8 +123,9 @@ command gives the same content as a structure.
 
 ## Ingest
 
-`create` scans a directory for `.nc`, `.nc4`, `.cdf`, and `.netcdf`. It sorts
-them, and writes one dataset per file, named after the stem. Each coordinate
+`create` scans a directory for `.nc`, `.nc4`, `.cdf`, and `.netcdf`, and
+descends into every subdirectory. It sorts them, and writes one dataset per
+file, named after the file. Each coordinate
 and data variable becomes an array. Each variable attribute becomes a per-array
 attribute. `_FillValue` becomes the fill of the array.
 
@@ -134,6 +138,13 @@ Nothing at the destination is readable until every file lands. A failure
 part-way leaves no collection, and not a partial one. `on_error="skip"`, or
 `--skip-errors`, trades that for progress.
 
+Atlas cannot store every numpy dtype, and `bool` is the common case. One such
+variable fails the whole file by default. `on_unsupported="skip"`, or
+`--skip-unsupported`, leaves out that one array and lands the rest.
+
+`--log-file PATH`, or `atlas.log_to_file(path)`, appends every error and
+warning to a file, each with its reason and the file it came from.
+
 ## dtypes
 
 | numpy | atlas |

{atlas_python-0.16.0 → atlas_python-0.16.2}/atlas-python/Cargo.toml

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

{atlas_python-0.16.0 → atlas_python-0.16.2}/atlas-python/README.md

@@ -11,11 +11,14 @@ pip install atlas-python
 ```bash
 atlas create /data/nc /data/collection
 atlas ls     /data/collection
-atlas show   /data/collection 2024-01
+atlas show   /data/collection 2024-01.nc
 atlas info   /data/collection
-atlas rm     /data/collection 2024-02 2024-03
+atlas rm     /data/collection 2024-02.nc 2024-03.nc
 ```
 
+`python -m atlas` runs the same command without a PATH lookup, for a shell that
+cannot find `atlas`.
+
 | Extra | Install | Adds |
 |---|---|---|
 | cloud | `pip install "atlas-python[cloud]"` | S3 / GCS / Azure / HTTP via [obstore](https://github.com/developmentseed/obstore) |
@@ -30,10 +33,10 @@ The same five as a library:
 import atlas
 
 atlas.create("/data/nc", "/data/collection")   # from a directory of NetCDF files
-atlas.list_datasets("/data/collection")        # ['2024-01', '2024-02', '2024-03']
-atlas.describe("/data/collection", "2024-01")  # types, shapes, attrs, statistics
+atlas.list_datasets("/data/collection")        # ['2024-01.nc', '2024-02.nc', '2024-03.nc']
+atlas.describe("/data/collection", "2024-01.nc")  # types, shapes, attrs, statistics
 atlas.info("/data/collection")                 # counts, size, codec, statistics
-atlas.remove("/data/collection", ["2024-02"])  # updates the mask
+atlas.remove("/data/collection", ["2024-02.nc"])  # updates the mask
 ```
 
 Every one takes a local path, a URL, or an obstore handle:
@@ -66,8 +69,8 @@ request.
 ## What `show` gives you
 
 ```text
-$ atlas show /data/collection 2024-01
-dataset 2024-01 {
+$ atlas show /data/collection 2024-01.nc
+dataset 2024-01.nc {
 dimensions:
 	lat = 4 ;
 	lon = 6 ;
@@ -92,8 +95,9 @@ command gives the same content as a structure.
 
 ## Ingest
 
-`create` scans a directory for `.nc`, `.nc4`, `.cdf`, and `.netcdf`. It sorts
-them, and writes one dataset per file, named after the stem. Each coordinate
+`create` scans a directory for `.nc`, `.nc4`, `.cdf`, and `.netcdf`, and
+descends into every subdirectory. It sorts them, and writes one dataset per
+file, named after the file. Each coordinate
 and data variable becomes an array. Each variable attribute becomes a per-array
 attribute. `_FillValue` becomes the fill of the array.
 
@@ -106,6 +110,13 @@ Nothing at the destination is readable until every file lands. A failure
 part-way leaves no collection, and not a partial one. `on_error="skip"`, or
 `--skip-errors`, trades that for progress.
 
+Atlas cannot store every numpy dtype, and `bool` is the common case. One such
+variable fails the whole file by default. `on_unsupported="skip"`, or
+`--skip-unsupported`, leaves out that one array and lands the rest.
+
+`--log-file PATH`, or `atlas.log_to_file(path)`, appends every error and
+warning to a file, each with its reason and the file it came from.
+
 ## dtypes
 
 | numpy | atlas |

{atlas_python-0.16.0 → atlas_python-0.16.2}/atlas-python/docs/cli.md

@@ -3,6 +3,10 @@
 `pip install atlas-python` puts `atlas` on your PATH. Five subcommands, one per
 operation.
 
+`python -m atlas` runs the same command without a PATH lookup. Use it in a
+container, in a CI job, or when the shell cannot find `atlas`. See
+[Installation](installation.md#the-atlas-command-is-not-found).
+
 ```text
 atlas create <netcdf-dir> <collection>   build a collection
 atlas rm     <collection> <name>...      remove datasets
@@ -16,8 +20,27 @@ A `<collection>` is a local path or a URL: `s3://bucket/prefix`, `gs://...`,
 `pip install "atlas-python[cloud]"`. See
 [Cloud storage](guides/cloud-storage.md).
 
-Every subcommand takes `--json`, and the remote flags `--region`,
-`--endpoint`, and `--anonymous`.
+Every subcommand takes `--json` and `--log-file PATH`, plus the remote flags
+`--region`, `--endpoint`, and `--anonymous`.
+
+## Logging
+
+`--log-file PATH` appends every error and warning to a file, with the reason:
+
+```bash
+$ atlas create /data/nc /data/collection --skip-unsupported --log-file ingest.log
+$ cat ingest.log
+2026-09-01 14:30:41 INFO    atlas.cli: atlas 0.16.2: create /data/nc ...
+2026-09-01 14:30:41 INFO    atlas.ops: ingesting 2 file(s) into /data/collection
+2026-09-01 14:30:41 WARNING atlas.ops: /data/nc/buoy.nc: skipped array 'flag' of dtype bool: numpy dtype dtype('bool') is not supported by atlas (supported: ...)
+2026-09-01 14:30:41 INFO    atlas.ops: wrote 1 dataset(s); skipped 0 file(s) and 1 array(s)
+```
+
+The file opens in append mode. Each line names the file it came from, so a
+large ingest stays readable.
+
+This is separate from `ATLAS_LOG`, which turns on the Rust `tracing` stream to
+stderr.
 
 ## create
 
@@ -25,25 +48,51 @@ Every subcommand takes `--json`, and the remote flags `--region`,
 atlas create /data/nc /data/collection
 ```
 
-Each NetCDF file becomes one dataset, named after its stem. `2024-01.nc`
-becomes `2024-01`. The files land in sorted order, which makes the ordinals of
-a collection reproducible.
+The scan descends into every subdirectory. Each NetCDF file becomes one
+dataset, named after the file. `2024-01.nc` becomes `2024-01.nc`, suffix and
+all. A name carries no directory, so two files of one name in two
+subdirectories collide. The files land in sorted order, which makes the
+ordinals of a collection reproducible.
 
 Nothing at the destination is readable until every file lands, with the footer.
 A failure part-way leaves no collection, and not a partial one.
 
 | Flag | Effect |
 |---|---|
-| `-r`, `--recursive` | Descend into subdirectories |
+| `--no-recursive` | Scan the top directory alone. The scan descends by default |
+| `-r`, `--recursive` | Accepted for compatibility. The scan already descends |
 | `--codec {zstd,lz4,none}` | Block compression. Default `zstd` |
 | `--chunk-size SIZE` | Block size to aim for. Default `128MiB` |
 | `--open-chunks MODE` | How files are read: `auto`, `native`, `none`, or a JSON dict |
 | `--chunks JSON` | Override the stored chunk shape, `'{"temperature": [64, 64]}'` |
 | `--skip-errors` | Skip files that fail instead of abandoning the collection |
+| `--skip-unsupported` | Leave out an array of an unsupported dtype, and keep the rest of the dataset |
 | `-q`, `--quiet` | Do not list a file as it lands |
 
 Progress goes to stderr, so a pipe still reads stdout.
 
+### Unsupported dtypes
+
+Atlas cannot store every numpy dtype. `bool` is the common case. By default one
+such variable fails the whole file:
+
+```bash
+$ atlas create /data/nc /data/collection
+atlas: /data/nc/buoy.nc: numpy dtype dtype('bool') is not supported by atlas ...
+```
+
+`--skip-unsupported` narrows that to the one array:
+
+```bash
+$ atlas create /data/nc /data/collection --skip-unsupported
+  skipped array buoy/flag (bool)
+1 dataset(s) written to /data/collection
+```
+
+Every other array of that dataset lands, with its attributes. `--json` reports
+the skipped arrays under `skipped_arrays`, with the dataset, the dtype, and the
+reason. See [Supported dtypes](guides/dtypes.md).
+
 ### Large files
 
 Each file reads in dask blocks. A file far larger than memory therefore
@@ -79,7 +128,7 @@ reads. Each misaligned block then costs a read-modify-write. Use
 
 ```bash
 # One collection from a tree of monthly directories, tolerating bad files
-atlas create /data/nc /data/collection --recursive --skip-errors
+atlas create /data/nc /data/collection --skip-errors
 
 # A big grid, chunked for selective reads, straight to a bucket
 atlas create /data/nc s3://bucket/2024 --chunk-size 64MiB --region eu-west-1
@@ -88,7 +137,7 @@ atlas create /data/nc s3://bucket/2024 --chunk-size 64MiB --region eu-west-1
 ## rm
 
 ```bash
-atlas rm /data/collection 2024-02 2024-03
+atlas rm /data/collection 2024-02.nc 2024-03.nc
 ```
 
 This removes several datasets in one call. A name is a dataset name, or the
@@ -114,9 +163,9 @@ error.
 
 ```bash
 $ atlas ls /data/collection
-2024-01
-2024-02
-2024-03
+2024-01.nc
+2024-02.nc
+2024-03.nc
 ```
 
 One name per line, in write order. A removed dataset does not appear. This
@@ -131,8 +180,8 @@ atlas ls /data/collection --json | jq .    # as a JSON array
 ## show
 
 ```bash
-$ atlas show /data/collection 2024-01
-dataset 2024-01 {
+$ atlas show /data/collection 2024-01.nc
+dataset 2024-01.nc {
 dimensions:
 	lat = 4 ;
 	lon = 6 ;

{atlas_python-0.16.0 → atlas_python-0.16.2}/atlas-python/docs/examples.md

@@ -19,8 +19,8 @@ python atlas-python/examples/01_library.py
 atlas create /data/nc /data/collection
 atlas ls     /data/collection
 atlas info   /data/collection
-atlas show   /data/collection 2024-01
-atlas rm     /data/collection 2024-02 2024-03
+atlas show   /data/collection 2024-01.nc
+atlas rm     /data/collection 2024-02.nc 2024-03.nc
 ```
 
 See [The `atlas` command](cli.md).

{atlas_python-0.16.0 → atlas_python-0.16.2}/atlas-python/docs/guides/cloud-storage.md

@@ -51,8 +51,8 @@ store = obs.store.S3Store(
 
 atlas.create("/data/nc", store)
 atlas.list_datasets(store)
-atlas.describe(store, "2024-01")
-atlas.remove(store, ["2024-02"])
+atlas.describe(store, "2024-01.nc")
+atlas.remove(store, ["2024-02.nc"])
 atlas.info(store)
 ```
 

{atlas_python-0.16.0 → atlas_python-0.16.2}/atlas-python/docs/guides/creating.md

@@ -15,8 +15,20 @@ atlas create /data/nc /data/collection
 ## What happens
 
 `create` collects every file that matches `.nc`, `.nc4`, `.cdf`, or `.netcdf`.
-It **sorts** them, and writes one dataset per file, named after the file stem.
-`2024-01.nc` becomes the dataset `2024-01`.
+The scan **descends into every subdirectory**. It **sorts** the result, and
+writes one dataset per file, named after the file. `2024-01.nc` becomes the
+dataset `2024-01.nc`. The suffix is part of the name, so `jan.nc` and
+`jan.nc4` are two datasets.
+
+Pass `recursive=False`, or `--no-recursive`, to scan the top directory alone:
+
+```python
+atlas.create("/data/nc", dest, recursive=False)
+```
+
+```bash
+atlas create /data/nc /data/collection --no-recursive
+```
 
 The sort matters. An ordinal comes from the write order, so a sorted ingest
 makes it reproducible. Rebuild the same directory, and every dataset lands at
@@ -25,8 +37,8 @@ the same position.
 Check what the call picks up before you run it:
 
 ```python
-atlas.find_netcdf_files("/data/nc")             # sorted list of paths
-atlas.find_netcdf_files("/data/nc", recursive=True)
+atlas.find_netcdf_files("/data/nc")                  # sorted, and recursive
+atlas.find_netcdf_files("/data/nc", recursive=False)  # the top level alone
 ```
 
 ## All or nothing
@@ -39,7 +51,7 @@ That is what you usually want. When it is not:
 
 ```python
 result = atlas.create("/data/nc", dest, on_error="skip")
-result["written"]   # ['2024-01', '2024-03']
+result["written"]   # ['2024-01.nc', '2024-03.nc']
 result["skipped"]   # [{'file': '.../2024-02.nc', 'error': '...'}]
 ```
 
@@ -51,6 +63,78 @@ A skipped file leaves no trace in the collection. The writer moves to the next
 one. The CLI exits `1` when it skipped anything, so a pipeline sees that. It
 still writes the collection.
 
+## One bad array, not one bad file
+
+`on_error` works at the granularity of a file. One variable of an unsupported
+dtype therefore costs the whole dataset. `on_unsupported="skip"` narrows that
+to the array:
+
+```python
+result = atlas.create("/data/nc", dest, on_unsupported="skip")
+result["skipped_arrays"]
+# [{'array': 'flag', 'dtype': 'bool', 'error': '...', 'dataset': '2024-01.nc'}]
+```
+
+```bash
+atlas create /data/nc /data/collection --skip-unsupported
+```
+
+The rest of the dataset lands as usual: every other array, every attribute,
+and the dataset itself. The skipped name is absent from the schema, so no
+empty array stands in for it.
+
+Atlas resolves every dtype before it defines the first array. A skip therefore
+never leaves a half-written array behind.
+
+The two settings compose. `--skip-unsupported` handles the array atlas cannot
+store. `--skip-errors` handles the file that fails for any other reason.
+
+See [Supported dtypes](dtypes.md) for what atlas can store.
+
+## The log file
+
+Both kinds of skip go to a log file, with the reason:
+
+```bash
+atlas create /data/nc /data/collection --skip-unsupported --log-file ingest.log
+```
+
+```text
+2026-09-01 14:30:41 INFO    atlas.ops: ingesting 2 file(s) into /data/collection
+2026-09-01 14:30:41 WARNING atlas.ops: /data/nc/broken.nc: ValueError: did not find a match ...
+2026-09-01 14:30:41 WARNING atlas.ops: /data/nc/buoy.nc: skipped array 'flag' of dtype bool: numpy dtype dtype('bool') is not supported by atlas (supported: ...)
+2026-09-01 14:30:41 INFO    atlas.ops: wrote 1 dataset(s); skipped 1 file(s) and 1 array(s)
+```
+
+Each line names the file, so a thousand-file ingest stays readable. The file
+opens in append mode, so a repeat run adds to it.
+
+From the library:
+
+```python
+import atlas
+
+atlas.log_to_file("ingest.log")
+atlas.create("/data/nc", dest, on_unsupported="skip")
+```
+
+Atlas logs to the `atlas` logger and attaches no handler of its own, so attach
+your own to send the records somewhere else:
+
+```python
+import logging
+
+logging.getLogger("atlas").addHandler(logging.StreamHandler())
+logging.getLogger("atlas").setLevel(logging.INFO)
+```
+
+`log_to_file` also captures Python warnings, such as the one about missing
+string cells. That moves them off stderr, because `logging.captureWarnings` is
+process-wide.
+
+The Rust core logs separately, through `tracing`. `atlas.init_tracing()` sends
+that stream to stderr. See [Installation](../installation.md).
+
 ## Chunking and memory
 
 These are one decision. The blocks a file *reads* in are the chunks it
@@ -114,12 +198,12 @@ alone. A one-chunk array reads whole, or not at all.
 Confirm what landed:
 
 ```python
-arrays = {a["name"]: a for a in atlas.describe(dest, "2024-01")["arrays"]}
+arrays = {a["name"]: a for a in atlas.describe(dest, "2024-01.nc")["arrays"]}
 arrays["temperature"]["chunk_shape"]
 ```
 
 ```bash
-atlas show dest 2024-01 | grep _ChunkShape
+atlas show dest 2024-01.nc | grep _ChunkShape
 ```
 
 ### The writer's own memory
@@ -157,12 +241,19 @@ turns it off.
 | Situation | Result |
 |---|---|
 | Directory holds no NetCDF files | `AtlasError` |
-| Two files share a stem | `AtlasError`. A dataset name must be unique |
-| A variable has a dtype atlas cannot store | `AtlasError` (or skipped) |
+| Two files share a name | `AtlasError`. A dataset name must be unique |
+| A variable has a dtype atlas cannot store | `AtlasError`, or one skipped array under `--skip-unsupported` |
+| Any other bad file | `AtlasError`, or one skipped file under `--skip-errors` |
 | Destination URL cannot be resolved | `SourceError` |
 
-Two files with one stem surprise people. `a/jan.nc` and `b/jan.nc` both want
-the name `jan`. Rename one, or ingest them into two collections.
+Two files with one name surprise people. `a/jan.nc` and `b/jan.nc` both want
+the name `jan.nc`. The scan descends by default, so a tree of monthly
+directories hits this often. A dataset name carries no directory, because a
+name may hold no `/`.
+
+Three ways out. Rename the files. Ingest each subdirectory into its own
+collection. Or pass `on_error="skip"`, which keeps the first file and reports
+the second.
 
 For the dtype rules, see [Supported dtypes](dtypes.md).
 

{atlas_python-0.16.0 → atlas_python-0.16.2}/atlas-python/docs/guides/dtypes.md

@@ -62,7 +62,7 @@ fill of the array, and not as an attribute.
 Check what landed:
 
 ```python
-arrays = {a["name"]: a for a in atlas.describe(collection, "2024-01")["arrays"]}
+arrays = {a["name"]: a for a in atlas.describe(collection, "2024-01.nc")["arrays"]}
 arrays["temperature"]["fill_value"]
 ```
 
@@ -86,7 +86,10 @@ array data, not to the attributes. They come through unchanged:
 | `list[...]`, `fixed_size_list[..., N]` | Not exposed yet |
 
 A NetCDF file with a boolean variable fails the ingest. Store it as `uint8`,
-and write the convention down.
+and write the convention down. To keep the rest of that file, pass
+`--skip-unsupported`, or `on_unsupported="skip"`. That leaves out the one array
+and lands everything else. See
+[Creating a collection](creating.md#one-bad-array-not-one-bad-file).
 
 All four work as an **attribute** value, which is where they usually appear.
 
@@ -100,7 +103,7 @@ Some xarray attributes are no scalar. A nested dict, a ragged list, and a numpy
 array each encode as JSON on the way in. `describe` decodes them again:
 
 ```python
-atlas.describe(collection, "2024-01")["attributes"]
+atlas.describe(collection, "2024-01.nc")["attributes"]
 # {'month': 1, 'bounds': [1.0, 2.0], 'nested': {'a': 1}}
 ```
 

{atlas_python-0.16.0 → atlas_python-0.16.2}/atlas-python/docs/guides/inspecting.md

@@ -7,7 +7,7 @@ fetches array data, so a catalogue of ten thousand datasets costs one request.
 
 ```python
 atlas.list_datasets("/data/collection")
-# ['2024-01', '2024-02', '2024-03']
+# ['2024-01.nc', '2024-02.nc', '2024-03.nc']
 ```
 
 ```bash
@@ -63,11 +63,11 @@ Use `describe` for the statistics of one dataset on its own.
 ## One dataset in detail: `describe` and `show`
 
 ```python
-atlas.describe("/data/collection", "2024-01")
+atlas.describe("/data/collection", "2024-01.nc")
 ```
 
 ```bash
-atlas show /data/collection 2024-01
+atlas show /data/collection 2024-01.nc
 ```
 
 The CLI prints it like `ncdump -h`. The library returns the structure. Both
@@ -78,7 +78,7 @@ attributes, the coordinate flag, and the statistics.
 `name` is a dataset name, or the NetCDF path the dataset came from:
 
 ```python
-atlas.describe(collection, "/data/nc/2024-01.nc")   # same as "2024-01"
+atlas.describe(collection, "/data/nc/2024-01.nc")   # same as "2024-01.nc"
 ```
 
 ### Statistics
@@ -117,7 +117,7 @@ The ingest records which variables were xarray coordinates, and reports them
 back:
 
 ```python
-detail = atlas.describe(collection, "2024-01")
+detail = atlas.describe(collection, "2024-01.nc")
 detail["coordinates"]              # ['lat', 'lon']
 [a["name"] for a in detail["arrays"] if a["is_coordinate"]]
 ```

{atlas_python-0.16.0 → atlas_python-0.16.2}/atlas-python/docs/guides/reading-data.md

@@ -4,10 +4,10 @@ Python reads the **metadata** of a collection. It reads no array value.
 
 ```python
 atlas.list_datasets(collection)            # ✓
-atlas.describe(collection, "jan")          # ✓  types, shapes, attrs, stats
+atlas.describe(collection, "jan.nc")       # ✓  types, shapes, attrs, stats
 atlas.info(collection)                     # ✓  counts, size, collection stats
 
-atlas.read_array(collection, "jan", "t")   # ✗ does not exist
+atlas.read_array(collection, "jan.nc", "t")  # ✗ does not exist
 ```
 
 ## Why
@@ -27,7 +27,7 @@ It is enough to build a catalogue, to check an ingest, or to choose the
 datasets worth a fetch:
 
 ```python
-detail = atlas.describe(collection, "2024-01")
+detail = atlas.describe(collection, "2024-01.nc")
 
 detail["dimensions"]     # {'lat': 4, 'lon': 6}
 detail["coordinates"]    # ['lat', 'lon']
@@ -99,7 +99,7 @@ simpler than anything else here.
 reader opens it:
 
 ```python
-start, end = atlas.describe(collection, "2024-01")["segment_range"]
+start, end = atlas.describe(collection, "2024-01.nc")["segment_range"]
 blob = open(f"{collection}/data.atlas", "rb").read()[start:end]
 open("2024-01.af", "wb").write(blob)
 ```

{atlas_python-0.16.0 → atlas_python-0.16.2}/atlas-python/docs/guides/removing.md

@@ -1,11 +1,11 @@
 # Removing datasets
 
 ```python
-atlas.remove("/data/collection", ["2024-02", "2024-03"])
+atlas.remove("/data/collection", ["2024-02.nc", "2024-03.nc"])
 ```
 
 ```bash
-atlas rm /data/collection 2024-02 2024-03
+atlas rm /data/collection 2024-02.nc 2024-03.nc
 ```
 
 One call, whatever the number of datasets. A name is a dataset name, or the
@@ -66,7 +66,7 @@ mask holds a sorted set of ordinals.
 The same holds on the command line, up to the argument limit of your shell:
 
 ```bash
-atlas rm /data/collection 2024-01 2024-02 2024-03
+atlas rm /data/collection 2024-01.nc 2024-02.nc 2024-03.nc
 ```
 
 For a list too long for one command line, call `atlas.remove` from Python.
@@ -83,8 +83,8 @@ atlas.remove(collection, ["nope"])
 `missing_ok` reports it instead:
 
 ```python
-result = atlas.remove(collection, ["2024-01", "nope"], missing_ok=True)
-result["removed"]   # ['2024-01']
+result = atlas.remove(collection, ["2024-01.nc", "nope"], missing_ok=True)
+result["removed"]   # ['2024-01.nc']
 result["missing"]   # ['nope']
 ```
 

{atlas_python-0.16.0 → atlas_python-0.16.2}/atlas-python/docs/index.md

@@ -10,9 +10,9 @@ atlas create /data/nc /data/collection
 
 ```text
 $ atlas ls /data/collection
-2024-01
-2024-02
-2024-03
+2024-01.nc
+2024-02.nc
+2024-03.nc
 ```
 
 ## The shape of it
@@ -60,8 +60,8 @@ atlas.list_datasets("s3://bucket/2024", region="eu-west-1")
 ## What `show` gives you
 
 ```text
-$ atlas show /data/collection 2024-01
-dataset 2024-01 {
+$ atlas show /data/collection 2024-01.nc
+dataset 2024-01.nc {
 dimensions:
 	lat = 4 ;
 	lon = 6 ;