Several pyspark.sql.functions have overly strict typing, in that the type is more restrictive than the functionality. Specifically, the function allows specifying the column to operate on with a pyspark.sql.Column or a str. This is handled internally by _to_java_column, which accepts a Column or string.
ColumnOrName was not added by Maciej Szymkiewicz since Maciej "was concerned that this might be confusing or ambiguous", because these functions take a column to operate on as well strings which are used in the operation.
But I think ColumnOrName makes clear that this variable refers to the column and not a string parameter. Also there are other ways to address confusion, such as via the docstring or by changing the argument name for the column to col from str.
Finally, there's considerable convenience for users to not have to wrap column names in pyspark.sql.functions.col. Elsewhere the API seems pretty consistent in its willingness to accept columns by name and not Column object (at least when there is not alternative meaning for a string value, exception would be .when/.otherwise).
For example, we were calling pyspark.sql.functions.split with a string value for the str argument (specifying which column to split). And I noticed this when we enforced typing with pyspark-stubs in preparation for pyspark 3.1. For users that will enable typing in 3.1, this is a restriction in functionality.
Pre-existing PRs to address this: