Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Add some basic documentation.

  • Loading branch information...
commit e94a5cc04cdb82b9ce20495766b0fef97f388f9c 1 parent 8d2ebec
Dusty Phillips authored
Showing with 81 additions and 0 deletions.
  1. +81 −0 README
View
81 README
@@ -0,0 +1,81 @@
+Opterator is an option parsing script for Python that takes the boilerplate out
+of option parsing. It currently wraps optparse.OptionParser, and thus behaves
+similarly, but in the future, it may take care of the parsing on its own to
+allow more freedom in specifying options.
+
+Opterator is based on an idea that a main() function for a script can be
+decorated to allow command-line arguments to be translated into method
+parameters. This allows it to be self-documenting, and reduces errors in
+creating and assigning options.
+
+For example, an optparse program for renaming a file might look like this:
+
+
+>>> from optparse import OptionParser
+>>> def main():
+... '''main entrypoint for renaming files. Accept two options, backup
+... and interactive'''
+... parser = OptionParser(usage="A script for renaming files")
+... parser.add_option('-b', '--backup', action=store_true,
+... help='backup the file')
+... parser.add_option('-i', '--interactive', action=store_true,
+... help='interactively move files')
+... # Move the file
+...
+>>> if __name__ == '__main__':
+... main()
+
+
+The equivalent code using opterator looks like this:
+
+
+>>> from opterator import opterate
+>>> @opterate
+... def main(source, dest, backup=False, interactive=False):
+... '''A script for renaming files
+... @param backup -b --backup store_true backup the file
+... @param interactive -i --interactive store_true interatively
+... move files... '''
+... # Move the file
+...
+>>> if __name__ == '__main__':
+... main()
+
+Opterator automatically generates help messages from the docstring. If your
+main function looks like this:
+
+
+@opterate
+def main(filename1, filename2, recursive=False, backup=False,
+ suffix='~', *other_filenames):
+ '''An example copy script with some example parameters that might
+ be used in a copy command.
+
+ @param recursive store_true -r --recursive copy directories
+ recursively
+ @param backup store_true -b --backup backup any files you copy over
+ @param suffix store -S --suffix override the usual backup
+ suffix '''
+ pass
+
+
+
+Your help text will look like this:
+
+
+dusty:opterator $ python copy.py -h
+Usage: copy.py [options] filename1 filename2 [other_filenames]
+
+An example copy script with some example parameters that might
+ be used in a copy command.
+
+Options:
+ -h, --help show this help message and exit
+ -r, --recursive copy directories recursively
+ -b, --backup backup any files you copy over
+ -S SUFFIX, --suffix=SUFFIX
+ override the usual backup suffix
+
+That's about it... let me know if you have any questions or suggestions.
+
+<dusty@linux.ca>
Please sign in to comment.
Something went wrong with that request. Please try again.