Skip to content

Commit

Permalink
DOC/CLN: Fix various docstring errors (#25295)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jreback
Daniel Saxton authored and jreback committed Feb 16, 2019
1 parent ea9848c commit eace576
Show file tree
Hide file tree
Showing 10 changed files with 232 additions and 211 deletions.
72 changes: 36 additions & 36 deletions pandas/core/arrays/categorical.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -214,7 +214,7 @@ def contains(cat, key, container):

class Categorical(ExtensionArray, PandasObject):
"""
Represent a categorical variable in classic R / S-plus fashion
Represent a categorical variable in classic R / S-plus fashion.
`Categoricals` can only take on only a limited, and usually fixed, number
of possible values (`categories`). In contrast to statistical categorical
Expand All @@ -235,7 +235,7 @@ class Categorical(ExtensionArray, PandasObject):
The unique categories for this categorical. If not given, the
categories are assumed to be the unique values of `values` (sorted, if
possible, otherwise in the order in which they appear).
ordered : boolean, (default False)
ordered : bool, default False
Whether or not this categorical is treated as a ordered categorical.
If True, the resulting categorical will be ordered.
An ordered categorical respects, when sorted, the order of its
Expand All @@ -253,7 +253,7 @@ class Categorical(ExtensionArray, PandasObject):
codes : ndarray
The codes (integer positions, which point to the categories) of this
categorical, read only.
ordered : boolean
ordered : bool
Whether or not this Categorical is ordered.
dtype : CategoricalDtype
The instance of ``CategoricalDtype`` storing the ``categories``
Expand Down Expand Up @@ -297,7 +297,7 @@ class Categorical(ExtensionArray, PandasObject):
Ordered `Categoricals` can be sorted according to the custom order
of the categories and can have a min and max value.
>>> c = pd.Categorical(['a','b','c','a','b','c'], ordered=True,
>>> c = pd.Categorical(['a', 'b', 'c', 'a', 'b', 'c'], ordered=True,
... categories=['c', 'b', 'a'])
>>> c
[a, b, c, a, b, c]
Expand Down Expand Up @@ -618,7 +618,7 @@ def from_codes(cls, codes, categories=None, ordered=None, dtype=None):
----------
codes : array-like, integers
An integer array, where each integer points to a category in
categories or dtype.categories, or else is -1 for NaN
categories or dtype.categories, or else is -1 for NaN.
categories : index-like, optional
The categories for the categorical. Items need to be unique.
If the categories are not given here, then they must be provided
Expand Down Expand Up @@ -700,7 +700,7 @@ def _set_categories(self, categories, fastpath=False):
Parameters
----------
fastpath : boolean (default: False)
fastpath : bool, default False
Don't perform validation of the categories for uniqueness or nulls
Examples
Expand Down Expand Up @@ -747,15 +747,15 @@ def _set_dtype(self, dtype):

def set_ordered(self, value, inplace=False):
"""
Set the ordered attribute to the boolean value
Set the ordered attribute to the boolean value.
Parameters
----------
value : boolean to set whether this categorical is ordered (True) or
not (False)
inplace : boolean (default: False)
Whether or not to set the ordered attribute inplace or return a copy
of this categorical with ordered set to the value
value : bool
Set whether this categorical is ordered (True) or not (False).
inplace : bool, default False
Whether or not to set the ordered attribute in-place or return
a copy of this categorical with ordered set to the value.
"""
inplace = validate_bool_kwarg(inplace, 'inplace')
new_dtype = CategoricalDtype(self.categories, ordered=value)
Expand All @@ -770,9 +770,9 @@ def as_ordered(self, inplace=False):
Parameters
----------
inplace : boolean (default: False)
Whether or not to set the ordered attribute inplace or return a copy
of this categorical with ordered set to True
inplace : bool, default False
Whether or not to set the ordered attribute in-place or return
a copy of this categorical with ordered set to True.
"""
inplace = validate_bool_kwarg(inplace, 'inplace')
return self.set_ordered(True, inplace=inplace)
Expand All @@ -783,9 +783,9 @@ def as_unordered(self, inplace=False):
Parameters
----------
inplace : boolean (default: False)
Whether or not to set the ordered attribute inplace or return a copy
of this categorical with ordered set to False
inplace : bool, default False
Whether or not to set the ordered attribute in-place or return
a copy of this categorical with ordered set to False.
"""
inplace = validate_bool_kwarg(inplace, 'inplace')
return self.set_ordered(False, inplace=inplace)
Expand Down Expand Up @@ -815,19 +815,19 @@ def set_categories(self, new_categories, ordered=None, rename=False,
----------
new_categories : Index-like
The categories in new order.
ordered : boolean, (default: False)
ordered : bool, default False
Whether or not the categorical is treated as a ordered categorical.
If not given, do not change the ordered information.
rename : boolean (default: False)
rename : bool, default False
Whether or not the new_categories should be considered as a rename
of the old categories or as reordered categories.
inplace : boolean (default: False)
Whether or not to reorder the categories inplace or return a copy of
this categorical with reordered categories.
inplace : bool, default False
Whether or not to reorder the categories in-place or return a copy
of this categorical with reordered categories.
Returns
-------
cat : Categorical with reordered categories or None if inplace.
Categorical with reordered categories or None if inplace.
Raises
------
Expand Down Expand Up @@ -890,7 +890,7 @@ def rename_categories(self, new_categories, inplace=False):
Currently, Series are considered list like. In a future version
of pandas they'll be considered dict-like.
inplace : boolean (default: False)
inplace : bool, default False
Whether or not to rename the categories inplace or return a copy of
this categorical with renamed categories.
Expand Down Expand Up @@ -967,10 +967,10 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False):
----------
new_categories : Index-like
The categories in new order.
ordered : boolean, optional
ordered : bool, optional
Whether or not the categorical is treated as a ordered categorical.
If not given, do not change the ordered information.
inplace : boolean (default: False)
inplace : bool, default False
Whether or not to reorder the categories inplace or return a copy of
this categorical with reordered categories.
Expand Down Expand Up @@ -1010,7 +1010,7 @@ def add_categories(self, new_categories, inplace=False):
----------
new_categories : category or list-like of category
The new categories to be included.
inplace : boolean (default: False)
inplace : bool, default False
Whether or not to add the categories inplace or return a copy of
this categorical with added categories.
Expand Down Expand Up @@ -1060,7 +1060,7 @@ def remove_categories(self, removals, inplace=False):
----------
removals : category or list of categories
The categories which should be removed.
inplace : boolean (default: False)
inplace : bool, default False
Whether or not to remove the categories inplace or return a copy of
this categorical with removed categories.
Expand Down Expand Up @@ -1108,7 +1108,7 @@ def remove_unused_categories(self, inplace=False):
Parameters
----------
inplace : boolean (default: False)
inplace : bool, default False
Whether or not to drop unused categories inplace or return a copy of
this categorical with unused categories dropped.
Expand Down Expand Up @@ -1460,7 +1460,7 @@ def value_counts(self, dropna=True):
Parameters
----------
dropna : boolean, default True
dropna : bool, default True
Don't include counts of NaN.
Returns
Expand Down Expand Up @@ -1581,9 +1581,9 @@ def sort_values(self, inplace=False, ascending=True, na_position='last'):
Parameters
----------
inplace : boolean, default False
inplace : bool, default False
Do operation in place.
ascending : boolean, default True
ascending : bool, default True
Order ascending. Passing False orders descending. The
ordering parameter provides the method by which the
category values are organized.
Expand Down Expand Up @@ -2239,7 +2239,7 @@ def mode(self, dropna=True):
Parameters
----------
dropna : boolean, default True
dropna : bool, default True
Don't consider counts of NaN/NaT.
.. versionadded:: 0.24.0
Expand Down Expand Up @@ -2332,7 +2332,7 @@ def equals(self, other):
Returns
-------
are_equal : boolean
bool
"""
if self.is_dtype_equal(other):
if self.categories.equals(other.categories):
Expand All @@ -2356,7 +2356,7 @@ def is_dtype_equal(self, other):
Returns
-------
are_equal : boolean
bool
"""

try:
Expand Down
64 changes: 30 additions & 34 deletions pandas/core/arrays/datetimes.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -799,14 +799,14 @@ def tz_convert(self, tz):
Parameters
----------
tz : string, pytz.timezone, dateutil.tz.tzfile or None
tz : str, pytz.timezone, dateutil.tz.tzfile or None
Time zone for time. Corresponding timestamps would be converted
to this time zone of the Datetime Array/Index. A `tz` of None will
convert to UTC and remove the timezone information.
Returns
-------
normalized : same type as self
Array or Index
Raises
------
Expand Down Expand Up @@ -842,7 +842,7 @@ def tz_convert(self, tz):
With the ``tz=None``, we can remove the timezone (after converting
to UTC if necessary):
>>> dti = pd.date_range(start='2014-08-01 09:00',freq='H',
>>> dti = pd.date_range(start='2014-08-01 09:00', freq='H',
... periods=3, tz='Europe/Berlin')
>>> dti
Expand Down Expand Up @@ -882,7 +882,7 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise',
Parameters
----------
tz : string, pytz.timezone, dateutil.tz.tzfile or None
tz : str, pytz.timezone, dateutil.tz.tzfile or None
Time zone to convert timestamps to. Passing ``None`` will
remove the time zone information preserving local time.
ambiguous : 'infer', 'NaT', bool array, default 'raise'
Expand Down Expand Up @@ -930,7 +930,7 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise',
Returns
-------
result : same type as self
Same type as self
Array/Index converted to the specified time zone.
Raises
Expand Down Expand Up @@ -970,43 +970,39 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise',
Be careful with DST changes. When there is sequential data, pandas can
infer the DST time:
>>> s = pd.to_datetime(pd.Series([
... '2018-10-28 01:30:00',
... '2018-10-28 02:00:00',
... '2018-10-28 02:30:00',
... '2018-10-28 02:00:00',
... '2018-10-28 02:30:00',
... '2018-10-28 03:00:00',
... '2018-10-28 03:30:00']))
>>> s = pd.to_datetime(pd.Series(['2018-10-28 01:30:00',
... '2018-10-28 02:00:00',
... '2018-10-28 02:30:00',
... '2018-10-28 02:00:00',
... '2018-10-28 02:30:00',
... '2018-10-28 03:00:00',
... '2018-10-28 03:30:00']))
>>> s.dt.tz_localize('CET', ambiguous='infer')
2018-10-28 01:30:00+02:00 0
2018-10-28 02:00:00+02:00 1
2018-10-28 02:30:00+02:00 2
2018-10-28 02:00:00+01:00 3
2018-10-28 02:30:00+01:00 4
2018-10-28 03:00:00+01:00 5
2018-10-28 03:30:00+01:00 6
dtype: int64
0 2018-10-28 01:30:00+02:00
1 2018-10-28 02:00:00+02:00
2 2018-10-28 02:30:00+02:00
3 2018-10-28 02:00:00+01:00
4 2018-10-28 02:30:00+01:00
5 2018-10-28 03:00:00+01:00
6 2018-10-28 03:30:00+01:00
dtype: datetime64[ns, CET]
In some cases, inferring the DST is impossible. In such cases, you can
pass an ndarray to the ambiguous parameter to set the DST explicitly
>>> s = pd.to_datetime(pd.Series([
... '2018-10-28 01:20:00',
... '2018-10-28 02:36:00',
... '2018-10-28 03:46:00']))
>>> s = pd.to_datetime(pd.Series(['2018-10-28 01:20:00',
... '2018-10-28 02:36:00',
... '2018-10-28 03:46:00']))
>>> s.dt.tz_localize('CET', ambiguous=np.array([True, True, False]))
0 2018-10-28 01:20:00+02:00
1 2018-10-28 02:36:00+02:00
2 2018-10-28 03:46:00+01:00
dtype: datetime64[ns, CET]
0 2015-03-29 03:00:00+02:00
1 2015-03-29 03:30:00+02:00
dtype: datetime64[ns, Europe/Warsaw]
If the DST transition causes nonexistent times, you can shift these
dates forward or backwards with a timedelta object or `'shift_forward'`
or `'shift_backwards'`.
>>> s = pd.to_datetime(pd.Series([
... '2015-03-29 02:30:00',
... '2015-03-29 03:30:00']))
>>> s = pd.to_datetime(pd.Series(['2015-03-29 02:30:00',
... '2015-03-29 03:30:00']))
>>> s.dt.tz_localize('Europe/Warsaw', nonexistent='shift_forward')
0 2015-03-29 03:00:00+02:00
1 2015-03-29 03:30:00+02:00
Expand Down Expand Up @@ -1129,7 +1125,7 @@ def to_period(self, freq=None):
Parameters
----------
freq : string or Offset, optional
freq : str or Offset, optional
One of pandas' :ref:`offset strings <timeseries.offset_aliases>`
or an Offset object. Will be inferred by default.
Expand All @@ -1150,7 +1146,7 @@ def to_period(self, freq=None):
Examples
--------
>>> df = pd.DataFrame({"y": [1,2,3]},
>>> df = pd.DataFrame({"y": [1, 2, 3]},
... index=pd.to_datetime(["2000-03-31 00:00:00",
... "2000-05-31 00:00:00",
... "2000-08-31 00:00:00"]))
Expand Down
Loading

0 comments on commit eace576

Please sign in to comment.