docstring-develop

RE: [Docstring-develop] Re: [Python-Dev] Re: AST mining (was Re: Direction of PyChecker)

[Tony J I. (Tibs) <to...@ls...>]

Jeremy Hylton wrote:
> I'd like to avoid producing many different versions
> for intermediate drafts.

Makes sense.

> Might you be able to grab the Python source tree and try it out:

I had a quick look earlier - our TeX setup doesn't seem to *quite* agree
with what's there. So in the end, given the documentation is (in fact)
not too long I've just printed the pages.

Hmm - might I suggest that so far as random users are concerned, one
long page in HTML may be more useful than the individual pages, for
external consumption?

Anyway, I'm currently in the midst (as time allows) of expanding your
original short example into a longer example that extracts more stuff -
fun. I'll post it (or put it up somewhere and say so) later on, I hope.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

RE: [Docstring-develop] Re: [Python-Dev] Re: AST mining (was Re: Direction of PyChecker)

[Tony J I. (Tibs) <to...@ls...>]

Hmm. Is everyone on that list of recipients really interested?

Anyway, I've spent a happy time (when I should have been earning money -
oh well) expanding Jeremy's example, ast-mining.py, to do more things.
I've done all of the easy stuff first (makes sense to me). Anyway, it
now reports on a lot more stuff, and is probably already useful enough
to be "plugged in" to initial DPS/reST usages.

Rather than make this message even longer, I've put it at:

	http://www.tibsnjoan.co.uk/reST/ast-mining.py

I've been testing it by running it on itself.

Comments, as ever, welcome.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

[Docstring-develop] Further adventures of ast-mining.py

[Tony J I. (Tibs) <to...@ls...>]

[recipients pruned - I've removed Python-Dev - will they care?]

I've had a *little* time to play with ast-mining.py, but won't have any
more today.

Whilst I'm not sure if this is of direct interest to anyone else, I'm
providing an update on the "release early, release often" principle.

I've uploaded two files:

	http://www.tibsnjoan.co.uk/reST/ast-mining.py
	http://www.tibsnjoan.co.uk/reST/test.py

The former now has a different command line interface (huh - sounds
posher than it is) - basically it can do what it did before, but it can
also "pretty print" the AST, or find candidates for assignments followed
by docstrings (DPS proposes to support these). It doesn't yet check the
candidates!

The latter is a simple test Python file suitable for input.

My intention is to provide a well commented example of a visitor, and
some simple tools for learning about ASTs. This is obviously of interest
to me, and I'm fairly sure addresses some of Neal's needs - is it also
useful to you, Jeremy?

The example visitor should then be directly usable by DPS, which is why
I'm faffing around with assignment docstrings (it will also make the
example a bit more interesting).

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

[Docstring-develop] Attribute docstrings

[Tony J I. (Tibs) <to...@ls...>]

I'm sending this to the development group and not the doc-sig because
I'm not convinced it makes enough sense!

DPS (pep 258) is proposing to support attribute docstrings.

Yet PEP 224 was rejected by the BDFL because he dislikes the look of::

    a = 1
    """Documentation."""
    b = 1

a. because he doesn't like it
b. because he can't tell if the docstring belongs
   to `a` or `b`

This rejection did *not* worry about issues of what value was used to
store the docstring (obviously not an issue for us).

Is DPS on dodgy ground in supporting a PEP that has been fundamentally
rejected?

As a potential *slight* cure for the BDFL objections (I'm doubtful), I
can only propose that we mark up the docstring itself::

    a = 1
    """.. doc::a Some documentation"""

would be documentation for `a`. That's a bit verbose, so maybe it should
be::

    """:doc:a Some documentation"""

Or even::

    """:a: Some documentation"""

(is that last stretching too far?)

[I'm not sure I like any of the above, in fact - do we have a BDFL
comment on this part of the DPS spec?]

Or maybe we should enforce no blank line before the docstring, and at
least one blank line after it (I've yet to see if we can tell that from
the AST, but I suspect we can).

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

Re: [Docstring-develop] Attribute docstrings

[David G. <dgo...@bi...>]

Tony J Ibbs (Tibs) <to...@ls...> wrote on 2001-08-16 09:42:
> I'm sending this to the development group and not the doc-sig
> because I'm not convinced it makes enough sense!

You're not convinced it makes sense to send this to the larger Doc-SIG
group, or you're not convinced that the *message itself* makes sense?
If the former, I think Doc-SIG *would* be appropriate (possibly get a
wider range of input). If the latter, I can't help you. ;-)

Seriously, I think docstring-develop should be used for
implementation issues (bugs, etc.), and Doc-SIG should be used for
general issues (policy, syntax). I've replied to Doc-SIG.

/David

Re: [Docstring-develop] Further adventures of ast-mining.py

[David G. <go...@us...>]

Tony J Ibbs (Tibs) <to...@ls...> wrote on 2001-08-16 09:18:
> [recipients pruned - I've removed Python-Dev - will they care?]

I think it's a good call.

> I've uploaded two files:
> 
>     http://www.tibsnjoan.co.uk/reST/ast-mining.py
>     http://www.tibsnjoan.co.uk/reST/test.py

Looks promising!

-- 
David Goodger    dgo...@us...    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net

[Docstring-develop] ast-mining version 0.3

[Tony J I. (Tibs) <to...@ls...>]

I've updated:

	http://www.tibsnjoan.co.uk/reST/ast-mining.py
	http://www.tibsnjoan.co.uk/reST/test.py

A first approximation to finding (DPS required) attribute docstrings is
in place (it's either very icky or very elegant - possibly both at
once).

Next is to make it aware of "hidden" globals - so the poor user can be
warned that there is a usage like::

    class A:
        def B():
            def C():
                def D():
                    global Z
                    # 100 lines of code, not mentioning Z
                    # and Z is not at the top level either
                    Z = 100

(which I think would be a Useful Thing to do - and also it's an
interesting thing to work out how to do).

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

[Docstring-develop] dps_visit.py (was ast-mining.py)

[Tony J I. (Tibs) <to...@ls...>]

This time, the files are:

 	http://www.tibsnjoan.co.uk/reST/dps_visit.py
 	http://www.tibsnjoan.co.uk/reST/test.py

ast-mining.py was becoming too unspecific, and as Jeremy pointed out,
not a valid name for importing.

I've changed various odds and ends - the scope info passed down now
means that functions inside functions inside... know about their scope
and superscope, which gives some hook for globals in them.

The next things to do are:

1. Internal documentation
2. Collect information about globals
3. Prune the final tree for DPS use
4. Plug in some DPS/reST code and see what happens

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)