Nikita Nemkin, 18.04.2013 07:07:
> Three improvements are included in this patch that I have found helpful when
> using Sphinx autodoc to document my project:
>
> 1) Default values preserve and display binary expressions and attribute
> access. For example, the following function will have its signature displayed
> as is:
>
> cpdef func(int flags=MyModule.FLAG1 | MyModule.FLAG2)
>
> This only affects expressions not reducible at compilation time, i.e. `2+2`
> will appear as `4`.
>
> 2) Public/readonly cdef attributes can have docstrings attached, using the
> [PEP 258 attribute docstring
> syntax](http://www.python.org/dev/peps/pep-0258/#attribute-docstrings).
> Example:
>
> cdef class X:
> cdef public attr
> """attr docstring"""
>
> When ``embedsignature=True`` Cython already adds a signature docstring to the
> generated property (assuming the example above). This patch allows to add an
> actual docstring too.
>
> Dosctrings on private cdef attributes will give a warning ("docstring
> ignored").
> Other forms and uses of attribute docstrings, as described in the PEP 258,
> are not supported at all (SyntaxError), because there is no standard
> introspection mechanism designed for them. ([PEP
> 224](http://www.python.org/dev/peps/pep-0224/) describing such mechanism had
> been rejected.)
>
> 3) `bint` appears as `bool` (instead of `int`) in autogenerated signatures,
> as I suggested on the mailing list.
>
> Each change is contained in its own commit in case you want to review them
> separately.
>
> https://github.com/cython/cython/pull/216
I like 1) and 3), but I'm not sure about 2).
Worth noting that PEP 258 was rejected, although definitely for other
reasons than this feature. I remember discussing this topic before on the
mailing list, but don't remember if we reached a conclusion. I faintly
recall that we preferred making the property explicit as soon as there's
more to it than a plain 1:1 mapping to the cdef attribute.
The above syntax is not wrong, but it also doesn't feel right to me. For
example, it's impossible to draw a distinction between the above and
something like
cdef class X:
cdef public attr
"""
quotes used for commenting out code here.
"""
And users are unlikely to notice that they just dropped some internals into
the docstring of a property they didn't even know they were implementing.
IMHO, the user intention is way too unclear in this syntactic construct.
Stefan
___
cython-devel mailing list
cython-devel@python.org
http://mail.python.org/mailman/listinfo/cython-devel
