Skip to content

DOC: Explicitly include "private" ExtensionArray methods in API docs #27279

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jul 15, 2019
Merged

DOC: Explicitly include "private" ExtensionArray methods in API docs #27279

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ab4879b
Adding explicit list of ExtensionArray methods to docstring.
tadeja Jul 7, 2019
4db99f1
Typo.
tadeja Jul 8, 2019
e8c5df7
Adding explicit list of ExtensionArray methods and attributes to exte…
tadeja Jul 8, 2019
45d70bb
Adding more documentation for private ExtensionArray methods.
tadeja Jul 10, 2019
016289d
Fixing Docstring validation errors for the added private EA methods.
tadeja Jul 11, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 35 additions & 1 deletion doc/source/reference/extensions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,44 @@ objects.
api.extensions.register_series_accessor
api.extensions.register_index_accessor
api.extensions.ExtensionDtype
api.extensions.ExtensionArray

.. autosummary::
:toctree: api/
:template: autosummary/class_without_autosummary.rst

api.extensions.ExtensionArray
arrays.PandasArray

.. We need this autosummary so that methods and attributes are generated.
.. Separate block, since they aren't classes.

.. autosummary::
:toctree: api/

api.extensions.ExtensionArray._concat_same_type
api.extensions.ExtensionArray._formatter
api.extensions.ExtensionArray._formatting_values
api.extensions.ExtensionArray._from_factorized
api.extensions.ExtensionArray._from_sequence
api.extensions.ExtensionArray._from_sequence_of_strings
api.extensions.ExtensionArray._ndarray_values
api.extensions.ExtensionArray._reduce
api.extensions.ExtensionArray._values_for_argsort
api.extensions.ExtensionArray._values_for_factorize
api.extensions.ExtensionArray.argsort
api.extensions.ExtensionArray.astype
api.extensions.ExtensionArray.copy
api.extensions.ExtensionArray.dropna
api.extensions.ExtensionArray.factorize
api.extensions.ExtensionArray.fillna
api.extensions.ExtensionArray.isna
api.extensions.ExtensionArray.ravel
api.extensions.ExtensionArray.repeat
api.extensions.ExtensionArray.searchsorted
api.extensions.ExtensionArray.shift
api.extensions.ExtensionArray.take
api.extensions.ExtensionArray.unique
api.extensions.ExtensionArray.dtype
api.extensions.ExtensionArray.nbytes
api.extensions.ExtensionArray.ndim
api.extensions.ExtensionArray.shape
62 changes: 53 additions & 9 deletions pandas/core/arrays/base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,39 @@ class ExtensionArray:

.. versionadded:: 0.23.0

Attributes
----------
dtype
nbytes
ndim
shape

Methods
-------
argsort
astype
copy
dropna
factorize
fillna
isna
ravel
repeat
searchsorted
shift
take
unique
_concat_same_type
_formatter
_formatting_values
_from_factorized
_from_sequence
_from_sequence_of_strings
_ndarray_values
_reduce
_values_for_argsort
_values_for_factorize

Notes
-----
The interface includes the following abstract methods that must be
Expand Down Expand Up @@ -170,7 +203,6 @@ def _from_sequence_of_strings(cls, strings, dtype=None, copy=False):
Returns
-------
ExtensionArray

"""
raise AbstractMethodError(cls)

Expand All @@ -188,7 +220,7 @@ def _from_factorized(cls, values, original):

See Also
--------
pandas.factorize
factorize
ExtensionArray.factorize
"""
raise AbstractMethodError(cls)
Expand Down Expand Up @@ -654,7 +686,7 @@ def factorize(self, na_sentinel: int = -1) -> Tuple[np.ndarray, ABCExtensionArra

See Also
--------
pandas.factorize : Top-level factorize method that dispatches here.
factorize : Top-level factorize method that dispatches here.

Notes
-----
Expand Down Expand Up @@ -778,18 +810,18 @@ def take(
When `indices` contains negative values other than ``-1``
and `allow_fill` is True.

See Also
--------
numpy.take
api.extensions.take
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you leave the pandas. here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jorisvandenbossche
I've removed pandas. to resolve the Docstring validation error. From CI:

pandas/core/arrays/base.py(770,): error SA05: pandas.api.extensions.ExtensionArray.take: pandas.api.extensions.take in `See Also` section does not need `pandas` prefix, use api.extensions.take instead.

What do you recommend to do?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I dislike this listing rule in this case. I believe it's to ensure we consistently do things like DataFrame.merge instead of pandas.DataFrame.merge.

But I think the (redundant) namespacing here is helpful here since I wouldn't immediately associate api... with pandas.api....

Regardless, for now we can just please the linter.


Notes
-----
ExtensionArray.take is called by ``Series.__getitem__``, ``.loc``,
``iloc``, when `indices` is a sequence of values. Additionally,
it's called by :meth:`Series.reindex`, or any other method
that causes realignment, with a `fill_value`.

See Also
--------
numpy.take
pandas.api.extensions.take

Examples
--------
Here's an example implementation, which relies on casting the
Expand Down Expand Up @@ -862,7 +894,7 @@ def _formatter(self, boxed: bool = False) -> Callable[[Any], Optional[str]]:

Parameters
----------
boxed: bool, default False
boxed : bool, default False
An indicated for whether or not your array is being printed
within a Series, DataFrame, or Index (True), or just by
itself (False). This may be useful if you want scalar values
Expand All @@ -889,6 +921,10 @@ def _formatting_values(self) -> np.ndarray:
.. deprecated:: 0.24.0

Use :meth:`ExtensionArray._formatter` instead.

Returns
-------
array : ndarray
"""
return np.array(self)

Expand All @@ -904,6 +940,10 @@ def ravel(self, order="C") -> ABCExtensionArray:
----------
order : {None, 'C', 'F', 'A', 'K'}, default 'C'

Returns
-------
ExtensionArray

Notes
-----
- Because ExtensionArrays are 1D-only, this is a no-op.
Expand Down Expand Up @@ -944,6 +984,10 @@ def _ndarray_values(self) -> np.ndarray:

The expectation is that this is cheap to compute, and is primarily
used for interacting with our indexers.

Returns
-------
array : ndarray
"""
return np.array(self)

Expand Down
4 changes: 2 additions & 2 deletions pandas/core/indexes/category.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -306,12 +306,12 @@ def _is_dtype_compat(self, other):

def equals(self, other):
"""
Determine if two CategorialIndex objects contain the same elements.
Determine if two CategoricalIndex objects contain the same elements.

Returns
-------
bool
If two CategorialIndex objects have equal elements True,
If two CategoricalIndex objects have equal elements True,
otherwise False.
"""
if self.is_(other):
Expand Down