tilearray 0.1.0__tar.gz → 0.2.0__tar.gz

{tilearray-0.1.0 → tilearray-0.2.0}/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-11-03
+
+Trustworthy-core release: clean-env GeoTIFF install, analysis-ready mosaic attrs, one preferred compute habit, typed public errors, default tile progress, and actionable stage-gate DX — without holding the cut for multi-AOI orchestration or later uniqueness work.
+
+### Documentation
+
+- Maintainer stage-gate notebook (`notebooks/stage_gate_0_2.ipynb`) + run notes in `notebooks/README.md`: local editable install → live OSM / EA DSP mosaics → politeness knobs, soft-fail attrs, and a human checklist before the 0.2.0 cut
+- Document private/keyed hosts via existing config `params=` / `headers=` (query keys, legacy username/password query params, Bearer/Basic headers); OS Maps XYZ recipe uses env-backed `params` instead of `?key=` in the URL template; soft-fail still hard-aborts 401 (related #58). Caps credential parity for WCS/WMTS is under Changed (#57)
+- Default tile progress + quiet opt-out documented in how-it-works, troubleshooting (“looks hung”), and API index (#86)
+- Troubleshooting: stage-gate symptom→cause table for wrong format / mistyped URL / bad `coverage_id`, and httpx (not `requests`) wording for caps failures (#88)
+
+### Fixed
+
+- Soft-fail observability: `compute_with_policy` refreshes `attrs["tilearray_tile_errors"]` (`soft_failed`, `aborted`, `examples`) from `FetchProgress` after lazy `create_array` — same counters as the eager `compute=True` path (#73)
+
+### Breaking
+
+- Removed `WCSConfig.for_ea_dsp` and `XYZConfig.for_openstreetmap`. Protocol configs stay on `from_url`; host politeness comes from `tilearray.fetch_presets` — compose with `WCSConfig.from_url(url, coverage_id, **ea_dsp_fetch_defaults())` and `XYZConfig.from_url(OSM_TILE_TEMPLATE, zoom=…, **osm_fetch_defaults())`. Docs, soak scripts, and tests updated to the compose path (alpha; no deprecation shim).
+
+### Changed
+
+- Stage-gate errors are more actionable: unsupported formats list library (and cached DescribeCoverage) MIME values; DescribeCoverage / GetCapabilities / `build_service` messages keep status or httpx type, distinguish DNS vs HTML/login vs unknown CoverageId, and redact secret query keys; soft-fail / 401 hard-abort behaviour unchanged (#88)
+- WCS GeoTIFF decode now uses ``tifffile`` directly (bytes or path); dropped the ``geotiff`` → ``zarr<2.13`` / ``numcodecs<0.16`` pin cage so clean-env installs no longer need that dependency gymnastics. XYZ-without-GDAL posture unchanged (no hard rasterio/GDAL runtime dep) (#53)
+- Public-boundary failures now raise the typed `TileArrayError` hierarchy instead of bare `ValueError` / `RuntimeError`: bad inputs → `ValidationError`, caps/XML parse → `ParseError`, service detection / missing decoder → `ConfigurationError`, WCS/WMTS capabilities HTTP (`httpx`) → `NetworkError`. **Compat:** callers that catch bare `ValueError` for library validation must switch to `TileArrayError` / the specific subclass (or catch both during transition). Pydantic model field checks (`BoundingBox` coordinates, etc.) still surface via pydantic as before (#72)
+- WCS/WMTS capabilities and DescribeCoverage (plus direct `WCSService.get_coverage`) now use sync **httpx** with one shared UA/timeout policy and inherit config `headers`/`params` — private-server credentials reach plan-time GETs the same way they reach tiles. Drops the runtime `requests` dependency (#57)
+- Docs: one compute habit on primary paths — OSM/GIBS guides, how-it-works, troubleshooting, and API index use `compute_with_policy`; `load_array` documented as eager sugar for `create_array(..., compute=True)`; quickstart WMTS honesty note (`WMTSConfig` supported, host guide TBD / #60) (#55)
+
+### Added
+
+- Default tqdm-style tile progress for multi-tile mosaics via existing `on_progress` / `FetchProgress` (scripts + notebooks). Quiet opt-out: `show_progress=False`, `TILEARRAY_PROGRESS=0`, or non-TTY/non-Jupyter display. Custom `on_progress=` still replaces the default bar. Runtime dependency: `tqdm`. No second compute API (#86)
+- Analysis-ready mosaic attrs for xarray/rioxarray handoff: Affine `transform` + `transform_source="mosaic_bbox"`, `band_policy`, and elevation GeoTIFF `nodata`/`_FillValue` (NaN after decode). Documented north-up + optional rioxarray recipe; mosaic CRS remains the request `crs=` (never silently replaced by per-tile GeoTIFF tags) (#54)
+- Large-AOI politeness evidence scaffold (#56): `@pytest.mark.soak` multi-tile cold mosaics under EA DSP + OSM preset ceilings (nightly via `@net`/`@slow`, deselected on PRs); offline fail-loud abort under concurrent pressure; maintainer script `scripts/soak_large_aoi_presets.py` for county-/valley-scale soaks; how-it-works / troubleshooting / building-docs note on nightly vs maintainer split
+- Opt-in plan-time tile error policy for mosaics (`on_tile_error=` / `soft_fail=True`) with library preset `soft_fail_exhausted_tiles`: after retries, soft-fill tile-local exhausted failures (404 / 5xx / transport) as NaN blocks without aborting siblings; auth (401), exhausted 429, decode errors, and soft-fail fraction above `soft_fail_max_fraction` still hard-abort. Default remains hard-fail + `FetchProgress.abort` (#65)
+- Top-level `FetchPolicy` export (`from tilearray import FetchPolicy`) so docs/API reference match `__all__` (#70)
+
+### Changed
+
+- Public `__all__` no longer advertises parsers (`WCSParser`, `WMTSParser`), concrete services (`WCSService`, `WMSService`, `WMTSService`, `XYZService`), or `BaseService`. Prefer configs + `create_array`; low-level clients remain importable from `tilearray.service` / submodules during alpha (#70)
+- Mosaic `y`/`x` coordinates are **pixel centers** consistent with `attrs["transform"]` (north-up Affine from planned bbox + shape), instead of edge-span `linspace` endpoints (#54)
+- Docs: `**service_options` key families (fetch / planner / identity) and `max_concurrent*` one-job-per-name map in how-it-works, with API + troubleshooting cross-links — no public signature change (#71)
+
+## [0.1.1] - 2026-11-01
+
+### Fixed
+
+- README header logo uses an absolute HTTPS PNG URL so PyPI / Warehouse renders the mark (relative `docs/_static/...` paths do not resolve in the uploaded long description)
+
 ## [0.1.0] - 2026-10-31
 
 Initial alpha release focused on lazy WCS- and XYZ-backed xarray arrays.
@@ -63,5 +110,7 @@ Initial alpha release focused on lazy WCS- and XYZ-backed xarray arrays.
 - Package renamed from scaffold `ogc-array` to `tilearray`; README, CI, and metadata aligned with shipped API
 - EA Lidar WCS GeoTIFF decode and non-divisible tile resize for native-resolution tiles
 
-[Unreleased]: https://github.com/MatthewJWhittle/tilearray/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/MatthewJWhittle/tilearray/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/MatthewJWhittle/tilearray/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/MatthewJWhittle/tilearray/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/MatthewJWhittle/tilearray/releases/tag/v0.1.0

{tilearray-0.1.0 → tilearray-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tilearray
-Version: 0.1.0
+Version: 0.2.0
 Summary: A Python library for loading geospatial data from remote tile servers as xarray objects
 Project-URL: Homepage, https://github.com/MatthewJWhittle/tilearray
 Project-URL: Repository, https://github.com/MatthewJWhittle/tilearray
@@ -226,17 +226,15 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Requires-Dist: dask>=2024.8.0
 Requires-Dist: eval-type-backport>=0.2.0; python_version < '3.10'
-Requires-Dist: geotiff>=0.2.10
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: numcodecs<0.16,>=0.12.1
 Requires-Dist: numpy>=2.0.2
 Requires-Dist: pillow>=11.3.0
 Requires-Dist: pydantic>=2.12.3
 Requires-Dist: pyproj>=3.6.1
-Requires-Dist: requests>=2.32.5
 Requires-Dist: tenacity>=9.0.0
+Requires-Dist: tifffile>=2024.8.30
+Requires-Dist: tqdm>=4.70.1
 Requires-Dist: xarray>=2024.7.0
-Requires-Dist: zarr<2.13,>=2.12.0
 Provides-Extra: dev
 Requires-Dist: coverage>=7.10.7; extra == 'dev'
 Requires-Dist: hypothesis>=6.141.1; extra == 'dev'
@@ -253,6 +251,8 @@ Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Requires-Dist: respx>=0.22.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: types-tqdm>=4.67.3.20260205; (python_version >= '3.10') and extra == 'dev'
+Requires-Dist: vcrpy>=7.0.0; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: matplotlib>=3.9.0; extra == 'docs'
 Requires-Dist: myst-parser>=3.0.0; extra == 'docs'
@@ -262,7 +262,7 @@ Requires-Dist: sphinx-design>=0.5.0; extra == 'docs'
 Requires-Dist: sphinx>=6.0.0; extra == 'docs'
 Description-Content-Type: text/markdown
 
-# <img src="docs/_static/logo/tilearray-mark.svg" alt="" width="36" height="36"> tilearray
+# <img src="https://matthewjwhittle.github.io/tilearray/_static/logo/tilearray-mark-128.png" alt="" width="36" height="36"> tilearray
 
 tilearray turns remote tile services into **Dask**-backed **xarray** arrays — one `create_array` call for WCS, WMS, WMTS, or XYZ. Shared fetch and decode keep mosaics polite to servers and analysis-ready on a laptop or a larger machine.
 
@@ -298,9 +298,10 @@ Prefer **`compute_with_policy`** over plain `.compute()` so Dask workers match t
 
 ```python
 from tilearray import XYZConfig, compute_with_policy, create_array
+from tilearray.fetch_presets import OSM_TILE_TEMPLATE, osm_fetch_defaults
 from tilearray.types import CRS
 
-config = XYZConfig.for_openstreetmap(zoom=16)
+config = XYZConfig.from_url(OSM_TILE_TEMPLATE, zoom=16, **osm_fetch_defaults())
 da = create_array(
     config,
     bbox=(-0.005, 51.495, 0.005, 51.505),  # small window near central London
@@ -317,16 +318,18 @@ Include © OpenStreetMap contributors when displaying map imagery.
 
 ```python
 from tilearray import WCSConfig, compute_with_policy, create_array
+from tilearray.fetch_presets import ea_dsp_fetch_defaults
 from tilearray.types import CRS, Format
 
-config = WCSConfig.for_ea_dsp(
+config = WCSConfig.from_url(
     "https://environment.data.gov.uk/spatialdata/"
     "lidar-composite-digital-terrain-model-dtm-1m/wcs",
-    coverage_id="13787b9a-26a4-4775-8523-806d13af58fc__Lidar_Composite_Elevation_DTM_1m",
+    "13787b9a-26a4-4775-8523-806d13af58fc__Lidar_Composite_Elevation_DTM_1m",
     crs=CRS.EPSG_27700,
     output_format=Format.GEOTIFF,
     chunk_size=(800, 800),
     grid_shape=(1, 1),
+    **ea_dsp_fetch_defaults(),
 )
 bbox = (431900.0, 382700.0, 432700.0, 383500.0)  # British National Grid
 da = create_array(config, bbox, CRS.EPSG_27700)
@@ -334,7 +337,7 @@ elevation = compute_with_policy(da)
 print(elevation.shape, float(elevation.mean()))
 ```
 
-The EA Lidar preset caps sustained concurrency at **10** (AIMD ceiling). More hosts, WMS/WMTS recipes, and polite-use notes live in the [docs](https://matthewjwhittle.github.io/tilearray/).
+EA Lidar fetch defaults (`tilearray.fetch_presets.ea_dsp_fetch_defaults`) cap sustained concurrency at **10** (AIMD ceiling). More hosts, WMS recipes, and polite-use notes live in the [docs](https://matthewjwhittle.github.io/tilearray/). WMTS is supported via `WMTSConfig`; a host guide is still TBD.
 
 ## Development
 

{tilearray-0.1.0 → tilearray-0.2.0}/README.md

@@ -1,4 +1,4 @@
-# <img src="docs/_static/logo/tilearray-mark.svg" alt="" width="36" height="36"> tilearray
+# <img src="https://matthewjwhittle.github.io/tilearray/_static/logo/tilearray-mark-128.png" alt="" width="36" height="36"> tilearray
 
 tilearray turns remote tile services into **Dask**-backed **xarray** arrays — one `create_array` call for WCS, WMS, WMTS, or XYZ. Shared fetch and decode keep mosaics polite to servers and analysis-ready on a laptop or a larger machine.
 
@@ -34,9 +34,10 @@ Prefer **`compute_with_policy`** over plain `.compute()` so Dask workers match t
 
 ```python
 from tilearray import XYZConfig, compute_with_policy, create_array
+from tilearray.fetch_presets import OSM_TILE_TEMPLATE, osm_fetch_defaults
 from tilearray.types import CRS
 
-config = XYZConfig.for_openstreetmap(zoom=16)
+config = XYZConfig.from_url(OSM_TILE_TEMPLATE, zoom=16, **osm_fetch_defaults())
 da = create_array(
     config,
     bbox=(-0.005, 51.495, 0.005, 51.505),  # small window near central London
@@ -53,16 +54,18 @@ Include © OpenStreetMap contributors when displaying map imagery.
 
 ```python
 from tilearray import WCSConfig, compute_with_policy, create_array
+from tilearray.fetch_presets import ea_dsp_fetch_defaults
 from tilearray.types import CRS, Format
 
-config = WCSConfig.for_ea_dsp(
+config = WCSConfig.from_url(
     "https://environment.data.gov.uk/spatialdata/"
     "lidar-composite-digital-terrain-model-dtm-1m/wcs",
-    coverage_id="13787b9a-26a4-4775-8523-806d13af58fc__Lidar_Composite_Elevation_DTM_1m",
+    "13787b9a-26a4-4775-8523-806d13af58fc__Lidar_Composite_Elevation_DTM_1m",
     crs=CRS.EPSG_27700,
     output_format=Format.GEOTIFF,
     chunk_size=(800, 800),
     grid_shape=(1, 1),
+    **ea_dsp_fetch_defaults(),
 )
 bbox = (431900.0, 382700.0, 432700.0, 383500.0)  # British National Grid
 da = create_array(config, bbox, CRS.EPSG_27700)
@@ -70,7 +73,7 @@ elevation = compute_with_policy(da)
 print(elevation.shape, float(elevation.mean()))
 ```
 
-The EA Lidar preset caps sustained concurrency at **10** (AIMD ceiling). More hosts, WMS/WMTS recipes, and polite-use notes live in the [docs](https://matthewjwhittle.github.io/tilearray/).
+EA Lidar fetch defaults (`tilearray.fetch_presets.ea_dsp_fetch_defaults`) cap sustained concurrency at **10** (AIMD ceiling). More hosts, WMS recipes, and polite-use notes live in the [docs](https://matthewjwhittle.github.io/tilearray/). WMTS is supported via `WMTSConfig`; a host guide is still TBD.
 
 ## Development
 

tilearray-0.2.0/docs/api/index.md

@@ -0,0 +1,160 @@
+# API reference
+
+Public entry points for building lazy mosaics, configuring services, and handling failures.
+
+## Array
+
+```{eval-rst}
+.. currentmodule:: tilearray
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   create_array
+   load_array
+   compute_with_policy
+   array.compute_thread_pool_size
+```
+
+`create_array` builds a lazy Dask-backed `xarray.DataArray`. Prefer {py:func}`~tilearray.compute_with_policy` over plain `.compute()` so Dask workers match the fetch ceiling. {py:func}`~tilearray.load_array` is eager sugar (`create_array(..., compute=True)` by default) — useful for tiny windows, not a second primary habit. Pass a service **config** (or URL where supported) as the first argument — not only a bare string for every service type.
+
+Multi-tile mosaics attach a default tqdm-style progress bar through `on_progress` during compute. Opt out with `show_progress=False` or `TILEARRAY_PROGRESS=0`; pass a custom `on_progress=` to replace the bar. There is no separate `compute_with_progress` helper — use {py:func}`~tilearray.compute_with_policy` as usual. Details: {doc}`../how-it-works` · {doc}`../troubleshooting`.
+
+`**service_options` on `create_array` / `load_array` is one bag with three key families (**fetch** politeness, **planner** geometry, **identity** / protocol). Concurrency names each have one job (`max_concurrent_requests` host ceiling vs `FetchPolicy.max_concurrent` shared gate vs `call_max_concurrent` per-call vs `compute_with_policy(..., max_concurrent=)` Dask workers). Name map: {doc}`../how-it-works`.
+
+## Configs
+
+```{eval-rst}
+.. currentmodule:: tilearray
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   ServiceConfig
+   WCSConfig
+   WMSConfig
+   WMTSConfig
+   XYZConfig
+```
+
+Configs stay protocol-shaped (`from_url`, …). Host politeness lives in `tilearray.fetch_presets` — compose rather than a second config habit:
+
+```python
+from tilearray import WCSConfig, XYZConfig
+from tilearray.fetch_presets import (
+    OSM_TILE_TEMPLATE,
+    ea_dsp_fetch_defaults,
+    osm_fetch_defaults,
+)
+
+WCSConfig.from_url(url, coverage_id, **ea_dsp_fetch_defaults())
+XYZConfig.from_url(OSM_TILE_TEMPLATE, zoom=16, **osm_fetch_defaults())
+```
+
+Custom hosts: `from_url` alone (no preset unpack). `WCSConfig.build_service()` validates coverage via live DescribeCoverage (network on first `create_array` path that needs capabilities, not only at import time).
+
+## Fetch presets
+
+```{eval-rst}
+.. currentmodule:: tilearray.fetch_presets
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   ea_dsp_fetch_defaults
+   osm_fetch_defaults
+   tilearray_user_agent
+   OSM_TILE_TEMPLATE
+   EA_LIDAR_WCS_URL
+   EA_LIDAR_COVERAGE_ID
+```
+
+Import from `tilearray.fetch_presets` (not re-exported on the package root — keeps host folklore off the primary config surface). Constants such as `EA_LIDAR_BENCH_BBOX` are for tests/benches; prefer the helpers above for callers.
+
+## Types
+
+```{eval-rst}
+.. currentmodule:: tilearray
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   types.CRS
+   types.Format
+   types.BoundingBox
+   types.TileRequest
+   types.TileResponse
+```
+
+## Errors
+
+```{eval-rst}
+.. currentmodule:: tilearray
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   TileArrayError
+   ServiceError
+   ValidationError
+   NetworkError
+   ParseError
+   ConfigurationError
+```
+
+{py:exc}`NetworkError` means a tile failed after retries — mosaics do not leave silent NaN holes **by default**. Caps/capabilities HTTP failures (WCS/WMTS `requests` paths) also raise {py:exc}`NetworkError`.
+
+Prefer catching {py:exc}`TileArrayError` (or a subclass) at public boundaries: bad inputs → {py:exc}`ValidationError`, XML/capabilities parse → {py:exc}`ParseError`, service detection / missing decoder → {py:exc}`ConfigurationError`. Do not rely on bare `ValueError` / `RuntimeError` from library entry points.
+
+## Tile errors (opt-in soft-fail)
+
+```{eval-rst}
+.. currentmodule:: tilearray
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   TileErrorAction
+   TileErrorContext
+   soft_fail_exhausted_tiles
+```
+
+Pass plan-time ``on_tile_error=`` (or ``soft_fail=True``) into {py:func}`~tilearray.create_array` / {py:func}`~tilearray.load_array`. The library preset {py:func}`~tilearray.soft_fail_exhausted_tiles` soft-fills exhausted tile-local fetch failures (404 / 5xx / transport) as NaN (or ``soft_fill_value``) blocks, keeps retries, hard-fails auth / exhausted 429 / decode errors, and aborts when soft-failed fraction exceeds ``soft_fail_max_fraction``. Default remains hard-fail + sibling abort.
+
+## Fetch
+
+```{eval-rst}
+.. currentmodule:: tilearray
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   FetchPolicy
+```
+
+`FetchPolicy` controls concurrency, retries, timeouts, rate limits, and optional AIMD / circuit-breaker behaviour. Service configs expose the same knobs and build a policy via `.fetch_policy()`. Advanced callers may also import it as `tilearray.fetch.FetchPolicy`.
+
+`FetchPolicy.max_concurrent` is the **shared process-gate** ceiling. Per-call politeness is `call_max_concurrent` (or a lower `max_concurrent_requests` override on `create_array`). `compute_with_policy(..., max_concurrent=)` sizes Dask workers only — see {doc}`../how-it-works`.
+
+## Registry
+
+```{eval-rst}
+.. currentmodule:: tilearray
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   get_service
+   register_service
+   detect_service_type
+```
+
+Concrete service clients and parsers (`WCSService`, `WMSService`, `WMTSService`, `XYZService`, `BaseService`, `WCSParser`, `WMTSParser`) are **not** part of the advertised public surface — import them from `tilearray.service` / `tilearray.service.wcs` (etc.) only if you need low-level access. Prefer configs + `create_array`. Arrays from `create_array` are north-up (row 0 = north). Mosaic attrs include `crs`, Affine `transform` (`transform_source="mosaic_bbox"`), `band_policy`, and elevation `nodata`/`_FillValue` when the format is GeoTIFF — see {doc}`../how-it-works` for the rioxarray handoff.

{tilearray-0.1.0 → tilearray-0.2.0}/docs/building-docs.md

@@ -24,6 +24,21 @@ make docs-artifacts
 
 That rebuilds How it works diagrams (offline) and live usage-guide mosaics (network, polite presets). Commit updated assets when they change.
 
+## Politeness soak / large-AOI evidence
+
+PR CI stays offline (`not slow and not net`). Live preset soaks are opt-in:
+
+```bash
+# Nightly-scale multi-tile soak (EA + OSM ceilings + fail-loud contract)
+uv run pytest -m soak --timeout=300 --cov-fail-under=0
+
+# Maintainer large-AOI soak (hundreds–thousands of tiles; feeds 0.3 evidence)
+uv run python scripts/soak_large_aoi_presets.py --host both --profile medium
+uv run python scripts/soak_large_aoi_presets.py --host ea --profile large
+```
+
+Design notes live in {doc}`how-it-works` (Politeness evidence). Do not wire large profiles into always-on PR jobs.
+
 ## First open release checklist (`0.1.0`)
 
 Do **not** push the release tag until the items below that need human secrets/clicks are done.

{tilearray-0.1.0 → tilearray-0.2.0}/docs/example-sources.md

@@ -1,11 +1,11 @@
 # Example sources
 
-Public endpoints and thin fetch presets for testing host quirks — **not** a product catalogue. Prefer the presets in {doc}`quickstart` where they apply; use `from_url` for everything else. Stay polite: identifiable User-Agent where required, and do not raise concurrency past a host's documented ceiling.
+Public endpoints and thin fetch presets for testing host quirks — **not** a product catalogue. Prefer `from_url` + `tilearray.fetch_presets` helpers in {doc}`quickstart` where they apply; use bare `from_url` for everything else. Stay polite: identifiable User-Agent where required, and do not raise concurrency past a host's documented ceiling.
 
 ## OpenStreetMap raster tiles (XYZ)
 
-- Template: `https://tile.openstreetmap.org/{z}/{x}/{y}.png`
-- Prefer `XYZConfig.for_openstreetmap(zoom=...)`.
+- Template: `https://tile.openstreetmap.org/{z}/{x}/{y}.png` (`OSM_TILE_TEMPLATE`)
+- Prefer `XYZConfig.from_url(OSM_TILE_TEMPLATE, zoom=..., **osm_fetch_defaults())`.
 - OSMF wants an identifiable User-Agent and polite use — the preset applies fixed limits (max 2 in-flight, ~2 req/s, no AIMD).
 - Open data; include © OpenStreetMap contributors when displaying.
 
@@ -13,7 +13,7 @@ Public endpoints and thin fetch presets for testing host quirks — **not** a pr
 
 - URL: `https://environment.data.gov.uk/spatialdata/lidar-composite-digital-terrain-model-dtm-1m/wcs`
 - CoverageId: `13787b9a-26a4-4775-8523-806d13af58fc__Lidar_Composite_Elevation_DTM_1m`
-- Prefer `WCSConfig.for_ea_dsp(...)` with this coverage id.
+- Prefer `WCSConfig.from_url(url, coverage_id, **ea_dsp_fetch_defaults())` with this coverage id.
 - The CoverageId comes from GetCapabilities (often `UUID__LayerName`) — never assume the URL path slug is the id.
 - Preset AIMD: start 8, ceiling **10**, floor 4, ×0.75 pressure, sustained-403 circuit breaker. For county-scale cold mosaics, keep `max_concurrent_requests` ≤ **10**.
 
@@ -40,8 +40,24 @@ Public endpoints and thin fetch presets for testing host quirks — **not** a pr
 
 ## OS Maps API ZXY (needs key)
 
-- Template: `https://api.os.uk/maps/raster/v1/zxy/Road_3857/{z}/{x}/{y}.png?key=…`
-- Useful for real HTTP 429 throttle behaviour. Attribution required. Do not commit keys.
+- Template (no secret in the URL): `https://api.os.uk/maps/raster/v1/zxy/Road_3857/{z}/{x}/{y}.png`
+- Pass the key via config `params` from the environment — prefer this over `?key=…` in the template:
+
+```python
+import os
+from tilearray import XYZConfig, compute_with_policy, create_array
+from tilearray.types import CRS
+
+config = XYZConfig.from_url(
+    "https://api.os.uk/maps/raster/v1/zxy/Road_3857/{z}/{x}/{y}.png",
+    zoom=10,
+    params={"key": os.environ["OS_MAPS_API_KEY"]},
+)
+da = create_array(config, bbox=(-0.1, 51.4, 0.0, 51.5), crs=CRS.EPSG_4326)
+arr = compute_with_policy(da)
+```
+
+- Useful for real HTTP 429 throttle behaviour. Attribution required. Do not commit keys. Same `params=` / `headers=` pattern covers other keyed or private tile hosts — see {doc}`troubleshooting`.
 
 ## Other XYZ (restricted)
 

{tilearray-0.1.0 → tilearray-0.2.0}/docs/guides/ea-lidar.md

@@ -2,13 +2,13 @@
 
 Fetch a small British National Grid window from the Environment Agency Lidar composite DTM (WCS), plot elevation, and summarise the distribution.
 
-Uses `WCSConfig.for_ea_dsp` (AIMD under a hard ceiling, pressure circuit breaker). Keep large cold mosaics at or below the preset ceiling — higher limits can trip gateway pressure.
+Uses `WCSConfig.from_url(..., **ea_dsp_fetch_defaults())` (AIMD under a hard ceiling, pressure circuit breaker). Keep large cold mosaics at or below the preset ceiling — higher limits can trip gateway pressure.
 
 ## Code
 
 ```python
-from tilearray import compute_with_policy, create_array
-from tilearray.service import WCSConfig
+from tilearray import WCSConfig, compute_with_policy, create_array
+from tilearray.fetch_presets import ea_dsp_fetch_defaults
 from tilearray.types import CRS, Format
 
 wcs_url = (
@@ -19,13 +19,14 @@ coverage_id = (
     "13787b9a-26a4-4775-8523-806d13af58fc__Lidar_Composite_Elevation_DTM_1m"
 )
 
-config = WCSConfig.for_ea_dsp(
+config = WCSConfig.from_url(
     wcs_url,
-    coverage_id=coverage_id,
+    coverage_id,
     crs=CRS.EPSG_27700,
     output_format=Format.GEOTIFF,
     chunk_size=(64, 64),
     resolution=(1.0, 1.0),
+    **ea_dsp_fetch_defaults(),
 )
 
 # ~256 m OSGB window

{tilearray-0.1.0 → tilearray-0.2.0}/docs/guides/gibs-bluemarble.md

@@ -5,7 +5,7 @@ Load a small mid-Atlantic window from NASA GIBS as JPEG RGB tiles. Uses `XYZConf
 ## Code
 
 ```python
-from tilearray import XYZConfig, create_array
+from tilearray import XYZConfig, compute_with_policy, create_array
 from tilearray.types import CRS, Format
 
 template = (
@@ -27,8 +27,9 @@ config = XYZConfig.from_url(
 )
 
 bbox = (-40.0, 20.0, -10.0, 45.0)
-da = create_array(config, bbox, CRS.EPSG_4326, compute=True)
-print(da.shape, da.dims)  # expect (y, x, band) for RGB JPEG
+da = create_array(config, bbox, CRS.EPSG_4326)
+arr = compute_with_policy(da)
+print(arr.shape, arr.dims)  # expect (y, x, band) for RGB JPEG
 ```
 
 ## Result

{tilearray-0.1.0 → tilearray-0.2.0}/docs/guides/osm-london.md

@@ -2,7 +2,7 @@
 
 Load a small slippy-map window, compute it, and plot the mosaic.
 
-Uses `XYZConfig.for_openstreetmap` (identifiable User-Agent, max 2 in-flight, ~2 req/s). Include **© OpenStreetMap contributors** when displaying the imagery.
+Uses `XYZConfig.from_url(OSM_TILE_TEMPLATE, …, **osm_fetch_defaults())` (identifiable User-Agent, max 2 in-flight, ~2 req/s). Include **© OpenStreetMap contributors** when displaying the imagery.
 
 ```{note}
 OSM raster tiles are often **palette PNGs**, so the mosaic may be single-band (grayscale) today. For a full-colour RGB XYZ example see {doc}`gibs-bluemarble`.
@@ -11,18 +11,22 @@ OSM raster tiles are often **palette PNGs**, so the mosaic may be single-band (g
 ## Code
 
 ```python
-from tilearray import XYZConfig, create_array
+from tilearray import XYZConfig, compute_with_policy, create_array
+from tilearray.fetch_presets import OSM_TILE_TEMPLATE, osm_fetch_defaults
 from tilearray.types import CRS, Format
 
-config = XYZConfig.for_openstreetmap(
+config = XYZConfig.from_url(
+    OSM_TILE_TEMPLATE,
     zoom=16,
     output_format=Format.PNG,
     chunk_size=(256, 256),
+    **osm_fetch_defaults(),
 )
 
 bbox = (-0.005, 51.495, 0.005, 51.505)  # ~central London
-da = create_array(config, bbox, CRS.EPSG_4326, compute=True)
-print(da.shape, da.dims, da.attrs["service_type"])
+da = create_array(config, bbox, CRS.EPSG_4326)
+arr = compute_with_policy(da)
+print(arr.shape, arr.dims, da.attrs["service_type"])
 ```
 
 ## Result