#9976: Decorated functions/methods have generic signature in documentation
--------------------------------+-------------------------------------------
Reporter: jsrn | Owner: jsrn
Type: enhancement | Status: needs_work
Priority: major | Milestone: sage-4.7
Component: documentation | Keywords: sphinx, documentation, cython
inspection
Author: jsrn, Simon King | Upstream: N/A
Reviewer: Simon King | Merged:
Work_issues: |
--------------------------------+-------------------------------------------
Comment(by SimonKing):
Replying to [comment:157 jsrn]:
> Alternatively, make a small heuristic that does the right thing in usual
and well-behaved situations: Let e.g. f0 be a function with n positional
arguments and m named arguments with default values. If a partial
application of a funcion f0 sets the first s positional, sets the last t
positional by name, and redefines a number of the m named arguments, then
it is still possible to extract this information and enclose it in an
ArgSpec.
The following example shows the problem with your suggestion:
{{{
sage: import functools
sage: def f0(a,b,c,d,e,f,x=1,y=2,z=3): return
....:
sage: f = functools.partial(f0)
sage: f = functools.partial(f0,1,e=4,f=5,z=6)
}}}
That is as in your suggestion: Providing values for the first s positional
arguments by position (here: partial(0,1,...)), and providing values for
the last t positional arguments by name (here: partial(..., e=4,f=5,...)),
and also providing values for some of those arguments that already have a
default value (here: partial(...,z=6)).
However, we can not have
{{{
sage: sage_getargspec(f)
ArgSpec(args=['c', 'd', 'x', 'y'], varargs=None, keywords=None,
defaults=(1,2))
}}}
since it would appear as if you could provide the arguments x and y by
position. Also, we must not include the new default values in `defaults`
and keep the associated argument names in `args`: There is no way to re-
assign them, and so, they are no longer arguments to the function!
Is there a way to express in an argspec that some arguments can ''only''
be provided by name?
If there is no such way, then we must be even more restrictive. Note that
all arguments of f0 are positional - that the last few of them have a
default does not change the fact that they are positional. So, we can only
infer an argspec, if partial assigns values to the first s positions and
to the last t positions. Such as here:
{{{
sage: f = functools.partial(f0,1,f=5,x=6,y=7,z=8)
sage: sage_getargspec(f) # not implemented
ArgSpec(args=['c', 'd', 'e'], varargs=None, keywords=None, defaults=None)
sage: f = functools.partial(f0,1,y=7,z=8)
sage: sage_getargspec(f) # not implemented
ArgSpec(args=['c', 'd', 'e', 'f', 'x'], varargs=None, keywords=None,
defaults=(1,))
}}}
> We might even consider giving a warning in cases where this is not done
(as it is an error to write Sage code which doesn't document properly, or
something). Thinking about it, I don't think this solution is very
difficult to implement.
Like a deprecation warning? I think that would be not so good. If people
have the freedom to use functools.partial, then we should cope with it.
So, what do you think: Try to infer an argspec in the restricted way that
I sketched above, and return the argspec of the underlying function if
that is impossible? Or ''always'' return the argspec of the underlying
function?
Cheers,
Simon
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:158>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en.
