[Python-Dev] Re: def fn (args) [dec,dec]:

[John Lenton]

On Mon, Aug 09, 2004 at 01:05:48PM +1200, Greg Ewing wrote:
> 
> Perhaps someone can post some real-life use cases written with this
> syntax, so we can see what it would *really* look like in typical use,
> as opposed to made-up worst-case examples?

well, how about this:

    def someMethod(klass, anarg, otharg, lastarg):
        """
            Summary.

            Long description that explains the details about someMethod.
            Aliquam venenatis orci in risus. Nunc ornare aliquam
            lectus. Integer ligula turpis, posuere id, commodo ut, molestie
            id, est. Donec eu odio. Fusce at tellus in erat iaculis
            suscipit. Nulla metus dui, tristique vel, posuere sed,
            consectetuer sed, pede. Pellentesque habitant morbi tristique
            senectus et netus et malesuada fames ac turpis egestas. Mauris in
            orci sed metus porta auctor.

            @pre some_validator(lastarg)
            @post rv_validator(__return__)

            @type anarg: aClass
            @param anarg: desc of anarg
            @type otharg: othClass
            @param otharg: desc of otharg
            @type lastarg: lastClass
            @param lastarg: longer desc of lastarg because it's special

            @rtype: rClass
            @return: return value description
        """
        pass
    someMethod = classmethod(someMethod)

(yes, I have code that looks like this, roughly, from memory; I
make no claims as to typicality)

this could be rendered as (inventing some stuff here, probably
suboptimally; also, I assume you can access the args of the
function by name---I'm unable to verify that at this time):

    @param(anarg, aClass, 'desc of anarg')
    @param(otharg, othClass, 'desc of otharg')
    @param(lastarg, lastClass, "longer desc of lastarg because it's special")
    @return(rClass, 'return value description')
    @precondition(some_validator, lastarg)
    @postcondition(rv_validator)
    @classmethod
    def someMethod(klass, anarg, otharg, lastarg):
        """
            Summary.

            Long description that explains the details about someMethod.
            Aliquam venenatis orci in risus. Nunc ornare aliquam
            lectus. Integer ligula turpis, posuere id, commodo ut, molestie
            id, est. Donec eu odio. Fusce at tellus in erat iaculis
            suscipit. Nulla metus dui, tristique vel, posuere sed,
            consectetuer sed, pede. Pellentesque habitant morbi tristique
            senectus et netus et malesuada fames ac turpis egestas. Mauris in
            orci sed metus porta auctor.

        """
        pass

versus

    def someMethod(klass, anarg, otharg, lastarg) \
        [param(anarg, aClass, 'desc of anarg'),
         param(otharg, othClass, 'desc of otharg'),
         param(lastarg, lastClass, "longer desc of lastarg because it's special"),
         return(rClass, 'return value description'),
         precondition(some_validator, lastarg),
         postcondition(rv_validator),
         classmethod]:
        """
            Summary.

            Long description that explains the details about someMethod.
            Aliquam venenatis orci in risus. Nunc ornare aliquam
            lectus. Integer ligula turpis, posuere id, commodo ut, molestie
            id, est. Donec eu odio. Fusce at tellus in erat iaculis
            suscipit. Nulla metus dui, tristique vel, posuere sed,
            consectetuer sed, pede. Pellentesque habitant morbi tristique
            senectus et netus et malesuada fames ac turpis egestas. Mauris in
            orci sed metus porta auctor.

        """
        pass

I must say I found decorators' '@' ugly until I thought about
using it for doing what epydoc and contract do in docstrings...

-- 
John Lenton (john at grulic.org.ar) -- Random fortune:
Se olvida una buena acción, y no un buen bofetón. 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://mail.python.org/pipermail/python-dev/attachments/20040810/d4de6078/attachment.pgp