Documentation on accessors?

[achapkowski]

I would like to extend the XArray library, but before I start, I am looking for more information. With Panda's Accessor pattern and DataArray, there was a defined pattern to extend the API.

What methods and properties must be implemented in DataArray to assure it works properly? Is there a full template/example of doing this?

http://xarray.pydata.org/en/stable/internals.html#extending-xarray documentation seems to say you can create a DataSet, but doesn't show what is required for a dataset. Is there a module I can look at in the repository to show how this is done?

[TomNicholas]

What methods and properties must be implemented in DataArray to assure it works properly?

You don't really need to implement anything, you're effectively just adding new methods and properties to the class, you don't need to reimplement anything which is already there.

@xarray.register_dataset_accessor('example')
class ExampleDataArrayAccessor():
    def __init__(self, da):
        pass

    def hello_world(self):
        print("hello world!")

ds = xr.Dataset({'longitude': np.linspace(0, 10), 'latitude': np.linspace(0, 20)})
ds.example.hello_world()

hello world!

Is there a full template/example of doing this?

You've linked to the only example current in the official documentation. (I think there should be more examples.) However I found reading the discussion and examples in this issue thread pretty helpful.

Also I have a very simple example of creating a dataset accessor here.

[dcherian]

@achapkowski We would appreciate it if you could suggest changes that would make the documentation less confusing.

[achapkowski]

@dcherian A non-trivial example would help for both types of accessor patterns would help a lot and the best practice defined by the dev team on how to extend the API when needed.

[dcherian]

http://xarray.pydata.org/en/stable/internals.html#extending-xarray
There seems to be a misunderstanding. The docs say that defining an accessor is equivalent to defining an additional property of the Dataset class, so you don't have to recreate DataArray or Dataset. You just need to use register_dataarray_accessor and register_dataset_accessor as in that example.

What about that example isn't clear enough? Would it help if the example in @TomNicholas's comment above was added to the documentation?