From 6fcc2efcef50085c62914bba0aed1db281ad0a91 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 16 Mar 2018 18:26:02 +0100 Subject: [PATCH 1/4] DOC: enable docstring on DataFrame.columns/index --- pandas/_libs/properties.pyx | 11 ++++++++--- pandas/core/generic.py | 2 +- pandas/tests/frame/test_api.py | 6 ++++-- pandas/tests/series/test_api.py | 4 +++- 4 files changed, 16 insertions(+), 7 deletions(-) diff --git a/pandas/_libs/properties.pyx b/pandas/_libs/properties.pyx index 67f58851a9a70..8190d3e08fa09 100644 --- a/pandas/_libs/properties.pyx +++ b/pandas/_libs/properties.pyx @@ -42,11 +42,16 @@ cache_readonly = CachedProperty cdef class AxisProperty(object): - cdef: + + cdef readonly: Py_ssize_t axis - def __init__(self, axis=0): + cdef readonly: + object __doc__ + + def __init__(self, axis=0, doc=""): self.axis = axis + self.__doc__ = doc def __get__(self, obj, type): cdef: @@ -54,7 +59,7 @@ cdef class AxisProperty(object): if obj is None: # Only instances have _data, not classes - return None + return self else: axes = obj._data.axes return axes[self.axis] diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 8bab065d8b748..73ba99ac08cbb 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -278,7 +278,7 @@ def _setup_axes(cls, axes, info_axis=None, stat_axis=None, aliases=None, if build_axes: def set_axis(a, i): - setattr(cls, a, properties.AxisProperty(i)) + setattr(cls, a, properties.AxisProperty(i, a)) cls._internal_names_set.add(a) if axes_are_reversed: diff --git a/pandas/tests/frame/test_api.py b/pandas/tests/frame/test_api.py index 8ba5469480e64..b2cbd0b07d7f5 100644 --- a/pandas/tests/frame/test_api.py +++ b/pandas/tests/frame/test_api.py @@ -6,6 +6,7 @@ # pylint: disable-msg=W0612,E1101 from copy import deepcopy +import pydoc import sys from distutils.version import LooseVersion @@ -362,8 +363,9 @@ def test_axis_aliases(self): def test_class_axis(self): # https://github.com/pandas-dev/pandas/issues/18147 - DataFrame.index # no exception! - DataFrame.columns # no exception! + # no exception and no empty docstring + assert pydoc.getdoc(DataFrame.index) + assert pydoc.getdoc(DataFrame.columns) def test_more_values(self): values = self.mixed_frame.values diff --git a/pandas/tests/series/test_api.py b/pandas/tests/series/test_api.py index cf8698bc5ed5e..f7f1ea019a3f0 100644 --- a/pandas/tests/series/test_api.py +++ b/pandas/tests/series/test_api.py @@ -1,6 +1,7 @@ # coding=utf-8 # pylint: disable-msg=E1101,W0612 from collections import OrderedDict +import pydoc import pytest @@ -384,7 +385,8 @@ def test_axis_alias(self): def test_class_axis(self): # https://github.com/pandas-dev/pandas/issues/18147 - Series.index # no exception! + # no exception and no empty docstring + assert pydoc.getdoc(Series.index) def test_numpy_unique(self): # it works! From 10b1f3d3f80c485888d3a2d5288e2df24b422480 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Mon, 19 Mar 2018 13:06:39 +0100 Subject: [PATCH 2/4] fix combine 2 cdefs --- pandas/_libs/properties.pyx | 2 -- 1 file changed, 2 deletions(-) diff --git a/pandas/_libs/properties.pyx b/pandas/_libs/properties.pyx index 8190d3e08fa09..e3f16f224db1c 100644 --- a/pandas/_libs/properties.pyx +++ b/pandas/_libs/properties.pyx @@ -45,8 +45,6 @@ cdef class AxisProperty(object): cdef readonly: Py_ssize_t axis - - cdef readonly: object __doc__ def __init__(self, axis=0, doc=""): From 8a38af69c06acf648f88231defbae10801e4e5c3 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Tue, 20 Mar 2018 13:53:45 +0100 Subject: [PATCH 3/4] Add actual summary lines --- pandas/core/frame.py | 4 +++- pandas/core/generic.py | 4 ++-- pandas/core/panel.py | 3 ++- pandas/core/series.py | 3 ++- 4 files changed, 9 insertions(+), 5 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index d9dbe22dddcdd..1d9971eb24767 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -6788,7 +6788,9 @@ def isin(self, values): DataFrame._setup_axes(['index', 'columns'], info_axis=1, stat_axis=0, - axes_are_reversed=True, aliases={'rows': 0}) + axes_are_reversed=True, aliases={'rows': 0}, + docs={'index': 'The index of the DataFrame.', + 'columns': 'The columns of the DataFrame.'}) DataFrame._add_numeric_operations() DataFrame._add_series_or_dataframe_operations() diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 73ba99ac08cbb..6d9a290af2c08 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -236,7 +236,7 @@ def _constructor_expanddim(self): @classmethod def _setup_axes(cls, axes, info_axis=None, stat_axis=None, aliases=None, slicers=None, axes_are_reversed=False, build_axes=True, - ns=None): + ns=None, docs=None): """Provide axes setup for the major PandasObjects. Parameters @@ -278,7 +278,7 @@ def _setup_axes(cls, axes, info_axis=None, stat_axis=None, aliases=None, if build_axes: def set_axis(a, i): - setattr(cls, a, properties.AxisProperty(i, a)) + setattr(cls, a, properties.AxisProperty(i, docs.get(a, a))) cls._internal_names_set.add(a) if axes_are_reversed: diff --git a/pandas/core/panel.py b/pandas/core/panel.py index 052d555df76f1..5bb4b72a0562d 100644 --- a/pandas/core/panel.py +++ b/pandas/core/panel.py @@ -1523,7 +1523,8 @@ def _extract_axis(self, data, axis=0, intersect=False): stat_axis=1, aliases={'major': 'major_axis', 'minor': 'minor_axis'}, slicers={'major_axis': 'index', - 'minor_axis': 'columns'}) + 'minor_axis': 'columns'}, + docs={}) ops.add_special_arithmetic_methods(Panel) ops.add_flex_arithmetic_methods(Panel) diff --git a/pandas/core/series.py b/pandas/core/series.py index 4d88b4e33b872..37a957568078e 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -3809,7 +3809,8 @@ def to_period(self, freq=None, copy=True): hist = gfx.hist_series -Series._setup_axes(['index'], info_axis=0, stat_axis=0, aliases={'rows': 0}) +Series._setup_axes(['index'], info_axis=0, stat_axis=0, aliases={'rows': 0}, + docs={'index': 'The index of the Series.'}) Series._add_numeric_operations() Series._add_series_only_operations() Series._add_series_or_dataframe_operations() From c9a8a34f64456d0b68aa0b54de720134f1919089 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Tue, 20 Mar 2018 14:35:42 +0100 Subject: [PATCH 4/4] add to api.rst --- doc/source/api.rst | 18 +++++++++++------- pandas/core/frame.py | 5 +++-- pandas/core/series.py | 2 +- 3 files changed, 15 insertions(+), 10 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index dba7f6526f22a..dfb6d03ec9159 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -263,7 +263,11 @@ Constructor Attributes ~~~~~~~~~~ **Axes** - * **index**: axis labels + +.. autosummary:: + :toctree: generated/ + + Series.index .. autosummary:: :toctree: generated/ @@ -845,13 +849,15 @@ Attributes and underlying data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Axes** - * **index**: row labels - * **columns**: column labels +.. autosummary:: + :toctree: generated/ + + DataFrame.index + DataFrame.columns .. autosummary:: :toctree: generated/ - DataFrame.as_matrix DataFrame.dtypes DataFrame.ftypes DataFrame.get_dtype_counts @@ -2546,8 +2552,7 @@ objects. :hidden: generated/pandas.DataFrame.blocks - generated/pandas.DataFrame.columns - generated/pandas.DataFrame.index + generated/pandas.DataFrame.as_matrix generated/pandas.DataFrame.ix generated/pandas.Index.asi8 generated/pandas.Index.data @@ -2566,6 +2571,5 @@ objects. generated/pandas.Series.asobject generated/pandas.Series.blocks generated/pandas.Series.from_array - generated/pandas.Series.index generated/pandas.Series.ix generated/pandas.Timestamp.offset diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 1d9971eb24767..7c0cce55eb021 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -6789,8 +6789,9 @@ def isin(self, values): DataFrame._setup_axes(['index', 'columns'], info_axis=1, stat_axis=0, axes_are_reversed=True, aliases={'rows': 0}, - docs={'index': 'The index of the DataFrame.', - 'columns': 'The columns of the DataFrame.'}) + docs={ + 'index': 'The index (row labels) of the DataFrame.', + 'columns': 'The column labels of the DataFrame.'}) DataFrame._add_numeric_operations() DataFrame._add_series_or_dataframe_operations() diff --git a/pandas/core/series.py b/pandas/core/series.py index 37a957568078e..38fe39e7e3f7b 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -3810,7 +3810,7 @@ def to_period(self, freq=None, copy=True): Series._setup_axes(['index'], info_axis=0, stat_axis=0, aliases={'rows': 0}, - docs={'index': 'The index of the Series.'}) + docs={'index': 'The index (axis labels) of the Series.'}) Series._add_numeric_operations() Series._add_series_only_operations() Series._add_series_or_dataframe_operations()