From fred.mailhot at gmail.com  Wed Jul 22 21:48:25 2009
From: fred.mailhot at gmail.com (Fred Mailhot)
Date: Wed, 22 Jul 2009 15:48:25 -0400
Subject: [Doc-SIG] PEP 257 question
Message-ID: <a24554e40907221248g2f49d2dbjb6796096ce51b6b8@mail.gmail.com>

Hi,

It is stated in PEP 257 that:

"The docstring of a script (a stand-alone program) should be usable as its
"usage" message, printed when the script is invoked with incorrect or
missing arguments (or perhaps with a "-h" option, for "help").[...]"

This is exactly what I'm trying to do, but I haven't been able to figure out
how to access a script's docstring from within it. That is, I'm assuming
(perhaps erroneously) that I can define some kind of usage function in my
script that will spit out the docstring, as in the following example

#!/usr/bin/python
"""
myscript.py

Usage:  python myscript.py <params>

Some more specific info here.
"""

[python code here]

def main():
    [do stuff here]

### THIS IS WHAT I'D LIKE TO DO... ###
def usage():
    sys.stderr.write(this.__doc__)
    sys.exit()
### EXCEPT OF COURSE "this" ISN'T DEFINED

if __name__ == "__main__":
    if [some condition is not satisfied]:
        usage()
    else:
        main()
################################

