atlas-python 0.16.1__tar.gz → 0.16.3__tar.gz

{atlas_python-0.16.1 → atlas_python-0.16.3}/Cargo.lock

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

{atlas_python-0.16.1 → atlas_python-0.16.3}/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.1"
+version = "0.16.3"
 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.1 → atlas_python-0.16.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atlas-python
-Version: 0.16.1
+Version: 0.16.3
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
@@ -44,6 +44,9 @@ atlas info   /data/collection
 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) |
@@ -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 file. 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.
 

{atlas_python-0.16.1 → atlas_python-0.16.3}/atlas-python/Cargo.toml

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

{atlas_python-0.16.1 → atlas_python-0.16.3}/atlas-python/README.md

@@ -16,6 +16,9 @@ atlas info   /data/collection
 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) |
@@ -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 file. 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.
 

{atlas_python-0.16.1 → atlas_python-0.16.3}/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
@@ -26,7 +30,7 @@ Every subcommand takes `--json` and `--log-file PATH`, plus the remote flags
 ```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.1: create /data/nc ...
+2026-09-01 14:30:41 INFO    atlas.cli: atlas 0.16.3: 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)
@@ -44,21 +48,25 @@ stderr.
 atlas create /data/nc /data/collection
 ```
 
-Each NetCDF file becomes one dataset, named after the file. `2024-01.nc`
-becomes `2024-01.nc`, suffix and all. 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 |
+| `--no-decode-times` | Keep a time axis as raw numbers, for a calendar that decodes to cftime |
 | `--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 |
 
@@ -121,7 +129,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

{atlas_python-0.16.1 → atlas_python-0.16.3}/atlas-python/docs/guides/creating.md

@@ -15,9 +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.
-`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.
+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
@@ -26,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
@@ -236,7 +247,13 @@ turns it off.
 | Destination URL cannot be resolved | `SourceError` |
 
 Two files with one name surprise people. `a/jan.nc` and `b/jan.nc` both want
-the name `jan.nc`. Rename one, or ingest them into two collections.
+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.1 → atlas_python-0.16.3}/atlas-python/docs/guides/dtypes.md

@@ -17,6 +17,71 @@ What a NetCDF variable becomes when `atlas create` ingests it.
 `atlas show` prints the atlas name, so a `datetime64[ns]` variable appears as
 `timestamp_nanoseconds`.
 
+### Calendars that decode to cftime
+
+xarray decodes a time axis to `datetime64[ns]` only when the calendar allows
+it. A Julian, `360_day`, or `noleap` calendar, or a date outside the
+`datetime64[ns]` range, decodes to a `cftime` object instead. Those arrive as
+a numpy `object` array, and atlas cannot store one:
+
+```text
+atlas: profile.nc: variable 'JULD' holds cftime objects (DatetimeJulian),
+which atlas cannot store...
+```
+
+Atlas refuses by default rather than guess, because two conversions exist and
+they differ by 13 days. Pick one.
+
+**Convert to the exact instant.** This is almost always what you want:
+
+```bash
+atlas create /data/nc /data/collection --convert-calendar
+```
+
+```python
+atlas.create("/data/nc", dest, convert_calendar=True)
+```
+
+The axis becomes `timestamp_nanoseconds`, and every value keeps the moment it
+named. A Julian `1973-02-25 18:15` becomes the Gregorian `1973-03-10 18:15`.
+Those are one instant under two calendars. cftime maps between them through
+the Julian Day, so nothing is approximated.
+
+**Keep the raw numbers.** The axis stores as an integer, with its `units` and
+`calendar` attributes beside it. A reader decodes it later with
+`cftime.num2date`:
+
+```bash
+atlas create /data/nc /data/collection --no-decode-times
+```
+
+**Drop the axis.** `--skip-unsupported` leaves the time array out, and keeps
+the rest of the dataset.
+
+#### Two conversions, 13 days apart
+
+The Julian calendar takes a leap year every four years. The Gregorian calendar
+drops three of those every four centuries. The gap grows by about three days
+per 400 years, and holds at 13 days from 1900 to 2100.
+
+| Conversion | Julian 2024-01-01 becomes | It keeps |
+|---|---|---|
+| `--convert-calendar` | 2024-01-14 | the instant |
+| `xr.Dataset.convert_calendar("standard")` | 2024-01-01 | the labels |
+
+The xarray method keeps the year, month, and day, which moves the moment by 13
+days. Use it only when the labels matter more than the instant.
+
+#### Two limits
+
+**An artificial calendar names no instant.** A `360_day`, `noleap`, or
+`all_leap` year is a model convention with no place on a real timeline.
+`--convert-calendar` raises for one. Use `--no-decode-times` instead.
+
+**A nanosecond timestamp spans 1677-09-21 to 2262-04-11.** A date outside that
+raises. numpy wraps such a date in silence, so atlas checks every value before
+it stores one.
+
 ### datetime and timedelta
 
 Atlas supports the `[ns]` resolution of `datetime64` alone. It rejects every

