feat(python): expand layer management and headless camera API (#1770)

* feat(python): expand layer management and headless camera API

Scripting a map from Python needed a browser round trip or a raw project
dict for common tasks: reordering, duplicating, renaming layers, reading
attribute values, and moving the camera. These now work as plain project
mutations on Map and Layer, and the project authoring helpers are exported
from the top-level package for scripts that never display a widget.

* Address review feedback

- Route Map._resolve_layer through authoring.find_layer so scripting and the
  MCP tools agree on what a layer reference means: id first, then exact name,
  then case-insensitive, with a duplicated name raising instead of silently
  picking one. Now that remove_layer accepts names, an arbitrary pick would
  delete the wrong layer.
- Validate duplicate_layer's explicit name against the reserved basemap
  pseudo-id, which rename_layer already rejects via update_layer.
- Route set_center through authoring.set_view so a manual recenter clears the
  bbox fit_project_bounds recorded, instead of leaving a stale extent behind.
- Make Layer.index raise the documented ValueError for a removed handle rather
  than a bare StopIteration, matching the other accessors.
- Add Map.bearing and Map.pitch read properties so every camera setter has a
  matching getter.
- Correct the move_layer docstring: negative values follow sequence indexing,
  not list.insert semantics.
- Sort __version__ into __all__ (RUF022) and make the README layer-handle
  example self-contained.

* Address CodeRabbit review feedback

- Bind the bare `duplicate.index` access to `_` so the statement reads as a
  deliberate property evaluation rather than dead code.
- Match on the reserved-name message instead of accepting any ValueError, so
  the test cannot pass on an unrelated failure.

* Address Claude review feedback

- Route duplicate_layer through authoring.add_layer instead of reaching into
  the private _reject_reserved_name, and reject a blank explicit name rather
  than silently substituting the auto-generated one, matching the Map.name
  setter.
- Stop deep-copying the whole project in describe(): copy the small summary
  instead, which detaches the live mapView it returns without duplicating
  every inlined GeoJSON blob to report a feature count.
- Document that remove_layer now raises on an unresolved or ambiguous
  reference, where it used to be a silent no-op.
- Cover move_layer's negative-index semantics, which differ from
  list.insert(-1, ...) and are easy to reintroduce a bug in.

* Address Claude review feedback

- Strip an explicit duplicate_layer name before storing it, matching the
  Map.name setter, so "  Clone  " does not become a padded name that is
  awkward to reference back.
- Document that the copy is appended to the draw order rather than placed
  next to its source, which was previously unstated either way.

* Address Claude review feedback

- Sweep credentials from Layer.source and Layer.data. Both hand a layer record
  straight to a caller, and a notebook auto-displays whatever a cell returns,
  so a source built with request_headers or a signed URL would print its
  secrets into an output that often gets committed. Factored the per-layer
  sweep redact_credentials already ran into project.redact_layer so the two
  paths cannot drift.
- Reject a blank name in rename_layer (and so in the Layer.name setter, which
  delegates to it); authoring.update_layer guards only the reserved basemap
  pseudo-id. Shares one _clean_layer_name helper with duplicate_layer.
- List the bearing and pitch read properties in the README table.

* Address Claude review feedback

- Redact Map.basemap the way Layer.source is redacted. MapTiler and Stadia put
  an API key in the style URL itself, so reading it back in a notebook printed
  the key; project.redact_url is the public entry point for the sweep
  redact_credentials already applied to that field.
- Document that Layer.data copies an inlined geojson blob whole, and point at
  properties()/describe() for the cases a summary covers.

* Address Claude review feedback

Redact URLs in layer_summary and describe_project rather than at the Map.describe
call site. A summary exists to be shown, and both callers show it somewhere
untrusted: a notebook cell that often gets committed, and an MCP tool result that
goes to a model client. Fixing it in authoring.py closes the same gap in the MCP
server's describe_project tool and keeps the one-place-per-change layering the
repo documents.

Author: giswqs

python/README.md

@@ -86,9 +86,46 @@ m.to_project()["mapView"]["center"]
 | `set_center_zoom(lng, lat, zoom=None)` | Alias of `set_center` (leafmap compatibility). |
 | `zoom_to_bounds(bounds)` / `zoom_to_layer(layer)` | Fit the view to bounds or a layer id/name/handle. |
 | `layer_names` / `find_layer(name)` / `set_layer_visibility` / `set_layer_opacity` | Inspect and update layers conveniently. |
-| `remove_layer(layer_id)` / `clear_layers()` | Remove layers. |
+| `rename_layer` / `move_layer` / `duplicate_layer` / `show_layer` / `hide_layer` | Manage layers by id, name, or `Layer` handle. |
+| `layer_properties(layer)` / `column_values(layer, column)` / `describe()` | Inspect inlined data and summarize a project without a browser round trip. |
+| `remove_layer(layer)` / `clear_layers()` | Remove one layer by id, name, or handle, or remove all layers. |
+| `center` / `zoom` / `bearing` / `pitch` / `basemap` / `name` | Read persisted project and camera state; `name` is writable. |
+| `set_zoom` / `set_bearing` / `set_pitch` / `fit_project_bounds` | Persist camera changes without requiring the widget to be displayed. |
 | `to_project()` / `load_project(src)` / `save_project(path)` | Project I/O. |
 
+Layer handles provide the same operations in an object-oriented form:
+
+```python
+m.add_geojson("https://example.com/roads.geojson", name="Roads")
+
+roads = m.find_layer("Roads")  # None when no layer has that name
+roads.opacity = 0.6
+roads.set_style(lineColor="#e63946", lineWidth=3)
+roads.move(0)
+
+print(roads.properties())      # sampled values for every property
+print(roads.column("highway")) # one value per feature
+roads_copy = roads.duplicate(name="Roads (proposed)")
+```
+
+For headless authoring and scripts that do not need a widget, commonly used
+project utilities are available directly from the top-level package:
+
+```python
+from geolibre import (
+    basemap_catalog,
+    builtin_legend_names,
+    color_ramp_names,
+    describe_project,
+    load_project,
+    save_project,
+)
+
+project = load_project("my-map.geolibre.json")
+print(describe_project(project))
+save_project("copy.geolibre.json", project)
+```
+
 ## Notes
 
 - The bundled app is served from a localhost HTTP server, so the interactive

python/src/geolibre/__init__.py

@@ -2,10 +2,29 @@
 
 from typing import Any
 
+from .authoring import (
+    basemap_catalog,
+    color_ramp_names,
+    describe_project,
+    load_project,
+    save_project,
+)
 from .geolibre import Feature, Layer, Map
+from .legends import builtin_legend_names
 
 __version__ = "2.5.0"
-__all__ = ["Feature", "Layer", "Map", "__version__"]
+__all__ = [
+    "Feature",
+    "Layer",
+    "Map",
+    "__version__",
+    "basemap_catalog",
+    "builtin_legend_names",
+    "color_ramp_names",
+    "describe_project",
+    "load_project",
+    "save_project",
+]
 
 
 def _jupyter_server_extension_points() -> list[dict[str, str]]:

python/src/geolibre/authoring.py

@@ -220,7 +220,10 @@ def layer_summary(layer: dict[str, Any]) -> dict[str, Any]:
     """Summarize one layer for display, omitting any inlined data.
 
     A GeoJSON layer's ``geojson`` blob can be tens of megabytes, so it is
-    reported as a feature count rather than echoed back.
+    reported as a feature count rather than echoed back. The source URL is
+    reported with its credentials stripped: a summary exists to be shown, and
+    both callers show it somewhere untrusted (a notebook cell that gets
+    committed, an MCP tool result that goes to a model client).
 
     Args:
         layer: A layer dict.
@@ -239,7 +242,7 @@ def layer_summary(layer: dict[str, Any]) -> dict[str, Any]:
     if isinstance(source, dict):
         url = source.get("url") or (source.get("tiles") or [None])[0]
         if url:
-            summary["source"] = url
+            summary["source"] = _project.redact_url(str(url))
     geojson = layer.get("geojson")
     if isinstance(geojson, dict):
         features = geojson.get("features")
@@ -257,6 +260,9 @@ def layer_summary(layer: dict[str, Any]) -> dict[str, Any]:
 def describe_project(project: dict[str, Any]) -> dict[str, Any]:
     """Summarize a project: its camera, basemap, layers, and map controls.
 
+    URLs come back with their credentials stripped, as in :func:`layer_summary`;
+    several basemap providers put an API key in the style URL itself.
+
     Args:
         project: The project dict.
 
@@ -279,11 +285,14 @@ def describe_project(project: dict[str, Any]) -> dict[str, Any]:
             components = settings.get(_project.COMPONENTS_PLUGIN_ID)
             if isinstance(components, dict):
                 controls.extend(key for key in ("legend", "colorbar") if key in components)
+    basemap_url = project.get("basemapStyleUrl")
     return {
         "name": project.get("name"),
         "version": project.get("version"),
         "mapView": project.get("mapView"),
-        "basemapStyleUrl": project.get("basemapStyleUrl"),
+        "basemapStyleUrl": (
+            _project.redact_url(str(basemap_url)) if basemap_url is not None else basemap_url
+        ),
         "layerCount": len(layers_of(project)),
         "layers": [layer_summary(layer) for layer in layers_of(project) if isinstance(layer, dict)],
         "mapControls": controls,