Skip to content

Commit f25c01d

Browse files
authored
DOC: Minor doc cleanups (#51202)
* Clean some mor whatsnew entries * Add ExcelFile to docs * Fix typo * Fix docs * Add examples * Add to ignore
1 parent c73dc7f commit f25c01d

File tree

8 files changed

+80
-45
lines changed

8 files changed

+80
-45
lines changed

ci/code_checks.sh

+1
Original file line numberDiff line numberDiff line change
@@ -266,6 +266,7 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
266266
pandas.api.types.is_integer \
267267
pandas.api.types.pandas_dtype \
268268
pandas.read_clipboard \
269+
pandas.ExcelFile \
269270
pandas.ExcelFile.parse \
270271
pandas.DataFrame.to_html \
271272
pandas.io.formats.style.Styler.to_html \

doc/source/reference/indexing.rst

+3
Original file line numberDiff line numberDiff line change
@@ -299,6 +299,9 @@ MultiIndex components
299299
MultiIndex.reorder_levels
300300
MultiIndex.remove_unused_levels
301301
MultiIndex.drop
302+
MultiIndex.copy
303+
MultiIndex.append
304+
MultiIndex.truncate
302305

303306
MultiIndex selecting
304307
~~~~~~~~~~~~~~~~~~~~

doc/source/reference/io.rst

+3
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,9 @@ Excel
4040

4141
read_excel
4242
DataFrame.to_excel
43+
ExcelFile
44+
ExcelFile.book
45+
ExcelFile.sheet_names
4346
ExcelFile.parse
4447

4548
.. currentmodule:: pandas.io.formats.style

doc/source/whatsnew/v1.5.0.rst

-9
Original file line numberDiff line numberDiff line change
@@ -361,7 +361,6 @@ Other enhancements
361361
- Added ``numeric_only`` argument to :meth:`DataFrame.corr`, :meth:`DataFrame.corrwith`, :meth:`DataFrame.cov`, :meth:`DataFrame.idxmin`, :meth:`DataFrame.idxmax`, :meth:`.DataFrameGroupBy.idxmin`, :meth:`.DataFrameGroupBy.idxmax`, :meth:`.DataFrameGroupBy.var`, :meth:`.SeriesGroupBy.var`, :meth:`.DataFrameGroupBy.std`, :meth:`.SeriesGroupBy.std`, :meth:`.DataFrameGroupBy.sem`, :meth:`.SeriesGroupBy.sem`, and :meth:`.DataFrameGroupBy.quantile` (:issue:`46560`)
362362
- A :class:`errors.PerformanceWarning` is now thrown when using ``string[pyarrow]`` dtype with methods that don't dispatch to ``pyarrow.compute`` methods (:issue:`42613`, :issue:`46725`)
363363
- Added ``validate`` argument to :meth:`DataFrame.join` (:issue:`46622`)
364-
- A :class:`errors.PerformanceWarning` is now thrown when using ``string[pyarrow]`` dtype with methods that don't dispatch to ``pyarrow.compute`` methods (:issue:`42613`)
365364
- Added ``numeric_only`` argument to :meth:`.Resampler.sum`, :meth:`.Resampler.prod`, :meth:`.Resampler.min`, :meth:`.Resampler.max`, :meth:`.Resampler.first`, and :meth:`.Resampler.last` (:issue:`46442`)
366365
- ``times`` argument in :class:`.ExponentialMovingWindow` now accepts ``np.timedelta64`` (:issue:`47003`)
367366
- :class:`.DataError`, :class:`.SpecificationError`, :class:`.SettingWithCopyError`, :class:`.SettingWithCopyWarning`, :class:`.NumExprClobberingError`, :class:`.UndefinedVariableError`, :class:`.IndexingError`, :class:`.PyperclipException`, :class:`.PyperclipWindowsException`, :class:`.CSSWarning`, :class:`.PossibleDataLossError`, :class:`.ClosedFileError`, :class:`.IncompatibilityWarning`, :class:`.AttributeConflictWarning`, :class:`.DatabaseError`, :class:`.PossiblePrecisionLoss`, :class:`.ValueLabelTypeMismatch`, :class:`.InvalidColumnName`, and :class:`.CategoricalConversionWarning` are now exposed in ``pandas.errors`` (:issue:`27656`)
@@ -1014,7 +1013,6 @@ Performance improvements
10141013
- Performance improvement in :meth:`Series.to_sql` and :meth:`DataFrame.to_sql` (:class:`SQLiteTable`) when processing time arrays. (:issue:`44764`)
10151014
- Performance improvement to :func:`read_sas` (:issue:`47404`)
10161015
- Performance improvement in ``argmax`` and ``argmin`` for :class:`arrays.SparseArray` (:issue:`34197`)
1017-
-
10181016

10191017
.. ---------------------------------------------------------------------------
10201018
.. _whatsnew_150.bug_fixes:
@@ -1041,19 +1039,16 @@ Datetimelike
10411039
- Bug in :class:`.DatetimeArray` construction when passed another :class:`.DatetimeArray` and ``freq=None`` incorrectly inferring the freq from the given array (:issue:`47296`)
10421040
- Bug in :func:`to_datetime` where ``OutOfBoundsDatetime`` would be thrown even if ``errors=coerce`` if there were more than 50 rows (:issue:`45319`)
10431041
- Bug when adding a :class:`DateOffset` to a :class:`Series` would not add the ``nanoseconds`` field (:issue:`47856`)
1044-
-
10451042

10461043
Timedelta
10471044
^^^^^^^^^
10481045
- Bug in :func:`astype_nansafe` astype("timedelta64[ns]") fails when np.nan is included (:issue:`45798`)
10491046
- Bug in constructing a :class:`Timedelta` with a ``np.timedelta64`` object and a ``unit`` sometimes silently overflowing and returning incorrect results instead of raising ``OutOfBoundsTimedelta`` (:issue:`46827`)
10501047
- Bug in constructing a :class:`Timedelta` from a large integer or float with ``unit="W"`` silently overflowing and returning incorrect results instead of raising ``OutOfBoundsTimedelta`` (:issue:`47268`)
1051-
-
10521048

10531049
Time Zones
10541050
^^^^^^^^^^
10551051
- Bug in :class:`Timestamp` constructor raising when passed a ``ZoneInfo`` tzinfo object (:issue:`46425`)
1056-
-
10571052

10581053
Numeric
10591054
^^^^^^^
@@ -1078,13 +1073,11 @@ Conversion
10781073
- Bug in :meth:`DataFrame.apply` that returns a :class:`DataFrame` instead of a :class:`Series` when applied to an empty :class:`DataFrame` and ``axis=1`` (:issue:`39111`)
10791074
- Bug when inferring the dtype from an iterable that is *not* a NumPy ``ndarray`` consisting of all NumPy unsigned integer scalars did not result in an unsigned integer dtype (:issue:`47294`)
10801075
- Bug in :meth:`DataFrame.eval` when pandas objects (e.g. ``'Timestamp'``) were column names (:issue:`44603`)
1081-
-
10821076

10831077
Strings
10841078
^^^^^^^
10851079
- Bug in :meth:`str.startswith` and :meth:`str.endswith` when using other series as parameter _pat_. Now raises ``TypeError`` (:issue:`3485`)
10861080
- Bug in :meth:`Series.str.zfill` when strings contain leading signs, padding '0' before the sign character rather than after as ``str.zfill`` from standard library (:issue:`20868`)
1087-
-
10881081

10891082
Interval
10901083
^^^^^^^^
@@ -1192,7 +1185,6 @@ Period
11921185
- Bug in adding ``np.timedelta64("NaT", "ns")`` to a :class:`Period` with a timedelta-like freq incorrectly raising ``IncompatibleFrequency`` instead of returning ``NaT`` (:issue:`47196`)
11931186
- Bug in adding an array of integers to an array with :class:`PeriodDtype` giving incorrect results when ``dtype.freq.n > 1`` (:issue:`47209`)
11941187
- Bug in subtracting a :class:`Period` from an array with :class:`PeriodDtype` returning incorrect results instead of raising ``OverflowError`` when the operation overflows (:issue:`47538`)
1195-
-
11961188

11971189
Plotting
11981190
^^^^^^^^
@@ -1236,7 +1228,6 @@ Groupby/resample/rolling
12361228
- Bug in :meth:`DataFrameGroupBy.resample` raises ``KeyError`` when getting the result from a key list which misses the resample key (:issue:`47362`)
12371229
- Bug in :meth:`DataFrame.groupby` would lose index columns when the DataFrame is empty for transforms, like fillna (:issue:`47787`)
12381230
- Bug in :meth:`DataFrame.groupby` and :meth:`Series.groupby` with ``dropna=False`` and ``sort=False`` would put any null groups at the end instead the order that they are encountered (:issue:`46584`)
1239-
-
12401231

12411232
Reshaping
12421233
^^^^^^^^^

doc/source/whatsnew/v2.0.0.rst

+20-16
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Previously it was only possible to use ``int64``, ``uint64`` & ``float64`` dtype
4646
In [3]: pd.Index([1, 2, 3], dtype=np.float32)
4747
Out[3]: Float64Index([1.0, 2.0, 3.0], dtype="float64")
4848
49-
:class:`Int64Index`, :class:`UInt64Index` & :class:`Float64Index` were depreciated in pandas
49+
:class:`Int64Index`, :class:`UInt64Index` & :class:`Float64Index` were deprecated in pandas
5050
version 1.4 and have now been removed. Instead :class:`Index` should be used directly, and
5151
can it now take all numpy numeric dtypes, i.e.
5252
``int8``/ ``int16``/``int32``/``int64``/``uint8``/``uint16``/``uint32``/``uint64``/``float32``/``float64`` dtypes:
@@ -57,7 +57,7 @@ can it now take all numpy numeric dtypes, i.e.
5757
pd.Index([1, 2, 3], dtype=np.uint16)
5858
pd.Index([1, 2, 3], dtype=np.float32)
5959
60-
The ability for ``Index`` to hold the numpy numeric dtypes has meant some changes in Pandas
60+
The ability for :class:`Index` to hold the numpy numeric dtypes has meant some changes in Pandas
6161
functionality. In particular, operations that previously were forced to create 64-bit indexes,
6262
can now create indexes with lower bit sizes, e.g. 32-bit indexes.
6363

@@ -247,11 +247,15 @@ Copy-on-Write improvements
247247
can never update the original Series or DataFrame. Therefore, an informative
248248
error is raised to the user instead of silently doing nothing (:issue:`49467`)
249249

250-
Copy-on-Write can be enabled through
250+
Copy-on-Write can be enabled through one of
251251

252252
.. code-block:: python
253253
254254
pd.set_option("mode.copy_on_write", True)
255+
256+
257+
.. code-block:: python
258+
255259
pd.options.mode.copy_on_write = True
256260
257261
Alternatively, copy on write can be enabled locally through:
@@ -283,7 +287,7 @@ Other enhancements
283287
- Added ``name`` parameter to :meth:`IntervalIndex.from_breaks`, :meth:`IntervalIndex.from_arrays` and :meth:`IntervalIndex.from_tuples` (:issue:`48911`)
284288
- Improve exception message when using :func:`.testing.assert_frame_equal` on a :class:`DataFrame` to include the column that is compared (:issue:`50323`)
285289
- Improved error message for :func:`merge_asof` when join-columns were duplicated (:issue:`50102`)
286-
- Added support for extension array dtypes to :func:`get_dummies` (:func:`32430`)
290+
- Added support for extension array dtypes to :func:`get_dummies` (:issue:`32430`)
287291
- Added :meth:`Index.infer_objects` analogous to :meth:`Series.infer_objects` (:issue:`50034`)
288292
- Added ``copy`` parameter to :meth:`Series.infer_objects` and :meth:`DataFrame.infer_objects`, passing ``False`` will avoid making copies for series or columns that are already non-object or where no better dtype can be inferred (:issue:`50096`)
289293
- :meth:`DataFrame.plot.hist` now recognizes ``xlabel`` and ``ylabel`` arguments (:issue:`49793`)
@@ -691,18 +695,18 @@ In the past, :func:`to_datetime` guessed the format for each element independent
691695

692696
*Old behavior*:
693697

694-
.. code-block:: ipython
698+
.. code-block:: ipython
695699
696-
In [1]: ser = pd.Series(['13-01-2000', '12-01-2000'])
697-
In [2]: pd.to_datetime(ser)
698-
Out[2]:
699-
0 2000-01-13
700-
1 2000-12-01
701-
dtype: datetime64[ns]
700+
In [1]: ser = pd.Series(['13-01-2000', '12-01-2000'])
701+
In [2]: pd.to_datetime(ser)
702+
Out[2]:
703+
0 2000-01-13
704+
1 2000-12-01
705+
dtype: datetime64[ns]
702706
703707
*New behavior*:
704708

705-
.. ipython:: python
709+
.. ipython:: python
706710
:okwarning:
707711
708712
ser = pd.Series(['13-01-2000', '12-01-2000'])
@@ -740,7 +744,7 @@ Other API changes
740744
- :func:`pandas.testing.assert_index_equal` with parameter ``exact="equiv"`` now considers two indexes equal when both are either a :class:`RangeIndex` or :class:`Index` with an ``int64`` dtype. Previously it meant either a :class:`RangeIndex` or a :class:`Int64Index` (:issue:`51098`)
741745
- :meth:`Series.unique` with dtype "timedelta64[ns]" or "datetime64[ns]" now returns :class:`TimedeltaArray` or :class:`DatetimeArray` instead of ``numpy.ndarray`` (:issue:`49176`)
742746
- :func:`to_datetime` and :class:`DatetimeIndex` now allow sequences containing both ``datetime`` objects and numeric entries, matching :class:`Series` behavior (:issue:`49037`, :issue:`50453`)
743-
- :func:`api.dtypes.is_string_dtype` now only returns ``True`` for array-likes with ``dtype=object`` when the elements are inferred to be strings (:issue:`15585`)
747+
- :func:`pandas.api.types.is_string_dtype` now only returns ``True`` for array-likes with ``dtype=object`` when the elements are inferred to be strings (:issue:`15585`)
744748
- Passing a sequence containing ``datetime`` objects and ``date`` objects to :class:`Series` constructor will return with ``object`` dtype instead of ``datetime64[ns]`` dtype, consistent with :class:`Index` behavior (:issue:`49341`)
745749
- Passing strings that cannot be parsed as datetimes to :class:`Series` or :class:`DataFrame` with ``dtype="datetime64[ns]"`` will raise instead of silently ignoring the keyword and returning ``object`` dtype (:issue:`24435`)
746750
- Passing a sequence containing a type that cannot be converted to :class:`Timedelta` to :func:`to_timedelta` or to the :class:`Series` or :class:`DataFrame` constructor with ``dtype="timedelta64[ns]"`` or to :class:`TimedeltaIndex` now raises ``TypeError`` instead of ``ValueError`` (:issue:`49525`)
@@ -783,7 +787,7 @@ Deprecations
783787
- :meth:`Index.is_numeric` has been deprecated. Use :func:`pandas.api.types.is_any_real_numeric_dtype` instead (:issue:`50042`,:issue:`51152`)
784788
- :meth:`Index.is_categorical` has been deprecated. Use :func:`pandas.api.types.is_categorical_dtype` instead (:issue:`50042`)
785789
- :meth:`Index.is_object` has been deprecated. Use :func:`pandas.api.types.is_object_dtype` instead (:issue:`50042`)
786-
- :meth:`Index.is_interval` has been deprecated. Use :func:`pandas.api.types.is_intterval_dtype` instead (:issue:`50042`)
790+
- :meth:`Index.is_interval` has been deprecated. Use :func:`pandas.api.types.is_interval_dtype` instead (:issue:`50042`)
787791
- Deprecated ``all`` and ``any`` reductions with ``datetime64`` and :class:`DatetimeTZDtype` dtypes, use e.g. ``(obj != pd.Timestamp(0), tz=obj.tz).all()`` instead (:issue:`34479`)
788792
- Deprecated unused arguments ``*args`` and ``**kwargs`` in :class:`Resampler` (:issue:`50977`)
789793
- Deprecated calling ``float`` or ``int`` on a single element :class:`Series` to return a ``float`` or ``int`` respectively. Extract the element before calling ``float`` or ``int`` instead (:issue:`51101`)
@@ -1174,7 +1178,7 @@ Numeric
11741178
- Bug in DataFrame reduction methods (e.g. :meth:`DataFrame.sum`) with object dtype, ``axis=1`` and ``numeric_only=False`` would not be coerced to float (:issue:`49551`)
11751179
- Bug in :meth:`DataFrame.sem` and :meth:`Series.sem` where an erroneous ``TypeError`` would always raise when using data backed by an :class:`ArrowDtype` (:issue:`49759`)
11761180
- Bug in :meth:`Series.__add__` casting to object for list and masked :class:`Series` (:issue:`22962`)
1177-
- Bug in :meth:`query` with ``engine="numexpr"`` and column names are ``min`` or ``max`` would raise a ``TypeError`` (:issue:`50937`)
1181+
- Bug in :meth:`DataFrame.query` with ``engine="numexpr"`` and column names are ``min`` or ``max`` would raise a ``TypeError`` (:issue:`50937`)
11781182

11791183
Conversion
11801184
^^^^^^^^^^
@@ -1195,7 +1199,7 @@ Conversion
11951199

11961200
Strings
11971201
^^^^^^^
1198-
- Bug in :func:`pandas.api.dtypes.is_string_dtype` that would not return ``True`` for :class:`StringDtype` or :class:`ArrowDtype` with ``pyarrow.string()`` (:issue:`15585`)
1202+
- Bug in :func:`pandas.api.types.is_string_dtype` that would not return ``True`` for :class:`StringDtype` or :class:`ArrowDtype` with ``pyarrow.string()`` (:issue:`15585`)
11991203
- Bug in converting string dtypes to "datetime64[ns]" or "timedelta64[ns]" incorrectly raising ``TypeError`` (:issue:`36153`)
12001204
-
12011205

pandas/core/indexes/multi.py

+41-8
Original file line numberDiff line numberDiff line change
@@ -1148,8 +1148,9 @@ def copy( # type: ignore[override]
11481148
name=None,
11491149
):
11501150
"""
1151-
Make a copy of this object. Names, dtype, levels and codes can be
1152-
passed and will be set on new copy.
1151+
Make a copy of this object.
1152+
1153+
Names, dtype, levels and codes can be passed and will be set on new copy.
11531154
11541155
Parameters
11551156
----------
@@ -1167,6 +1168,16 @@ def copy( # type: ignore[override]
11671168
In most cases, there should be no functional difference from using
11681169
``deep``, but if ``deep`` is passed it will attempt to deepcopy.
11691170
This could be potentially expensive on large MultiIndex objects.
1171+
1172+
Examples
1173+
--------
1174+
>>> mi = pd.MultiIndex.from_arrays([['a'], ['b'], ['c']])
1175+
>>> mi
1176+
MultiIndex([('a', 'b', 'c')],
1177+
)
1178+
>>> mi.copy()
1179+
MultiIndex([('a', 'b', 'c')],
1180+
)
11701181
"""
11711182
names = self._validate_names(name=name, names=names, deep=deep)
11721183
keep_id = not deep
@@ -2085,15 +2096,26 @@ def take(
20852096

20862097
def append(self, other):
20872098
"""
2088-
Append a collection of Index options together
2099+
Append a collection of Index options together.
20892100
20902101
Parameters
20912102
----------
20922103
other : Index or list/tuple of indices
20932104
20942105
Returns
20952106
-------
2096-
appended : Index
2107+
Index
2108+
The combined index.
2109+
2110+
Examples
2111+
--------
2112+
>>> mi = pd.MultiIndex.from_arrays([['a'], ['b']])
2113+
>>> mi
2114+
MultiIndex([('a', 'b')],
2115+
)
2116+
>>> mi.append(mi)
2117+
MultiIndex([('a', 'b'), ('a', 'b')],
2118+
)
20972119
"""
20982120
if not isinstance(other, (list, tuple)):
20992121
other = [other]
@@ -3397,18 +3419,29 @@ def _reorder_indexer(
33973419

33983420
def truncate(self, before=None, after=None) -> MultiIndex:
33993421
"""
3400-
Slice index between two labels / tuples, return new MultiIndex
3422+
Slice index between two labels / tuples, return new MultiIndex.
34013423
34023424
Parameters
34033425
----------
34043426
before : label or tuple, can be partial. Default None
3405-
None defaults to start
3427+
None defaults to start.
34063428
after : label or tuple, can be partial. Default None
3407-
None defaults to end
3429+
None defaults to end.
34083430
34093431
Returns
34103432
-------
3411-
truncated : MultiIndex
3433+
MultiIndex
3434+
The truncated MultiIndex.
3435+
3436+
Examples
3437+
--------
3438+
>>> mi = pd.MultiIndex.from_arrays([['a', 'b', 'c'], ['x', 'y', 'z']])
3439+
>>> mi
3440+
MultiIndex([('a', 'x'), ('b', 'y'), ('c', 'z')],
3441+
)
3442+
>>> mi.truncate(before='a', after='b')
3443+
MultiIndex([('a', 'x'), ('b', 'y')],
3444+
)
34123445
"""
34133446
if after and before and after < before:
34143447
raise ValueError("after < before")

pandas/io/excel/_base.py

+3-2
Original file line numberDiff line numberDiff line change
@@ -1413,14 +1413,14 @@ def inspect_excel_format(
14131413

14141414
class ExcelFile:
14151415
"""
1416-
Class for parsing tabular excel sheets into DataFrame objects.
1416+
Class for parsing tabular Excel sheets into DataFrame objects.
14171417
14181418
See read_excel for more documentation.
14191419
14201420
Parameters
14211421
----------
14221422
path_or_buffer : str, bytes, path object (pathlib.Path or py._path.local.LocalPath),
1423-
a file-like object, xlrd workbook or openpyxl workbook.
1423+
A file-like object, xlrd workbook or openpyxl workbook.
14241424
If a string or path object, expected to be a path to a
14251425
.xls, .xlsx, .xlsb, .xlsm, .odf, .ods, or .odt file.
14261426
engine : str, default None
@@ -1448,6 +1448,7 @@ class ExcelFile:
14481448
`pyxlsb <https://pypi.org/project/pyxlsb/>`_ will be used.
14491449
14501450
.. versionadded:: 1.3.0
1451+
14511452
- Otherwise if `openpyxl <https://pypi.org/project/openpyxl/>`_ is installed,
14521453
then ``openpyxl`` will be used.
14531454
- Otherwise if ``xlrd >= 2.0`` is installed, a ``ValueError`` will be raised.

pandas/io/excel/_odfreader.py

+9-10
Original file line numberDiff line numberDiff line change
@@ -27,21 +27,20 @@
2727

2828
@doc(storage_options=_shared_docs["storage_options"])
2929
class ODFReader(BaseExcelReader):
30-
"""
31-
Read tables out of OpenDocument formatted files.
32-
33-
Parameters
34-
----------
35-
filepath_or_buffer : str, path to be parsed or
36-
an open readable stream.
37-
{storage_options}
38-
"""
39-
4030
def __init__(
4131
self,
4232
filepath_or_buffer: FilePath | ReadBuffer[bytes],
4333
storage_options: StorageOptions = None,
4434
) -> None:
35+
"""
36+
Read tables out of OpenDocument formatted files.
37+
38+
Parameters
39+
----------
40+
filepath_or_buffer : str, path to be parsed or
41+
an open readable stream.
42+
{storage_options}
43+
"""
4544
import_optional_dependency("odf")
4645
super().__init__(filepath_or_buffer, storage_options=storage_options)
4746

0 commit comments

Comments
 (0)