DOC: missing docs for `pd.col` Expression objects

[tswast]

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/dev/reference/api/pandas.col.html

Documentation problem

The returns section pandas.api.typing.Expression is not a link and I can't find anywhere else in the documentation that describes what you can do with an expression beyond this statement:

Any place which accepts lambda df: df[col_name], such as DataFrame.assign() or DataFrame.loc(), can also accept pd.col(col_name).

Suggested fix for documentation

Per https://github.com/pandas-dev/pandas/blob/main/pandas/core/col.py I can see that the following is supported:

• several binary operators
• any ufunc
• any Series accessor method
• any Series method (implemented by the "wrapper" at

  pandas/pandas/core/col.py

  Lines 179 to 190 in 415830f

  	def func(df: DataFrame, *args: Any, **kwargs: Any) -> Any:
  	parsed_args = _parse_args(df, *args)
  	parsed_kwargs = _parse_kwargs(df, **kwargs)
  	return getattr(self(df), attr)(*parsed_args, **parsed_kwargs)
  	def wrapper(*args: Any, **kwargs: Any) -> Expression:
  	args_str = _pretty_print_args_kwargs(*args, **kwargs)
  	repr_str = f"{self._repr_str}.{attr}({args_str})"
  	return Expression(lambda df: func(df, *args, **kwargs), repr_str)
  	return wrapper

  )

Ideally, pandas.api.typing.Expression would link to a documentation page that documents all of this.

Since the pandas.api.typing.Expression is just an alias, it would seem that code-wise very little if anything would have to change, just need to make sure this type shows up in a toc somewhere.

pandas/pandas/api/typing/__init__.py

Line 9 in 415830f

from pandas.core.col import Expression

[pranavkp71]

Hi, I’d like to work on this documentation issue. Can I take it up?