-
-
Notifications
You must be signed in to change notification settings - Fork 18.6k
adding pandas.api.typing.aliases and docs #61735
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.
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
Dr-Irv
wants to merge
6
commits into
pandas-dev:main
Choose a base branch
from
Dr-Irv:add-typing-aliases
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+296
−1
Open
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
e6fb15b
adding pandas.api.typing.aliases and docs
Dr-Irv 1cdef76
create aliases file and update tests
Dr-Irv c45b291
put internals back in test even though it fails on
Dr-Irv cfafd55
fix spelling issue in whatsnew
Dr-Irv bf0a106
Merge remote-tracking branch 'upstream/main' into add-typing-aliases
Dr-Irv f4804d3
implemented doc fixes
Dr-Irv File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,91 @@ | ||
| {{ header }} | ||
|
|
||
| .. _api.typing.aliases: | ||
|
|
||
| ====================================== | ||
| pandas typing aliases | ||
| ====================================== | ||
|
|
||
| ************** | ||
| Typing aliases | ||
| ************** | ||
|
|
||
| .. currentmodule:: pandas.api.atyping.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 | ||
| highly recommended to use the ``pandas-stubs`` package that represents the officially | ||
| supported type declarations for users of pandas. | ||
| Note that the definitions and use cases of these aliases are subject to change. | ||
| They are documented here for users who wish to use these declarations in their | ||
| own python code that calls pandas or expects certain results. | ||
|
|
||
| Each of these aliases listed in the table 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 many I/O output methods | ||
| :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:`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` Basic type that can be stored in :class:`Series` | ||
| :py:type:`SequenceNotStr` Used for arguments that require sequences, but not plain strings | ||
| :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` | ||
| ==================================== ================================================================ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,131 @@ | ||
| from pandas._typing import ( | ||
| AggFuncType, | ||
| AlignJoin, | ||
| AnyAll, | ||
| AnyArrayLike, | ||
| ArrayLike, | ||
| AstypeArg, | ||
| Axes, | ||
| Axis, | ||
| ColspaceArgType, | ||
| CompressionOptions, | ||
| CorrelationMethod, | ||
| CSVEngine, | ||
| DropKeep, | ||
| Dtype, | ||
| DtypeArg, | ||
| DtypeBackend, | ||
| DtypeObj, | ||
| ExcelWriterIfSheetExists, | ||
| ExcelWriterMergeCells, | ||
| FilePath, | ||
| FillnaOptions, | ||
| FloatFormatType, | ||
| FormattersType, | ||
| FromDictOrient, | ||
| HTMLFlavors, | ||
| IgnoreRaise, | ||
| IndexLabel, | ||
| InterpolateOptions, | ||
| JoinHow, | ||
| JoinValidate, | ||
| JSONEngine, | ||
| JSONSerializable, | ||
| MergeHow, | ||
| MergeValidate, | ||
| NaPosition, | ||
| NsmallestNlargestKeep, | ||
| OpenFileErrors, | ||
| Ordered, | ||
| QuantileInterpolation, | ||
| ReadBuffer, | ||
| ReadCsvBuffer, | ||
| ReadPickleBuffer, | ||
| ReindexMethod, | ||
| Scalar, | ||
| SequenceNotStr, | ||
| SortKind, | ||
| StorageOptions, | ||
| Suffixes, | ||
| TakeIndexer, | ||
| TimeAmbiguous, | ||
| TimedeltaConvertibleTypes, | ||
| TimeGrouperOrigin, | ||
| TimeNonexistent, | ||
| TimestampConvertibleTypes, | ||
| TimeUnit, | ||
| ToStataByteorder, | ||
| ToTimestampHow, | ||
| UpdateJoin, | ||
| UsecolsArgType, | ||
| WindowingRankType, | ||
| WriteBuffer, | ||
| WriteExcelBuffer, | ||
| XMLParsers, | ||
| ) | ||
|
|
||
| __all__ = [ | ||
| "AggFuncType", | ||
| "AlignJoin", | ||
| "AnyAll", | ||
| "AnyArrayLike", | ||
| "ArrayLike", | ||
| "AstypeArg", | ||
| "Axes", | ||
| "Axis", | ||
| "CSVEngine", | ||
| "ColspaceArgType", | ||
| "CompressionOptions", | ||
| "CorrelationMethod", | ||
| "DropKeep", | ||
| "Dtype", | ||
| "DtypeArg", | ||
| "DtypeBackend", | ||
| "DtypeObj", | ||
| "ExcelWriterIfSheetExists", | ||
| "ExcelWriterMergeCells", | ||
| "FilePath", | ||
| "FillnaOptions", | ||
| "FloatFormatType", | ||
| "FormattersType", | ||
| "FromDictOrient", | ||
| "HTMLFlavors", | ||
| "IgnoreRaise", | ||
| "IndexLabel", | ||
| "InterpolateOptions", | ||
| "JSONEngine", | ||
| "JSONSerializable", | ||
| "JoinHow", | ||
| "JoinValidate", | ||
| "MergeHow", | ||
| "MergeValidate", | ||
| "NaPosition", | ||
| "NsmallestNlargestKeep", | ||
| "OpenFileErrors", | ||
| "Ordered", | ||
| "QuantileInterpolation", | ||
| "ReadBuffer", | ||
| "ReadCsvBuffer", | ||
| "ReadPickleBuffer", | ||
| "ReindexMethod", | ||
| "Scalar", | ||
| "SequenceNotStr", | ||
| "SortKind", | ||
| "StorageOptions", | ||
| "Suffixes", | ||
| "TakeIndexer", | ||
| "TimeAmbiguous", | ||
| "TimeGrouperOrigin", | ||
| "TimeNonexistent", | ||
| "TimeUnit", | ||
| "TimedeltaConvertibleTypes", | ||
| "TimestampConvertibleTypes", | ||
| "ToStataByteorder", | ||
| "ToTimestampHow", | ||
| "UpdateJoin", | ||
| "UsecolsArgType", | ||
| "WindowingRankType", | ||
| "WriteBuffer", | ||
| "WriteExcelBuffer", | ||
| "XMLParsers", | ||
| ] | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There are many type aliases here where it is not clear what method(s) they are appropriate for. E.g. it would be wrong to use this for
DataFrame.to_parquet.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I tried to cover that in the docs, without getting too specific. I can make the docs more specific, although there are cases where the aliases are used in lots of methods, so the list can get quite long. E.g., for
CompressionOptions, I said "Argument type forcompressionin many I/O output methods" .Open to suggestions as to how to better document this.