#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: |
--------------------------------+-------------------------------------------
Changes (by jsrn):
* status: needs_review => needs_work
Comment:
Phew, sometimes -- in the name of freedom -- Python standards have just
not been thought through :-S Partial seems to be a ''very'' confusing
function in general, and it seems surprising and very un-Guido Rossum like
to have it in the standard library. Notice that Python can not itself
figure these things out; if we make wrong calls to your f function above,
we get cryptic error messages:
{{{
sage: f()
...
TypeError: f0() takes exactly 6 non-keyword arguments (2 given)
sage: f(4,5)
...
TypeError: f0() takes exactly 6 non-keyword arguments (5 given)
}}}
so when I give no arguments, it thinks I gave 2 (to f0), but I have
actually given 3. When I supply 2 arguments, it thinks I gave 5. Something
is wrong here in the lines of what you have also found.
I think the most generally non-confusing, always working, and easiest to
implement solution would be to always use the ArgSpec of the partially
applied function (that is, recursively call the sage_get* function). The
author of the module should then indeed be wary that his "hack" didn't
cause anything to be widely erroneous in the documentation.
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. 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. However, one might argue that it will overly
specialise the sageinspect functions to cater for one certain type of
(misbehaving) wrapping, and that Sage authors in general should avoid
applying partial to module-level entities.
I would be satisfied with both. I don't think it is good programming
practice to use obscure wrapping in module-level entities, so I would
accept the first as fine. On the other hand, Sage in several places
already take the stance that programmers should be allowed to do whatever
works; and in this philosophy, we should aim for the second one.
This patch just keeps going on an on...
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/9976#comment:157>
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.
