Repository navigation
Improve discoverability of index build options #8002
Description
Is your feature request related to a problem?
Currently Dataset.set_xindex(coord_names, index_cls=None, **options) allows passing index build options (if any) via the **options arguments. Those options are not easily discoverable, though (no auto-completion, etc.).
Describe the solution you'd like
What about something like this?
ds.set_xindex("x", MyCustomIndex.with_options(foo=1, bar=True))
# or
ds.set_xindex("x", *MyCustomIndex.with_options(foo=1, bar=True))This would require adding a .with_options() class method that can be overridden in Index subclasses (optional):
# xarray.core.indexes
class Index:
@classmethod
def with_options(cls) -> tuple[type[Self], dict[str, Any]]:
return cls, {}# third-party code
from xarray.indexes import Index
class MyCustomIndex(Index):
@classmethod
def with_options(cls, foo: int = 0, bar: bool = False) -> tuple[type[Self], dict[str, Any]]:
"""Set a new MyCustomIndex with options.
Parameters
------------
foo : int, optional
The foo option (default: 1).
bar : bool, optional
The bar option (default: False).
"""
return cls, {"foo": foo, "bar": bar}Thoughts?
Describe alternatives you've considered
Build options are also likely defined in the Index constructor, e.g.,
# third-party code
from xarray.indexes import Index
class MyCustomIndex(Index):
def __init__(self, data, foo=0, bar=False):
...However, the Index constructor is not public API (only used internally and indirectly in Xarray when setting a new index from existing coordinates).
Any other idea?
Additional context
No response
Activity
TomNicholas commentedon Jul 19, 2023
So if I understand this correctly the advantage of
with_optionsis that is would allow the author of the custom index to define the signature of additional arguments it expects? I think that's useful.I also think it's generally a bit confusing that in all these index examples
__init__is defined but not actually how the index is first created. I understand why, but the intended patterns could be more clearly documented.benbovy commentedon Jul 19, 2023
Yes and it would expose the signature directly to the users of the index (type checking, auto-completion, etc.).
Yeah this may be confusing I agree. And I also agree about clarifying it in the documentation.