Let substitute_function handle anon functions explicitly

[rws]

substitute_function expects two function objects as argument not expressions (f(x)). This leads to the (to some users) unexpected:

sage: f = function('f')(x)
....: g = function('g')(x)
....: df = f(x).diff(x)
sage: f.substitute_function(f,g)
f(x)
sage: f(1).substitute_function(f,g)
f(1)
sage: df.substitute_function(f,g)
diff(f(x), x)
sage: df(1).substitute_function(f,g)
D[0](f)(1)

(same with f(x)=function...)

The problem is that f and g are not function objects like sin. Taking this into account:

sage: f.substitute_function(f.operator(), g.operator())
g(x)
sage: f(1).substitute_function(f.operator(), g.operator())
g(1)
sage: df.substitute_function(f.operator(), g.operator())
diff(g(x), x)
sage: df(1).substitute_function(f.operator(), g.operator())
D[0](g)(1)

The ticket should make substitute_function raise an exception with a hint. Note that the mess results from function('f') returning a function object but function('f')(x) returning f(x) and users assigning this to f or f(x) instead of just doing

sage: f=function('f')
sage: f(1).substitute_function(f,g)
g(1)

Documentation of substitute_function could be made more explicit as well.

[nbruin]

The problem that "function" returned f(x) has been fixed since #17447, so I don't think this is an issue anymore. You can see it in the syntax that is used in the description: in function('f')(x) a function gets called explicitly to turn it into an expression.

Rather than substitute_function trying to guess how to sanitize its arguments, perhaps it should raise an exception if it can tell its argument will for sure not appear in the "function" slot.