diff --git a/doc/source/api.rst b/doc/source/api.rst index ce88aed91823c..f3405fcdee608 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -281,6 +281,15 @@ Attributes Series.base Series.T Series.memory_usage + Series.hasnans + Series.flags + Series.empty + Series.dtypes + Series.ftypes + Series.data + Series.is_copy + Series.name + Series.put Conversion ~~~~~~~~~~ @@ -289,9 +298,14 @@ Conversion Series.astype Series.infer_objects + Series.convert_objects Series.copy - Series.isna - Series.notna + Series.bool + Series.to_period + Series.to_timestamp + Series.tolist + Series.get_values + Indexing, iteration ~~~~~~~~~~~~~~~~~~~ @@ -305,6 +319,11 @@ Indexing, iteration Series.iloc Series.__iter__ Series.iteritems + Series.items + Series.keys + Series.pop + Series.item + Series.xs For more information on ``.at``, ``.iat``, ``.loc``, and ``.iloc``, see the :ref:`indexing documentation `. @@ -339,6 +358,8 @@ Binary operator functions Series.ge Series.ne Series.eq + Series.product + Series.dot Function application, GroupBy & Window ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -346,6 +367,7 @@ Function application, GroupBy & Window :toctree: generated/ Series.apply + Series.agg Series.aggregate Series.transform Series.map @@ -353,6 +375,7 @@ Function application, GroupBy & Window Series.rolling Series.expanding Series.ewm + Series.pipe .. _api.series.stats: @@ -397,6 +420,7 @@ Computations / Descriptive Stats Series.std Series.sum Series.var + Series.kurtosis Series.unique Series.nunique Series.is_unique @@ -404,6 +428,10 @@ Computations / Descriptive Stats Series.is_monotonic_increasing Series.is_monotonic_decreasing Series.value_counts + Series.compound + Series.nonzero + Series.ptp + Reindexing / Selection / Label manipulation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -434,12 +462,17 @@ Reindexing / Selection / Label manipulation Series.truncate Series.where Series.mask + Series.add_prefix + Series.add_suffix + Series.filter Missing data handling ~~~~~~~~~~~~~~~~~~~~~ .. autosummary:: :toctree: generated/ + Series.isna + Series.notna Series.dropna Series.fillna Series.interpolate @@ -450,12 +483,20 @@ Reshaping, sorting :toctree: generated/ Series.argsort + Series.argmin + Series.argmax Series.reorder_levels Series.sort_values Series.sort_index Series.swaplevel Series.unstack Series.searchsorted + Series.ravel + Series.repeat + Series.squeeze + Series.view + Series.sortlevel + Combining / joining / merging ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -479,6 +520,10 @@ Time series-related Series.resample Series.tz_convert Series.tz_localize + Series.at_time + Series.between_time + Series.tshift + Series.slice_shift Datetimelike Properties ~~~~~~~~~~~~~~~~~~~~~~~ @@ -635,17 +680,15 @@ strings and apply several methods to it. These can be accessed like Series.cat Series.dt Index.str - MultiIndex.str - DatetimeIndex.str - TimedeltaIndex.str - .. _api.categorical: Categorical ~~~~~~~~~~~ -The dtype of a ``Categorical`` can be described by a :class:`pandas.api.types.CategoricalDtype`. +Pandas defines a custom data type for representing data that can take only a +limited, fixed set of values. The dtype of a ``Categorical`` can be described by +a :class:`pandas.api.types.CategoricalDtype`. .. autosummary:: :toctree: generated/ @@ -653,46 +696,38 @@ The dtype of a ``Categorical`` can be described by a :class:`pandas.api.types.Ca api.types.CategoricalDtype -If the Series is of dtype ``CategoricalDtype``, ``Series.cat`` can be used to change the categorical -data. This accessor is similar to the ``Series.dt`` or ``Series.str`` and has the -following usable methods and properties: - .. autosummary:: :toctree: generated/ - :template: autosummary/accessor_attribute.rst - Series.cat.categories - Series.cat.ordered - Series.cat.codes + api.types.CategoricalDtype.categories + api.types.CategoricalDtype.ordered + +Categorical data can be stored in a :class:`pandas.Categorical` .. autosummary:: :toctree: generated/ - :template: autosummary/accessor_method.rst + :template: autosummary/class_without_autosummary.rst - Series.cat.rename_categories - Series.cat.reorder_categories - Series.cat.add_categories - Series.cat.remove_categories - Series.cat.remove_unused_categories - Series.cat.set_categories - Series.cat.as_ordered - Series.cat.as_unordered + Categorical -To create a Series of dtype ``category``, use ``cat = s.astype("category")``. -The following two ``Categorical`` constructors are considered API but should only be used when -adding ordering information or special categories is need at creation time of the categorical data: +The alternative :meth:`Categorical.from_codes` constructor can be used when you +have the categories and integer codes already: .. autosummary:: :toctree: generated/ - :template: autosummary/class_without_autosummary.rst - Categorical + Categorical.from_codes + +The dtype information is available on the ``Categorical`` .. autosummary:: :toctree: generated/ - Categorical.from_codes + Categorical.dtype + Categorical.categories + Categorical.ordered + Categorical.codes ``np.asarray(categorical)`` works by implementing the array interface. Be aware, that this converts the Categorical back to a numpy array, so categories and order information is not preserved! @@ -702,6 +737,38 @@ the Categorical back to a numpy array, so categories and order information is no Categorical.__array__ +A ``Categorical`` can be stored in a ``Series`` or ``DataFrame``. +To create a Series of dtype ``category``, use ``cat = s.astype(dtype)`` or +``Series(..., dtype=dtype)`` where ``dtype`` is either + +* the string ``'category'`` +* an instance of :class:`~pandas.api.types.CategoricalDtype`. + +If the Series is of dtype ``CategoricalDtype``, ``Series.cat`` can be used to change the categorical +data. This accessor is similar to the ``Series.dt`` or ``Series.str`` and has the +following usable methods and properties: + +.. autosummary:: + :toctree: generated/ + :template: autosummary/accessor_attribute.rst + + Series.cat.categories + Series.cat.ordered + Series.cat.codes + +.. autosummary:: + :toctree: generated/ + :template: autosummary/accessor_method.rst + + Series.cat.rename_categories + Series.cat.reorder_categories + Series.cat.add_categories + Series.cat.remove_categories + Series.cat.remove_unused_categories + Series.cat.set_categories + Series.cat.as_ordered + Series.cat.as_unordered + Plotting ~~~~~~~~ @@ -738,7 +805,6 @@ Serialization / IO / Conversion .. autosummary:: :toctree: generated/ - Series.from_csv Series.to_pickle Series.to_csv Series.to_dict @@ -792,11 +858,14 @@ Attributes and underlying data DataFrame.get_ftype_counts DataFrame.select_dtypes DataFrame.values + DataFrame.get_values DataFrame.axes DataFrame.ndim DataFrame.size DataFrame.shape DataFrame.memory_usage + DataFrame.empty + DataFrame.is_copy Conversion ~~~~~~~~~~ @@ -809,6 +878,7 @@ Conversion DataFrame.copy DataFrame.isna DataFrame.notna + DataFrame.bool Indexing, iteration ~~~~~~~~~~~~~~~~~~~ @@ -821,7 +891,10 @@ Indexing, iteration DataFrame.loc DataFrame.iloc DataFrame.insert + DataFrame.insert DataFrame.__iter__ + DataFrame.items + DataFrame.keys DataFrame.iteritems DataFrame.iterrows DataFrame.itertuples @@ -829,6 +902,7 @@ Indexing, iteration DataFrame.pop DataFrame.tail DataFrame.xs + DataFrame.get DataFrame.isin DataFrame.where DataFrame.mask @@ -851,6 +925,7 @@ Binary operator functions DataFrame.floordiv DataFrame.mod DataFrame.pow + DataFrame.dot DataFrame.radd DataFrame.rsub DataFrame.rmul @@ -875,6 +950,8 @@ Function application, GroupBy & Window DataFrame.apply DataFrame.applymap + DataFrame.pipe + DataFrame.agg DataFrame.aggregate DataFrame.transform DataFrame.groupby @@ -895,6 +972,7 @@ Computations / Descriptive Stats DataFrame.clip DataFrame.clip_lower DataFrame.clip_upper + DataFrame.compound DataFrame.corr DataFrame.corrwith DataFrame.count @@ -907,6 +985,7 @@ Computations / Descriptive Stats DataFrame.diff DataFrame.eval DataFrame.kurt + DataFrame.kurtosis DataFrame.mad DataFrame.max DataFrame.mean @@ -915,6 +994,7 @@ Computations / Descriptive Stats DataFrame.mode DataFrame.pct_change DataFrame.prod + DataFrame.product DataFrame.quantile DataFrame.rank DataFrame.round @@ -923,6 +1003,7 @@ Computations / Descriptive Stats DataFrame.sum DataFrame.std DataFrame.var + DataFrame.nunique Reindexing / Selection / Label manipulation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -932,6 +1013,8 @@ Reindexing / Selection / Label manipulation DataFrame.add_prefix DataFrame.add_suffix DataFrame.align + DataFrame.at_time + DataFrame.between_time DataFrame.drop DataFrame.drop_duplicates DataFrame.duplicated @@ -950,6 +1033,7 @@ Reindexing / Selection / Label manipulation DataFrame.reset_index DataFrame.sample DataFrame.select + DataFrame.set_axis DataFrame.set_index DataFrame.tail DataFrame.take @@ -965,6 +1049,7 @@ Missing data handling DataFrame.dropna DataFrame.fillna DataFrame.replace + DataFrame.interpolate Reshaping, sorting, transposing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -972,6 +1057,7 @@ Reshaping, sorting, transposing :toctree: generated/ DataFrame.pivot + DataFrame.pivot_table DataFrame.reorder_levels DataFrame.sort_values DataFrame.sort_index @@ -980,10 +1066,12 @@ Reshaping, sorting, transposing DataFrame.swaplevel DataFrame.stack DataFrame.unstack + DataFrame.swapaxes DataFrame.melt - DataFrame.T + DataFrame.squeeze DataFrame.to_panel DataFrame.to_xarray + DataFrame.T DataFrame.transpose Combining / joining / merging @@ -1005,6 +1093,8 @@ Time series-related DataFrame.asfreq DataFrame.asof DataFrame.shift + DataFrame.slice_shift + DataFrame.tshift DataFrame.first_valid_index DataFrame.last_valid_index DataFrame.resample @@ -1059,6 +1149,7 @@ Serialization / IO / Conversion DataFrame.from_items DataFrame.from_records DataFrame.info + DataFrame.to_parquet DataFrame.to_pickle DataFrame.to_csv DataFrame.to_hdf @@ -1077,6 +1168,7 @@ Serialization / IO / Conversion DataFrame.to_dense DataFrame.to_string DataFrame.to_clipboard + DataFrame.style Sparse ~~~~~~ @@ -1219,6 +1311,7 @@ Computations / Descriptive Stats Panel.std Panel.var + Reindexing / Selection / Label manipulation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. autosummary:: @@ -1240,13 +1333,13 @@ Reindexing / Selection / Label manipulation Panel.take Panel.truncate + Missing data handling ~~~~~~~~~~~~~~~~~~~~~ .. autosummary:: :toctree: generated/ Panel.dropna - Panel.fillna Reshaping, sorting, transposing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1289,7 +1382,6 @@ Serialization / IO / Conversion Panel.to_hdf Panel.to_sparse Panel.to_frame - Panel.to_xarray Panel.to_clipboard .. _api.index: @@ -1318,10 +1410,14 @@ Attributes Index.is_monotonic_decreasing Index.is_unique Index.has_duplicates + Index.hasnans Index.dtype + Index.dtype_str Index.inferred_type Index.is_all_dates Index.shape + Index.name + Index.names Index.nbytes Index.ndim Index.size @@ -1350,9 +1446,20 @@ Modifying and Computations Index.factorize Index.identical Index.insert + Index.is_ + Index.is_boolean + Index.is_categorical + Index.is_floating + Index.is_integer + Index.is_interval + Index.is_lexsorted_for_tuple + Index.is_mixed + Index.is_numeric + Index.is_object Index.min Index.max Index.reindex + Index.rename Index.repeat Index.where Index.take @@ -1378,10 +1485,15 @@ Conversion :toctree: generated/ Index.astype + Index.item + Index.map + Index.ravel Index.tolist Index.to_datetime + Index.to_native_types Index.to_series Index.to_frame + Index.view Sorting ~~~~~~~ @@ -1389,6 +1501,7 @@ Sorting :toctree: generated/ Index.argsort + Index.searchsorted Index.sort_values Time-specific operations @@ -1415,11 +1528,19 @@ Selecting .. autosummary:: :toctree: generated/ + Index.asof + Index.asof_locs + Index.contains + Index.get_duplicates Index.get_indexer + Index.get_indexer_for Index.get_indexer_non_unique Index.get_level_values Index.get_loc + Index.get_slice_bound Index.get_value + Index.get_values + Index.set_value Index.isin Index.slice_indexer Index.slice_locs @@ -1438,6 +1559,15 @@ Numeric Index UInt64Index Float64Index +.. We need this autosummary so that the methods are generated. +.. Separate block, since they aren't classes. + +.. autosummary:: + :toctree: generated/ + + RangeIndex.from_range + + .. _api.categoricalindex: CategoricalIndex @@ -1466,6 +1596,7 @@ Categorical Components CategoricalIndex.set_categories CategoricalIndex.as_ordered CategoricalIndex.as_unordered + CategoricalIndex.map .. _api.intervalindex: @@ -1488,6 +1619,14 @@ IntervalIndex Components IntervalIndex.from_tuples IntervalIndex.from_breaks IntervalIndex.from_intervals + IntervalIndex.contains + IntervalIndex.left + IntervalIndex.right + IntervalIndex.mid + IntervalIndex.closed + IntervalIndex.values + IntervalIndex.is_non_overlapping_monotonic + .. _api.multiindex: @@ -1496,12 +1635,17 @@ MultiIndex .. autosummary:: :toctree: generated/ + :template: autosummary/class_without_autosummary.rst MultiIndex + +.. autosummary:: + :toctree: generated/ + IndexSlice -MultiIndex Components -~~~~~~~~~~~~~~~~~~~~~~ +MultiIndex Constructors +~~~~~~~~~~~~~~~~~~~~~~~ .. autosummary:: :toctree: generated/ @@ -1509,11 +1653,31 @@ MultiIndex Components MultiIndex.from_arrays MultiIndex.from_tuples MultiIndex.from_product + +MultiIndex Attributes +~~~~~~~~~~~~~~~~~~~~~ + +.. autosummary:: + :toctree: generated/ + + MultiIndex.names + MultiIndex.levels + MultiIndex.labels + MultiIndex.nlevels + MultiIndex.levshape + +MultiIndex Components +~~~~~~~~~~~~~~~~~~~~~ + +.. autosummary:: + :toctree: generated/ + MultiIndex.set_levels MultiIndex.set_labels MultiIndex.to_hierarchical MultiIndex.to_frame MultiIndex.is_lexsorted + MultiIndex.sortlevel MultiIndex.droplevel MultiIndex.swaplevel MultiIndex.reorder_levels @@ -1526,6 +1690,7 @@ DatetimeIndex .. autosummary:: :toctree: generated/ + :template: autosummary/class_without_autosummary.rst DatetimeIndex @@ -1604,6 +1769,7 @@ TimedeltaIndex .. autosummary:: :toctree: generated/ + :template: autosummary/class_without_autosummary.rst TimedeltaIndex @@ -1745,6 +1911,7 @@ Properties Timestamp.dayofyear Timestamp.days_in_month Timestamp.daysinmonth + Timestamp.fold Timestamp.hour Timestamp.is_leap_year Timestamp.is_month_end @@ -1756,6 +1923,7 @@ Properties Timestamp.max Timestamp.microsecond Timestamp.min + Timestamp.minute Timestamp.month Timestamp.nanosecond Timestamp.quarter @@ -1764,6 +1932,7 @@ Properties Timestamp.tz Timestamp.tzinfo Timestamp.value + Timestamp.week Timestamp.weekday_name Timestamp.weekofyear Timestamp.year @@ -1848,7 +2017,9 @@ Properties Timedelta.asm8 Timedelta.components Timedelta.days + Timedelta.delta Timedelta.freq + Timedelta.is_populated Timedelta.max Timedelta.microseconds Timedelta.min @@ -1856,6 +2027,7 @@ Properties Timedelta.resolution Timedelta.seconds Timedelta.value + Timedelta.view Methods ~~~~~~~ @@ -1877,41 +2049,13 @@ Frequencies .. currentmodule:: pandas.tseries.frequencies - -.. autosummary:: - :toctree: generated/ - - to_offset - .. _api.offsets: -Offsets -------- - -.. currentmodule:: pandas.tseries.offsets - .. autosummary:: :toctree: generated/ - DateOffset - Week - Day - Hour - Minute - Second - Milli - Micro - Nano - -.. autosummary:: - :toctree: generated/ + to_offset - MonthBegin - MonthEnd - QuarterBegin - QuarterEnd - YearBegin - YearEnd Window ------ @@ -2006,6 +2150,7 @@ Indexing, iteration .. autosummary:: :toctree: generated/ + :template: autosummary/class_without_autosummary.rst Grouper @@ -2172,13 +2317,23 @@ Style ``Styler`` objects are returned by :attr:`pandas.DataFrame.style`. - -Constructor -~~~~~~~~~~~ +Styler Constructor +~~~~~~~~~~~~~~~~~~ .. autosummary:: :toctree: generated/ Styler + Styler.from_custom_template + + +Styler Attributes +~~~~~~~~~~~~~~~~~ +.. autosummary:: + :toctree: generated/ + + Styler.env + Styler.template + Styler.loader Style Application ~~~~~~~~~~~~~~~~~ @@ -2191,6 +2346,7 @@ Style Application Styler.format Styler.set_precision Styler.set_table_styles + Styler.set_table_attributes Styler.set_caption Styler.set_properties Styler.set_uuid @@ -2217,6 +2373,7 @@ Style Export and Import Styler.render Styler.export Styler.use + Styler.to_excel .. currentmodule:: pandas @@ -2328,3 +2485,35 @@ Scalar introspection api.types.is_re api.types.is_re_compilable api.types.is_scalar + + +.. This is to prevent warnings in the doc build. We don't want to encourage +.. these methods. + +.. toctree:: + :hidden: + + generated/pandas.DataFrame.blocks + generated/pandas.DataFrame.columns + generated/pandas.DataFrame.index + generated/pandas.DataFrame.ix + generated/pandas.Index.asi8 + generated/pandas.Index.data + generated/pandas.Index.flags + generated/pandas.Index.nlevels + generated/pandas.Index.sort + generated/pandas.Panel.agg + generated/pandas.Panel.aggregate + generated/pandas.Panel.blocks + generated/pandas.Panel.empty + generated/pandas.Panel.is_copy + generated/pandas.Panel.items + generated/pandas.Panel.ix + generated/pandas.Panel.major_axis + generated/pandas.Panel.minor_axis + 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/doc/source/conf.py b/doc/source/conf.py index 6d85f64317e7c..3ac41b0e7e0c9 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -55,7 +55,7 @@ 'sphinx.ext.doctest', 'sphinx.ext.extlinks', 'sphinx.ext.todo', - 'numpydoc', # used to parse numpy-style docstrings for autodoc + 'numpydoc', 'IPython.sphinxext.ipython_directive', 'IPython.sphinxext.ipython_console_highlighting', 'sphinx.ext.intersphinx', diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 40189f0e45518..0e5d701353d78 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -317,6 +317,27 @@ Some other important things to know about the docs: doc build. This approach means that code examples will always be up to date, but it does make the doc building a bit more complex. +- Our API documentation in ``doc/source/api.rst`` houses the auto-generated + documentation from the docstrings. For classes, there are a few subtleties + around controlling which methods and attributes have pages auto-generated. + + We have two autosummary templates for classes. + + 1. ``_templates/autosummary/class.rst``. Use this when you want to + automatically generate a page for every public method and attribute on the + class. The ``Attributes`` and ``Methods`` sections will be automatically + added to the class' rendered documentation by numpydoc. See ``DataFrame`` + for an example. + + 2. ``_templates/autosummary/class_without_autosummary``. Use this when you + want to pick a subset of methods / attributes to auto-generate pages for. + When using this template, you should include an ``Attributes`` and + ``Methods`` section in the class docstring. See ``CategoricalIndex`` for an + example. + + Every method should be included in a ``toctree`` in ``api.rst``, else Sphinx + will emit a warning. + .. note:: The ``.rst`` files are used to automatically generate Markdown and HTML versions diff --git a/doc/sphinxext/numpydoc/numpydoc.py b/doc/sphinxext/numpydoc/numpydoc.py index 09e31f9efd217..2bc2d1e91ed3f 100755 --- a/doc/sphinxext/numpydoc/numpydoc.py +++ b/doc/sphinxext/numpydoc/numpydoc.py @@ -42,13 +42,6 @@ def mangle_docstrings(app, what, name, obj, options, lines, class_members_toctree=app.config.numpydoc_class_members_toctree, ) - # PANDAS HACK (to remove the list of methods/attributes for Categorical) - no_autosummary = [".Categorical", "CategoricalIndex", "IntervalIndex", - "RangeIndex", "Int64Index", "UInt64Index", - "Float64Index", "PeriodIndex", "CategoricalDtype"] - if what == "class" and any(name.endswith(n) for n in no_autosummary): - cfg['class_members_list'] = False - if what == 'module': # Strip top title title_re = re.compile(sixu('^\\s*[#*=]{4,}\\n[a-z0-9 -]+\\n[#*=]{4,}\\s*'), diff --git a/pandas/_libs/tslib.pyx b/pandas/_libs/tslib.pyx index 540a081bdda2e..cd1440a90fcec 100644 --- a/pandas/_libs/tslib.pyx +++ b/pandas/_libs/tslib.pyx @@ -282,6 +282,8 @@ class Timestamp(_Timestamp): @classmethod def fromordinal(cls, ordinal, freq=None, tz=None, offset=None): """ + Timestamp.fromordinal(ordinal, freq=None, tz=None, offset=None) + passed an ordinal, translate and convert to a ts note: by definition there cannot be any tz info on the ordinal itself @@ -302,8 +304,10 @@ class Timestamp(_Timestamp): @classmethod def now(cls, tz=None): """ - Return the current time in the local timezone. Equivalent - to datetime.now([tz]) + Timestamp.now(tz=None) + + Returns new Timestamp object representing current time local to + tz. Parameters ---------- @@ -317,6 +321,8 @@ class Timestamp(_Timestamp): @classmethod def today(cls, tz=None): """ + Timestamp.today(cls, tz=None) + Return the current time in the local timezone. This differs from datetime.today() in that it can be localized to a passed timezone. @@ -330,18 +336,38 @@ class Timestamp(_Timestamp): @classmethod def utcnow(cls): + """ + Timestamp.utcnow() + + Return a new Timestamp representing UTC day and time. + """ return cls.now('UTC') @classmethod def utcfromtimestamp(cls, ts): + """ + Timestamp.utcfromtimestamp(ts) + + Construct a naive UTC datetime from a POSIX timestamp. + """ return cls(datetime.utcfromtimestamp(ts)) @classmethod def fromtimestamp(cls, ts): + """ + Timestamp.fromtimestamp(ts) + + timestamp[, tz] -> tz's local time from POSIX timestamp. + """ return cls(datetime.fromtimestamp(ts)) @classmethod def combine(cls, date, time): + """ + Timsetamp.combine(date, time) + + date, time -> datetime with same date and time fields + """ return cls(datetime.combine(date, time)) def __new__(cls, object ts_input=_no_input, diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index a5861f5865a39..d9234bc3779a8 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -336,16 +336,39 @@ class NaTType(_NaT): tzname = _make_error_func('tzname', datetime) utcoffset = _make_error_func('utcoffset', datetime) - # Timestamp has empty docstring for some methods. - utcfromtimestamp = _make_error_func('utcfromtimestamp', None) - fromtimestamp = _make_error_func('fromtimestamp', None) - combine = _make_error_func('combine', None) - utcnow = _make_error_func('utcnow', None) - # ---------------------------------------------------------------------- # The remaining methods have docstrings copy/pasted from the analogous # Timestamp methods. + utcfromtimestamp = _make_error_func('utcfromtimestamp', # noqa:E128 + """ + Timestamp.utcfromtimestamp(ts) + + Construct a naive UTC datetime from a POSIX timestamp. + """ + ) + fromtimestamp = _make_error_func('fromtimestamp', # noqa:E128 + """ + Timestamp.fromtimestamp(ts) + + timestamp[, tz] -> tz's local time from POSIX timestamp. + """ + ) + combine = _make_error_func('combine', # noqa:E128 + """ + Timsetamp.combine(date, time) + + date, time -> datetime with same date and time fields + """ + ) + utcnow = _make_error_func('utcnow', # noqa:E128 + """ + Timestamp.utcnow() + + Return a new Timestamp representing UTC day and time. + """ + ) + timestamp = _make_error_func('timestamp', # noqa:E128 """Return POSIX timestamp as float.""") @@ -372,6 +395,8 @@ class NaTType(_NaT): """) fromordinal = _make_error_func('fromordinal', # noqa:E128 """ + Timestamp.fromordinal(ordinal, freq=None, tz=None, offset=None) + passed an ordinal, translate and convert to a ts note: by definition there cannot be any tz info on the ordinal itself @@ -397,8 +422,10 @@ class NaTType(_NaT): now = _make_nat_func('now', # noqa:E128 """ - Return the current time in the local timezone. Equivalent - to datetime.now([tz]) + Timestamp.now(tz=None) + + Returns new Timestamp object representing current time local to + tz. Parameters ---------- @@ -407,6 +434,8 @@ class NaTType(_NaT): """) today = _make_nat_func('today', # noqa:E128 """ + Timestamp.today(cls, tz=None) + Return the current time in the local timezone. This differs from datetime.today() in that it can be localized to a passed timezone. diff --git a/pandas/core/categorical.py b/pandas/core/categorical.py index 6d60cf72efd62..d0851e3ab4f96 100644 --- a/pandas/core/categorical.py +++ b/pandas/core/categorical.py @@ -194,6 +194,11 @@ class Categorical(PandasObject): .. versionadded:: 0.21.0 + Methods + ------- + from_codes + __array__ + Raises ------ ValueError @@ -401,7 +406,7 @@ def ordered(self): @property def dtype(self): - """The :ref:`~pandas.api.types.CategoricalDtype` for this instance""" + """The :class:`~pandas.api.types.CategoricalDtype` for this instance""" return self._dtype @property diff --git a/pandas/core/dtypes/dtypes.py b/pandas/core/dtypes/dtypes.py index b4467f0f9733b..040b735f8de2c 100644 --- a/pandas/core/dtypes/dtypes.py +++ b/pandas/core/dtypes/dtypes.py @@ -120,6 +120,15 @@ class CategoricalDtype(ExtensionDtype): Must be unique, and must not contain any nulls. ordered : bool, default False + Attributes + ---------- + categories + ordered + + Methods + ------- + None + Notes ----- This class is useful for specifying the type of a ``Categorical`` diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index 70b531ffb0ec4..3812ed96b6c36 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -46,6 +46,24 @@ class CategoricalIndex(Index, accessor.PandasDelegate): name : object Name to be stored in the index + Attributes + ---------- + codes + categories + ordered + + Methods + ------- + rename_categories + reorder_categories + add_categories + remove_categories + remove_unused_categories + set_categories + as_ordered + as_unordered + map + See Also -------- Categorical, Index diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py index 2e022cb151008..b0e22460fdcb0 100644 --- a/pandas/core/indexes/datetimes.py +++ b/pandas/core/indexes/datetimes.py @@ -203,6 +203,54 @@ class DatetimeIndex(DatelikeOps, TimelikeOps, DatetimeIndexOpsMixin, name : object Name to be stored in the index + Attributes + ---------- + year + month + day + hour + minute + second + microsecond + nanosecond + date + time + dayofyear + weekofyear + week + dayofweek + weekday + weekday_name + quarter + tz + freq + freqstr + is_month_start + is_month_end + is_quarter_start + is_quarter_end + is_year_start + is_year_end + is_leap_year + inferred_freq + + Methods + ------- + normalize + strftime + snap + tz_convert + tz_localize + round + floor + ceil + to_datetime + to_period + to_perioddelta + to_pydatetime + to_series + to_frame + Notes ----- To learn more about the frequency strings, please see `this link diff --git a/pandas/core/indexes/interval.py b/pandas/core/indexes/interval.py index 7bf7cfce515a1..6ae55b063b676 100644 --- a/pandas/core/indexes/interval.py +++ b/pandas/core/indexes/interval.py @@ -121,6 +121,17 @@ class IntervalIndex(IntervalMixin, Index): Name to be stored in the index. copy : boolean, default False Copy the meta-data + mid + values + is_non_overlapping_monotonic + + Methods + ------- + from_arrays + from_tuples + from_breaks + from_intervals + contains Examples --------- diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index e6294f7d47aff..87d899a5902a8 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -95,6 +95,30 @@ class MultiIndex(Index): of iterables MultiIndex.from_tuples : Convert list of tuples to a MultiIndex Index : The base pandas Index type + + Attributes + ---------- + names + levels + labels + nlevels + levshape + + Methods + ------- + from_arrays + from_tuples + from_product + set_levels + set_labels + to_hierarchical + to_frame + is_lexsorted + sortlevel + droplevel + swaplevel + reorder_levels + remove_unused_levels """ # initialize to zero-length tuples to make everything work @@ -1362,10 +1386,12 @@ def remove_unused_levels(self): @property def nlevels(self): + """Integer number of levels in this MultiIndex.""" return len(self.levels) @property def levshape(self): + """A tuple with the length of each level.""" return tuple(len(x) for x in self.levels) def __reduce__(self): diff --git a/pandas/core/indexes/numeric.py b/pandas/core/indexes/numeric.py index b0703869948c2..ae6a810ece510 100644 --- a/pandas/core/indexes/numeric.py +++ b/pandas/core/indexes/numeric.py @@ -122,6 +122,14 @@ def is_all_dates(self): name : object Name to be stored in the index + Attributes + ---------- + inferred_type + + Methods + ------- + None + Notes ----- An Index instance can **only** contain hashable objects. @@ -154,6 +162,7 @@ class Int64Index(NumericIndex): @property def inferred_type(self): + """Always 'integer' for ``Int64Index``""" return 'integer' @property @@ -213,6 +222,7 @@ class UInt64Index(NumericIndex): @property def inferred_type(self): + """Always 'integer' for ``UInt64Index``""" return 'integer' @property @@ -290,6 +300,7 @@ class Float64Index(NumericIndex): @property def inferred_type(self): + """Always 'floating' for ``Float64Index``""" return 'floating' @Appender(_index_shared_docs['astype']) diff --git a/pandas/core/indexes/period.py b/pandas/core/indexes/period.py index df242e657c9d7..85e3300913000 100644 --- a/pandas/core/indexes/period.py +++ b/pandas/core/indexes/period.py @@ -161,6 +161,37 @@ class PeriodIndex(DatelikeOps, DatetimeIndexOpsMixin, Int64Index): Timezone for converting datetime64 data to Periods dtype : str or PeriodDtype, default None + Attributes + ---------- + day + dayofweek + dayofyear + days_in_month + daysinmonth + end_time + freq + freqstr + hour + is_leap_year + minute + month + quarter + qyear + second + start_time + week + weekday + weekofyear + year + + Methods + ------- + asfreq + strftime + to_timestamp + tz_convert + tz_localize + Examples -------- >>> idx = PeriodIndex(year=year_arr, quarter=q_arr) diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index 9cb01896424f7..c8f1c26f532a7 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -48,6 +48,10 @@ class RangeIndex(Int64Index): -------- Index : The base pandas Index type Int64Index : Index of int64 data + + Methods + ------- + from_range """ _typ = 'rangeindex' diff --git a/pandas/core/indexes/timedeltas.py b/pandas/core/indexes/timedeltas.py index e4bc46fb7bdbe..c592aa9608d97 100644 --- a/pandas/core/indexes/timedeltas.py +++ b/pandas/core/indexes/timedeltas.py @@ -137,6 +137,24 @@ class TimedeltaIndex(DatetimeIndexOpsMixin, TimelikeOps, Int64Index): Timedelta : Represents a duration between two dates or times. DatetimeIndex : Index of datetime64 data PeriodIndex : Index of Period data + + Attributes + ---------- + days + seconds + microseconds + nanoseconds + components + inferred_freq + + Methods + ------- + to_pytimedelta + to_series + round + floor + ceil + to_frame """ _typ = 'timedeltaindex' diff --git a/pandas/core/reshape/reshape.py b/pandas/core/reshape/reshape.py index 96738afbca9e3..8b656d8ba25e9 100644 --- a/pandas/core/reshape/reshape.py +++ b/pandas/core/reshape/reshape.py @@ -727,6 +727,7 @@ def get_dummies(data, prefix=None, prefix_sep='_', dummy_na=False, first level. .. versionadded:: 0.18.0 + Returns ------- dummies : DataFrame or SparseDataFrame diff --git a/pandas/core/tools/datetimes.py b/pandas/core/tools/datetimes.py index 19f7e459d0725..cbf393046907f 100644 --- a/pandas/core/tools/datetimes.py +++ b/pandas/core/tools/datetimes.py @@ -185,6 +185,7 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, strings, especially ones with timezone offsets. .. versionadded: 0.22.0 + Returns ------- ret : datetime if parsing succeeded. @@ -200,7 +201,6 @@ def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, Examples -------- - Assembling a datetime from multiple columns of a DataFrame. The keys can be common abbreviations like ['year', 'month', 'day', 'minute', 'second', 'ms', 'us', 'ns']) or plurals of the same diff --git a/pandas/io/formats/style.py b/pandas/io/formats/style.py index 776669d6d28db..6a99b798a123d 100644 --- a/pandas/io/formats/style.py +++ b/pandas/io/formats/style.py @@ -386,12 +386,11 @@ def format(self, formatter, subset=None): return self def render(self, **kwargs): - r""" - Render the built up styles to HTML + """Render the built up styles to HTML Parameters ---------- - **kwargs: + `**kwargs`: Any additional keyword arguments are passed through to ``self.template.render``. This is useful when you need to provide additional variables for a custom diff --git a/pandas/io/gbq.py b/pandas/io/gbq.py index b4dc9173f11ba..12e52123064e2 100644 --- a/pandas/io/gbq.py +++ b/pandas/io/gbq.py @@ -75,7 +75,7 @@ def read_gbq(query, project_id=None, index_col=None, col_order=None, see `BigQuery SQL Reference `__ - **kwargs : Arbitrary keyword arguments + `**kwargs` : Arbitrary keyword arguments configuration (dict): query config parameters for job processing. For example: diff --git a/pandas/plotting/_core.py b/pandas/plotting/_core.py index 62b2899f49413..c934648a1d111 100644 --- a/pandas/plotting/_core.py +++ b/pandas/plotting/_core.py @@ -1859,7 +1859,7 @@ def _plot(data, x=None, y=None, subplots=False, mark_right : boolean, default True When using a secondary_y axis, automatically mark the column labels with "(right)" in the legend - kwds : keywords + `**kwds` : keywords Options to pass to matplotlib plotting method Returns @@ -1955,8 +1955,9 @@ def plot_series(data, kind='line', ax=None, # Series unique array of axes is returned with the same shape as ``layout``. See the prose documentation for more. - kwds : other plotting keyword arguments to be passed to matplotlib boxplot - function + `**kwds` : Keyword Arguments + All other plotting keyword arguments to be passed to + matplotlib's boxplot function Returns ------- @@ -2152,7 +2153,7 @@ def hist_frame(data, column=None, by=None, grid=True, xlabelsize=None, Tuple of (rows, columns) for the layout of the histograms bins : integer, default 10 Number of histogram bins to be used - kwds : other plotting keyword arguments + `**kwds` : other plotting keyword arguments To be passed to hist function """ _setup() @@ -2215,7 +2216,7 @@ def hist_series(self, by=None, ax=None, grid=True, xlabelsize=None, figure size in inches by default bins: integer, default 10 Number of histogram bins to be used - kwds : keywords + `**kwds` : keywords To be passed to the actual plotting function Notes @@ -2327,8 +2328,9 @@ def boxplot_frame_groupby(grouped, subplots=True, column=None, fontsize=None, figsize : A tuple (width, height) in inches layout : tuple (optional) (rows, columns) for the layout of the plot - kwds : other plotting keyword arguments to be passed to matplotlib boxplot - function + `**kwds` : Keyword Arguments + All other plotting keyword arguments to be passed to + matplotlib's boxplot function Returns ------- @@ -2505,7 +2507,7 @@ def line(self, **kwds): Parameters ---------- - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2520,7 +2522,7 @@ def bar(self, **kwds): Parameters ---------- - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2535,7 +2537,7 @@ def barh(self, **kwds): Parameters ---------- - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2550,7 +2552,7 @@ def box(self, **kwds): Parameters ---------- - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2567,7 +2569,7 @@ def hist(self, bins=10, **kwds): ---------- bins: integer, default 10 Number of histogram bins to be used - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2582,7 +2584,7 @@ def kde(self, **kwds): Parameters ---------- - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2599,7 +2601,7 @@ def area(self, **kwds): Parameters ---------- - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2614,7 +2616,7 @@ def pie(self, **kwds): Parameters ---------- - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.Series.plot`. Returns @@ -2665,7 +2667,7 @@ def line(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2682,7 +2684,7 @@ def bar(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2699,7 +2701,7 @@ def barh(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2716,7 +2718,7 @@ def box(self, by=None, **kwds): ---------- by : string or sequence Column in the DataFrame to group by. - \*\*kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2735,7 +2737,7 @@ def hist(self, by=None, bins=10, **kwds): Column in the DataFrame to group by. bins: integer, default 10 Number of histogram bins to be used - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2750,7 +2752,7 @@ def kde(self, **kwds): Parameters ---------- - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2769,7 +2771,7 @@ def area(self, x=None, y=None, **kwds): ---------- x, y : label or position, optional Coordinates for each point. - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2786,7 +2788,7 @@ def pie(self, y=None, **kwds): ---------- y : label or position, optional Column to plot. - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2807,7 +2809,7 @@ def scatter(self, x, y, s=None, c=None, **kwds): Size of each point. c : label or position, optional Color of each point. - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns @@ -2832,7 +2834,7 @@ def hexbin(self, x, y, C=None, reduce_C_function=None, gridsize=None, a single number (e.g. `mean`, `max`, `sum`, `std`). gridsize : int, optional Number of bins. - **kwds : optional + `**kwds` : optional Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`. Returns