Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make the doc argument optional; use the docstring for the caller's module by default #318

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

kalekundert
Copy link

The most common way to use docopt is to write a module docstring and to pass it to docopt.docopt() using the special __doc__ global variable:

import docopt
args = docopt.docopt(__doc__)

This pull request makes this the default behavior. In other words, the code below would be equivalent to the code above:

import docopt
args = docopt.docopt()

There are two advantages to having this be the default behavior. First, users who aren't experienced enough to know that docstrings are accessible to their scripts via __doc__ won't need to worry about that detail anymore. Second, this saves some typing in the most common case. I type the docopt header in almost every script I write, so shortening it by ~20% would be nice.

It's worth noting that this feature uses the inspect module to interrogate the caller's stack frame and global namespace. This is somewhat magical, but I don't think it's any more magical (or different in philosophy) than using sys.argv by default.

New tests and updated documentation are included in the pull request.

Use the docstring from the caller's module if ``doc`` isn't explicitly
given.
@kalekundert kalekundert changed the title Make the doc argument optional; use the docstring for caller's module by default Make the doc argument optional; use the docstring for the caller's module by default Apr 11, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant