adding pandas.api.typing.aliases and docs #61735
+296
−1
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, | ||
|
There was a problem hiding this comment. 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 There was a problem hiding this comment. 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 Open to suggestions as to how to better document this. There was a problem hiding this comment. The only resolution I see is to introduce more aliases, e.g. In any case, if we deem something to be not "sufficiently good" I think we should refrain from releasing something new. That is my take on some of the aliases here, but I won't block if I'm alone. There was a problem hiding this comment. The current aliases follow what's in the code. So in your example, right now the type for There was a problem hiding this comment. Shouldn't those improvements be made prior to making them public? |
||
| 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.
I think this is implying that they are subject to change without any user notice. If that is the case, can this be made more explicit and put in a
.. warning::box. Perhaps something likeI would also be okay with only saying
major or minor; it seems okay to me saying we can promise not to make changes in patch releases.