Skip to content

Add list_templates() to discover from_template names#3536

Merged
brendancol merged 2 commits into
mainfrom
issue-3535
Jun 26, 2026
Merged

Add list_templates() to discover from_template names#3536
brendancol merged 2 commits into
mainfrom
issue-3535

Conversation

@brendancol

Copy link
Copy Markdown
Contributor

Summary

from_template accepts curated regions, world cities, and country codes, but the names live in private dicts (_REGIONS, _CITIES, _COUNTRY_BBOXES). Short of reading the source, there was no supported way to find out what's available. This adds list_templates() to fill that gap.

  • list_templates() returns the accepted names grouped into regions, cities, and countries, each a sorted list.
  • list_templates(kind) returns one group's list; a bad kind raises ValueError.
  • Every name it returns is a valid from_template argument (regions/cities lowercase, countries uppercase ISO-3166 / GADM alpha-3).
  • The unknown-name error and the templates reference doc now point at the helper.

Available as both xrspatial.list_templates (next to from_template) and xrspatial.templates.list_templates.

Backends

No backend dimension. list_templates returns plain lists and dicts of strings, not arrays. from_template is unchanged.

Test plan

  • list_templates() keys are exactly regions/cities/countries, each equal to the sorted registry keys
  • kind filter returns the right sorted list; invalid kind raises
  • every listed name builds via from_template
  • unknown-name error mentions list_templates
  • full test_templates.py passes (63 tests), flake8 clean

Closes #3535

Expose a public helper that returns the names from_template accepts,
grouped into regions / cities / countries (or filtered by kind). Point
the unknown-name error and the templates reference at it.

Closes #3535

@brendancol brendancol left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR Review: Add list_templates() to discover from_template names

Blockers

None.

Suggestions

None.

Nits

  • xrspatial/templates.py:202 and :238-242 keep the kind names in two places: the _TEMPLATE_KINDS tuple feeds the error message, while the validation checks kind not in groups. Add a fourth group to groups and forget the tuple, and the error message goes stale. Building the message from tuple(groups) and dropping _TEMPLATE_KINDS removes the drift.

What looks good

  • Every name the helper returns is a real from_template argument, and the tests check that directly: test_list_templates_grouped compares against the sorted registry keys, and test_list_templates_names_resolve builds one from each group. That's the contract that matters.
  • The unknown-name error and the reference doc both point at the helper now, which is what the issue asked for.
  • Leaving list_templates out of the README backend matrix is right. It returns plain strings, no backend behavior to track.

Checklist

  • Algorithm matches reference: N/A (registry listing)
  • Backend parity: N/A (no backend dimension)
  • NaN handling: N/A
  • Edge cases covered by tests: yes (invalid kind, every group resolves)
  • Dask chunk boundaries: N/A
  • No premature materialization: yes
  • Benchmark: not needed (dict lookup)
  • README feature matrix updated: yes (folded into the from_template row)
  • Docstrings present and accurate: yes

@brendancol brendancol left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up review

The single nit from the first pass is resolved in 2b9c6a4: dropped the _TEMPLATE_KINDS constant and the error message now reads its options from tuple(groups), so the message can't drift from the actual groups.

No new issues. Tests still pass (9 list_templates/error tests green, flake8 clean). Nothing else outstanding.

@brendancol brendancol merged commit 3f11388 into main Jun 26, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Expose a public way to list available from_template names (regions + cities)

1 participant