FAQ
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>

Search Discussions

  • Michael Foord at Jul 23, 2009 at 11:24 am

    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/
  • Nick Coghlan at Jul 23, 2009 at 12:40 pm

    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
    ---------------------------------------------------------------
  • Michael Foord at Jul 23, 2009 at 1:09 pm

    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/

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupdoc-sig @
categoriespython
postedJul 22, '09 at 7:48p
activeJul 23, '09 at 1:09p
posts4
users3
websitepython.org

People

Translate

site design / logo © 2019 Grokbase