Skip to content

Commit 1f2805b

Browse files
HughKelleydatapythonista
authored andcommitted
DOC: Fixes to the docstrings, mainly PR09 (#29466)
1 parent 18efcb2 commit 1f2805b

File tree

9 files changed

+69
-63
lines changed

9 files changed

+69
-63
lines changed

pandas/core/frame.py

+5-4
Original file line numberDiff line numberDiff line change
@@ -5848,13 +5848,13 @@ def pivot(self, index=None, columns=None, values=None):
58485848
hierarchical columns whose top level are the function names
58495849
(inferred from the function objects themselves)
58505850
If dict is passed, the key is column to aggregate and value
5851-
is function or list of functions
5851+
is function or list of functions.
58525852
fill_value : scalar, default None
5853-
Value to replace missing values with
5853+
Value to replace missing values with.
58545854
margins : bool, default False
5855-
Add all row / columns (e.g. for subtotal / grand totals)
5855+
Add all row / columns (e.g. for subtotal / grand totals).
58565856
dropna : bool, default True
5857-
Do not include columns whose entries are all NaN
5857+
Do not include columns whose entries are all NaN.
58585858
margins_name : str, default 'All'
58595859
Name of the row / column that will contain the totals
58605860
when margins is True.
@@ -5868,6 +5868,7 @@ def pivot(self, index=None, columns=None, values=None):
58685868
Returns
58695869
-------
58705870
DataFrame
5871+
An Excel style pivot table.
58715872
58725873
See Also
58735874
--------

pandas/core/indexes/interval.py

+5-5
Original file line numberDiff line numberDiff line change
@@ -1407,24 +1407,24 @@ def interval_range(
14071407
Parameters
14081408
----------
14091409
start : numeric or datetime-like, default None
1410-
Left bound for generating intervals
1410+
Left bound for generating intervals.
14111411
end : numeric or datetime-like, default None
1412-
Right bound for generating intervals
1412+
Right bound for generating intervals.
14131413
periods : int, default None
1414-
Number of periods to generate
1414+
Number of periods to generate.
14151415
freq : numeric, str, or DateOffset, default None
14161416
The length of each interval. Must be consistent with the type of start
14171417
and end, e.g. 2 for numeric, or '5H' for datetime-like. Default is 1
14181418
for numeric and 'D' for datetime-like.
14191419
name : str, default None
1420-
Name of the resulting IntervalIndex
1420+
Name of the resulting IntervalIndex.
14211421
closed : {'left', 'right', 'both', 'neither'}, default 'right'
14221422
Whether the intervals are closed on the left-side, right-side, both
14231423
or neither.
14241424
14251425
Returns
14261426
-------
1427-
rng : IntervalIndex
1427+
IntervalIndex
14281428
14291429
See Also
14301430
--------

pandas/core/indexes/period.py

+8-8
Original file line numberDiff line numberDiff line change
@@ -997,28 +997,28 @@ def memory_usage(self, deep=False):
997997

998998
def period_range(start=None, end=None, periods=None, freq=None, name=None):
999999
"""
1000-
Return a fixed frequency PeriodIndex, with day (calendar) as the default
1001-
frequency.
1000+
Return a fixed frequency PeriodIndex.
1001+
1002+
The day (calendar) is the default frequency.
10021003
10031004
Parameters
10041005
----------
10051006
start : str or period-like, default None
1006-
Left bound for generating periods
1007+
Left bound for generating periods.
10071008
end : str or period-like, default None
1008-
Right bound for generating periods
1009+
Right bound for generating periods.
10091010
periods : int, default None
1010-
Number of periods to generate
1011+
Number of periods to generate.
10111012
freq : str or DateOffset, optional
10121013
Frequency alias. By default the freq is taken from `start` or `end`
10131014
if those are Period objects. Otherwise, the default is ``"D"`` for
10141015
daily frequency.
1015-
10161016
name : str, default None
1017-
Name of the resulting PeriodIndex
1017+
Name of the resulting PeriodIndex.
10181018
10191019
Returns
10201020
-------
1021-
prng : PeriodIndex
1021+
PeriodIndex
10221022
10231023
Notes
10241024
-----

pandas/core/reshape/melt.py

+5-5
Original file line numberDiff line numberDiff line change
@@ -206,27 +206,27 @@ def wide_to_long(df, stubnames, i, j, sep: str = "", suffix: str = r"\d+"):
206206
Parameters
207207
----------
208208
df : DataFrame
209-
The wide-format DataFrame
209+
The wide-format DataFrame.
210210
stubnames : str or list-like
211211
The stub name(s). The wide format variables are assumed to
212212
start with the stub names.
213213
i : str or list-like
214-
Column(s) to use as id variable(s)
214+
Column(s) to use as id variable(s).
215215
j : str
216216
The name of the sub-observation variable. What you wish to name your
217217
suffix in the long format.
218218
sep : str, default ""
219219
A character indicating the separation of the variable names
220220
in the wide format, to be stripped from the names in the long format.
221221
For example, if your column names are A-suffix1, A-suffix2, you
222-
can strip the hyphen by specifying `sep='-'`
222+
can strip the hyphen by specifying `sep='-'`.
223223
suffix : str, default '\\d+'
224224
A regular expression capturing the wanted suffixes. '\\d+' captures
225225
numeric suffixes. Suffixes with no numbers could be specified with the
226226
negated character class '\\D+'. You can also further disambiguate
227227
suffixes, for example, if your wide variables are of the form
228228
A-one, B-two,.., and you have an unrelated column A-rating, you can
229-
ignore the last one by specifying `suffix='(!?one|two)'`
229+
ignore the last one by specifying `suffix='(!?one|two)'`.
230230
231231
.. versionchanged:: 0.23.0
232232
When all suffixes are numeric, they are cast to int64/float64.
@@ -360,7 +360,7 @@ def wide_to_long(df, stubnames, i, j, sep: str = "", suffix: str = r"\d+"):
360360
361361
>>> stubnames = sorted(
362362
... set([match[0] for match in df.columns.str.findall(
363-
... r'[A-B]\(.*\)').values if match != [] ])
363+
... r'[A-B]\(.*\)').values if match != []])
364364
... )
365365
>>> list(stubnames)
366366
['A(weekly)', 'B(weekly)']

pandas/core/reshape/merge.py

+24-17
Original file line numberDiff line numberDiff line change
@@ -175,9 +175,10 @@ def merge_ordered(
175175
how="outer",
176176
):
177177
"""
178-
Perform merge with optional filling/interpolation designed for ordered
179-
data like time series data. Optionally perform group-wise merge (see
180-
examples).
178+
Perform merge with optional filling/interpolation.
179+
180+
Designed for ordered data like time series data. Optionally
181+
perform group-wise merge (see examples).
181182
182183
Parameters
183184
----------
@@ -188,18 +189,18 @@ def merge_ordered(
188189
left_on : label or list, or array-like
189190
Field names to join on in left DataFrame. Can be a vector or list of
190191
vectors of the length of the DataFrame to use a particular vector as
191-
the join key instead of columns
192+
the join key instead of columns.
192193
right_on : label or list, or array-like
193194
Field names to join on in right DataFrame or vector/list of vectors per
194-
left_on docs
195+
left_on docs.
195196
left_by : column name or list of column names
196197
Group left DataFrame by group columns and merge piece by piece with
197-
right DataFrame
198+
right DataFrame.
198199
right_by : column name or list of column names
199200
Group right DataFrame by group columns and merge piece by piece with
200-
left DataFrame
201+
left DataFrame.
201202
fill_method : {'ffill', None}, default None
202-
Interpolation method for data
203+
Interpolation method for data.
203204
suffixes : Sequence, default is ("_x", "_y")
204205
A length-2 sequence where each element is optionally a string
205206
indicating the suffix to add to overlapping column names in
@@ -213,13 +214,13 @@ def merge_ordered(
213214
* left: use only keys from left frame (SQL: left outer join)
214215
* right: use only keys from right frame (SQL: right outer join)
215216
* outer: use union of keys from both frames (SQL: full outer join)
216-
* inner: use intersection of keys from both frames (SQL: inner join)
217+
* inner: use intersection of keys from both frames (SQL: inner join).
217218
218219
Returns
219220
-------
220-
merged : DataFrame
221-
The output type will the be same as 'left', if it is a subclass
222-
of DataFrame.
221+
DataFrame
222+
The merged DataFrame output type will the be same as
223+
'left', if it is a subclass of DataFrame.
223224
224225
See Also
225226
--------
@@ -228,15 +229,21 @@ def merge_ordered(
228229
229230
Examples
230231
--------
231-
>>> A >>> B
232-
key lvalue group key rvalue
233-
0 a 1 a 0 b 1
234-
1 c 2 a 1 c 2
235-
2 e 3 a 2 d 3
232+
>>> A
233+
key lvalue group
234+
0 a 1 a
235+
1 c 2 a
236+
2 e 3 a
236237
3 a 1 b
237238
4 c 2 b
238239
5 e 3 b
239240
241+
>>> B
242+
Key rvalue
243+
0 b 1
244+
1 c 2
245+
2 d 3
246+
240247
>>> merge_ordered(A, B, fill_method='ffill', left_by='group')
241248
group key lvalue rvalue
242249
0 a a 1 NaN

pandas/core/tools/datetimes.py

+14-16
Original file line numberDiff line numberDiff line change
@@ -577,14 +577,12 @@ def to_datetime(
577577
578578
Parameters
579579
----------
580-
arg : int, float, str, datetime, list, tuple, 1-d array, Series
581-
or DataFrame/dict-like
582-
580+
arg : int, float, str, datetime, list, tuple, 1-d array, Series DataFrame/dict-like
581+
The object to convert to a datetime.
583582
errors : {'ignore', 'raise', 'coerce'}, default 'raise'
584-
585-
- If 'raise', then invalid parsing will raise an exception
586-
- If 'coerce', then invalid parsing will be set as NaT
587-
- If 'ignore', then invalid parsing will return the input
583+
- If 'raise', then invalid parsing will raise an exception.
584+
- If 'coerce', then invalid parsing will be set as NaT.
585+
- If 'ignore', then invalid parsing will return the input.
588586
dayfirst : bool, default False
589587
Specify a date parse order if `arg` is str or its list-likes.
590588
If True, parses dates with the day first, eg 10/11/12 is parsed as
@@ -605,7 +603,6 @@ def to_datetime(
605603
Return UTC DatetimeIndex if True (converting any tz-aware
606604
datetime.datetime objects as well).
607605
box : bool, default True
608-
609606
- If True returns a DatetimeIndex or Index-like object
610607
- If False returns ndarray of values.
611608
@@ -615,17 +612,17 @@ def to_datetime(
615612
respectively.
616613
617614
format : str, default None
618-
strftime to parse time, eg "%d/%m/%Y", note that "%f" will parse
615+
The strftime to parse time, eg "%d/%m/%Y", note that "%f" will parse
619616
all the way up to nanoseconds.
620617
See strftime documentation for more information on choices:
621-
https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior
618+
https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior.
622619
exact : bool, True by default
623-
620+
Behaves as:
624621
- If True, require an exact format match.
625622
- If False, allow the format to match anywhere in the target string.
626623
627624
unit : str, default 'ns'
628-
unit of the arg (D,s,ms,us,ns) denote the unit, which is an
625+
The unit of the arg (D,s,ms,us,ns) denote the unit, which is an
629626
integer or float number. This will be based off the origin.
630627
Example, with unit='ms' and origin='unix' (the default), this
631628
would calculate the number of milliseconds to the unix epoch start.
@@ -652,11 +649,12 @@ def to_datetime(
652649
.. versionadded:: 0.23.0
653650
654651
.. versionchanged:: 0.25.0
655-
- changed default value from False to True
652+
- changed default value from False to True.
656653
657654
Returns
658655
-------
659-
ret : datetime if parsing succeeded.
656+
datetime
657+
If parsing succeeded.
660658
Return type depends on input:
661659
662660
- list-like: DatetimeIndex
@@ -712,10 +710,10 @@ def to_datetime(
712710
4 3/12/2000
713711
dtype: object
714712
715-
>>> %timeit pd.to_datetime(s,infer_datetime_format=True) # doctest: +SKIP
713+
>>> %timeit pd.to_datetime(s, infer_datetime_format=True) # doctest: +SKIP
716714
100 loops, best of 3: 10.4 ms per loop
717715
718-
>>> %timeit pd.to_datetime(s,infer_datetime_format=False) # doctest: +SKIP
716+
>>> %timeit pd.to_datetime(s, infer_datetime_format=False) # doctest: +SKIP
719717
1 loop, best of 3: 471 ms per loop
720718
721719
Using a unix epoch time

pandas/core/util/hashing.py

+5-5
Original file line numberDiff line numberDiff line change
@@ -67,11 +67,11 @@ def hash_pandas_object(
6767
Parameters
6868
----------
6969
index : bool, default True
70-
include the index in the hash (if Series/DataFrame)
70+
Include the index in the hash (if Series/DataFrame).
7171
encoding : str, default 'utf8'
72-
encoding for data & key when strings
72+
Encoding for data & key when strings.
7373
hash_key : str, default _default_hash_key
74-
hash_key for string key to encode
74+
Hash_key for string key to encode.
7575
categorize : bool, default True
7676
Whether to first categorize object arrays before hashing. This is more
7777
efficient when the array contains duplicate values.
@@ -253,9 +253,9 @@ def hash_array(
253253
----------
254254
vals : ndarray, Categorical
255255
encoding : str, default 'utf8'
256-
encoding for data & key when strings
256+
Encoding for data & key when strings.
257257
hash_key : str, default _default_hash_key
258-
hash_key for string key to encode
258+
Hash_key for string key to encode.
259259
categorize : bool, default True
260260
Whether to first categorize object arrays before hashing. This is more
261261
efficient when the array contains duplicate values.

pandas/io/excel/_base.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -79,8 +79,6 @@
7979
subset of data is selected with ``usecols``, index_col
8080
is based on the subset.
8181
usecols : int, str, list-like, or callable default None
82-
Return a subset of the columns.
83-
8482
* If None, then parse all columns.
8583
* If int, then indicates last column to be parsed.
8684
@@ -98,6 +96,8 @@
9896
* If callable, then evaluate each column name against it and parse the
9997
column if the callable returns ``True``.
10098
99+
Returns a subset of the columns according to behavior above.
100+
101101
.. versionadded:: 0.24.0
102102
103103
squeeze : bool, default False

pandas/io/packers.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -191,7 +191,7 @@ def read_msgpack(path_or_buf, encoding="utf-8", iterator=False, **kwargs):
191191
``StringIO``.
192192
encoding : Encoding for decoding msgpack str type
193193
iterator : boolean, if True, return an iterator to the unpacker
194-
(default is False)
194+
(default is False).
195195
196196
Returns
197197
-------

0 commit comments

Comments
 (0)