[three]Bean

I was using argparse and entry-points [console_scripts] in a project at work and I wanted each of the 12 console scripts to have a --help option that would display (among other things) the __doc__ of their main entry function. This way I wouldn't have to rewrite those docs over and over when I added a new script.

I came up with this little guy:

#!/usr/bin/env python
""" The module level docstring """

import inspect


def f():
    """ The function level docstring """
    print __my_doc__()


def g():
    """ Another function level docstring """
    print __my_doc__()


def __my_doc__():
    """ Print the docstring of the calling function """
    return globals()[inspect.stack()[1][0].f_code.co_name].__doc__


if __name__ == '__main__':
    f()
    g()

You could use it to, say, do:

import argparse

def some_command():
    """ This command will knock your socks off! """
    parser = argparse.ArgumentParser(description=__my_doc__())
    args = parser.parse_args()
    raise NotImplementedError("TODO -- gotta write this command still...")

Relying on globals() really sucks. If anyone can think of a better way to do it, let me know!

Thanks to some inspiration from @heewa, I landed on this solution which is much more portable.

import inspect

def __my_doc__(n=1):
    """ Print the docstring of the calling function.
    
    Because this function doesn't rely on :py:func:`globals()`, it is more
    portable.  It can now live in its own module and be invoked from elsewhere.
    """

    frame = inspect.stack()[n][0]
    return frame.f_globals[frame.f_code.co_name].__doc__

After consulting with Joseph Tate, we came to the decision to refactor the namespace for jquery plugins in ToscaWidgets2. Everything previously known as tw2.jquery.plugins.* is now known as tw2.jqplugins.*.

It all boils down to fighting with the tw2.jquery non-namespace. A jquery plugin package would live in ..../site-packages/tw2/jquery/plugins/someplugin and would have to ship its own file to ..../site-packages/tw2/jquery/__init__.py. However, tw2.jquery's own __init__.py file was non-empty. In order to not break everything, jquery plugin packages would have to mirror tw2.jquery-proper's own content but in the end still break the rule suggested in the second-to-last paragraph of this section of the setuptools documentation.

Apologies to anyone adversely affected who previously depended on any tw2.jquery.plugins.* packages. The following four of mine were affected, renamed, and should no longer be prone to big changes.

• tw2.jquery.plugins.ui moved to tw2.jqplugins.ui
• tw2.jquery.plugins.fg moved to tw2.jqplugins.fg
• tw2.jquery.plugins.jqgrid moved to tw2.jqplugins.jqgrid
• tw2.jquery.plugins.jqplot moved to tw2.jqplugins.jqplot

Lastly, if you do have projects that depend on anything in the tw2.jquery.plugins namespace, the following command should fix you up:
$ find . -name "*.py" -exec sed -i 's/jquery.plugins/jqplugins/g' {} \;