From be3e8bb06dea2cc906838086fa08213e2b90b829 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 23 Apr 2018 09:20:22 -0500 Subject: [PATCH 1/5] API: Added extensions to the public API --- pandas/api/extensions/__init__.py | 2 ++ pandas/core/common.py | 5 ++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/pandas/api/extensions/__init__.py b/pandas/api/extensions/__init__.py index 64f5e8fb939a4..cc09204d992d8 100644 --- a/pandas/api/extensions/__init__.py +++ b/pandas/api/extensions/__init__.py @@ -2,3 +2,5 @@ from pandas.core.accessor import (register_dataframe_accessor, # noqa register_index_accessor, register_series_accessor) +from pandas.core.arrays.base import ExtensionArray # noqa +from pandas.core.dtypes.dtypes import ExtensionDtype # noqa diff --git a/pandas/core/common.py b/pandas/core/common.py index c4890dbd39ef1..b9182bfd2cbe2 100644 --- a/pandas/core/common.py +++ b/pandas/core/common.py @@ -14,10 +14,9 @@ from pandas.compat import long, zip, iteritems, PY36, OrderedDict from pandas.core.config import get_option from pandas.core.dtypes.generic import ABCSeries, ABCIndex -from pandas.core.dtypes.common import _NS_DTYPE +from pandas.core.dtypes.common import _NS_DTYPE, is_integer from pandas.core.dtypes.inference import _iterable_not_string from pandas.core.dtypes.missing import isna, isnull, notnull # noqa -from pandas.api import types from pandas.core.dtypes.cast import construct_1d_object_array_from_listlike @@ -570,7 +569,7 @@ def _random_state(state=None): np.random.RandomState """ - if types.is_integer(state): + if is_integer(state): return np.random.RandomState(state) elif isinstance(state, np.random.RandomState): return state From 7d2126088577e281df3dc527264812e665ffaa2a Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 23 Apr 2018 09:20:54 -0500 Subject: [PATCH 2/5] DOC: Added to public API docs --- doc/source/api.rst | 2 ++ doc/source/extending.rst | 12 ++++++------ doc/source/whatsnew/v0.23.0.txt | 2 +- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index e43632ea46bfb..93edd090d846b 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -2549,6 +2549,8 @@ objects. api.extensions.register_dataframe_accessor api.extensions.register_series_accessor api.extensions.register_index_accessor + api.extensions.ExtensionDtype + api.extensions.ExtensionArray .. This is to prevent warnings in the doc build. We don't want to encourage .. these methods. diff --git a/doc/source/extending.rst b/doc/source/extending.rst index b94a43480ed93..474f02744325b 100644 --- a/doc/source/extending.rst +++ b/doc/source/extending.rst @@ -61,7 +61,7 @@ Extension Types .. warning:: - The ``ExtensionDtype`` and ``ExtensionArray`` APIs are new and + The :ref:`pandas.api.extension.ExtensionDtype` and :ref:`pandas.api.extension.ExtensionArray` APIs are new and experimental. They may change between versions without warning. Pandas defines an interface for implementing data types and arrays that *extend* @@ -79,10 +79,10 @@ on :ref:`ecosystem.extensions`. The interface consists of two classes. -``ExtensionDtype`` -^^^^^^^^^^^^^^^^^^ +:ref:`pandas.api.extension.ExtensionDtype` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -An ``ExtensionDtype`` is similar to a ``numpy.dtype`` object. It describes the +An :ref:`pandas.api.extension.ExtensionDtype` is similar to a ``numpy.dtype`` object. It describes the data type. Implementors are responsible for a few unique items like the name. One particularly important item is the ``type`` property. This should be the @@ -91,8 +91,8 @@ extension array for IP Address data, this might be ``ipaddress.IPv4Address``. See the `extension dtype source`_ for interface definition. -``ExtensionArray`` -^^^^^^^^^^^^^^^^^^ +:ref:`pandas.api.extension.ExtensionArray` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This class provides all the array-like functionality. ExtensionArrays are limited to 1 dimension. An ExtensionArray is linked to an ExtensionDtype via the diff --git a/doc/source/whatsnew/v0.23.0.txt b/doc/source/whatsnew/v0.23.0.txt index e19aedac80213..e0515c5213bd4 100644 --- a/doc/source/whatsnew/v0.23.0.txt +++ b/doc/source/whatsnew/v0.23.0.txt @@ -365,7 +365,7 @@ for storing ip addresses. ...: ``IPArray`` isn't a normal 1-D NumPy array, but because it's a pandas -``ExtensionArray``, it can be stored properly inside pandas' containers. +:ref:`~pandas.api.extension.ExtensionArray, it can be stored properly inside pandas' containers. .. code-block:: ipython From 9674091db713e36aedc8f667d50e0c6e2401fd94 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 23 Apr 2018 09:26:18 -0500 Subject: [PATCH 3/5] ref->class --- doc/source/extending.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/extending.rst b/doc/source/extending.rst index 474f02744325b..59e7ee60fe01a 100644 --- a/doc/source/extending.rst +++ b/doc/source/extending.rst @@ -61,7 +61,7 @@ Extension Types .. warning:: - The :ref:`pandas.api.extension.ExtensionDtype` and :ref:`pandas.api.extension.ExtensionArray` APIs are new and + The :class:`pandas.api.extension.ExtensionDtype` and :class:`pandas.api.extension.ExtensionArray` APIs are new and experimental. They may change between versions without warning. Pandas defines an interface for implementing data types and arrays that *extend* @@ -79,10 +79,10 @@ on :ref:`ecosystem.extensions`. The interface consists of two classes. -:ref:`pandas.api.extension.ExtensionDtype` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:class:`pandas.api.extension.ExtensionDtype` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -An :ref:`pandas.api.extension.ExtensionDtype` is similar to a ``numpy.dtype`` object. It describes the +A :class:`pandas.api.extension.ExtensionDtype` is similar to a ``numpy.dtype`` object. It describes the data type. Implementors are responsible for a few unique items like the name. One particularly important item is the ``type`` property. This should be the @@ -91,8 +91,8 @@ extension array for IP Address data, this might be ``ipaddress.IPv4Address``. See the `extension dtype source`_ for interface definition. -:ref:`pandas.api.extension.ExtensionArray` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:class:`pandas.api.extension.ExtensionArray` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This class provides all the array-like functionality. ExtensionArrays are limited to 1 dimension. An ExtensionArray is linked to an ExtensionDtype via the From c52970b2cd54b20b14337b3f4b692cc914fb6b2d Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 23 Apr 2018 09:35:16 -0500 Subject: [PATCH 4/5] Short links in the title --- doc/source/extending.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/extending.rst b/doc/source/extending.rst index 59e7ee60fe01a..f665b219a7bd1 100644 --- a/doc/source/extending.rst +++ b/doc/source/extending.rst @@ -79,8 +79,8 @@ on :ref:`ecosystem.extensions`. The interface consists of two classes. -:class:`pandas.api.extension.ExtensionDtype` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:class:`~pandas.api.extension.ExtensionDtype` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A :class:`pandas.api.extension.ExtensionDtype` is similar to a ``numpy.dtype`` object. It describes the data type. Implementors are responsible for a few unique items like the name. @@ -91,8 +91,8 @@ extension array for IP Address data, this might be ``ipaddress.IPv4Address``. See the `extension dtype source`_ for interface definition. -:class:`pandas.api.extension.ExtensionArray` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:class:`~pandas.api.extension.ExtensionArray` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This class provides all the array-like functionality. ExtensionArrays are limited to 1 dimension. An ExtensionArray is linked to an ExtensionDtype via the From fc3dfaa463fa1729b5c3a1f1f874db5620cd01d0 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 23 Apr 2018 16:14:29 -0500 Subject: [PATCH 5/5] Added shape docstring --- pandas/core/arrays/base.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pandas/core/arrays/base.py b/pandas/core/arrays/base.py index 97a764fa7dbe8..27da3f3750283 100644 --- a/pandas/core/arrays/base.py +++ b/pandas/core/arrays/base.py @@ -222,6 +222,7 @@ def dtype(self): @property def shape(self): # type: () -> Tuple[int, ...] + """Return a tuple of the array dimensions.""" return (len(self),) @property