DOC: add note about `args`/`kwargs` to description of callable arguments

[deka27]

Is your feature request related to a problem? Please describe.

The approx_fprime function in scipy.optimize currently does not support keyword arguments (kwargs) for the objective function f. This limitation can lead to errors or warnings when f is a keyword-only function, as described in PEP 3102.

PEP 3102 introduces the concept of keyword-only arguments in Python, where arguments can be passed only by keyword and not by position. This is increasingly used in modern Python code to improve clarity and prevent errors. However, when such a function is passed to approx_fprime, it results in errors because approx_fprime only supports positional arguments through *args.

Describe the solution you'd like.

Enhance approx_fprime to accept kwargs and pass them to the objective function f. This would align approx_fprime with modern Python practices, reduce potential errors, and improve its flexibility.

The updated signature could look like this:

def approx_fprime(xk, f, epsilon=_epsilon, *args, **kwargs):
    ...

Describe alternatives you've considered.

Example of the Issue

Consider a function that requires keyword-only arguments:

import numpy as np
from scipy.optimize import approx_fprime

def func_with_kwargs(x, *, a=1.0, b=2.0):
    return a * np.sum(x**2) + b

xk = np.array([1.0, 2.0, 3.0])
epsilon = 1e-8

# This will raise an error because approx_fprime does not support kwargs
grad = approx_fprime(xk, func_with_kwargs, epsilon, 1.0, 2.0)

In this case, func_with_kwargs cannot be passed to approx_fprime without a workaround, such as wrapping it in another function or using functools.partial, both of which add unnecessary complexity.

Additional context (e.g. screenshots, GIFs)

Benefits

• Compatibility with Modern Python Code: By supporting kwargs, approx_fprime would be compatible with functions that utilize keyword-only arguments, as per PEP 3102.

• Ease of Use: Users would no longer need to resort to workarounds like wrappers or functools.partial to pass keyword arguments, making the function easier to use in a broader range of scenarios.

• Backward Compatibility: The proposed change is backward-compatible, as it would not affect existing code that only uses positional arguments.

Conclusion

Supporting kwargs in approx_fprime would make the function more versatile, aligning it with modern Python practices and improving its usability. This enhancement would be particularly beneficial for users working with keyword-only functions, which are becoming more common in the Python ecosystem.

[andyfaff]

approx_fprime may be superseded in future by the differentiation functionality introduced by @mdhaber. If that happens we'll definitely bear this issue in mind.

In the meantime it'll be easy to add it to approx_fprime, but that opens a can of worms - do we add it for the rest of scipy.optimize?

As an aside, I don't quite agree with

aligning it with modern Python practices and improving its usability

. One could still be using modern Python practices without using kwd only arguments.

[mdhaber]

Re: new differentiation functionality

This (scipy.differentiate) and the other elementwise iterative methods are the only functions I know of in which args actually needs to be accepted by the SciPy function for full functionality (which I won't get into here). So there, I might actually add kwargs.

---

As an aside, I don't quite agree with...

I would also suggest that "Supporting kwargs in approx_fprime would make the function more versatile", "approx_fprime would be compatible with functions that utilize keyword-only arguments" and the like overstate the benefits a bit. approx_fprime's versatility and compatibility would be unchanged because - as the next bullet states - approx_fprime can already be used with functions that accept additional positional and keyword arguments. The alternative to calling:

approx_fprime(x, f, args=args, kwargs=kwargs)

is typically as simple as:

approx_fprime(x, lambda x: f(x, *args, **kwargs))

because under the hood, that is all SciPy would do. So asking SciPy to relay args and kwargs to the callable is almost always for "Ease of Use" only. (The exception is mentioned at the top.)

This has been discussed many times, so I don't expect to convince anyone, but for completeness: if the latter were the one obvious way to do it, it would save SciPy from implementing, documenting, and testing args and kwargs in every SciPy function that accepts a callable. That time could be spent fixing bugs and implementing features that aren't already possible. However, because args is accepted by some functions, it looks like args and kwargs are missing from all others. Ideally, I would prefer to go in the other direction (e.g. deprecate args and simply document the alternative with a standard message for all functions that accept a callable), but I realize that this may be too disruptive.

[fancidev]

Ideally, I would prefer to go in the other direction (e.g. deprecate args and simply document the alternative), but I realize that this may be too disruptive.

+1 in this (other) direction. If the Python philosophy is to have one (obvious) way to do one thing, I think the (obvious) way for this kind of usage is to use a lambda.

[andyfaff]

the (obvious) way for this kind of usage is to use a lambda.

agree, until the function needs to be pickled.

[mdhaber]

Then write a one-line function, right?

[deka27]

Thank you for your thorough and insightful response to my feature request. After considering your points and reflecting on the matter, I've decided to withdraw my proposal for adding kwargs support to approx_fprime.

Your explanation of the existing workarounds and the potential trade-offs in implementation has helped me better understand the situation. I now see that the current functionality, combined with the lambda function approach you suggested, is sufficient for most use cases.

I appreciate the time you took to consider and respond to my suggestion.

[mdhaber]

@deka27 How about I leave this open as a documentation request? I'll add a standard note about using a lambda into the documentation of functions that accept a callable.

[deka27]

@mdhaber Thank you for this thoughtful suggestion. Adding a note about using lambda functions to the documentation sounds like a great idea. It will definitely help users like me understand how to work with these functions better.