[SPARK-47854][PYTHON][CONNECT] Avoid shadowing python built-ins in python function variable naming

[skanderboudawara]

What changes were proposed in this pull request?

Change all the functions parameters shadowing python built-in to a distinguished ones.

Why are the changes needed?

As mentionned in the Jira ticket

# breaks:
foo(str="x", bar="y")

# okay:
foo("x", bar="y")

Does this PR introduce any user-facing change?

Yes.

How was this patch tested?

Github actions

Was this patch authored or co-authored using generative AI tooling?

No

[HyukjinKwon]

This is actually a breaking change if users use this API via kwargs ..

[skanderboudawara]

Shall I add to keep both versions?

@overload
def expr(str: str) -> Column: …

Or else I create a decorator for future releases like so

from functools import wraps

def deprecated_param(old_param: str, new_param: str):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            if old_param in kwargs:
                import warnings
                warnings.warn(f"'{old_param}' is deprecated, use '{new_param}' instead", DeprecationWarning)
                kwargs[new_param] = kwargs.pop(old_param)
            return func(*args, **kwargs)
        return wrapper
    return decorator

@deprecated_param("str", "expression")
def expr(expression: str): ...

what do you think?

[HyukjinKwon]

We can do but i feel like deprecating the parameter is too much too. Shadowing the builtin names are not nice but it won't affect end users anyway

[skanderboudawara]

Hey,

I think my decorator needs another update. Since we can deprecate more than one parameter, I’m wondering if it makes sense to use a dictionary or maybe something else.

On the consistency side, all the new functions since version 3.3 use “col” instead of “str” for parameters. It feels like harmonizing everything would be a good move, but as you mentioned, it could be a breaking change for folks using keyword arguments.

What do you think?
Should we wait for more opinions on this topic ?