What should I be doing instead? I've Googled a bunch and turned up nothing,
so I may just not be looking for the right terms (Googling "python print
script docstring" gets me nothing).

Thanks!
Fred.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20090722/e3265364/attachment.htm>

From fuzzyman at voidspace.org.uk  Thu Jul 23 13:24:17 2009
From: fuzzyman at voidspace.org.uk (Michael Foord)
Date: Thu, 23 Jul 2009 12:24:17 +0100
Subject: [Doc-SIG] PEP 257 question
In-Reply-To: <a24554e40907221248g2f49d2dbjb6796096ce51b6b8@mail.gmail.com>
References: <a24554e40907221248g2f49d2dbjb6796096ce51b6b8@mail.gmail.com>
Message-ID: <4A684861.9080506@voidspace.org.uk>

Fred Mailhot wrote:
> Hi,
>
> It is stated in PEP 257 that:
>
> "The docstring of a script (a stand-alone program) should be usable as 
> its "usage" message, printed when the script is invoked with incorrect 
> or missing arguments (or perhaps with a "-h" option, for "help").[...]"

I wasn't aware of that advice. Hmmm...

Anway - how about this:

import sys
module =  sys.modules['__main__'] # or [__name__]
docstring = module.__doc__

All the best,

Michael


>
> This is exactly what I'm trying to do, but I haven't been able to 
> figure out how to access a script's docstring from within it. That is, 
> I'm assuming (perhaps erroneously) that I can define some kind of 
> usage function in my script that will spit out the docstring, as in 
> the following example
>
> #!/usr/bin/python
> """
> myscript.py
>
> Usage:  python myscript.py <params>
>
> Some more specific info here.
> """
>
> [python code here]
>
> def main():
>     [do stuff here]
>
> ### THIS IS WHAT I'D LIKE TO DO... ###
> def usage():
>     sys.stderr.write(this.__doc__)
>     sys.exit()
> ### EXCEPT OF COURSE "this" ISN'T DEFINED
>
> if __name__ == "__main__":
>     if [some condition is not satisfied]:
>         usage()
>     else:
>         main()
> ################################
>
> What should I be doing instead? I've Googled a bunch and turned up 
> nothing, so I may just not be looking for the right terms (Googling 
> "python print script docstring" gets me nothing).
>
> Thanks!
> Fred.
>
> ------------------------------------------------------------------------
>
> _______________________________________________
> Doc-SIG maillist  -  Doc-SIG at python.org
> http://mail.python.org/mailman/listinfo/doc-sig
>   


-- 
http://www.ironpythoninaction.com/


From ncoghlan at gmail.com  Thu Jul 23 14:40:29 2009
From: ncoghlan at gmail.com (Nick Coghlan)
Date: Thu, 23 Jul 2009 22:40:29 +1000
Subject: [Doc-SIG] PEP 257 question
In-Reply-To: <4A684861.9080506@voidspace.org.uk>
References: <a24554e40907221248g2f49d2dbjb6796096ce51b6b8@mail.gmail.com>
	<4A684861.9080506@voidspace.org.uk>
Message-ID: <4A685A3D.30404@gmail.com>

Michael Foord wrote:
> Fred Mailhot wrote:
>> Hi,
>>
>> It is stated in PEP 257 that:
>>
>> "The docstring of a script (a stand-alone program) should be usable as
>> its "usage" message, printed when the script is invoked with incorrect
>> or missing arguments (or perhaps with a "-h" option, for "help").[...]"
> 
> I wasn't aware of that advice. Hmmm...
> 
> Anway - how about this:
> 
> import sys
> module =  sys.modules['__main__'] # or [__name__]
> docstring = module.__doc__

No need for the fancy footwork - remember that a module's globals and
its attributes are the same dict:

~/devel$ cat > demo.py
"My docstring"
print __doc__

~/devel$ python demo.py
My docstring

For modules and classes, the interpreter sets "__doc__" in the current
namespace automatically when it builds the docstring (not functions
though - their docstring isn't added to the local scope).

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
---------------------------------------------------------------

From fuzzyman at voidspace.org.uk  Thu Jul 23 15:09:14 2009
From: fuzzyman at voidspace.org.uk (Michael Foord)
Date: Thu, 23 Jul 2009 14:09:14 +0100
Subject: [Doc-SIG] PEP 257 question
In-Reply-To: <4A685A3D.30404@gmail.com>
References: <a24554e40907221248g2f49d2dbjb6796096ce51b6b8@mail.gmail.com>
	<4A684861.9080506@voidspace.org.uk> <4A685A3D.30404@gmail.com>
Message-ID: <4A6860FA.5050007@voidspace.org.uk>

Nick Coghlan wrote:
> Michael Foord wrote:
>   
>> Fred Mailhot wrote:
>>     
>>> Hi,
>>>
>>> It is stated in PEP 257 that:
>>>
>>> "The docstring of a script (a stand-alone program) should be usable as
>>> its "usage" message, printed when the script is invoked with incorrect
>>> or missing arguments (or perhaps with a "-h" option, for "help").[...]"
>>>       
>> I wasn't aware of that advice. Hmmm...
>>
>> Anway - how about this:
>>
>> import sys
>> module =  sys.modules['__main__'] # or [__name__]
>> docstring = module.__doc__
>>     
>
> No need for the fancy footwork - remember that a module's globals and
> its attributes are the same dict:
>
> ~/devel$ cat > demo.py
> "My docstring"
> print __doc__
>
>   

Ha! :-)

Thanks

Michael

> ~/devel$ python demo.py
> My docstring
>
> For modules and classes, the interpreter sets "__doc__" in the current
> namespace automatically when it builds the docstring (not functions
> though - their docstring isn't added to the local scope).
>
> Cheers,
> Nick.
>
>   


-- 
http://www.ironpythoninaction.com/


From g.brandl at gmx.net  Sun Jul 26 22:54:43 2009
From: g.brandl at gmx.net (Georg Brandl)
Date: Sun, 26 Jul 2009 22:54:43 +0200
Subject: [Doc-SIG] Out-of-service message for Python 3.0 docs?
Message-ID: <h4ifsd$7j3$1@ger.gmane.org>

Hi,

I wondered if it might sense to put some text into the 3.0 docs that
said that it's not supported anymore and users should go to 3.1.
Mockup: http://pocoo.org/~g/note.png

The link will go to the equivalent page in the 3.1 docs.

What do you think?

Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.


From fuzzyman at voidspace.org.uk  Sun Jul 26 22:57:52 2009
From: fuzzyman at voidspace.org.uk (Michael Foord)
Date: Sun, 26 Jul 2009 21:57:52 +0100
Subject: [Doc-SIG] Out-of-service message for Python 3.0 docs?
In-Reply-To: <h4ifsd$7j3$1@ger.gmane.org>
References: <h4ifsd$7j3$1@ger.gmane.org>
Message-ID: <4A6CC350.4010807@voidspace.org.uk>

Georg Brandl wrote:
> Hi,
>
> I wondered if it might sense to put some text into the 3.0 docs that
> said that it's not supported anymore and users should go to 3.1.
> Mockup: http://pocoo.org/~g/note.png
>
> The link will go to the equivalent page in the 3.1 docs.
>   

Sounds good. JFDI.

Michael

> What do you think?
>
> Georg
>
>   


-- 
http://www.ironpythoninaction.com/
http://www.voidspace.org.uk/blog