Skip to content

DOC: Add py:type reference targets to pandas.api.typing.aliases #63812

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sanrishi wants to merge 25 commits into
base: main
Choose a base branch
from
+65 −65
Open

DOC: Add py:type reference targets to pandas.api.typing.aliases #63812

Changes from 12 commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
e7500fe
added py:type reference targets
sanrishi Jan 22, 2026
39faa44
Added release notes
sanrishi Jan 22, 2026
c4ab08d
Clean up v3.0.0 documentation and fix references
sanrishi Jan 23, 2026
3297a4b
Add warning to avoid using a specific section
sanrishi Jan 23, 2026
ab72fad
Remove unnecessary blank line before Contributors section
sanrishi Jan 23, 2026
a39d612
Update doc/source/reference/aliases.rst
sanrishi Jan 23, 2026
1875ddd
Change module directive to currentmodule in aliases.rst
sanrishi Jan 23, 2026
b3da4ad
Update module directive in aliases.rst
sanrishi Jan 23, 2026
7ba1a2c
Refactor typing aliases documentation format
sanrishi Jan 24, 2026
f25f333
Update module directive in aliases.rst
sanrishi Jan 24, 2026
eafc53e
Clean up argument type definitions in aliases.rst
sanrishi Jan 24, 2026
19f025d
Fix formatting of type aliases in documentation
sanrishi Jan 24, 2026
77bd505
Update aliases in reference documentation
sanrishi Jan 24, 2026
8a5a66e
Update aliases.rst
sanrishi Jan 24, 2026
d0a2ff4
Merge branch 'main' into fix-type-aliases-refs
sanrishi Jan 25, 2026
9be934f
Update aliases.rst
sanrishi Jan 25, 2026
9f77356
Update aliases.rst
sanrishi Jan 25, 2026
dcc8ee7
Update aliases.rst
sanrishi Jan 25, 2026
6c67201
Update aliases.rst
sanrishi Jan 25, 2026
cc79f8e
Update aliases.rst
sanrishi Jan 25, 2026
daada57
Update aliases.rst
sanrishi Jan 25, 2026
8bbe339
Update aliases.rst
sanrishi Jan 25, 2026
4ba4f3e
Update aliases.rst
sanrishi Jan 25, 2026
dfb67a0
Update doc/source/reference/aliases.rst
sanrishi Jan 25, 2026
4bddfe4
Update doc/source/reference/aliases.rst
sanrishi Jan 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
274 changes: 203 additions & 71 deletions doc/source/reference/aliases.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ pandas typing aliases
Typing aliases
**************

.. currentmodule:: pandas.api.typing.aliases
.. module:: pandas.api.typing.aliases

The typing declarations in ``pandas/_typing.py`` are considered private, and used
by pandas developers for type checking of the pandas code base. For users, it is
Expand All @@ -23,74 +23,206 @@ own python code that calls pandas or expects certain results.

Note that the definitions and use cases of these aliases are subject to change without notice in any major, minor, or patch release of pandas.

Each of these aliases listed in the table below can be found by importing them from :py:mod:`pandas.api.typing.aliases`.
Each of these aliases listed below can be found by importing them from :py:mod:`pandas.api.typing.aliases`.

