Pandas version checks

  • [X] I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.astype.html

Documentation problem

Currently, the parameter specification

dtype: data type, or dict of column name

does not mention that Series are natively supported.

Suggested fix for documentation

Something along the lines of

dtype: string, data type, Series or Mapping of column name

Use a data type like object (string, numpy.dtype, pandas.ExtensionDtype or Python type) to cast entire pandas object to the same type. Alternatively, use a Mapping such as a dictionary of the form {col: dtype, …}, where col is a column label and dtype is the scalar type to cast one or more of the DataFrame’s columns to column-specific types.

One might also want to add: (https://github.com/pandas-dev/pandas/issues/43837)

The Mapping is not allowed to contain column names that are present in the DataFrame.

I also noticed that the relevant code

https://github.com/pandas-dev/pandas/blob/91111fd99898d9dcaa6bf6bedb662db4108da6e6/pandas/core/dtypes/inference.py#L266-L295

essentially is a weaker version of isinstance(obj, collections.abc.Mapping) that I guess was introduced to also catch Series. I would propose to think about replacing this with isinstance(obj, Mapping | Series) when appropriate.

Related: https://github.com/pandas-dev/pandas-stubs/issues/410

Comment From: randolf-scholz

Supporting Series is crucial in order to guarantee self-consistency:

import pandas as pd
df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
df = df.astype(df.dtypes)

Comment From: ramvikrams

@randolf-scholz can I do the fix in the documentation

Comment From: randolf-scholz

@ramvikrams Of course.