Add create_test_data to public testing API

[TomNicholas]

• Closes Is create_test_data() public API? #2686 and Add simple array creation functions for easier unit testing #1839
• Fully documented, including whats-new.rst for all changes and api.rst for new API

[max-sixty]

Thanks @TomNicholas 🙏

[shoyer]

I am slightly reluctant about this because it would mean effectively freezing the output of this helper function. I guess that would probably be OK, but the design was never quite fully considered!

[max-sixty]

it would mean effectively freezing the output of this helper function

We could add a param or version arg so we can make changes in the future, if this is a concern?

[TomNicholas]

it would mean effectively freezing the output of this helper function

Or we could have a public create_example_data, and an internal create_test_data? That way to begin with create_example_data is just an alias to the internal create_test_data, but if we end up needing to change the internal one (to test for some new type of common indexing edge case for example) then we can just separate them?

[shoyer]

Why not just encourage users to copy/paste the helper function into their own codebases? This seems like a pretty good use case for copy/paste.

Otherwise -- maybe we should think a little more carefully about what to include on the result. Or require explicitly providing a name for the desired dataset structure? E.g., xarray.testing.dummy_dataset('some_name')

[TomNicholas]

Why not just encourage users to copy/paste the helper function into their own codebases?

Just because they aren't going to know it exists unless we put it in a public place I suppose?

Happy to do any of those things, I just think that having some kind of public function/copyable code example etc is a simple thing for us to do that will make it just a bit easier for users who want to build upon xarray.

[shoyer]

I think putting an example that can be copied/pasted somewhere on the docs in the "extending xarray" section would be a nice way to solve this.

…

On Mon, Jan 21, 2019 at 11:18 AM Tom Nicholas ***@***.***> wrote: Why not just encourage users to copy/paste the helper function into their own codebases? Just because they aren't going to know it exists unless we put it in a public place I suppose? Happy to do any of those things, I just think that having some kind of public function/copyable code example etc is a simple thing for us to do that will make it just a bit easier for users who want to build upon xarray. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#2690 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABKS1vAzMMaKanBeW4AkUylnB7YqMg4Jks5vFaHogaJpZM4aHs0n> .

[max-sixty]

The reason I had liked this was that I'm often creating a dataset manually, either in a repl or as a fixture in a test, and that added an overhead in both time and reduced consistency.
I recently started using the tutorial data, but that requires a network connection (and I kept forgetting the name...)

But I can empathize re compatibility issues; I defer to @shoyer on the balance, or whether xarray.testing.dummy_dataset('some_name') would be feasible

[shoyer]

Maybe having a simple example available under just xarray.testing.dummy_dataset() is a good idea after all. If we do ever want to change it for xarray's own testing purposes, that would be quite easy.

That said... if we're going to emesh this in our API lets at least think a little bit to make sure we cover most of the special cases we care about. I think we cover most of the dtypes we care about, but let's also add at least:

• Some global attributes
• A scalar data variable (it's easy to forget about these)

Anything else?

We might also consider tweaking the names -- dim1, dim2 and dim3 is not very descriptive. Even x, y and z would be better.

[max-sixty]

The only other features I could imagine adding would be a coord over multiple dimensions, and a multi-indexed dimension (but potentially we leave the latter out until we're completely confident about the conventions)

Agree on the names!

@TomNicholas if you want to split this up at all lmk

[stale]

In order to maintain a list of currently relevant issues, we mark issues as stale after a period of inactivity

If this issue remains relevant, please comment here or remove the stale label; otherwise it will be marked as closed automatically

[keewis]

this has been unintentionally closed while renaming main, probably because the feature branch was removed. Feel free to reopen if you want to work on this in the future.