[Python-ideas] Proposal: Use mypy syntax for function annotations

[Barry Warsaw]

On Aug 14, 2014, at 12:01 PM, Sunjay Varma wrote:

>Here's a taste of what that looks like:
>    class SimpleEquation(object):
>
>        def demo(self, a, b, c):
>            """
>            This function returns the product of a, b and c
>            @type self: SimpleEquation
>            :param a: int - The first number
>            :param b: int
>            :param c: int - The third number should not be zero and should
>also
>                only be -1 if you enjoy carrots (this comment spans 2 lines)
>            :return: int
>            """
>            return a * b * c

I use this all the time.  I think I originally adopted this from epydoc:

http://epydoc.sourceforge.net/manual-fields.html

(i.e. the reStructuredText flavor of epydoc fields.)

E.g.

def inject_message(mlist, msg, recipients=None, switchboard=None, **kws):
    """Inject a message into a queue.

    If the message does not have a Message-ID header, one is added.  An
    X-Message-Id-Hash header is also always added.

    :param mlist: The mailing list this message is destined for.
    :type mlist: IMailingList
    :param msg: The Message object to inject.
    :type msg: a Message object
    :param recipients: Optional set of recipients to put into the message's
        metadata.
    :type recipients: sequence of strings
    :param switchboard: Optional name of switchboard to inject this message
        into.  If not given, the 'in' switchboard is used.
    :type switchboard: string
    :param kws: Additional values for the message metadata.
    :type kws: dictionary
    """

With perhaps a little more formalism (or care on the part of the author
<wink>), e.g. a better spelling of "sequence of strings", this format seems
much more readable to me.  And being tucked away in a docstring, it can really
be safely ignored.  It also seems like a processor like mypy could use this
information just as easily as type annotations.

For whatever reason, this style seems much more comfortable to me than trying
to encode everything in the function signature.  it also has the added benefit
of actually describing the purpose and detail of the arguments to a human
reader rather than leaving it up to a mental mapping to translate annotated
types to semantics or content detail.

Cheers,
-Barry
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20140815/1d4356ec/attachment.sig>