[sage-devel] Re: Documentation of prcedures with decorator
I don't know what influence there is from Cython, but for general python-functions, decorators need to decorate their return functions with @sage_wraps (see e.g. sage.plots.contour_plot.contour_plot) to get the correct doc-strings. Setting these could be done manually in the decorator, but it is the intention that sage_wraps should coherently take care of all this and related stuff, so this should always be used instead of manually setting these. If decorated Cython functions are special, perhaps we should make a Cython-version of sage_wraps to fix this in the same, coherent manner. Even when using sage_wraps, Sphinx still uses the argument strings of the decorator when compiling the documentation. I posted a patch (Trac #9976) for this several months ago, which patches Sphinx and enhances the capabilities of sage_wraps to fix this, but there hasn't been a reviewer. Regards, Johan On Mar 1, 8:48 am, Robert Bradshaw wrote: > On Mon, Feb 28, 2011 at 11:39 PM, Simon King wrote: > > Hi Robert, > > > On 1 Mrz., 00:15, Robert Bradshaw > > wrote: > >> ... > >> > Namely, cached_method tries to obtain certain attributes common to > >> > python functions from its argument. func_defaults is just one among > >> > others. > > >> We don't have as much freedom here, as C-defined and python-defined > >> functions are quite different (standard library) objects. In this > >> case, cached_method should recognize > >> method_descriptors/builtin_function_or_method types and handle them > >> differently (if possible). > > > Where is the source code for method_descriptor or > > builtin_function_or_method? What is needed to be cimported from where, > > in order to access the attributes corresponding to func_defaults and > > friends? > > The source code is in the Python library itself, > e.g.http://svn.python.org/projects/python/trunk/Objects/methodobject.c > There's no direct analogue to many of these fields... > > - Robert -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Documentation of prcedures with decorator
On Mon, Feb 28, 2011 at 11:39 PM, Simon King wrote: > Hi Robert, > > On 1 Mrz., 00:15, Robert Bradshaw > wrote: >> ... >> > Namely, cached_method tries to obtain certain attributes common to >> > python functions from its argument. func_defaults is just one among >> > others. >> >> We don't have as much freedom here, as C-defined and python-defined >> functions are quite different (standard library) objects. In this >> case, cached_method should recognize >> method_descriptors/builtin_function_or_method types and handle them >> differently (if possible). > > Where is the source code for method_descriptor or > builtin_function_or_method? What is needed to be cimported from where, > in order to access the attributes corresponding to func_defaults and > friends? The source code is in the Python library itself, e.g. http://svn.python.org/projects/python/trunk/Objects/methodobject.c There's no direct analogue to many of these fields... - Robert -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
[sage-devel] Re: Documentation of prcedures with decorator
Hi Robert, On 1 Mrz., 00:15, Robert Bradshaw wrote: > ... > > Namely, cached_method tries to obtain certain attributes common to > > python functions from its argument. func_defaults is just one among > > others. > > We don't have as much freedom here, as C-defined and python-defined > functions are quite different (standard library) objects. In this > case, cached_method should recognize > method_descriptors/builtin_function_or_method types and handle them > differently (if possible). Where is the source code for method_descriptor or builtin_function_or_method? What is needed to be cimported from where, in order to access the attributes corresponding to func_defaults and friends? Cheers, Simon -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Documentation of prcedures with decorator
On Mon, Feb 28, 2011 at 2:35 PM, Simon King wrote:
> Hi Robert!
>
> On 28 Feb., 21:00, Robert Bradshaw
> wrote:
>> ...
>> Sorry, I forgot to mention that it must be declared as "cdef public
>> object __doc__". Otherwise it doesn't create a Python-visible wrapper,
>> so you're still (from Python) accessing the class-level __doc__.
>
> So, is there a difference between "cpdef" and "cdef public"? I wasn't
> aware of that.
Currently, cpdef is only for methods (not attributes), though there is
talk of changing that. It's probably a bug that we let it through
silently.
> But that's great, and naturally suggests a patch for coerce_binary.
Yep, should be a rather easy one. Is there a ticket yet?
> While we are at it: Are similar solutions available for the
> cached_method decorators?
>
> Currently, it fails as follows:
> sage: cython('''from sage.all import cached_method
> cdef class C:
> @cached_method
> def f(self,x):
> return x
> ''')
> Traceback (most recent call last):
> ...
> AttributeError: 'method_descriptor' object has no attribute
> 'func_defaults'
>
> Namely, cached_method tries to obtain certain attributes common to
> python functions from its argument. func_defaults is just one among
> others.
We don't have as much freedom here, as C-defined and python-defined
functions are quite different (standard library) objects. In this
case, cached_method should recognize
method_descriptors/builtin_function_or_method types and handle them
differently (if possible).
- Robert
--
To post to this group, send an email to sage-devel@googlegroups.com
To unsubscribe from this group, send an email to
sage-devel+unsubscr...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URL: http://www.sagemath.org
[sage-devel] Re: Documentation of prcedures with decorator
Hi Robert!
On 28 Feb., 21:00, Robert Bradshaw
wrote:
> ...
> Sorry, I forgot to mention that it must be declared as "cdef public
> object __doc__". Otherwise it doesn't create a Python-visible wrapper,
> so you're still (from Python) accessing the class-level __doc__.
So, is there a difference between "cpdef" and "cdef public"? I wasn't
aware of that.
But that's great, and naturally suggests a patch for coerce_binary.
While we are at it: Are similar solutions available for the
cached_method decorators?
Currently, it fails as follows:
sage: cython('''from sage.all import cached_method
cdef class C:
@cached_method
def f(self,x):
return x
''')
Traceback (most recent call last):
...
AttributeError: 'method_descriptor' object has no attribute
'func_defaults'
Namely, cached_method tries to obtain certain attributes common to
python functions from its argument. func_defaults is just one among
others.
Best regards,
Simon
--
To post to this group, send an email to sage-devel@googlegroups.com
To unsubscribe from this group, send an email to
sage-devel+unsubscr...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URL: http://www.sagemath.org
Re: [sage-devel] Re: Documentation of prcedures with decorator
On Mon, Feb 28, 2011 at 11:38 AM, Simon King wrote:
> Hi Robert,
>
> On 28 Feb., 19:56, Robert Bradshaw
> wrote:
>> If you add a "cdef object __doc__" member to that class, you should be
>> able to assign to it.
>
> I am afraid this is not true.
>
> One is not able to assign it. __doc__ is read only, even if you define
> it cpdef or :
>
> sage: cython('''cdef class C:
> : "Documentation of C"
> : cpdef object __doc__
> : ''')
> sage: c = C()
> sage: c?
> ...
> File: _mnt_local_king__sage_temp_mpc622_11271_tmp_0_spyx_0.pyx
> (starting at line 6) Documentation of C
> sage: c.__doc__='other documentation'
> Traceback (most recent call last)
> ...
> AttributeError: '_mnt_local_king__sage_temp_mpc622_11271_tmp_0_spyx'
> object attribute '__doc__' is read-only
Sorry, I forgot to mention that it must be declared as "cdef public
object __doc__". Otherwise it doesn't create a Python-visible wrapper,
so you're still (from Python) accessing the class-level __doc__.
sage: cython("""cdef class C:
...: cdef public object __doc__""")
sage: c = C()
sage: c.__doc__ = "my doc"
sage: c.__doc__
'my doc'
- Robert
--
To post to this group, send an email to sage-devel@googlegroups.com
To unsubscribe from this group, send an email to
sage-devel+unsubscr...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URL: http://www.sagemath.org
[sage-devel] Re: Documentation of prcedures with decorator
Hi Robert,
On 28 Feb., 19:56, Robert Bradshaw
wrote:
> If you add a "cdef object __doc__" member to that class, you should be
> able to assign to it.
I am afraid this is not true.
One is not able to assign it. __doc__ is read only, even if you define
it cpdef or :
sage: cython('''cdef class C:
: "Documentation of C"
: cpdef object __doc__
: ''')
sage: c = C()
sage: c?
...
File: _mnt_local_king__sage_temp_mpc622_11271_tmp_0_spyx_0.pyx
(starting at line 6) Documentation of C
sage: c.__doc__='other documentation'
Traceback (most recent call last)
...
AttributeError: '_mnt_local_king__sage_temp_mpc622_11271_tmp_0_spyx'
object attribute '__doc__' is read-only
Other attempt: We cdef (or cpdef, that doesn't matter here [I tested])
__doc__ and use methods to write to and read from it. Still, it
doesn't work.
sage: cython('''cdef class C:
: "Documentation of C"
: cpdef object __doc__
: def set_doc(self,s):
: self.__doc__=s
: def get_doc(self):
: return self.__doc__
: ''')
sage: c = C()
sage: c?
...
File: _mnt_local_king__sage_temp_mpc622_11271_tmp_1_spyx_0.pyx
(starting at line 6) Documentation of C
sage: c.set_doc('New documentation')
sage: c.get_doc()
'New documentation'
sage: c.__doc__
'File: _mnt_local_king__sage_temp_mpc622_11271_tmp_3_spyx_0.pyx
(starting at line 6)\nDocumentation of C'
sage: c?
...
File: _mnt_local_king__sage_temp_mpc622_11271_tmp_1_spyx_0.pyx
(starting at line 6) Documentation of C
So, even if you cdef (or cpdef) __doc__ and use a method to assign to
it, you would still not be able to use it for introspection.
Cheers,
Simon
--
To post to this group, send an email to sage-devel@googlegroups.com
To unsubscribe from this group, send an email to
sage-devel+unsubscr...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URL: http://www.sagemath.org
Re: [sage-devel] Re: Documentation of prcedures with decorator
On Mon, Feb 28, 2011 at 3:32 AM, Simon King wrote: > On 28 Feb., 12:18, Simon King wrote: >> ... >> I recall that it is impossible >> to modifiy __doc__ in Cython - could this be a related problem? > > That could very well be: cached_method is defined in sage/misc/ > cachefunc.py, whereas coerce_binop is an alias for a cdef-class > NamedBinopMethod from sage/structure/element.pyx > > So, IIRC, it would be impossible to assign __doc__ to an instance of > coerce_binop. If you add a "cdef object __doc__" member to that class, you should be able to assign to it. - Robert -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
[sage-devel] Re: Documentation of prcedures with decorator
On 28 Feb., 12:18, Simon King wrote: > ... > I recall that it is impossible > to modifiy __doc__ in Cython - could this be a related problem? That could very well be: cached_method is defined in sage/misc/ cachefunc.py, whereas coerce_binop is an alias for a cdef-class NamedBinopMethod from sage/structure/element.pyx So, IIRC, it would be impossible to assign __doc__ to an instance of coerce_binop. Cheers, Simon -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
[sage-devel] Re: Documentation of prcedures with decorator
Hi Marco, On 28 Feb., 11:00, mmarco wrote: > I think that it is because of the @coerce_binop decorator before the > definition of the procedure. So i wonder if it is a general problem > (that is, when you build the html documentation of a procedure which > is defined after a decorator, you get the help of the decorator) or if > there is something more specific going on here. At least it is not a general problem for all decorators. For example, the @cached_method seems fine. It is, e.g., used for the groebner_basis method of multivariate polynomial ideals, see http://www.sagemath.org/doc/reference/sage/rings/polynomial/multi_polynomial_ideal.html?highlight=groebner_basis#sage.rings.polynomial.multi_polynomial_ideal.MPolynomialIdeal.groebner_basis I don't know if the @coerce_binop decorator "forgot" to insert the proper doc string in the proper place. I recall that it is impossible to modifiy __doc__ in Cython - could this be a related problem? Best regards, Simon -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