==================================== ================================================================
Alias Meaning
==================================== ================================================================
:py:type:`AggFuncType` Type of functions that can be passed to :meth:`agg` methods
:py:type:`AlignJoin` Argument type for ``join`` in :meth:`DataFrame.join`
:py:type:`AnyAll` Argument type for ``how`` in :meth:`dropna`
:py:type:`AnyArrayLike` Used to represent :class:`ExtensionArray`, ``numpy`` arrays, :class:`Index` and :class:`Series`
:py:type:`ArrayLike` Used to represent :class:`ExtensionArray`, ``numpy`` arrays
:py:type:`AstypeArg` Argument type in :meth:`astype`
:py:type:`Axes` :py:type:`AnyArrayLike` plus sequences (not strings) and ``range``
:py:type:`Axis` Argument type for ``axis`` in many methods
:py:type:`CSVEngine` Argument type for ``engine`` in :meth:`DataFrame.read_csv`
:py:type:`ColspaceArgType` Argument type for ``colspace`` in :meth:`DataFrame.to_html`
:py:type:`CompressionOptions` Argument type for ``compression`` in all I/O output methods except :meth:`DataFrame.to_parquet`
:py:type:`CorrelationMethod` Argument type for ``correlation`` in :meth:`corr`
:py:type:`DropKeep` Argument type for ``keep`` in :meth:`drop_duplicates`
:py:type:`Dtype` Types as objects that can be used to specify dtypes
:py:type:`DtypeArg` Argument type for ``dtype`` in various methods
:py:type:`DtypeBackend` Argument type for ``dtype_backend`` in various methods
:py:type:`DtypeObj` Numpy dtypes and Extension dtypes
:py:type:`ExcelWriterIfSheetExists` Argument type for ``if_sheet_exists`` in :class:`ExcelWriter`
:py:type:`ExcelWriterMergeCells` Argument type for ``merge_cells`` in :meth:`to_excel`
:py:type:`FilePath` Type of paths for files for I/O methods
:py:type:`FillnaOptions` Argument type for ``method`` in various methods where NA values are filled
:py:type:`FloatFormatType` Argument type for ``float_format`` in :meth:`to_string`
:py:type:`FormattersType` Argument type for ``formatters`` in :meth:`to_string`
:py:type:`FromDictOrient` Argument type for ``orient`` in :meth:`DataFrame.from_dict`
:py:type:`HTMLFlavors` Argument type for ``flavor`` in :meth:`pandas.read_html`
:py:type:`IgnoreRaise` Argument type for ``errors`` in multiple methods
:py:type:`IndexLabel` Argument type for ``level`` in multiple methods
:py:type:`InterpolateOptions` Argument type for ``interpolate`` in :meth:`interpolate`
:py:type:`JSONEngine` Argument type for ``engine`` in :meth:`read_json`
:py:type:`JSONSerializable` Argument type for the return type of a callable for argument ``default_handler`` in :meth:`to_json`
:py:type:`JoinHow` Argument type for ``how`` in :meth:`pandas.merge_ordered` and for ``join`` in :meth:`Series.align`
:py:type:`JoinValidate` Argument type for ``validate`` in :meth:`DataFrame.join`
:py:type:`MergeHow` Argument type for ``how`` in :meth:`merge`
:py:type:`MergeValidate` Argument type for ``validate`` in :meth:`merge`
:py:type:`NaPosition` Argument type for ``na_position`` in :meth:`sort_index` and :meth:`sort_values`
:py:type:`NsmallestNlargestKeep` Argument type for ``keep`` in :meth:`nlargest` and :meth:`nsmallest`
:py:type:`OpenFileErrors` Argument type for ``errors`` in :meth:`to_hdf` and :meth:`to_csv`
:py:type:`Ordered` Return type for :py:attr:`ordered` in :class:`CategoricalDtype` and :class:`Categorical`
:py:type:`ParquetCompressionOptions` Argument type for ``compression`` in :meth:`DataFrame.to_parquet`
:py:type:`QuantileInterpolation` Argument type for ``interpolation`` in :meth:`quantile`
:py:type:`ReadBuffer` Additional argument type corresponding to buffers for various file reading methods
:py:type:`ReadCsvBuffer` Additional argument type corresponding to buffers for :meth:`pandas.read_csv`
:py:type:`ReadPickleBuffer` Additional argument type corresponding to buffers for :meth:`pandas.read_pickle`
:py:type:`ReindexMethod` Argument type for ``reindex`` in :meth:`reindex`
:py:type:`Scalar` Types that can be stored in :class:`Series` with non-object dtype
:py:type:`SequenceNotStr` Used for arguments that require sequences, but not plain strings
:py:type:`SliceType` Argument types for ``start`` and ``end`` in :meth:`Index.slice_locs`
:py:type:`SortKind` Argument type for ``kind`` in :meth:`sort_index` and :meth:`sort_values`
:py:type:`StorageOptions` Argument type for ``storage_options`` in various file output methods
:py:type:`Suffixes` Argument type for ``suffixes`` in :meth:`merge`, :meth:`compare` and :meth:`merge_ordered`
:py:type:`TakeIndexer` Argument type for ``indexer`` and ``indices`` in :meth:`take`
:py:type:`TimeAmbiguous` Argument type for ``ambiguous`` in time operations
:py:type:`TimeGrouperOrigin` Argument type for ``origin`` in :meth:`resample` and :class:`TimeGrouper`
:py:type:`TimeNonexistent` Argument type for ``nonexistent`` in time operations
:py:type:`TimeUnit` Time unit argument and return type for :py:attr:`unit`, arguments ``unit`` and ``date_unit``
:py:type:`TimedeltaConvertibleTypes` Argument type for ``offset`` in :meth:`resample`, ``halflife`` in :meth:`ewm` and ``start`` and ``end`` in :meth:`pandas.timedelta_range`
:py:type:`TimestampConvertibleTypes` Argument type for ``origin`` in :meth:`resample` and :meth:`pandas.to_datetime`
:py:type:`ToStataByteorder` Argument type for ``byteorder`` in :meth:`DataFrame.to_stata`
:py:type:`ToTimestampHow` Argument type for ``how`` in :meth:`to_timestamp` and ``convention`` in :meth:`resample`
:py:type:`UpdateJoin` Argument type for ``join`` in :meth:`DataFrame.update`
:py:type:`UsecolsArgType` Argument type for ``usecols`` in :meth:`pandas.read_clipboard`, :meth:`pandas.read_csv` and :meth:`pandas.read_excel`
:py:type:`WindowingRankType` Argument type for ``method`` in :meth:`rank` in rolling and expanding window operations
:py:type:`WriteBuffer` Additional argument type corresponding to buffers for various file output methods
:py:type:`WriteExcelBuffer` Additional argument type corresponding to buffers for :meth:`to_excel`
:py:type:`XMLParsers` Argument type for ``parser`` in :meth:`DataFrame.to_xml` and :meth:`pandas.read_xml`
==================================== ================================================================
.. list-table::
:widths: 30 70
:header-rows: 1
Copy link
Contributor

