DOC: make clear that `DataFrame.astype` supports `Series` input

[randolf-scholz]

Pandas version checks

• 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: (#43837)

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

I also noticed that the relevant code

pandas/pandas/core/dtypes/inference.py

Lines 266 to 295 in 91111fd

	def is_dict_like(obj) -> bool:
	"""
	Check if the object is dict-like.
	Parameters
	----------
	obj : The object to check
	Returns
	-------
	is_dict_like : bool
	Whether `obj` has dict-like properties.
	Examples
	--------
	>>> is_dict_like({1: 2})
	True
	>>> is_dict_like([1, 2, 3])
	False
	>>> is_dict_like(dict)
	False
	>>> is_dict_like(dict())
	True
	"""
	dict_like_attrs = ("__getitem__", "keys", "__contains__")
	return (
	all(hasattr(obj, attr) for attr in dict_like_attrs)
	# [GH 25196] exclude classes
	and not isinstance(obj, type)
	)

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: pandas-dev/pandas-stubs#410

[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)

[ramvikrams]

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

[randolf-scholz]

@ramvikrams Of course.