Add list_templates() to discover from_template names#3536
Merged
Conversation
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
commented
Jun 26, 2026
brendancol
left a comment
Contributor
Author
There was a problem hiding this comment.
PR Review: Add list_templates() to discover from_template names
Blockers
None.
Suggestions
None.
Nits
xrspatial/templates.py:202and:238-242keep the kind names in two places: the_TEMPLATE_KINDStuple feeds the error message, while the validation checkskind not in groups. Add a fourth group togroupsand forget the tuple, and the error message goes stale. Building the message fromtuple(groups)and dropping_TEMPLATE_KINDSremoves the drift.
What looks good
- Every name the helper returns is a real
from_templateargument, and the tests check that directly:test_list_templates_groupedcompares against the sorted registry keys, andtest_list_templates_names_resolvebuilds 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_templatesout 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
commented
Jun 26, 2026
brendancol
left a comment
Contributor
Author
There was a problem hiding this comment.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
from_templateaccepts 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 addslist_templates()to fill that gap.list_templates()returns the accepted names grouped intoregions,cities, andcountries, each a sorted list.list_templates(kind)returns one group's list; a badkindraisesValueError.from_templateargument (regions/cities lowercase, countries uppercase ISO-3166 / GADM alpha-3).Available as both
xrspatial.list_templates(next tofrom_template) andxrspatial.templates.list_templates.Backends
No backend dimension.
list_templatesreturns plain lists and dicts of strings, not arrays.from_templateis unchanged.Test plan
list_templates()keys are exactlyregions/cities/countries, each equal to the sorted registry keyskindfilter returns the right sorted list; invalidkindraisesfrom_templatelist_templatestest_templates.pypasses (63 tests), flake8 cleanCloses #3535