env-able 1.2.0__tar.gz → 1.2.2__tar.gz

{env_able-1.2.0 → env_able-1.2.2}/.gitignore

@@ -1,60 +1,68 @@
-# ── Secrets — never commit ────────────────────────────────────────────────────
-# Live PyPI API token used by dev/publish-*.bat
-**/dev/token.txt
-**/token.txt
-*.pem
-*.key
-.env
-.env.*
-
-# ── Virtual environments ──────────────────────────────────────────────────────
-.venv/
-venv/
-env/
-**/.venv/
-
-# ── Python build / cache ──────────────────────────────────────────────────────
-__pycache__/
-*.py[cod]
-*.egg-info/
-build/
-dist/
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-
-# ── Atlas debug session logs ──────────────────────────────────────────────────
-# Bug reports are per-session working files, not source. README.md is kept.
-debug/atlas-*.jsonl
-debug/atlas-*.md
-debug/latest.md
-
-# ── Large test / sample data — on disk, not in history ────────────────────────
-# 364 MB of Bakken + Vaca Muerta shapefiles. Git is not a data store; keeping
-# these out is what makes the repo clonable. They stay on disk untouched.
-incubator/testing-data/
-**/TestingData/
-*.duckdb
-*.zip
-
-# Parked experiments (see CLAUDE.md) — ~58 MB, mostly binary assets.
-# Untracked, not deleted. Remove this line if you want them versioned.
-incubator/archive/
-
-# ── Editor / OS ───────────────────────────────────────────────────────────────
-.idea/
-.vscode/
-*.swp
-Thumbs.db
-desktop.ini
-$RECYCLE.BIN/
-
-# ── Claude Code working state ─────────────────────────────────────────────────
-.claude/worktrees/
-.claude/shell-snapshots/
-.claude/statsig/
-.claude/todos/
-
-# ── Scratch output ────────────────────────────────────────────────────────────
-*.atlas.json.bak
-*.bak-*
+# ── Secrets — never commit ────────────────────────────────────────────────────
+# Live PyPI API token used by dev/publish-*.bat
+**/dev/token.txt
+**/token.txt
+*.pem
+*.key
+.env
+.env.*
+
+# ── Virtual environments ──────────────────────────────────────────────────────
+.venv/
+venv/
+env/
+**/.venv/
+
+# ── Python build / cache ──────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# ── Atlas debug session logs ──────────────────────────────────────────────────
+# Bug reports are per-session working files, not source. README.md is kept.
+debug/atlas-*.jsonl
+debug/atlas-*.md
+debug/latest.md
+
+# ── Large test / sample data — on disk, not in history ────────────────────────
+# 364 MB of Bakken + Vaca Muerta shapefiles. Git is not a data store; keeping
+# these out is what makes the repo clonable. They stay on disk untouched.
+incubator/testing-data/
+**/TestingData/
+*.duckdb
+*.zip
+
+# Parked experiments (see CLAUDE.md) — ~58 MB, mostly binary assets.
+# Untracked, not deleted. Remove this line if you want them versioned.
+incubator/archive/
+
+# ── Editor / OS ───────────────────────────────────────────────────────────────
+.idea/
+.vscode/
+*.swp
+Thumbs.db
+desktop.ini
+$RECYCLE.BIN/
+
+# ── Claude Code working state ─────────────────────────────────────────────────
+.claude/worktrees/
+.claude/shell-snapshots/
+.claude/statsig/
+.claude/todos/
+
+# ── Scratch output ────────────────────────────────────────────────────────────
+*.atlas.json.bak
+*.bak-*
+
+# ── Virtual environments the skill creates ────────────────────────────────────
+# preflight.py builds skill/venv on the user's machine; it is platform-specific and large.
+skill/venv/
+
+# ── Handoff artifacts ─────────────────────────────────────────────────────────
+# The .skill is rebuilt by package_skill.py and already versioned in releases/.
+handoff/*.skill

{env_able-1.2.0 → env_able-1.2.2}/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## [1.2.2] - 2026-08-17
+
+### Fixed
+- **The README documented three operations out of seven.** `Union`, `Dissolve`, `SpatialJoin` and
+  `Near` had no entry at all, on the page PyPI renders as the front door, and had not for several
+  releases. All four now carry their real signatures and defaults; `Union` and `Intersect` note
+  that they accept a list; the async section names every variant rather than saying "all three";
+  and `SpatialResult` no longer claims to come from three operations.
+
+  Two things were wrong in the first draft and were caught against the code rather than shipped:
+  `Near` does **not** use ArcGIS's `NEAR_DIST` / `-1` convention — it writes a single column
+  named `dist_<near layer>_<unit>` and leaves it *null* beyond `max_distance`, keeping every
+  input feature — and the Spatial Join match list is all seven options in `SJ_MATCH`.
+
+  The durable part is in `docs/verify.py`: the expected operation list is derived from
+  `dir(env)`, and the quoted `DISSOLVE_STATISTICS` and `SJ_MATCH` values are compared against the
+  module. A new operation is now documented or the release fails. Nothing checked before, which
+  is why four of them went missing without anyone noticing.
+
+## [1.2.1] - 2026-08-17
+
+### Added
+- **Union and Intersect take more than two layers.** Both accept a list where they used to
+  accept one other layer — `env.Union("a.shp", ["b.shp", "c.shp", "d.shp"])` — and Atlas offers
+  a checkbox list of layers instead of a single dropdown, the same picker Dissolve uses for
+  fields. Three shapefiles used to be two operations plus an intermediate file to name, track
+  and delete.
+
+  The layers are folded pairwise, which is the correct N-way answer. For Union, the `FID_`
+  columns are attached to every input **before** the fold rather than per pair, so each input
+  keeps its own through every pass: a piece of the output still says which of the ten layers
+  made it. The input's `where` filter applies to the first pass only — after that the
+  accumulator is an intermediate the filter was never written against.
+
+  `POST /api/geoprocess` takes `other_layers` alongside the old `other_layer`, merges the two
+  and drops duplicates, so a script written against the previous shape keeps working. Clip and
+  Spatial Join still pair exactly two layers, and say so if handed a list.
+- **`POST /api/export/pdf`** builds a PDF from a map image with Pillow and returns the bytes.
+- **`POST /api/databricks/open-token-page`** and **`POST /api/open-url`** open a
+  settings-derived address in the user's real default browser. The page names a *setting*, never
+  a URL, so there is no request that makes the server open something the user did not configure.
+
+### Changed
+- **The desktop window opens maximized.** Filling the screen is what a map
+  application wants: the old 1600x1000 default left a ribbon, two docked panels and a status
+  strip competing for what was left. Maximized rather than fullscreen, deliberately — the
+  title bar, close button and taskbar stay, because Atlas is something you work alongside
+  Claude and a file explorer, not a kiosk. Un-maximizing gives back the 1600x1000 window.
+  Both window paths honour it (pywebview's `maximized`, Chromium's `--start-maximized`), an
+  older pywebview without the argument degrades to a sized window rather than failing, and
+  `open_window(..., maximized=False)` opts out.
+- **Atlas raises no browser dialogs at all.** Every `alert`, `confirm` and `prompt` — twenty of
+  them — is now an Atlas panel: themed, with buttons that say what they do (**Delete field**,
+  not **OK**), red for destructive answers, Esc to cancel and Enter to accept. A native dialog
+  announces its origin in the title bar (*"localhost:8000 says"*), which reads as a stray
+  browser inside a desktop application, cannot be styled or relabelled, and blocks the event
+  loop so the map stops redrawing behind it.
+- **Nothing calls `window.open` either.** In a desktop window an embedded webview has no
+  pop-ups, so those calls returned null and did nothing: **Find token** silently failed, and
+  *Export PDF* threw where it wrote into the window it never got. Both now go through the
+  server — Find token opens the page, PDF comes back as bytes the page downloads like the SVG.
+  A PDF export is also now genuinely a PDF, rather than whatever the print dialog produced.
+
+### Fixed
+- **Intersect said "returned 0 features" when a fold emptied the result**, which with several
+  inputs is not a diagnosis. It now names the layer nothing survived, says how many were
+  skipped, and points out that every layer overlaps the *input* — it is the running result they
+  stop sharing area with.
+- **A zero-area intersection read as success.** Where layers touch along a boundary rather than
+  overlapping, OGR returns the shared edge as a feature: `output_count` was 1 with no area in
+  it, and `count_slivers` does not catch it because a line is not a thin polygon. Now warned
+  about explicitly.
+- **`FID_` collisions in Union.** Two layers with the same stem, or two GeoDataFrames (which
+  have no stem at all), produced the same column name — and a collision does not raise, the
+  second write just wins, so the output claimed a piece came from a layer that did not
+  contribute it.
+
 ## [1.2.0] - 2026-08-13
 
 Symbology fixes, all of them one mistake made in several places: coercing on the wrong side of

{env_able-1.2.0 → env_able-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: env-able
-Version: 1.2.0
+Version: 1.2.2
 Summary: AI-ready GIS toolkit for energy and subsurface workflows.
 License: MIT
 License-File: LICENSE
@@ -128,18 +128,97 @@ print(result)                                    # SpatialResult stats
 ---
 
 ### `env.Intersect(input_layer, intersect_layer, output=None, where=None, preview=False)`
-Geometric intersection of two layers (`OGR Layer.Intersection()` engine). Input geometries are trimmed to their overlap; attributes from **both** layers appear in the result. Returns a `SpatialResult`.
+Geometric intersection — only what the layers share, with attributes from all of them (`OGR Layer.Intersection()` engine). Returns a `SpatialResult`.
 - `input_layer` — point, line, or polygon (file path or GeoDataFrame)
-- `intersect_layer` — polygon boundary to intersect against
+- `intersect_layer` — **one layer or a list.** A list is folded pairwise, which is exactly the N-way intersection: what the input shares with the first, then what that shares with the second, and so on
 - `output` — output file path
 - `where` — optional SQL attribute filter on the input layer
 - `preview` — if `True`, pushes result to Atlas on completion
 
 ```python
 result = env.Intersect("wells.shp", "permits.gpkg", output="wells_permits.gpkg")
+result = env.Intersect("wells.shp", ["leases.gpkg", "counties.gpkg"])   # three-way
 result.preview("Permitted Wells")
 ```
 
+If one layer leaves nothing, the fold stops and the warning names it — with four inputs, "returned 0 features" is not a diagnosis.
+
+---
+
+### `env.Union(input_layer, union_layer, output=None, join_attributes="ALL", gaps=True, cluster_tolerance=None, where=None, preview=False)`
+Everything from every layer, cut where they overlap (`OGR Layer.Union()` engine). Polygons. Mirrors `arcpy.analysis.Union`. Returns a `SpatialResult`.
+
+Where Intersect answers "what do these share?", Union answers "what is covered by either, and by which?" — so the output usually has **more** features than the inputs, because each overlap becomes its own piece.
+
+- `union_layer` — **one layer or a list**, folded pairwise. Each input keeps its own `FID_` column through the whole fold
+- `join_attributes` — `"ALL"` (everything, plus a `FID_<layer>` per input), `"NO_FID"` (everything except those), `"ONLY_FID"` (just those)
+- `gaps` — `False` (ArcGIS `NO_GAPS`) gives each enclosed void a feature of its own, with every `FID_` at `-1`, so gaps can be selected and inspected
+- `cluster_tolerance` — snap coordinates within this distance together, as a GEOS precision grid
+- `where` — SQL attribute filter on the input, applied before the overlay
+
+```python
+result = env.Union("leases.gpkg", "units.gpkg", output="lease_units.gpkg",
+                   join_attributes="ONLY_FID")
+result = env.Union("a.shp", ["b.shp", "c.shp", "d.shp"])   # four layers, one call
+result = env.Union(a, b, gaps=False)                       # a feature per enclosed void
+```
+
+`FID_<layer>` is the source feature's id, or **-1** where that layer contributed nothing to the piece — which is how you tell a lease-only sliver from a genuine overlap. Non-overlapping inputs are valid (the answer is the layers side by side) and warn, naming the layer that misses, because that usually means a CRS mistake.
+
+---
+
+### `env.Dissolve(input_layer, output=None, dissolve_field=None, statistics_fields=None, multi_part=True, unsplit_lines=False, where=None, preview=False)`
+Merge features that share a value, and summarise the rest. Mirrors `arcpy.management.Dissolve`. Returns a `SpatialResult`.
+
+- `dissolve_field` — field name or list of them. **Omit it and every feature merges into one**, which is the usual way to turn a pile of parcels into an outline
+- `statistics_fields` — `[[field, stat], ...]`. `SUM`, `MEAN`, `MIN`, `MAX`, `RANGE`, `STD`, `COUNT`, `FIRST`, `LAST`, `MEDIAN`, `VARIANCE`, `UNIQUE`, `CONCATENATE`. Output columns are named `SUM_acres`, `COUNT_id` and so on, as ArcGIS names them
+- `multi_part` — `False` splits disjoint pieces into a feature each, repeating the attributes (ArcGIS's `SINGLE_PART`)
+- `unsplit_lines` — lines only: merge runs that join end to end, so two unconnected roads called "Main" stay two features
+
+```python
+result = env.Dissolve("parcels.gpkg", output="operators.gpkg",
+                      dissolve_field="operator",
+                      statistics_fields=[["acres", "SUM"], ["wells", "COUNT"]])
+result = env.Dissolve("parcels.gpkg")            # everything becomes one outline
+```
+
+---
+
+### `env.SpatialJoin(target_layer, join_layer, match="intersects", how="one_to_one", keep_all=True, fields=None, stats=None, search_radius=None, unit="km", output=None, preview=False)`
+Transfer attributes from one layer to another by location. Mirrors `arcpy.analysis.SpatialJoin`. Returns a `SpatialResult`.
+
+- `match` — `intersects` (default), `contains`, `within`, `crosses`, `overlaps`, `touches`, `closest`
+- `how` — `one_to_one` (one output row per target, summarised) or `one_to_many` (a row per match)
+- `keep_all` — `True` keeps targets with no match (ArcGIS's `KEEP_ALL`); `False` drops them
+- `fields` — which join-layer fields to carry across. Omit for all of them
+- `stats` — `[[field, stat], ...]` for `one_to_one`, since several matches have to collapse into one row
+- `search_radius` / `unit` — only meaningful for `match="closest"`
+
+```python
+result = env.SpatialJoin("wells.shp", "counties.gpkg", match="within")
+result = env.SpatialJoin("wells.shp", "leases.gpkg", match="closest",
+                         search_radius=2, unit="miles")
+```
+
+---
+
+### `env.Near(input_layer, near_layer, name=None, unit="km", output=None, max_distance=None, preview=False)`
+Distance from each input feature to the nearest feature in another layer. Returns a `SpatialResult`.
+
+It **adds a column and changes nothing else** — same geometry, same feature count, every input kept. So the result draws exactly like the input and can be styled, filtered or sorted by distance. Distances are measured in a projected CRS for true ground distance, then the result comes back in the input's own CRS.
+
+- `name` — the column to write. Defaults to **`dist_<near layer>_<unit>`**, so measuring one layer against several gives you a column per comparison rather than a collision
+- `unit` — `km` (default), `meters`, `miles`, `feet`, `nm`
+- `max_distance` — in `unit`. Beyond it the column is **null**, not a sentinel value, and the result warns how many features had no neighbour in range
+
+```python
+result = env.Near("wells.shp", "pipelines.gpkg", unit="miles", max_distance=5)
+result = env.Near("wells.shp", "faults.gpkg", name="dist_to_fault_km")
+result.preview("Wells by distance to pipeline")
+```
+
+Where several near features tie for closest, the first is kept and the result says how many tied.
+
 ---
 
 ### `env.load(source)` — fluent spatial pipeline
@@ -166,7 +245,7 @@ results = await asyncio.gather(
 ---
 
 ### Async variants
-All three operations have async counterparts that run in a thread-pool executor. GDAL releases the GIL so multiple calls run truly in parallel via `asyncio.gather()`.
+Every operation has an async counterpart — `clip_async`, `buffer_async`, `intersect_async`, `union_async`, `dissolve_async`, `spatial_join_async`, `near_async`, `morph_async` — running in a thread-pool executor. GDAL releases the GIL, so multiple calls run truly in parallel via `asyncio.gather()`.
 
 ```python
 import asyncio
@@ -185,13 +264,13 @@ r1, r2, r3 = await asyncio.gather(
 ---
 
 ### `SpatialResult`
-Returned by `Clip`, `Buffer`, `Intersect`, and the pipeline `.run()`. Exposes operation stats and chainable output methods.
+Returned by every operation and by the pipeline's `.run()`. Exposes operation stats and chainable output methods.
 
 | Attribute / Method | Description |
 |---|---|
 | `input_count` | Feature count of the input layer |
 | `output_count` | Feature count of the result |
-| `dropped` | `input_count - output_count` |
+| `dropped` | Features lost. Never negative — Union and Dissolve can grow the count |
 | `slivers` | Polygon features with suspiciously small area (intersection artifacts) |
 | `crs` | CRS of the output (e.g. `EPSG:4326`) |
 | `elapsed_s` | Wall-clock seconds for the operation |
@@ -309,6 +388,50 @@ print(f"{rows:,} rows written")
 ---
 
 ## Changelog
+### Unreleased
+
+**Fixed**
+- **The README documented three operations out of seven.** `Union`, `Dissolve`, `SpatialJoin`
+  and `Near` had no entry at all — for several releases, on the page PyPI renders as the front
+  door. All four are now documented with their real signatures and defaults, `Union` and
+  `Intersect` note that they take a list, and the async list names every variant instead of
+  claiming there are three.
+
+  Two corrections while writing them: `Near` was about to be described with ArcGIS's
+  `NEAR_DIST` / `-1` convention, which it does **not** use — it writes one column named
+  `dist_<near layer>_<unit>` and leaves it *null* beyond `max_distance` — and the Spatial Join
+  match list is all seven options from `SJ_MATCH`, not three and an "and the rest".
+
+  `docs/verify.py` now derives the expected list from `dir(env)`, so the next operation added is
+  either documented or the release fails. That is the actual fix; the prose was only the symptom.
+
+### v1.2.1 — 2026-08-17
+
+**Added**
+- **Union and Intersect take more than two layers.** Pass a list —
+  `env.Union("a.shp", ["b.shp", "c.shp", "d.shp"])` — and Atlas offers a checkbox list of layers
+  instead of one dropdown. They fold pairwise, which is the correct N-way answer, and every
+  input keeps its own `FID_` column through the whole fold, so the output still says which layer
+  made each piece. `POST /api/geoprocess` gained `other_layers`; the old `other_layer` still
+  works and the two are merged.
+- `POST /api/export/pdf` builds a real PDF server-side. `POST /api/databricks/open-token-page`
+  and `POST /api/open-url` open a settings-derived address in the default browser.
+
+**Changed**
+- **The desktop window opens maximized** rather than at 1600x1000 — the whole
+  screen, but still a window: title bar, close button and taskbar all stay.
+- **No browser dialogs anywhere in Atlas.** All twenty `alert`/`confirm`/`prompt` calls are now
+  themed Atlas panels with buttons that name the action. A native dialog says
+  *"localhost:8000 says"*, cannot be styled, and blocks the map from redrawing behind it.
+- **No `window.open` either** — it opens nothing at all in a desktop window, which is why
+  **Find token** silently did nothing and *Export PDF* failed. Both go through the server now.
+
+**Fixed**
+- Intersect names the layer that emptied a multi-layer fold instead of reporting "0 features".
+- A zero-area intersection (layers that touch rather than overlap) is warned about rather than
+  counted as a result.
+- `FID_` column collisions in Union, where two layers shared a stem and the second silently won.
+
 ### v1.2.0 — 2026-08-13
 
 Symbology fixes. All of them the same mistake in several places: coercing on the wrong side of a