From 0e0d42c3570e4e99ef38361c61f0c607907b6446 Mon Sep 17 00:00:00 2001 From: Stephan Hoyer Date: Wed, 3 Jul 2019 20:24:37 -0700 Subject: [PATCH] Add FAQ entry clarifying what parts of xarray are public API (#3075) xref https://github.com/Unidata/MetPy/issues/1077 --- doc/api.rst | 2 ++ doc/faq.rst | 19 +++++++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/doc/api.rst b/doc/api.rst index 03e7f6766ea..ac87d3e6a73 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -8,6 +8,8 @@ This page provides an auto-generated summary of xarray's API. For more details and examples, refer to the relevant chapters in the main part of the documentation. +See also: :ref:`public api`_. + Top-level functions =================== diff --git a/doc/faq.rst b/doc/faq.rst index 465a5a6d250..22a4f6cf095 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -212,3 +212,22 @@ would certainly appreciate it. We recommend two citations. doi = {10.5281/zenodo.59499}, url = {https://doi.org/10.5281/zenodo.59499} } + +.. _public api: + +What parts of xarray are considered public API? +----------------------------------------------- + +As a rule, only functions/methods documented in our :ref:`api` are considered +part of xarray's public API. Everything else (in particular, everything in +``xarray.core`` that is not also exposed in the top level ``xarray`` namespace) +is considered a private implementation detail that may change at any time. + +Objects that exist to facilitate xarray's fluent interface on ``DataArray`` and +``Dataset`` objects are a special case. For convenience, we document them in +the API docs, but only their methods and the ``DataArray``/``Dataset`` +methods/properties to construct them (e.g., ``.plot()``, ``.groupby()``, +``.str``) are considered public API. Constructors and other details of the +internal classes used to implemented them (i.e., +``xarray.plot.plotting._PlotMethods``, ``xarray.core.groupby.DataArrayGroupBy``, +``xarray.core.accessor_str.StringAccessor``) are not.