@Dr-Irv Dr-Irv Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why can't we continue to use the markdown table with ===== as we do through most of the pandas docs?

Copy link
Contributor

@flying-sheep flying-sheep Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't check but as said multiple times, rST has a lot of implicit rules about where it accepts inline syntax, block syntax, both, or neither.

I assume table syntax might only support inline syntax and not block syntax, and directives are block syntax.

But as said, that's only an assumption based on the PR author not using table syntax.


* - Alias
- Meaning
* -
.. py:type:: AggFuncType
Copy link
Contributor

@Dr-Irv Dr-Irv Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When this is rendered it looks like:

type pandas.api.typing.aliases.AggFuncType

The module pandas.api.typing.aliases is quite redundant for every entry. Is there a way that could be removed?

Copy link
Contributor Author

@sanrishi sanrishi Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok thanks for clarification i think two backtick method will work by changing the module back to current module

Copy link
Contributor

@flying-sheep flying-sheep Jan 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, double backticks mean “this is code”. There point of this PR is to create reference targets.

In reference roles, using ~ will leave out the redundant part, but I'm not sure if it's possible to shorten here.

- Type of functions that can be passed to :meth:`agg` methods.
* -
.. py:type:: AlignJoin
- Argument type for ``join`` in :meth:`DataFrame.join`.
* -
.. py:type:: AnyAll
- Argument type for ``how`` in :meth:`dropna`.
* -
.. py:type:: AnyArrayLike
- Used to represent :class:`ExtensionArray`, ``numpy`` arrays, :class:`Index` and :class:`Series`.
* -
.. py:type:: ArrayLike
- Used to represent :class:`ExtensionArray`, ``numpy`` arrays.
* -
.. py:type:: AstypeArg
- Argument type in :meth:`astype`.
* -
.. py:type:: Axes
- :py:type:`AnyArrayLike` plus sequences (not strings) and ``range``.
* -
.. py:type:: Axis
- Argument type for ``axis`` in many methods.
* -
.. py:type:: CSVEngine
- Argument type for ``engine`` in :meth:`DataFrame.read_csv`.
* -
.. py:type:: ColspaceArgType
- Argument type for ``colspace`` in :meth:`DataFrame.to_html`.
* -
.. py:type:: CompressionOptions
- Argument type for ``compression`` in all I/O output methods except :meth:`DataFrame.to_parquet`.
* -
.. py:type:: CorrelationMethod
- Argument type for ``correlation`` in :meth:`corr`.
* -
.. py:type:: DropKeep
- Argument type for ``keep`` in :meth:`drop_duplicates`.
* -
.. py:type:: Dtype
- Types as objects that can be used to specify dtypes.
* -
.. py:type:: DtypeArg
- Argument type for ``dtype`` in various methods.
* -
.. py:type:: DtypeBackend
- Argument type for ``dtype_backend`` in various methods.
* -
.. py:type:: DtypeObj
- Numpy dtypes and Extension dtypes.
* -
.. py:type:: ExcelWriterIfSheetExists
- Argument type for ``if_sheet_exists`` in :class:`ExcelWriter`.
* -
.. py:type:: ExcelWriterMergeCells
- Argument type for ``merge_cells`` in :meth:`to_excel`.
* -
.. py:type:: FilePath
- Type of paths for files for I/O methods.
* -
.. py:type:: FillnaOptions
- Argument type for ``method`` in various methods where NA values are filled.
* -
.. py:type:: FloatFormatType
- Argument type for ``float_format`` in :meth:`to_string`.
* -
.. py:type:: FormattersType
- Argument type for ``formatters`` in :meth:`to_string`.
* -
.. py:type:: FromDictOrient
- Argument type for ``orient`` in :meth:`DataFrame.from_dict`.
* -
.. py:type:: HTMLFlavors
- Argument type for ``flavor`` in :meth:`pandas.read_html`.
* -
.. py:type:: IgnoreRaise
- Argument type for ``errors`` in multiple methods.
* -
.. py:type:: IndexLabel
- Argument type for ``level`` in multiple methods.
* -
.. py:type:: InterpolateOptions
- Argument type for ``interpolate`` in :meth:`interpolate`.
* -
.. py:type:: JSONEngine
- Argument type for ``engine`` in :meth:`read_json`.
* -
.. py:type:: JSONSerializable
- Argument type for the return type of a callable for argument ``default_handler`` in :meth:`to_json`.
* -
.. py:type:: JoinHow
- Argument type for ``how`` in :meth:`pandas.merge_ordered` and for ``join`` in :meth:`Series.align`.
* -
.. py:type:: JoinValidate
- Argument type for ``validate`` in :meth:`DataFrame.join`.
* -
.. py:type:: MergeHow
- Argument type for ``how`` in :meth:`merge`.
* -
.. py:type:: MergeValidate
- Argument type for ``validate`` in :meth:`merge`.
* -
.. py:type:: NaPosition
- Argument type for ``na_position`` in :meth:`sort_index` and :meth:`sort_values`.
* -
.. py:type:: NsmallestNlargestKeep
- Argument type for ``keep`` in :meth:`nlargest` and :meth:`nsmallest`.
* -
.. py:type:: OpenFileErrors
- Argument type for ``errors`` in :meth:`to_hdf` and :meth:`to_csv`.
* -
.. py:type:: Ordered
- Return type for :py:attr:`ordered` in :class:`CategoricalDtype` and :class:`Categorical`.
* -
.. py:type:: ParquetCompressionOptions
- Argument type for ``compression`` in :meth:`DataFrame.to_parquet`.
* -
.. py:type:: QuantileInterpolation
- Argument type for ``interpolation`` in :meth:`quantile`.
* -
.. py:type:: ReadBuffer
- Additional argument type corresponding to buffers for various file reading methods.
* -
.. py:type:: ReadCsvBuffer
- Additional argument type corresponding to buffers for :meth:`pandas.read_csv`.
* -
.. py:type:: ReadPickleBuffer
- Additional argument type corresponding to buffers for :meth:`pandas.read_pickle`.
* -
.. py:type:: ReindexMethod
- Argument type for ``reindex`` in :meth:`reindex`.
* -
.. py:type:: Scalar
- Types that can be stored in :class:`Series` with non-object dtype.
* -
.. py:type:: SequenceNotStr
- Used for arguments that require sequences, but not plain strings.
* -
.. py:type:: SliceType
- Argument types for ``start`` and ``end`` in :meth:`Index.slice_locs`.
* -
.. py:type:: SortKind
- Argument type for ``kind`` in :meth:`sort_index` and :meth:`sort_values`.
* -
.. py:type:: StorageOptions
- Argument type for ``storage_options`` in various file output methods.
* -
.. py:type:: Suffixes
- Argument type for ``suffixes`` in :meth:`merge`, :meth:`compare` and :meth:`merge_ordered`.
* -
.. py:type:: TakeIndexer
- Argument type for ``indexer`` and ``indices`` in :meth:`take`.
* -
.. py:type:: TimeAmbiguous
- Argument type for ``ambiguous`` in time operations.
* -
.. py:type:: TimeGrouperOrigin
- Argument type for ``origin`` in :meth:`resample` and :class:`TimeGrouper`.
* -
.. py:type:: TimeNonexistent
- Argument type for ``nonexistent`` in time operations.
* -
.. py:type:: TimeUnit
- Time unit argument and return type for :py:attr:`unit`, arguments ``unit`` and ``date_unit``.
* -
.. py:type:: TimedeltaConvertibleTypes
- Argument type for ``offset`` in :meth:`resample`, ``halflife`` in :meth:`ewm` and ``start`` and ``end`` in :meth:`pandas.timedelta_range`.
* -
.. py:type:: TimestampConvertibleTypes
- Argument type for ``origin`` in :meth:`resample` and :meth:`pandas.to_datetime`.
* -
.. py:type:: ToStataByteorder
- Argument type for ``byteorder`` in :meth:`DataFrame.to_stata`.
* -
.. py:type:: ToTimestampHow
- Argument type for ``how`` in :meth:`to_timestamp` and ``convention`` in :meth:`resample`.
* -
.. py:type:: UpdateJoin
- Argument type for ``join`` in :meth:`DataFrame.update`.
* -
.. py:type:: UsecolsArgType
- Argument type for ``usecols`` in :meth:`pandas.read_clipboard`, :meth:`pandas.read_csv` and :meth:`pandas.read_excel`.
* -
.. py:type:: WindowingRankType
- Argument type for ``method`` in :meth:`rank` in rolling and expanding window operations.
* -
.. py:type:: WriteBuffer
- Additional argument type corresponding to buffers for various file output methods.
* -
.. py:type:: WriteExcelBuffer
- Additional argument type corresponding to buffers for :meth:`to_excel`.
* -
.. py:type:: XMLParsers
- Argument type for ``parser`` in :meth:`DataFrame.to_xml` and :meth:`pandas.read_xml`.
Loading