← Back to branch summary

~ubuntu-branches/ubuntu/lucid/python2.6/lucid

« back to all changes in this revision

Viewing changes to Doc/library/optparse.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2010-03-11 13:30:19 UTC
  • mto: (10.1.13 sid)
  • mto: This revision was merged to the branch mainline in revision 44.
  • Revision ID: james.westby@ubuntu.com-20100311133019-sblbooa3uqrkoe70
Tags: upstream-2.6.5~rc2
Import upstream version 2.6.5~rc2

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/optparse.rst
55
55
   <yourscript> -h
56
56
   <yourscript> --help
57
57
 
58
 
and :mod:`optparse` will print out a brief summary of your script's options::
 
58
and :mod:`optparse` will print out a brief summary of your script's options:
 
59
 
 
60
.. code-block:: text
59
61
 
60
62
   usage: <yourscript> [options]
61
63
 
130
132
   an argument that follows an option, is closely associated with that option,
131
133
   and is consumed from the argument list when that option is. With
132
134
   :mod:`optparse`, option arguments may either be in a separate argument from
133
 
   their option::
 
135
   their option:
 
136
 
 
137
   .. code-block:: text
134
138
 
135
139
      -f foo
136
140
      --file foo
137
141
 
138
 
   or included in the same argument::
 
142
   or included in the same argument:
 
143
 
 
144
   .. code-block:: text
139
145
 
140
146
      -ffoo
141
147
      --file=foo
482
488
 
483
489
If :mod:`optparse` encounters either ``"-h"`` or ``"--help"`` on the
484
490
command-line, or if you just call :meth:`parser.print_help`, it prints the
485
 
following to standard output::
 
491
following to standard output:
 
492
 
 
493
.. code-block:: text
486
494
 
487
495
   usage: <yourscript> [options] arg1 arg2
488
496
 
556
564
    group.add_option("-g", action="store_true", help="Group option.")
557
565
    parser.add_option_group(group)
558
566
 
559
 
This would result in the following help output::
 
567
This would result in the following help output:
 
568
 
 
569
.. code-block:: text
560
570
 
561
571
    usage:  [options] arg1 arg2
562
572
 
595
605
   $ /usr/bin/foo --version
596
606
   foo 1.0
597
607
 
 
608
The following two methods can be used to print and get the ``version`` string:
 
609
 
 
610
.. method:: OptionParser.print_version(file=None)
 
611
 
 
612
   Print the version message for the current program (``self.version``) to
 
613
   *file* (default stdout).  As with :meth:`print_usage`, any occurrence
 
614
   of ``"%prog"`` in ``self.version`` is replaced with the name of the current
 
615
   program.  Does nothing if ``self.version`` is empty or undefined.
 
616
 
 
617
.. method:: OptionParser.get_version()
 
618
 
 
619
   Same as :meth:`print_version` but returns the version string instead of
 
620
   printing it.
 
621
 
598
622
 
599
623
.. _optparse-how-optparse-handles-errors:
600
624
 
645
669
:func:`OptionParser.error` from your application code.
646
670
 
647
671
If :mod:`optparse`'s default error-handling behaviour does not suit your needs,
648
 
you'll need to subclass OptionParser and override its :meth:`exit` and/or
649
 
:meth:`error` methods.
 
672
you'll need to subclass OptionParser and override its :meth:`~OptionParser.exit`
 
673
and/or :meth:`~OptionParser.error` methods.
650
674
 
651
675
 
652
676
.. _optparse-putting-it-all-together:
1133
1157
 
1134
1158
  If :mod:`optparse` sees either ``"-h"`` or ``"--help"`` on the command line,
1135
1159
  it will print something like the following help message to stdout (assuming
1136
 
  ``sys.argv[0]`` is ``"foo.py"``)::
 
1160
  ``sys.argv[0]`` is ``"foo.py"``):
 
1161
 
 
1162
  .. code-block:: text
1137
1163
 
1138
1164
     usage: foo.py [options]
1139
1165
 
1379
1405
   constructor keyword argument.  Passing ``None`` sets the default usage
1380
1406
   string; use :data:`optparse.SUPPRESS_USAGE` to suppress a usage message.
1381
1407
 
 
1408
.. method:: OptionParser.print_usage(file=None)
 
1409
 
 
1410
   Print the usage message for the current program (``self.usage``) to *file*
 
1411
   (default stdout).  Any occurrence of the string ``"%prog"`` in ``self.usage``
 
1412
   is replaced with the name of the current program.  Does nothing if
 
1413
   ``self.usage`` is empty or not defined.
 
1414
 
 
1415
.. method:: OptionParser.get_usage()
 
1416
 
 
1417
   Same as :meth:`print_usage` but returns the usage string instead of
 
1418
   printing it.
 
1419
 
1382
1420
.. method:: OptionParser.set_defaults(dest=value, ...)
1383
1421
 
1384
1422
   Set default values for several option destinations at once.  Using
1855
1893
 
1856
1894
Again we define a subclass of Option::
1857
1895
 
1858
 
   class MyOption (Option):
 
1896
   class MyOption(Option):
1859
1897
 
1860
1898
       ACTIONS = Option.ACTIONS + ("extend",)
1861
1899
       STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)