From 108ca880f017f6ad4dbf7808e3549f8064f9d7be Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Wed, 5 Jan 2022 19:55:13 -0800 Subject: [PATCH 1/3] DOC: Improve Series summaries --- pandas/core/arrays/categorical.py | 2 +- pandas/core/arrays/datetimes.py | 17 +++++++++++------ pandas/core/arrays/sparse/array.py | 4 ++-- pandas/core/groupby/groupby.py | 4 ++-- pandas/core/indexes/accessors.py | 4 ++-- pandas/core/indexes/base.py | 2 +- pandas/core/indexes/category.py | 2 +- pandas/core/series.py | 2 +- pandas/core/shared_docs.py | 6 ++---- 9 files changed, 23 insertions(+), 20 deletions(-) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 7e83cc93bb5a5..3114908485b13 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -1360,7 +1360,7 @@ def remove_unused_categories(self, inplace=no_default): def map(self, mapper): """ - Map categories using input correspondence (dict, Series, or function). + Map categories using an input mapping or function. Maps the categories to new categories. If the mapping correspondence is one-to-one the result is a :class:`~pandas.Categorical` which has the diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py index 647698f472978..d9915aedea947 100644 --- a/pandas/core/arrays/datetimes.py +++ b/pandas/core/arrays/datetimes.py @@ -570,7 +570,7 @@ def dtype(self) -> np.dtype | DatetimeTZDtype: # type: ignore[override] @property def tz(self) -> tzinfo | None: """ - Return timezone, if any. + Return the timezone. Returns ------- @@ -1278,7 +1278,9 @@ def day_name(self, locale=None): @property def time(self) -> npt.NDArray[np.object_]: """ - Returns numpy array of datetime.time. The time part of the Timestamps. + Returns numpy array of :class:`datetime.time`. + + The time part of the Timestamps. """ # If the Timestamps have a timezone that is not UTC, # convert them into their i8 representation while @@ -1290,16 +1292,19 @@ def time(self) -> npt.NDArray[np.object_]: @property def timetz(self) -> npt.NDArray[np.object_]: """ - Returns numpy array of datetime.time also containing timezone - information. The time part of the Timestamps. + Returns numpy array of :class:`datetime.time` also containing timezone + information. + + The time part of the Timestamps. """ return ints_to_pydatetime(self.asi8, self.tz, box="time") @property def date(self) -> npt.NDArray[np.object_]: """ - Returns numpy array of python datetime.date objects (namely, the date - part of Timestamps without timezone information). + Returns numpy array of python :class:`datetime.date` objects. + + Namely, the date part of Timestamps without timezone information. """ # If the Timestamps have a timezone that is not UTC, # convert them into their i8 representation while diff --git a/pandas/core/arrays/sparse/array.py b/pandas/core/arrays/sparse/array.py index c861abfc7920d..db1cd1ac39790 100644 --- a/pandas/core/arrays/sparse/array.py +++ b/pandas/core/arrays/sparse/array.py @@ -298,7 +298,7 @@ class SparseArray(OpsMixin, PandasObject, ExtensionArray): repeats of the scalar value instead. fill_value : scalar, optional - Elements in `data` that are `fill_value` are not stored in the + Elements in data that are ``fill_value`` are not stored in the SparseArray. For memory savings, this should be the most common value in `data`. By default, `fill_value` depends on the dtype of `data`: @@ -1265,7 +1265,7 @@ def astype(self, dtype: AstypeArg | None = None, copy: bool = True): def map(self: SparseArrayT, mapper) -> SparseArrayT: """ - Map categories using input correspondence (dict, Series, or function). + Map categories using an input mapping or function. Parameters ---------- diff --git a/pandas/core/groupby/groupby.py b/pandas/core/groupby/groupby.py index 4a42e2b61823d..9ceb50611f1c5 100644 --- a/pandas/core/groupby/groupby.py +++ b/pandas/core/groupby/groupby.py @@ -375,8 +375,8 @@ class providing the base-class of operations. the results together. %(klass)s.groupby.aggregate : Aggregate using one or more operations over the specified axis. -%(klass)s.transform : Call ``func`` on self producing a %(klass)s with - transformed values. +%(klass)s.transform : Call ``func`` on self producing a %(klass)s with the + same axis shape as self. Notes ----- diff --git a/pandas/core/indexes/accessors.py b/pandas/core/indexes/accessors.py index 3aad1140294e5..f33f1fbb6361f 100644 --- a/pandas/core/indexes/accessors.py +++ b/pandas/core/indexes/accessors.py @@ -193,7 +193,7 @@ class DatetimeProperties(Properties): def to_pydatetime(self) -> np.ndarray: """ - Return the data as an array of native Python datetime objects. + Return the data as an array of :class:`datetime.datetime`. Timezone information is retained if present. @@ -333,7 +333,7 @@ class TimedeltaProperties(Properties): def to_pytimedelta(self) -> np.ndarray: """ - Return an array of native `datetime.timedelta` objects. + Return an array of native :class:`datetime.timedelta` objects. Python's standard `datetime` library uses a different representation timedelta's. This method converts a Series of pandas Timedeltas diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 6c7499a575fca..5c97bdda0980d 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -6026,7 +6026,7 @@ def groupby(self, values) -> PrettyDict[Hashable, np.ndarray]: def map(self, mapper, na_action=None): """ - Map values using input correspondence (a dict, Series, or function). + Map values using an input mapping or function. Parameters ---------- diff --git a/pandas/core/indexes/category.py b/pandas/core/indexes/category.py index 2c615e96c22e0..5be04c7ab8c53 100644 --- a/pandas/core/indexes/category.py +++ b/pandas/core/indexes/category.py @@ -506,7 +506,7 @@ def take_nd(self, *args, **kwargs): def map(self, mapper): """ - Map values using input correspondence (a dict, Series, or function). + Map values using input an input mapping or function. Maps the values (their categories, not the codes) of the index to new categories. If the mapping correspondence is one-to-one the result is a diff --git a/pandas/core/series.py b/pandas/core/series.py index 7ca80601bbfd0..471cf1f3f6f57 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -4141,7 +4141,7 @@ def unstack(self, level=-1, fill_value=None) -> DataFrame: def map(self, arg, na_action=None) -> Series: """ - Map values of Series according to input correspondence. + Map values of Series according to an input mapping or function. Used for substituting each value in a Series with another value, that may be derived from a function, a ``dict`` or diff --git a/pandas/core/shared_docs.py b/pandas/core/shared_docs.py index f79fd3ed09f8d..3547b75eac807 100644 --- a/pandas/core/shared_docs.py +++ b/pandas/core/shared_docs.py @@ -96,7 +96,7 @@ will be used to determine the groups (the Series' values are first aligned; see ``.align()`` method). If a list or ndarray of length equal to the selected axis is passed (see the `groupby user guide - `), + `_), the values are used as-is to determine the groups. A label or list of labels may be passed to group by the columns in ``self``. Notice that a tuple is interpreted as a (single) key. @@ -267,9 +267,7 @@ _shared_docs[ "transform" ] = """ -Call ``func`` on self producing a {klass} with transformed values. - -Produced {klass} will have same axis length as self. +Call ``func`` on self producing a {klass} with the same axis shape as self. Parameters ---------- From bccd112edc59a1d55d37de9f8c06ef732e3229d8 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Thu, 6 Jan 2022 17:13:38 -0800 Subject: [PATCH 2/3] consistently use objects --- pandas/core/arrays/datetimes.py | 2 +- pandas/core/indexes/accessors.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py index d9915aedea947..509cb038558c7 100644 --- a/pandas/core/arrays/datetimes.py +++ b/pandas/core/arrays/datetimes.py @@ -1292,7 +1292,7 @@ def time(self) -> npt.NDArray[np.object_]: @property def timetz(self) -> npt.NDArray[np.object_]: """ - Returns numpy array of :class:`datetime.time` also containing timezone + Returns numpy array of :class:`datetime.time` objects with timezone information. The time part of the Timestamps. diff --git a/pandas/core/indexes/accessors.py b/pandas/core/indexes/accessors.py index f33f1fbb6361f..8c2813f2b57ec 100644 --- a/pandas/core/indexes/accessors.py +++ b/pandas/core/indexes/accessors.py @@ -193,7 +193,7 @@ class DatetimeProperties(Properties): def to_pydatetime(self) -> np.ndarray: """ - Return the data as an array of :class:`datetime.datetime`. + Return the data as an array of :class:`datetime.datetime` objects. Timezone information is retained if present. From f09760148180ee38431d726225b80e9c8dc16a4b Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Fri, 7 Jan 2022 11:55:13 -0800 Subject: [PATCH 3/3] Address review --- pandas/core/arrays/datetimes.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py index 509cb038558c7..03808b214b048 100644 --- a/pandas/core/arrays/datetimes.py +++ b/pandas/core/arrays/datetimes.py @@ -1278,7 +1278,7 @@ def day_name(self, locale=None): @property def time(self) -> npt.NDArray[np.object_]: """ - Returns numpy array of :class:`datetime.time`. + Returns numpy array of :class:`datetime.time` objects. The time part of the Timestamps. """ @@ -1304,7 +1304,8 @@ def date(self) -> npt.NDArray[np.object_]: """ Returns numpy array of python :class:`datetime.date` objects. - Namely, the date part of Timestamps without timezone information. + Namely, the date part of Timestamps without time and + timezone information. """ # If the Timestamps have a timezone that is not UTC, # convert them into their i8 representation while