From 34ba548450df2561561b8ea8931a29ec060b368b Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 22 Mar 2018 11:34:26 +0100 Subject: [PATCH] DOC: general docstring formatting fixes (#20449) --- pandas/core/base.py | 1 + pandas/core/frame.py | 2 -- pandas/core/generic.py | 20 +++++++++++--------- pandas/core/indexes/base.py | 11 ++++++----- pandas/core/indexes/datetimelike.py | 16 ++++++---------- pandas/core/reshape/tile.py | 2 +- 6 files changed, 25 insertions(+), 27 deletions(-) diff --git a/pandas/core/base.py b/pandas/core/base.py index f686975366419..b3eb9a0ae7530 100644 --- a/pandas/core/base.py +++ b/pandas/core/base.py @@ -855,6 +855,7 @@ def min(self): 'a' For a MultiIndex, the minimum is determined lexicographically. + >>> idx = pd.MultiIndex.from_product([('a', 'b'), (2, 1)]) >>> idx.min() ('a', 1) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 081a8b39a3849..cf41737a04ba6 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -5465,8 +5465,6 @@ def _gotitem(self, key, ndim, subset=None): return self[key] _agg_doc = dedent(""" - Notes - ----- The aggregation operations are always performed over an axis, either the index (default) or the column axis. This behavior is different from `numpy` aggregation functions (`mean`, `median`, `prod`, `sum`, `std`, diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 74b760fa4e3c4..bd1a2371315a0 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -1910,20 +1910,20 @@ def to_hdf(self, path_or_buf, key, **kwargs): Identifier for the group in the store. mode : {'a', 'w', 'r+'}, default 'a' Mode to open file: - + - 'w': write, a new file is created (an existing file with - the same name would be deleted). + the same name would be deleted). - 'a': append, an existing file is opened for reading and - writing, and if the file does not exist it is created. + writing, and if the file does not exist it is created. - 'r+': similar to 'a', but the file must already exist. format : {'fixed', 'table'}, default 'fixed' Possible values: - + - 'fixed': Fixed format. Fast writing/reading. Not-appendable, - nor searchable. + nor searchable. - 'table': Table format. Write as a PyTables Table structure - which may perform worse but allow more flexible operations - like searching / selecting subsets of the data. + which may perform worse but allow more flexible operations + like searching / selecting subsets of the data. append : bool, default False For Table formats, append the input data to the existing. data_columns : list of columns or True, optional @@ -5795,10 +5795,11 @@ def replace(self, to_replace=None, value=None, inplace=False, limit=None, * None: (default) no fill restriction * 'inside' Only fill NaNs surrounded by valid values (interpolate). * 'outside' Only fill NaNs outside valid values (extrapolate). - .. versionadded:: 0.21.0 If limit is specified, consecutive NaNs will be filled in this direction. + + .. versionadded:: 0.21.0 inplace : bool, default False Update the NDFrame in place if possible. downcast : optional, 'infer' or None, defaults to None @@ -7717,6 +7718,7 @@ def truncate(self, before=None, after=None, axis=None, copy=True): The index values in ``truncate`` can be datetimes or string dates. + >>> dates = pd.date_range('2016-01-01', '2016-02-01', freq='s') >>> df = pd.DataFrame(index=dates, data={'A': 1}) >>> df.tail() @@ -7960,7 +7962,7 @@ def abs(self): 0 1 days dtype: timedelta64[ns] - Select rows with data closest to certian value using argsort (from + Select rows with data closest to certain value using argsort (from `StackOverflow `__). >>> df = pd.DataFrame({ diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 95bfc8bfcb5c5..40f543e211f0c 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -1,6 +1,7 @@ from datetime import datetime, timedelta import warnings import operator +from textwrap import dedent import numpy as np from pandas._libs import (lib, index as libindex, tslib as libts, @@ -2183,7 +2184,7 @@ def isna(self): mapped to ``True`` values. Everything else get mapped to ``False`` values. Characters such as empty strings `''` or :attr:`numpy.inf` are not considered NA values - (unless you set :attr:`pandas.options.mode.use_inf_as_na` `= True`). + (unless you set ``pandas.options.mode.use_inf_as_na = True``). .. versionadded:: 0.20.0 @@ -4700,7 +4701,7 @@ def _add_logical_methods(cls): %(outname)s : bool or array_like (if axis is specified) A single element array_like may be converted to bool.""" - _index_shared_docs['index_all'] = """ + _index_shared_docs['index_all'] = dedent(""" See Also -------- @@ -4738,9 +4739,9 @@ def _add_logical_methods(cls): >>> pd.Index([0, 0, 0]).any() False - """ + """) - _index_shared_docs['index_any'] = """ + _index_shared_docs['index_any'] = dedent(""" See Also -------- @@ -4761,7 +4762,7 @@ def _add_logical_methods(cls): >>> index = pd.Index([0, 0, 0]) >>> index.any() False - """ + """) def _make_logical_function(name, desc, f): @Substitution(outname=name, desc=desc) diff --git a/pandas/core/indexes/datetimelike.py b/pandas/core/indexes/datetimelike.py index e9011a3eb912c..b906ea0f4784c 100644 --- a/pandas/core/indexes/datetimelike.py +++ b/pandas/core/indexes/datetimelike.py @@ -86,16 +86,12 @@ def strftime(self, date_format): Examples -------- - >>> import datetime - >>> data = pd.date_range(datetime.datetime(2018,3,10,19,27,52), - ... periods=4, freq='B') - >>> df = pd.DataFrame(data, columns=['date']) - >>> df.date[1] - Timestamp('2018-03-13 19:27:52') - >>> df.date[1].strftime('%d-%m-%Y') - '13-03-2018' - >>> df.date[1].strftime('%B %d, %Y, %r') - 'March 13, 2018, 07:27:52 PM' + >>> rng = pd.date_range(pd.Timestamp("2018-03-10 09:00"), + ... periods=3, freq='s') + >>> rng.strftime('%B %d, %Y, %r') + Index(['March 10, 2018, 09:00:00 AM', 'March 10, 2018, 09:00:01 AM', + 'March 10, 2018, 09:00:02 AM'], + dtype='object') """.format("https://docs.python.org/3/library/datetime.html" "#strftime-and-strptime-behavior") diff --git a/pandas/core/reshape/tile.py b/pandas/core/reshape/tile.py index be28f7091712f..118198ea0320d 100644 --- a/pandas/core/reshape/tile.py +++ b/pandas/core/reshape/tile.py @@ -51,7 +51,7 @@ def cut(x, bins, right=True, labels=None, retbins=False, precision=3, right : bool, default True Indicates whether `bins` includes the rightmost edge or not. If ``right == True`` (the default), then the `bins` ``[1, 2, 3, 4]`` - indicate (1,2], (2,3], (3,4]. This argument is ignored when + indicate (1,2], (2,3], (3,4]. This argument is ignored when `bins` is an IntervalIndex. labels : array or bool, optional Specifies the labels for the returned bins. Must be the same length as