{atlas_python-0.16.1 → atlas_python-0.16.3}/atlas-python/docs/installation.md

@@ -47,6 +47,47 @@ To run the test suite:
 pytest atlas-python/tests/ -v
 ```
 
+## The `atlas` command is not found
+
+`pip install` puts the `atlas` script in the script directory of the
+environment it installed into. The shell finds it only when that directory is
+on `PATH`.
+
+Run the command through Python instead. This form needs no `PATH` entry, so it
+works everywhere the package imports:
+
+```bash
+python -m atlas --version
+python -m atlas ls /data/collection
+```
+
+To fix the `PATH` itself, first find where the script landed:
+
+```bash
+pip show -f atlas-python | grep -i bin
+python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
+```
+
+Three causes cover almost every case:
+
+- **`pip install --user`.** The script goes to `~/.local/bin`. Many
+  distributions leave that off `PATH`. Add it:
+  `export PATH="$HOME/.local/bin:$PATH"`.
+- **A virtual environment nobody activated.** Run `source .venv/bin/activate`,
+  or call `.venv/bin/atlas` directly.
+- **Two Pythons.** `pip` and `python` resolve to different environments. Use
+  `python -m pip install atlas-python` to install into the interpreter you
+  actually run.
+
+Confirm the package itself is sound:
+
+```bash
+python -c "import atlas; print(atlas.__version__, atlas.__file__)"
+```
+
+A version and a path mean the install worked, and only the script lookup
+failed.
+
 ## Optional: cloud storage (S3, GCS, Azure)
 
 Install the `cloud` extra to open or create an atlas store on S3, GCS, Azure

{atlas_python-0.16.1 → atlas_python-0.16.3}/atlas-python/src/writer.rs

@@ -322,7 +322,7 @@ impl PyDatasetWriter {
                     String::from_utf8_lossy(&b).into_owned()
                 } else {
                     return Err(PyTypeError::new_err(format!(
-                        "string array element must be str or bytes, got {:?}",
+                        "array {name:?}: a string element must be str or bytes, got {:?}",
                         bound.get_type().name()?
                     )));
                 };

{atlas_python-0.16.1 → atlas_python-0.16.3}/atlas-python/tests/test_cli.py

@@ -165,6 +165,27 @@ def test_log_file_records_a_failure(capsys, tmp_path):
     assert "ERROR" in log.read_text()
 
 
+def test_create_descends_by_default_and_no_recursive_opts_out(capsys, tmp_path):
+    from conftest import make_dataset
+
+    src = tmp_path / "nc"
+    (src / "sub").mkdir(parents=True)
+    make_dataset(1).to_netcdf(src / "sub" / "deep.nc")
+    make_dataset(2).to_netcdf(src / "top.nc")
+
+    run(capsys, "create", str(src), str(tmp_path / "all"), "-q")
+    code, out, _ = run(capsys, "ls", str(tmp_path / "all"))
+    assert out.split() == ["deep.nc", "top.nc"]
+
+    run(capsys, "create", str(src), str(tmp_path / "flat"), "-q", "--no-recursive")
+    code, out, _ = run(capsys, "ls", str(tmp_path / "flat"))
+    assert out.split() == ["top.nc"]
+
+    # -r still parses, so an existing script keeps working.
+    code, _, err = run(capsys, "create", str(src), str(tmp_path / "r"), "-q", "-r")
+    assert code == 0, err
+
+
 # ── ls ───────────────────────────────────────────────────────────────
 
 
@@ -307,6 +328,41 @@ def test_info_json(capsys, collection):
     assert i["format_version"] == 1
 
 
+# ── entry points ─────────────────────────────────────────────────────
+
+
+def test_python_dash_m_atlas_runs_the_cli(netcdf_dir, tmp_path):
+    """`python -m atlas` needs no directory on PATH, so it always works."""
+    import subprocess
+    import sys
+
+    dest = tmp_path / "c"
+    done = subprocess.run(
+        [sys.executable, "-m", "atlas", "create", str(netcdf_dir), str(dest), "-q"],
+        capture_output=True,
+        text=True,
+    )
+    assert done.returncode == 0, done.stderr
+
+    done = subprocess.run(
+        [sys.executable, "-m", "atlas", "ls", str(dest)],
+        capture_output=True,
+        text=True,
+    )
+    assert done.returncode == 0, done.stderr
+    assert done.stdout.split() == ["2024-01.nc", "2024-02.nc", "2024-03.nc"]
+
+
+def test_the_console_script_is_declared():
+    """The wheel must carry the `atlas` console script."""
+    from importlib.metadata import entry_points
+
+    scripts = {
+        e.name: e.value for e in entry_points(group="console_scripts")
+    }
+    assert scripts.get("atlas") == "atlas._cli:main"
+
+
 # ── parsing ──────────────────────────────────────────────────────────
 
 

{atlas_python-0.16.1 → atlas_python-0.16.3}/atlas-python/tests/test_ops.py

@@ -48,33 +48,34 @@ def test_create_is_ordered_by_filename(netcdf_dir, tmp_path):
         )
 
 
-def test_create_finds_files_recursively_when_asked(tmp_path):
+def test_create_descends_into_subdirectories_by_default(tmp_path):
     nested = tmp_path / "nc" / "2024" / "q1"
     nested.mkdir(parents=True)
     make_dataset(1).to_netcdf(nested / "jan.nc")
+    make_dataset(2).to_netcdf(tmp_path / "nc" / "top.nc")
 
-    flat = atlas.find_netcdf_files(tmp_path / "nc")
-    assert flat == []
+    found = atlas.find_netcdf_files(tmp_path / "nc")
+    assert [p.name for p in found] == ["jan.nc", "top.nc"]
 
-    found = atlas.find_netcdf_files(tmp_path / "nc", recursive=True)
-    assert [p.name for p in found] == ["jan.nc"]
+    atlas.create(tmp_path / "nc", str(tmp_path / "c"))
+    assert atlas.list_datasets(str(tmp_path / "c")) == ["jan.nc", "top.nc"]
 
-    atlas.create(tmp_path / "nc", str(tmp_path / "c"), recursive=True)
-    assert atlas.list_datasets(str(tmp_path / "c")) == ["jan.nc"]
 
+def test_recursive_false_scans_the_top_directory_alone(tmp_path):
+    nested = tmp_path / "nc" / "2024" / "q1"
+    nested.mkdir(parents=True)
+    make_dataset(1).to_netcdf(nested / "jan.nc")
+    make_dataset(2).to_netcdf(tmp_path / "nc" / "top.nc")
 
-def test_an_empty_directory_is_an_error(tmp_path):
-    (tmp_path / "empty").mkdir()
-    with pytest.raises(atlas.AtlasError, match="no NetCDF files"):
-        atlas.create(tmp_path / "empty", str(tmp_path / "c"))
-
+    found = atlas.find_netcdf_files(tmp_path / "nc", recursive=False)
+    assert [p.name for p in found] == ["top.nc"]
 
-def test_a_missing_directory_is_an_error(tmp_path):
-    with pytest.raises(atlas.AtlasError, match="not a directory"):
-        atlas.create(tmp_path / "nope", str(tmp_path / "c"))
+    atlas.create(tmp_path / "nc", str(tmp_path / "c"), recursive=False)
+    assert atlas.list_datasets(str(tmp_path / "c")) == ["top.nc"]
 
 
-def test_two_files_with_the_same_name_collide(tmp_path):
+def test_a_name_repeated_across_subdirectories_collides(tmp_path):
+    """A dataset name carries no directory, so two `jan.nc` files clash."""
     src = tmp_path / "nc"
     (src / "a").mkdir(parents=True)
     (src / "b").mkdir()
@@ -82,7 +83,24 @@ def test_two_files_with_the_same_name_collide(tmp_path):
     make_dataset(2).to_netcdf(src / "b" / "jan.nc")
 
     with pytest.raises(atlas.AtlasError, match="duplicate dataset name"):
-        atlas.create(src, str(tmp_path / "c"), recursive=True)
+        atlas.create(src, str(tmp_path / "c"))
+
+    # on_error="skip" keeps the first and reports the second.
+    result = atlas.create(src, str(tmp_path / "c2"), on_error="skip")
+    assert result["written"] == ["jan.nc"]
+    assert len(result["skipped"]) == 1
+    assert "duplicate dataset name" in result["skipped"][0]["error"]
+
+
+def test_an_empty_directory_is_an_error(tmp_path):
+    (tmp_path / "empty").mkdir()
+    with pytest.raises(atlas.AtlasError, match="no NetCDF files"):
+        atlas.create(tmp_path / "empty", str(tmp_path / "c"))
+
+
+def test_a_missing_directory_is_an_error(tmp_path):
+    with pytest.raises(atlas.AtlasError, match="not a directory"):
+        atlas.create(tmp_path / "nope", str(tmp_path / "c"))
 
 
 def test_a_bad_file_abandons_the_collection_by_default(tmp_path):
@@ -197,6 +215,151 @@ def test_a_clean_ingest_reports_no_skipped_arrays(netcdf_dir, tmp_path):
     assert result["skipped_arrays"] == []
 
 
+# ── cftime calendars ─────────────────────────────────────────────────
+
+
+@pytest.fixture
+def netcdf_dir_with_a_julian_calendar(tmp_path):
+    """A time axis xarray decodes to cftime, not to datetime64."""
+    import cftime
+
+    d = tmp_path / "nc"
+    d.mkdir()
+    times = [cftime.DatetimeJulian(2024, 1, i + 1) for i in range(4)]
+    xr.Dataset(
+        {"temp": ("time", np.arange(4, dtype=np.float32))},
+        coords={"time": ("time", times)},
+    ).to_netcdf(d / "julian.nc")
+    return d
+
+
+def test_a_cftime_axis_reports_the_variable_and_the_remedy(
+    netcdf_dir_with_a_julian_calendar, tmp_path
+):
+    with pytest.raises(atlas.AtlasError) as exc:
+        atlas.create(netcdf_dir_with_a_julian_calendar, str(tmp_path / "c"))
+
+    message = str(exc.value)
+    assert "'time'" in message, "the message must name the variable"
+    assert "DatetimeJulian" in message
+    assert "decode_times=False" in message
+
+
+def test_decode_times_false_stores_a_cftime_axis_as_raw_numbers(
+    netcdf_dir_with_a_julian_calendar, tmp_path
+):
+    dest = tmp_path / "c"
+    atlas.create(netcdf_dir_with_a_julian_calendar, str(dest), decode_times=False)
+
+    arrays = {a["name"]: a for a in atlas.describe(str(dest), "julian.nc")["arrays"]}
+    assert arrays["time"]["dtype"] == "int64"
+    # The units and the calendar survive, so a reader can decode the numbers.
+    assert arrays["time"]["attributes"]["calendar"] == "julian"
+    assert "days since" in arrays["time"]["attributes"]["units"]
+    assert arrays["temp"]["dtype"] == "float32"
+
+
+def test_a_cftime_axis_can_be_skipped_per_array(
+    netcdf_dir_with_a_julian_calendar, tmp_path
+):
+    dest = tmp_path / "c"
+    result = atlas.create(
+        netcdf_dir_with_a_julian_calendar, str(dest), on_unsupported="skip"
+    )
+
+    assert [s["array"] for s in result["skipped_arrays"]] == ["time"]
+    assert [a["name"] for a in atlas.describe(str(dest), "julian.nc")["arrays"]] == [
+        "temp"
+    ]
+
+
+def test_convert_calendar_keeps_the_exact_instant(
+    netcdf_dir_with_a_julian_calendar, tmp_path
+):
+    """A Julian label and its Gregorian label name one moment, 13 days apart."""
+    dest = tmp_path / "c"
+    atlas.create(netcdf_dir_with_a_julian_calendar, str(dest), convert_calendar=True)
+
+    arrays = {a["name"]: a for a in atlas.describe(str(dest), "julian.nc")["arrays"]}
+    assert arrays["time"]["dtype"] == "timestamp_nanoseconds"
+
+    # The fixture holds Julian 2024-01-01 through 2024-01-04. The same instants
+    # carry the Gregorian labels 2024-01-14 through 2024-01-17.
+    first = np.datetime64(arrays["time"]["stats"]["min"], "ns")
+    last = np.datetime64(arrays["time"]["stats"]["max"], "ns")
+    assert first == np.datetime64("2024-01-14T00:00:00")
+    assert last == np.datetime64("2024-01-17T00:00:00")
+
+
+def test_convert_calendar_matches_a_per_element_conversion(
+    netcdf_dir_with_a_julian_calendar,
+):
+    """The array-at-once conversion must equal the obvious slow one."""
+    from atlas.xarray import _cftime_to_datetime64
+
+    ds = xr.open_dataset(netcdf_dir_with_a_julian_calendar / "julian.nc")
+    values = np.asarray(ds["time"].values)
+
+    fast = _cftime_to_datetime64("time", values)
+    slow = np.array(
+        [
+            np.datetime64(v.change_calendar("proleptic_gregorian").isoformat(), "ns")
+            for v in values
+        ]
+    )
+    assert np.array_equal(fast, slow)
+
+
+def test_an_artificial_calendar_has_no_exact_gregorian_date(tmp_path):
+    """A 360_day year names no real instant, so no conversion exists."""
+    import cftime
+
+    from atlas.xarray import _cftime_to_datetime64
+
+    values = np.array([cftime.Datetime360Day(2024, 2, 30)], dtype=object)
+    with pytest.raises(NotImplementedError, match="360_day"):
+        _cftime_to_datetime64("time", values)
+
+
+def test_a_date_outside_the_nanosecond_range_is_refused_not_wrapped(tmp_path):
+    """numpy wraps such a date in silence. Atlas must not pass one on."""
+    import cftime
+
+    from atlas.xarray import _cftime_to_datetime64
+
+    for year in (1600, 2300):
+        values = np.array([cftime.DatetimeJulian(year, 1, 1)], dtype=object)
+        with pytest.raises(NotImplementedError, match="outside the range"):
+            _cftime_to_datetime64("time", values)
+
+
+def test_convert_calendar_leaves_a_normal_time_axis_alone(netcdf_dir, tmp_path):
+    dest = tmp_path / "c"
+    atlas.create(netcdf_dir, str(dest), convert_calendar=True)
+    arrays = {a["name"]: a for a in atlas.describe(str(dest), "2024-01.nc")["arrays"]}
+    assert arrays["time"]["dtype"] == "timestamp_nanoseconds"
+
+
+def test_an_object_array_of_something_else_is_refused_clearly(tmp_path):
+    """numpy reports `object` for both a string array and this one."""
+    from atlas.xarray import _reject_unstorable_object_array
+
+    var = xr.DataArray(np.array([{"a": 1}, {"b": 2}], dtype=object), dims=["x"])
+    with pytest.raises(NotImplementedError, match="object array of dict"):
+        _reject_unstorable_object_array("payload", var)
+
+
+def test_a_real_string_array_still_passes_the_object_check(tmp_path):
+    from atlas.xarray import _reject_unstorable_object_array
+
+    # A missing cell must not be mistaken for an unsupported element.
+    var = xr.DataArray(np.array([None, "b", "c"], dtype=object), dims=["x"])
+    _reject_unstorable_object_array("label", var)
+
+    empty = xr.DataArray(np.array([], dtype=object), dims=["x"])
+    _reject_unstorable_object_array("empty", empty)
+
+
 # ── the log file ─────────────────────────────────────────────────────
 
 

{atlas_python-0.16.1 → atlas_python-0.16.3}/docs/python.md

@@ -46,10 +46,15 @@ for `ATLS`, and you get nothing.
 
 ## Ingest
 
-`create` scans a directory for `.nc`, `.nc4`, `.cdf`, and `.netcdf` files. It
-sorts them, and writes one dataset per file, named after the file. `2024-01.nc`
-becomes `2024-01.nc`, suffix and all. The sort makes the ordinals reproducible.
-Build the same directory twice, and every dataset lands at the same position.
+`create` scans a directory for `.nc`, `.nc4`, `.cdf`, and `.netcdf` files, and
+descends into every subdirectory. It sorts them, and writes one dataset per
+file, named after the file. `2024-01.nc` becomes `2024-01.nc`, suffix and all.
+The sort makes the ordinals reproducible. Build the same directory twice, and
+every dataset lands at the same position.
+
+A dataset name carries no directory, because a name may hold no `/`. Two files
+of one name in two subdirectories therefore collide. `recursive=False` scans
+the top directory alone.
 
 One writer does all of it. Nothing at the destination is readable until the
 last file lands, with the footer. A failure part-way leaves no collection. That

{atlas_python-0.16.1 → atlas_python-0.16.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "atlas-python"
-version = "0.16.1"
+version = "0.16.3"
 description = "Python bindings for the ATLAS array store"
 readme = "README.md"
 requires-python = ">=3.10"