PEP 257 question

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

PEP 257 question

Diakronik
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.


_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: PEP 257 question

Michael Foord-5
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  -  [hidden email]
> http://mail.python.org/mailman/listinfo/doc-sig
>  


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

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: PEP 257 question

Nick Coghlan
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   |   [hidden email]   |   Brisbane, Australia
---------------------------------------------------------------
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: PEP 257 question

Michael Foord-5
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/

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig