mirror of
https://github.com/python/cpython.git
synced 2024-11-28 12:31:14 +08:00
Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r86521 | eric.araujo | 2010-11-18 17:38:46 +0100 (jeu., 18 nov. 2010) | 17 lines Fix usage of :option: in the docs (#9312). :option: is used to create a link to an option of python, not to mark up any instance of any arbitrary command-line option. These were changed to ````. For modules which do have a command-line interface, lists of options have been properly marked up with the program/cmdoption directives combo. Options defined in such blocks can be linked to with :option: later in the same file, they won’t link to an option of python. Finally, the markup of command-line fragments in optparse.rst has been cleaned to use ``x`` instead of ``"x"``, keeping that latter form for actual Python strings. Patch by Eli Bendersky and Éric Araujo. ........ r86632 | eric.araujo | 2010-11-21 04:09:17 +0100 (dim., 21 nov. 2010) | 2 lines Style edits in followup to r86521 (#9312) ........ r86823 | eric.araujo | 2010-11-27 00:31:07 +0100 (sam., 27 nov. 2010) | 2 lines Use link-generating markup (see #9312) ........ r86824 | eric.araujo | 2010-11-27 00:46:18 +0100 (sam., 27 nov. 2010) | 2 lines Rewrap long lines + minor edits ........ r87294 | eric.araujo | 2010-12-16 01:07:01 +0100 (jeu., 16 déc. 2010) | 2 lines No need to generate a link for something that’s just above. ........ r87296 | eric.araujo | 2010-12-16 01:23:30 +0100 (jeu., 16 déc. 2010) | 2 lines Advertise “python -m” instead of direct filename. ........ r87300 | eric.araujo | 2010-12-16 02:40:26 +0100 (jeu., 16 déc. 2010) | 2 lines Advertise “python -m test” over test.regrtest (r87296 followup) ........ r87302 | eric.araujo | 2010-12-16 03:10:11 +0100 (jeu., 16 déc. 2010) | 2 lines Add versionadded directive missing from r78983. ........
This commit is contained in:
Éric Araujo
parent
b7ae2095d0
commit
3efdf0630b
@ -788,7 +788,7 @@ Encodings and Unicode
|
||||
|
||||
Strings are stored internally as sequences of codepoints (to be precise
|
||||
as :ctype:`Py_UNICODE` arrays). Depending on the way Python is compiled (either
|
||||
via :option:`--without-wide-unicode` or :option:`--with-wide-unicode`, with the
|
||||
via ``--without-wide-unicode`` or ``--with-wide-unicode``, with the
|
||||
former being the default) :ctype:`Py_UNICODE` is either a 16-bit or 32-bit data
|
||||
type. Once a string object is used outside of CPU and memory, CPU endianness
|
||||
and how these arrays are stored as bytes become an issue. Transforming a
|
||||
|
||||
@ -10,14 +10,44 @@ libraries. These functions compile Python source files in a directory tree,
|
||||
allowing users without permission to write to the libraries to take advantage of
|
||||
cached byte-code files.
|
||||
|
||||
This module may also be used as a script (using the :option:`-m` Python flag) to
|
||||
compile Python sources. Directories to recursively traverse (passing
|
||||
:option:`-l` stops the recursive behavior) for sources are listed on the command
|
||||
line. If no arguments are given, the invocation is equivalent to ``-l
|
||||
sys.path``. Printing lists of the files compiled can be disabled with the
|
||||
:option:`-q` flag. In addition, the :option:`-x` option takes a regular
|
||||
expression argument. All files that match the expression will be skipped.
|
||||
|
||||
Command-line use
|
||||
----------------
|
||||
|
||||
This module can work as a script (using :program:`python -m compileall`) to
|
||||
compile Python sources.
|
||||
|
||||
.. program:: compileall
|
||||
|
||||
.. cmdoption:: [directory|file]...
|
||||
|
||||
Positional arguments are files to compile or directories that contain
|
||||
source files, traversed recursively. If no argument is given, behave as if
|
||||
the command line was ``-l <directories from sys.path>``.
|
||||
|
||||
.. cmdoption:: -l
|
||||
|
||||
Do not recurse.
|
||||
|
||||
.. cmdoption:: -f
|
||||
|
||||
Force rebuild even if timestamps are up-to-date.
|
||||
|
||||
.. cmdoption:: -q
|
||||
|
||||
Do not print the list of files compiled.
|
||||
|
||||
.. cmdoption:: -d destdir
|
||||
|
||||
Purported directory name for error messages.
|
||||
|
||||
.. cmdoption:: -x regex
|
||||
|
||||
Skip files with a full path that matches given regular expression.
|
||||
|
||||
|
||||
Public functions
|
||||
----------------
|
||||
|
||||
.. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=False)
|
||||
|
||||
@ -34,7 +64,6 @@ expression argument. All files that match the expression will be skipped.
|
||||
If *quiet* is true, nothing is printed to the standard output in normal
|
||||
operation.
|
||||
|
||||
|
||||
.. function:: compile_path(skip_curdir=True, maxlevels=0, force=False)
|
||||
|
||||
Byte-compile all the :file:`.py` files found along ``sys.path``. If
|
||||
@ -58,4 +87,3 @@ subdirectory and all its subdirectories::
|
||||
|
||||
Module :mod:`py_compile`
|
||||
Byte-compile a single source file.
|
||||
|
||||
|
||||
@ -88,7 +88,7 @@ works its magic::
|
||||
$
|
||||
|
||||
There's no output! That's normal, and it means all the examples worked. Pass
|
||||
:option:`-v` to the script, and :mod:`doctest` prints a detailed log of what
|
||||
``-v`` to the script, and :mod:`doctest` prints a detailed log of what
|
||||
it's trying, and prints a summary at the end::
|
||||
|
||||
$ python example.py -v
|
||||
@ -151,7 +151,7 @@ example(s) and the cause(s) of the failure(s) are printed to stdout, and the
|
||||
final line of output is ``***Test Failed*** N failures.``, where *N* is the
|
||||
number of examples that failed.
|
||||
|
||||
Run it with the :option:`-v` switch instead::
|
||||
Run it with the ``-v`` switch instead::
|
||||
|
||||
python M.py -v
|
||||
|
||||
@ -160,7 +160,7 @@ with assorted summaries at the end.
|
||||
|
||||
You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or
|
||||
prohibit it by passing ``verbose=False``. In either of those cases,
|
||||
``sys.argv`` is not examined by :func:`testmod` (so passing :option:`-v` or not
|
||||
``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not
|
||||
has no effect).
|
||||
|
||||
There is also a command line shortcut for running :func:`testmod`. You can
|
||||
@ -229,7 +229,7 @@ See section :ref:`doctest-basic-api` for a description of the optional arguments
|
||||
that can be used to tell it to look for files in other locations.
|
||||
|
||||
Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the
|
||||
:option:`-v` command-line switch or with the optional keyword argument
|
||||
``-v`` command-line switch or with the optional keyword argument
|
||||
*verbose*.
|
||||
|
||||
There is also a command line shortcut for running :func:`testfile`. You can
|
||||
@ -1361,7 +1361,7 @@ DocTestRunner objects
|
||||
verbosity. If *verbose* is ``True``, then information is printed about each
|
||||
example, as it is run. If *verbose* is ``False``, then only failures are
|
||||
printed. If *verbose* is unspecified, or ``None``, then verbose output is used
|
||||
iff the command-line switch :option:`-v` is used.
|
||||
iff the command-line switch ``-v`` is used.
|
||||
|
||||
The optional keyword argument *optionflags* can be used to control how the test
|
||||
runner compares expected output to actual output, and how it displays failures.
|
||||
|
||||
@ -120,7 +120,7 @@ The following exceptions are the exceptions that are usually raised.
|
||||
|
||||
Raised when a floating point operation fails. This exception is always defined,
|
||||
but can only be raised when Python is configured with the
|
||||
:option:`--with-fpectl` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is
|
||||
``--with-fpectl`` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is
|
||||
defined in the :file:`pyconfig.h` file.
|
||||
|
||||
|
||||
|
||||
@ -41,7 +41,7 @@ exception:
|
||||
empty string. Long options on the command line can be recognized so long as
|
||||
they provide a prefix of the option name that matches exactly one of the
|
||||
accepted options. For example, if *longopts* is ``['foo', 'frob']``, the
|
||||
option :option:`--fo` will match as :option:`--foo`, but :option:`--f` will
|
||||
option ``--fo`` will match as ``--foo``, but ``--f`` will
|
||||
not match uniquely, so :exc:`GetoptError` will be raised.
|
||||
|
||||
The return value consists of two elements: the first is a list of ``(option,
|
||||
@ -62,7 +62,7 @@ exception:
|
||||
intermixed. The :func:`getopt` function stops processing options as soon as a
|
||||
non-option argument is encountered.
|
||||
|
||||
If the first character of the option string is '+', or if the environment
|
||||
If the first character of the option string is ``'+'``, or if the environment
|
||||
variable :envvar:`POSIXLY_CORRECT` is set, then option processing stops as
|
||||
soon as a non-option argument is encountered.
|
||||
|
||||
|
||||
@ -286,13 +286,13 @@ Command line usage
|
||||
|
||||
If there are arguments:
|
||||
|
||||
#. If :option:`-e` is used, arguments are files opened for editing and
|
||||
#. If ``-e`` is used, arguments are files opened for editing and
|
||||
``sys.argv`` reflects the arguments passed to IDLE itself.
|
||||
|
||||
#. Otherwise, if :option:`-c` is used, all arguments are placed in
|
||||
#. Otherwise, if ``-c`` is used, all arguments are placed in
|
||||
``sys.argv[1:...]``, with ``sys.argv[0]`` set to ``'-c'``.
|
||||
|
||||
#. Otherwise, if neither :option:`-e` nor :option:`-c` is used, the first
|
||||
#. Otherwise, if neither ``-e`` nor ``-c`` is used, the first
|
||||
argument is a script which is executed with the remaining arguments in
|
||||
``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the script
|
||||
name is '-', no script is executed but an interactive Python session is started;
|
||||
|
||||
@ -98,26 +98,26 @@ option
|
||||
an argument used to supply extra information to guide or customize the
|
||||
execution of a program. There are many different syntaxes for options; the
|
||||
traditional Unix syntax is a hyphen ("-") followed by a single letter,
|
||||
e.g. ``"-x"`` or ``"-F"``. Also, traditional Unix syntax allows multiple
|
||||
options to be merged into a single argument, e.g. ``"-x -F"`` is equivalent
|
||||
to ``"-xF"``. The GNU project introduced ``"--"`` followed by a series of
|
||||
hyphen-separated words, e.g. ``"--file"`` or ``"--dry-run"``. These are the
|
||||
e.g. ``-x`` or ``-F``. Also, traditional Unix syntax allows multiple
|
||||
options to be merged into a single argument, e.g. ``-x -F`` is equivalent
|
||||
to ``-xF``. The GNU project introduced ``--`` followed by a series of
|
||||
hyphen-separated words, e.g. ``--file`` or ``--dry-run``. These are the
|
||||
only two option syntaxes provided by :mod:`optparse`.
|
||||
|
||||
Some other option syntaxes that the world has seen include:
|
||||
|
||||
* a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same
|
||||
* a hyphen followed by a few letters, e.g. ``-pf`` (this is *not* the same
|
||||
as multiple options merged into a single argument)
|
||||
|
||||
* a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically
|
||||
* a hyphen followed by a whole word, e.g. ``-file`` (this is technically
|
||||
equivalent to the previous syntax, but they aren't usually seen in the same
|
||||
program)
|
||||
|
||||
* a plus sign followed by a single letter, or a few letters, or a word, e.g.
|
||||
``"+f"``, ``"+rgb"``
|
||||
``+f``, ``+rgb``
|
||||
|
||||
* a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``,
|
||||
``"/file"``
|
||||
* a slash followed by a letter, or a few letters, or a word, e.g. ``/f``,
|
||||
``/file``
|
||||
|
||||
These option syntaxes are not supported by :mod:`optparse`, and they never
|
||||
will be. This is deliberate: the first three are non-standard on any
|
||||
@ -145,9 +145,9 @@ option argument
|
||||
Typically, a given option either takes an argument or it doesn't. Lots of
|
||||
people want an "optional option arguments" feature, meaning that some options
|
||||
will take an argument if they see it, and won't if they don't. This is
|
||||
somewhat controversial, because it makes parsing ambiguous: if ``"-a"`` takes
|
||||
an optional argument and ``"-b"`` is another option entirely, how do we
|
||||
interpret ``"-ab"``? Because of this ambiguity, :mod:`optparse` does not
|
||||
somewhat controversial, because it makes parsing ambiguous: if ``-a`` takes
|
||||
an optional argument and ``-b`` is another option entirely, how do we
|
||||
interpret ``-ab``? Because of this ambiguity, :mod:`optparse` does not
|
||||
support this feature.
|
||||
|
||||
positional argument
|
||||
@ -165,9 +165,9 @@ For example, consider this hypothetical command-line::
|
||||
|
||||
prog -v --report /tmp/report.txt foo bar
|
||||
|
||||
``"-v"`` and ``"--report"`` are both options. Assuming that :option:`--report`
|
||||
takes one argument, ``"/tmp/report.txt"`` is an option argument. ``"foo"`` and
|
||||
``"bar"`` are positional arguments.
|
||||
``-v`` and ``--report`` are both options. Assuming that ``--report``
|
||||
takes one argument, ``/tmp/report.txt`` is an option argument. ``foo`` and
|
||||
``bar`` are positional arguments.
|
||||
|
||||
|
||||
.. _optparse-what-options-for:
|
||||
@ -252,7 +252,7 @@ Then you can start defining options. The basic syntax is::
|
||||
parser.add_option(opt_str, ...,
|
||||
attr=value, ...)
|
||||
|
||||
Each option has one or more option strings, such as ``"-f"`` or ``"--file"``,
|
||||
Each option has one or more option strings, such as ``-f`` or ``--file``,
|
||||
and several option attributes that tell :mod:`optparse` what to expect and what
|
||||
to do when it encounters that option on the command line.
|
||||
|
||||
@ -281,7 +281,7 @@ that's rarely necessary: by default it uses ``sys.argv[1:]``.)
|
||||
:meth:`parse_args` returns two values:
|
||||
|
||||
* ``options``, an object containing values for all of your options---e.g. if
|
||||
``"--file"`` takes a single string argument, then ``options.file`` will be the
|
||||
``--file`` takes a single string argument, then ``options.file`` will be the
|
||||
filename supplied by the user, or ``None`` if the user did not supply that
|
||||
option
|
||||
|
||||
@ -327,8 +327,8 @@ Now let's make up a fake command line and ask :mod:`optparse` to parse it::
|
||||
args = ["-f", "foo.txt"]
|
||||
(options, args) = parser.parse_args(args)
|
||||
|
||||
When :mod:`optparse` sees the option string ``"-f"``, it consumes the next
|
||||
argument, ``"foo.txt"``, and stores it in ``options.filename``. So, after this
|
||||
When :mod:`optparse` sees the option string ``-f``, it consumes the next
|
||||
argument, ``foo.txt``, and stores it in ``options.filename``. So, after this
|
||||
call to :meth:`parse_args`, ``options.filename`` is ``"foo.txt"``.
|
||||
|
||||
Some other option types supported by :mod:`optparse` are ``int`` and ``float``.
|
||||
@ -340,13 +340,13 @@ Note that this option has no long option string, which is perfectly acceptable.
|
||||
Also, there's no explicit action, since the default is ``store``.
|
||||
|
||||
Let's parse another fake command-line. This time, we'll jam the option argument
|
||||
right up against the option: since ``"-n42"`` (one argument) is equivalent to
|
||||
``"-n 42"`` (two arguments), the code ::
|
||||
right up against the option: since ``-n42`` (one argument) is equivalent to
|
||||
``-n 42`` (two arguments), the code ::
|
||||
|
||||
(options, args) = parser.parse_args(["-n42"])
|
||||
print(options.num)
|
||||
|
||||
will print ``"42"``.
|
||||
will print ``42``.
|
||||
|
||||
If you don't specify a type, :mod:`optparse` assumes ``string``. Combined with
|
||||
the fact that the default action is ``store``, that means our first example can
|
||||
@ -356,9 +356,9 @@ be a lot shorter::
|
||||
|
||||
If you don't supply a destination, :mod:`optparse` figures out a sensible
|
||||
default from the option strings: if the first long option string is
|
||||
``"--foo-bar"``, then the default destination is ``foo_bar``. If there are no
|
||||
``--foo-bar``, then the default destination is ``foo_bar``. If there are no
|
||||
long option strings, :mod:`optparse` looks at the first short option string: the
|
||||
default destination for ``"-f"`` is ``f``.
|
||||
default destination for ``-f`` is ``f``.
|
||||
|
||||
:mod:`optparse` also includes the built-in ``complex`` type. Adding
|
||||
types is covered in section :ref:`optparse-extending-optparse`.
|
||||
@ -372,7 +372,7 @@ Handling boolean (flag) options
|
||||
Flag options---set a variable to true or false when a particular option is seen
|
||||
---are quite common. :mod:`optparse` supports them with two separate actions,
|
||||
``store_true`` and ``store_false``. For example, you might have a ``verbose``
|
||||
flag that is turned on with ``"-v"`` and off with ``"-q"``::
|
||||
flag that is turned on with ``-v`` and off with ``-q``::
|
||||
|
||||
parser.add_option("-v", action="store_true", dest="verbose")
|
||||
parser.add_option("-q", action="store_false", dest="verbose")
|
||||
@ -381,8 +381,8 @@ Here we have two different options with the same destination, which is perfectly
|
||||
OK. (It just means you have to be a bit careful when setting default values---
|
||||
see below.)
|
||||
|
||||
When :mod:`optparse` encounters ``"-v"`` on the command line, it sets
|
||||
``options.verbose`` to ``True``; when it encounters ``"-q"``,
|
||||
When :mod:`optparse` encounters ``-v`` on the command line, it sets
|
||||
``options.verbose`` to ``True``; when it encounters ``-q``,
|
||||
``options.verbose`` is set to ``False``.
|
||||
|
||||
|
||||
@ -422,7 +422,7 @@ supply a default value for each destination, which is assigned before the
|
||||
command line is parsed.
|
||||
|
||||
First, consider the verbose/quiet example. If we want :mod:`optparse` to set
|
||||
``verbose`` to ``True`` unless ``"-q"`` is seen, then we can do this::
|
||||
``verbose`` to ``True`` unless ``-q`` is seen, then we can do this::
|
||||
|
||||
parser.add_option("-v", action="store_true", dest="verbose", default=True)
|
||||
parser.add_option("-q", action="store_false", dest="verbose")
|
||||
@ -480,7 +480,7 @@ user-friendly (documented) options::
|
||||
help="interaction mode: novice, intermediate, "
|
||||
"or expert [default: %default]")
|
||||
|
||||
If :mod:`optparse` encounters either ``"-h"`` or ``"--help"`` on the
|
||||
If :mod:`optparse` encounters either ``-h`` or ``--help`` on the
|
||||
command-line, or if you just call :meth:`parser.print_help`, it prints the
|
||||
following to standard output:
|
||||
|
||||
@ -507,7 +507,7 @@ help message:
|
||||
|
||||
usage = "usage: %prog [options] arg1 arg2"
|
||||
|
||||
:mod:`optparse` expands ``"%prog"`` in the usage string to the name of the
|
||||
:mod:`optparse` expands ``%prog`` in the usage string to the name of the
|
||||
current program, i.e. ``os.path.basename(sys.argv[0])``. The expanded string
|
||||
is then printed before the detailed option help.
|
||||
|
||||
@ -525,17 +525,17 @@ help message:
|
||||
-m MODE, --mode=MODE
|
||||
|
||||
Here, "MODE" is called the meta-variable: it stands for the argument that the
|
||||
user is expected to supply to :option:`-m`/:option:`--mode`. By default,
|
||||
user is expected to supply to ``-m``/``--mode``. By default,
|
||||
:mod:`optparse` converts the destination variable name to uppercase and uses
|
||||
that for the meta-variable. Sometimes, that's not what you want---for
|
||||
example, the :option:`--filename` option explicitly sets ``metavar="FILE"``,
|
||||
example, the ``--filename`` option explicitly sets ``metavar="FILE"``,
|
||||
resulting in this automatically-generated option description::
|
||||
|
||||
-f FILE, --filename=FILE
|
||||
|
||||
This is important for more than just saving space, though: the manually
|
||||
written help text uses the meta-variable "FILE" to clue the user in that
|
||||
there's a connection between the semi-formal syntax "-f FILE" and the informal
|
||||
written help text uses the meta-variable ``FILE`` to clue the user in that
|
||||
there's a connection between the semi-formal syntax ``-f FILE`` and the informal
|
||||
semantic description "write output to FILE". This is a simple but effective
|
||||
way to make your help text a lot clearer and more useful for end users.
|
||||
|
||||
@ -587,11 +587,11 @@ argument to OptionParser::
|
||||
|
||||
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
|
||||
|
||||
``"%prog"`` is expanded just like it is in ``usage``. Apart from that,
|
||||
``%prog`` is expanded just like it is in ``usage``. Apart from that,
|
||||
``version`` can contain anything you like. When you supply it, :mod:`optparse`
|
||||
automatically adds a ``"--version"`` option to your parser. If it encounters
|
||||
automatically adds a ``--version`` option to your parser. If it encounters
|
||||
this option on the command line, it expands your ``version`` string (by
|
||||
replacing ``"%prog"``), prints it to stdout, and exits.
|
||||
replacing ``%prog``), prints it to stdout, and exits.
|
||||
|
||||
For example, if your script is called ``/usr/bin/foo``::
|
||||
|
||||
@ -604,7 +604,7 @@ The following two methods can be used to print and get the ``version`` string:
|
||||
|
||||
Print the version message for the current program (``self.version``) to
|
||||
*file* (default stdout). As with :meth:`print_usage`, any occurrence
|
||||
of ``"%prog"`` in ``self.version`` is replaced with the name of the current
|
||||
of ``%prog`` in ``self.version`` is replaced with the name of the current
|
||||
program. Does nothing if ``self.version`` is empty or undefined.
|
||||
|
||||
.. method:: OptionParser.get_version()
|
||||
@ -627,9 +627,9 @@ usual way: raise an exception (either :exc:`optparse.OptionError` or
|
||||
|
||||
Handling user errors is much more important, since they are guaranteed to happen
|
||||
no matter how stable your code is. :mod:`optparse` can automatically detect
|
||||
some user errors, such as bad option arguments (passing ``"-n 4x"`` where
|
||||
:option:`-n` takes an integer argument), missing arguments (``"-n"`` at the end
|
||||
of the command line, where :option:`-n` takes an argument of any type). Also,
|
||||
some user errors, such as bad option arguments (passing ``-n 4x`` where
|
||||
``-n`` takes an integer argument), missing arguments (``-n`` at the end
|
||||
of the command line, where ``-n`` takes an argument of any type). Also,
|
||||
you can call :func:`OptionParser.error` to signal an application-defined error
|
||||
condition::
|
||||
|
||||
@ -642,7 +642,7 @@ In either case, :mod:`optparse` handles the error the same way: it prints the
|
||||
program's usage message and an error message to standard error and exits with
|
||||
error status 2.
|
||||
|
||||
Consider the first example above, where the user passes ``"4x"`` to an option
|
||||
Consider the first example above, where the user passes ``4x`` to an option
|
||||
that takes an integer::
|
||||
|
||||
$ /usr/bin/foo -n 4x
|
||||
@ -735,8 +735,8 @@ The first step in using :mod:`optparse` is to create an OptionParser instance.
|
||||
``version`` (default: ``None``)
|
||||
A version string to print when the user supplies a version option. If you
|
||||
supply a true value for ``version``, :mod:`optparse` automatically adds a
|
||||
version option with the single option string ``"--version"``. The
|
||||
substring ``"%prog"`` is expanded the same as for ``usage``.
|
||||
version option with the single option string ``--version``. The
|
||||
substring ``%prog`` is expanded the same as for ``usage``.
|
||||
|
||||
``conflict_handler`` (default: ``"error"``)
|
||||
Specifies what to do when options with conflicting option strings are
|
||||
@ -755,11 +755,11 @@ The first step in using :mod:`optparse` is to create an OptionParser instance.
|
||||
IndentedHelpFormatter and TitledHelpFormatter.
|
||||
|
||||
``add_help_option`` (default: ``True``)
|
||||
If true, :mod:`optparse` will add a help option (with option strings ``"-h"``
|
||||
and ``"--help"``) to the parser.
|
||||
If true, :mod:`optparse` will add a help option (with option strings ``-h``
|
||||
and ``--help``) to the parser.
|
||||
|
||||
``prog``
|
||||
The string to use when expanding ``"%prog"`` in ``usage`` and ``version``
|
||||
The string to use when expanding ``%prog`` in ``usage`` and ``version``
|
||||
instead of ``os.path.basename(sys.argv[0])``.
|
||||
|
||||
``epilog`` (default: ``None``)
|
||||
@ -803,7 +803,7 @@ Defining options
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Each Option instance represents a set of synonymous command-line option strings,
|
||||
e.g. :option:`-f` and :option:`--file`. You can specify any number of short or
|
||||
e.g. ``-f`` and ``--file``. You can specify any number of short or
|
||||
long option strings, but you must specify at least one overall option string.
|
||||
|
||||
The canonical way to create an :class:`Option` instance is with the
|
||||
@ -966,7 +966,7 @@ relevant to a particular option, or fail to pass a required option attribute,
|
||||
.. attribute:: Option.help
|
||||
|
||||
Help text to print for this option when listing all available options after
|
||||
the user supplies a :attr:`~Option.help` option (such as ``"--help"``). If
|
||||
the user supplies a :attr:`~Option.help` option (such as ``--help``). If
|
||||
no help text is supplied, the option will be listed without help text. To
|
||||
hide this option, use the special value :data:`optparse.SUPPRESS_HELP`.
|
||||
|
||||
@ -1004,9 +1004,9 @@ must specify for any option using that action.
|
||||
If :attr:`~Option.type` is not supplied, it defaults to ``"string"``.
|
||||
|
||||
If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a destination
|
||||
from the first long option string (e.g., ``"--foo-bar"`` implies
|
||||
from the first long option string (e.g., ``--foo-bar`` implies
|
||||
``foo_bar``). If there are no long option strings, :mod:`optparse` derives a
|
||||
destination from the first short option string (e.g., ``"-f"`` implies ``f``).
|
||||
destination from the first short option string (e.g., ``-f`` implies ``f``).
|
||||
|
||||
Example::
|
||||
|
||||
@ -1037,7 +1037,7 @@ must specify for any option using that action.
|
||||
parser.add_option("--noisy",
|
||||
action="store_const", const=2, dest="verbose")
|
||||
|
||||
If ``"--noisy"`` is seen, :mod:`optparse` will set ::
|
||||
If ``--noisy`` is seen, :mod:`optparse` will set ::
|
||||
|
||||
options.verbose = 2
|
||||
|
||||
@ -1072,13 +1072,13 @@ must specify for any option using that action.
|
||||
|
||||
parser.add_option("-t", "--tracks", action="append", type="int")
|
||||
|
||||
If ``"-t3"`` is seen on the command-line, :mod:`optparse` does the equivalent
|
||||
If ``-t3`` is seen on the command-line, :mod:`optparse` does the equivalent
|
||||
of::
|
||||
|
||||
options.tracks = []
|
||||
options.tracks.append(int("3"))
|
||||
|
||||
If, a little later on, ``"--tracks=4"`` is seen, it does::
|
||||
If, a little later on, ``--tracks=4`` is seen, it does::
|
||||
|
||||
options.tracks.append(int("4"))
|
||||
|
||||
@ -1100,13 +1100,13 @@ must specify for any option using that action.
|
||||
|
||||
parser.add_option("-v", action="count", dest="verbosity")
|
||||
|
||||
The first time ``"-v"`` is seen on the command line, :mod:`optparse` does the
|
||||
The first time ``-v`` is seen on the command line, :mod:`optparse` does the
|
||||
equivalent of::
|
||||
|
||||
options.verbosity = 0
|
||||
options.verbosity += 1
|
||||
|
||||
Every subsequent occurrence of ``"-v"`` results in ::
|
||||
Every subsequent occurrence of ``-v`` results in ::
|
||||
|
||||
options.verbosity += 1
|
||||
|
||||
@ -1149,7 +1149,7 @@ must specify for any option using that action.
|
||||
help="Input file to read data from")
|
||||
parser.add_option("--secret", help=SUPPRESS_HELP)
|
||||
|
||||
If :mod:`optparse` sees either ``"-h"`` or ``"--help"`` on the command line,
|
||||
If :mod:`optparse` sees either ``-h`` or ``--help`` on the command line,
|
||||
it will print something like the following help message to stdout (assuming
|
||||
``sys.argv[0]`` is ``"foo.py"``):
|
||||
|
||||
@ -1263,8 +1263,8 @@ provides several methods to help you out:
|
||||
|
||||
.. method:: OptionParser.disable_interspersed_args()
|
||||
|
||||
Set parsing to stop on the first non-option. For example, if ``"-a"`` and
|
||||
``"-b"`` are both simple options that take no arguments, :mod:`optparse`
|
||||
Set parsing to stop on the first non-option. For example, if ``-a`` and
|
||||
``-b`` are both simple options that take no arguments, :mod:`optparse`
|
||||
normally accepts this syntax::
|
||||
|
||||
prog -a arg1 -b arg2
|
||||
@ -1294,7 +1294,7 @@ provides several methods to help you out:
|
||||
.. method:: OptionParser.has_option(opt_str)
|
||||
|
||||
Return true if the OptionParser has an option with option string *opt_str*
|
||||
(e.g., ``"-q"`` or ``"--verbose"``).
|
||||
(e.g., ``-q`` or ``--verbose``).
|
||||
|
||||
.. method:: OptionParser.remove_option(opt_str)
|
||||
|
||||
@ -1347,9 +1347,9 @@ intelligently and add conflicting options to it::
|
||||
parser.add_option("-n", "--noisy", ..., help="be noisy")
|
||||
|
||||
At this point, :mod:`optparse` detects that a previously-added option is already
|
||||
using the ``"-n"`` option string. Since ``conflict_handler`` is ``"resolve"``,
|
||||
it resolves the situation by removing ``"-n"`` from the earlier option's list of
|
||||
option strings. Now ``"--dry-run"`` is the only way for the user to activate
|
||||
using the ``-n`` option string. Since ``conflict_handler`` is ``"resolve"``,
|
||||
it resolves the situation by removing ``-n`` from the earlier option's list of
|
||||
option strings. Now ``--dry-run`` is the only way for the user to activate
|
||||
that option. If the user asks for help, the help message will reflect that::
|
||||
|
||||
options:
|
||||
@ -1365,7 +1365,7 @@ existing OptionParser::
|
||||
|
||||
parser.add_option("--dry-run", ..., help="new dry-run option")
|
||||
|
||||
At this point, the original :option:`-n/--dry-run` option is no longer
|
||||
At this point, the original ``-n``/``--dry-run`` option is no longer
|
||||
accessible, so :mod:`optparse` removes it, leaving this help text::
|
||||
|
||||
options:
|
||||
@ -1403,7 +1403,7 @@ OptionParser supports several other public methods:
|
||||
.. method:: OptionParser.print_usage(file=None)
|
||||
|
||||
Print the usage message for the current program (``self.usage``) to *file*
|
||||
(default stdout). Any occurrence of the string ``"%prog"`` in ``self.usage``
|
||||
(default stdout). Any occurrence of the string ``%prog`` in ``self.usage``
|
||||
is replaced with the name of the current program. Does nothing if
|
||||
``self.usage`` is empty or not defined.
|
||||
|
||||
@ -1467,9 +1467,9 @@ only option attribute you must specify is ``callback``, the function to call::
|
||||
|
||||
``callback`` is a function (or other callable object), so you must have already
|
||||
defined ``my_callback()`` when you create this callback option. In this simple
|
||||
case, :mod:`optparse` doesn't even know if :option:`-c` takes any arguments,
|
||||
case, :mod:`optparse` doesn't even know if ``-c`` takes any arguments,
|
||||
which usually means that the option takes no arguments---the mere presence of
|
||||
:option:`-c` on the command-line is all it needs to know. In some
|
||||
``-c`` on the command-line is all it needs to know. In some
|
||||
circumstances, though, you might want your callback to consume an arbitrary
|
||||
number of command-line arguments. This is where writing callbacks gets tricky;
|
||||
it's covered later in this section.
|
||||
@ -1522,8 +1522,8 @@ where
|
||||
``opt_str``
|
||||
is the option string seen on the command-line that's triggering the callback.
|
||||
(If an abbreviated long option was used, ``opt_str`` will be the full,
|
||||
canonical option string---e.g. if the user puts ``"--foo"`` on the
|
||||
command-line as an abbreviation for ``"--foobar"``, then ``opt_str`` will be
|
||||
canonical option string---e.g. if the user puts ``--foo`` on the
|
||||
command-line as an abbreviation for ``--foobar``, then ``opt_str`` will be
|
||||
``"--foobar"``.)
|
||||
|
||||
``value``
|
||||
@ -1598,8 +1598,8 @@ Of course, you could do that with the ``"store_true"`` action.
|
||||
Callback example 2: check option order
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Here's a slightly more interesting example: record the fact that ``"-a"`` is
|
||||
seen, but blow up if it comes after ``"-b"`` in the command-line. ::
|
||||
Here's a slightly more interesting example: record the fact that ``-a`` is
|
||||
seen, but blow up if it comes after ``-b`` in the command-line. ::
|
||||
|
||||
def check_order(option, opt_str, value, parser):
|
||||
if parser.values.b:
|
||||
@ -1616,7 +1616,7 @@ Callback example 3: check option order (generalized)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you want to re-use this callback for several similar options (set a flag, but
|
||||
blow up if ``"-b"`` has already been seen), it needs a bit of work: the error
|
||||
blow up if ``-b`` has already been seen), it needs a bit of work: the error
|
||||
message and the flag that it sets must be generalized. ::
|
||||
|
||||
def check_order(option, opt_str, value, parser):
|
||||
@ -1686,15 +1686,15 @@ For this case, you must write a callback, as :mod:`optparse` doesn't provide any
|
||||
built-in capabilities for it. And you have to deal with certain intricacies of
|
||||
conventional Unix command-line parsing that :mod:`optparse` normally handles for
|
||||
you. In particular, callbacks should implement the conventional rules for bare
|
||||
``"--"`` and ``"-"`` arguments:
|
||||
``--`` and ``-`` arguments:
|
||||
|
||||
* either ``"--"`` or ``"-"`` can be option arguments
|
||||
* either ``--`` or ``-`` can be option arguments
|
||||
|
||||
* bare ``"--"`` (if not the argument to some option): halt command-line
|
||||
processing and discard the ``"--"``
|
||||
* bare ``--`` (if not the argument to some option): halt command-line
|
||||
processing and discard the ``--``
|
||||
|
||||
* bare ``"-"`` (if not the argument to some option): halt command-line
|
||||
processing but keep the ``"-"`` (append it to ``parser.largs``)
|
||||
* bare ``-`` (if not the argument to some option): halt command-line
|
||||
processing but keep the ``-`` (append it to ``parser.largs``)
|
||||
|
||||
If you want an option that takes a variable number of arguments, there are
|
||||
several subtle, tricky issues to worry about. The exact implementation you
|
||||
@ -1765,7 +1765,7 @@ To add new types, you need to define your own subclass of :mod:`optparse`'s
|
||||
def check_mytype(option, opt, value)
|
||||
|
||||
where ``option`` is an :class:`Option` instance, ``opt`` is an option string
|
||||
(e.g., ``"-f"``), and ``value`` is the string from the command line that must
|
||||
(e.g., ``-f``), and ``value`` is the string from the command line that must
|
||||
be checked and converted to your desired type. ``check_mytype()`` should
|
||||
return an object of the hypothetical type ``mytype``. The value returned by
|
||||
a type-checking function will wind up in the OptionValues instance returned
|
||||
@ -1877,7 +1877,7 @@ For example, let's add an ``"extend"`` action. This is similar to the standard
|
||||
``"append"`` action, but instead of taking a single value from the command-line
|
||||
and appending it to an existing list, ``"extend"`` will take multiple values in
|
||||
a single comma-delimited string, and extend an existing list with them. That
|
||||
is, if ``"--names"`` is an ``"extend"`` option of type ``"string"``, the command
|
||||
is, if ``--names`` is an ``"extend"`` option of type ``"string"``, the command
|
||||
line ::
|
||||
|
||||
--names=foo,bar --names blah --names ding,dong
|
||||
|
||||
@ -41,25 +41,25 @@ produced for that file.
|
||||
executed on that occasion. Use an ``if __name__ == '__main__':`` guard to
|
||||
only execute code when a file is invoked as a script and not just imported.
|
||||
|
||||
Specifying a :option:`-w` flag before the argument will cause HTML documentation
|
||||
Specifying a ``-w`` flag before the argument will cause HTML documentation
|
||||
to be written out to a file in the current directory, instead of displaying text
|
||||
on the console.
|
||||
|
||||
Specifying a :option:`-k` flag before the argument will search the synopsis
|
||||
Specifying a ``-k`` flag before the argument will search the synopsis
|
||||
lines of all available modules for the keyword given as the argument, again in a
|
||||
manner similar to the Unix :program:`man` command. The synopsis line of a
|
||||
module is the first line of its documentation string.
|
||||
|
||||
You can also use :program:`pydoc` to start an HTTP server on the local machine
|
||||
that will serve documentation to visiting Web browsers. :program:`pydoc`
|
||||
:option:`-p 1234` will start a HTTP server on port 1234, allowing you to browse
|
||||
that will serve documentation to visiting Web browsers. :program:`pydoc -p 1234`
|
||||
will start a HTTP server on port 1234, allowing you to browse
|
||||
the documentation at ``http://localhost:1234/`` in your preferred Web browser.
|
||||
:program:`pydoc` :option:`-g` will start the server and additionally bring up a
|
||||
:program:`pydoc -g` will start the server and additionally bring up a
|
||||
small :mod:`tkinter`\ -based graphical interface to help you search for
|
||||
documentation pages.
|
||||
|
||||
When :program:`pydoc` generates documentation, it uses the current environment
|
||||
and path to locate modules. Thus, invoking :program:`pydoc` :option:`spam`
|
||||
and path to locate modules. Thus, invoking :program:`pydoc spam`
|
||||
documents precisely the version of the module you would get if you started the
|
||||
Python interpreter and typed ``import spam``.
|
||||
|
||||
|
||||
@ -162,7 +162,7 @@ always available.
|
||||
|
||||
A string giving the site-specific directory prefix where the platform-dependent
|
||||
Python files are installed; by default, this is also ``'/usr/local'``. This can
|
||||
be set at build time with the :option:`--exec-prefix` argument to the
|
||||
be set at build time with the ``--exec-prefix`` argument to the
|
||||
:program:`configure` script. Specifically, all configuration files (e.g. the
|
||||
:file:`pyconfig.h` header file) are installed in the directory ``exec_prefix +
|
||||
'/lib/pythonversion/config'``, and shared library modules are installed in
|
||||
@ -617,7 +617,7 @@ always available.
|
||||
|
||||
A string giving the site-specific directory prefix where the platform
|
||||
independent Python files are installed; by default, this is the string
|
||||
``'/usr/local'``. This can be set at build time with the :option:`--prefix`
|
||||
``'/usr/local'``. This can be set at build time with the ``--prefix``
|
||||
argument to the :program:`configure` script. The main collection of Python
|
||||
library modules is installed in the directory ``prefix + '/lib/pythonversion'``
|
||||
while the platform independent header files (all except :file:`pyconfig.h`) are
|
||||
@ -795,7 +795,7 @@ always available.
|
||||
|
||||
Activate dumping of VM measurements using the Pentium timestamp counter, if
|
||||
*on_flag* is true. Deactivate these dumps if *on_flag* is off. The function is
|
||||
available only if Python was compiled with :option:`--with-tsc`. To understand
|
||||
available only if Python was compiled with ``--with-tsc``. To understand
|
||||
the output of this dump, read :file:`Python/ceval.c` in the Python sources.
|
||||
|
||||
|
||||
|
||||
@ -154,33 +154,33 @@ guidelines to be followed:
|
||||
|
||||
.. _regrtest:
|
||||
|
||||
Running tests using :mod:`test.regrtest`
|
||||
----------------------------------------
|
||||
Running tests using the command-line interface
|
||||
----------------------------------------------
|
||||
|
||||
:mod:`test.regrtest` can be used as a script to drive Python's regression test
|
||||
suite. Running the script by itself automatically starts running all regression
|
||||
The :mod:`test.regrtest` module can be run as a script to drive Python's regression
|
||||
test suite, thanks to the :option:`-m` option: :program:`python -m test.regrtest`.
|
||||
Running the script by itself automatically starts running all regression
|
||||
tests in the :mod:`test` package. It does this by finding all modules in the
|
||||
package whose name starts with ``test_``, importing them, and executing the
|
||||
function :func:`test_main` if present. The names of tests to execute may also be
|
||||
passed to the script. Specifying a single regression test (:program:`python
|
||||
regrtest.py` :option:`test_spam.py`) will minimize output and only print whether
|
||||
-m test.regrtest test_spam`) will minimize output and only print whether
|
||||
the test passed or failed and thus minimize output.
|
||||
|
||||
Running :mod:`test.regrtest` directly allows what resources are available for
|
||||
tests to use to be set. You do this by using the :option:`-u` command-line
|
||||
option. Run :program:`python regrtest.py` :option:`-uall` to turn on all
|
||||
resources; specifying :option:`all` as an option for :option:`-u` enables all
|
||||
option. Run :program:`python -m test.regrtest -uall` to turn on all
|
||||
resources; specifying ``all`` as an option for ``-u`` enables all
|
||||
possible resources. If all but one resource is desired (a more common case), a
|
||||
comma-separated list of resources that are not desired may be listed after
|
||||
:option:`all`. The command :program:`python regrtest.py`
|
||||
:option:`-uall,-audio,-largefile` will run :mod:`test.regrtest` with all
|
||||
resources except the :option:`audio` and :option:`largefile` resources. For a
|
||||
list of all resources and more command-line options, run :program:`python
|
||||
regrtest.py` :option:`-h`.
|
||||
``all``. The command :program:`python -m test.regrtest -uall,-audio,-largefile`
|
||||
will run :mod:`test.regrtest` with all resources except the ``audio`` and
|
||||
``largefile`` resources. For a list of all resources and more command-line
|
||||
options, run :program:`python -m test.regrtest -h`.
|
||||
|
||||
Some other ways to execute the regression tests depend on what platform the
|
||||
tests are being executed on. On Unix, you can run :program:`make` :option:`test`
|
||||
at the top-level directory where Python was built. On Windows, executing
|
||||
tests are being executed on. On Unix, you can run :program:`make test` at the
|
||||
top-level directory where Python was built. On Windows, executing
|
||||
:program:`rt.bat` from your :file:`PCBuild` directory will run all regression
|
||||
tests.
|
||||
|
||||
|
||||
@ -117,27 +117,36 @@ When called as a program from the command line, the following form is used::
|
||||
|
||||
python -m timeit [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]
|
||||
|
||||
where the following options are understood:
|
||||
Where the following options are understood:
|
||||
|
||||
.. program:: timeit
|
||||
|
||||
.. cmdoption:: -n N, --number=N
|
||||
|
||||
-n N/:option:`--number=N`
|
||||
how many times to execute 'statement'
|
||||
|
||||
-r N/:option:`--repeat=N`
|
||||
.. cmdoption:: -r N, --repeat=N
|
||||
|
||||
how many times to repeat the timer (default 3)
|
||||
|
||||
-s S/:option:`--setup=S`
|
||||
statement to be executed once initially (default ``'pass'``)
|
||||
.. cmdoption:: -s S, --setup=S
|
||||
|
||||
statement to be executed once initially (default ``pass``)
|
||||
|
||||
.. cmdoption:: -t, --time
|
||||
|
||||
-t/:option:`--time`
|
||||
use :func:`time.time` (default on all platforms but Windows)
|
||||
|
||||
-c/:option:`--clock`
|
||||
.. cmdoption:: -c, --clock
|
||||
|
||||
use :func:`time.clock` (default on Windows)
|
||||
|
||||
-v/:option:`--verbose`
|
||||
.. cmdoption:: -v, --verbose
|
||||
|
||||
print raw timing results; repeat for more digits precision
|
||||
|
||||
-h/:option:`--help`
|
||||
.. cmdoption:: -h, --help
|
||||
|
||||
print a short usage message and exit
|
||||
|
||||
A multi-line statement may be given by specifying each line as a separate
|
||||
|
||||
@ -143,7 +143,7 @@ example, :meth:`~TestCase.setUp` was used to create a fresh sequence for each
|
||||
test.
|
||||
|
||||
The final block shows a simple way to run the tests. :func:`unittest.main`
|
||||
provides a command line interface to the test script. When run from the command
|
||||
provides a command-line interface to the test script. When run from the command
|
||||
line, the above script produces an output that looks like this::
|
||||
|
||||
...
|
||||
@ -176,6 +176,30 @@ are sufficient to meet many everyday testing needs. The remainder of the
|
||||
documentation explores the full feature set from first principles.
|
||||
|
||||
|
||||
.. _unittest-command-line-interface:
|
||||
|
||||
Command-Line Interface
|
||||
----------------------
|
||||
|
||||
The unittest module can be used from the command line to run tests from
|
||||
modules, classes or even individual test methods::
|
||||
|
||||
python -m unittest test_module1 test_module2
|
||||
python -m unittest test_module.TestClass
|
||||
python -m unittest test_module.TestClass.test_method
|
||||
|
||||
You can pass in a list with any combination of module names, and fully
|
||||
qualified class or method names.
|
||||
|
||||
You can run tests with more detail (higher verbosity) by passing in the -v flag::
|
||||
|
||||
python -m unittest -v test_module
|
||||
|
||||
For a list of all the command-line options::
|
||||
|
||||
python -m unittest -h
|
||||
|
||||
|
||||
.. _organizing-tests:
|
||||
|
||||
Organizing test code
|
||||
|
||||
@ -31,8 +31,8 @@ browser and wait.
|
||||
|
||||
The script :program:`webbrowser` can be used as a command-line interface for the
|
||||
module. It accepts an URL as the argument. It accepts the following optional
|
||||
parameters: :option:`-n` opens the URL in a new browser window, if possible;
|
||||
:option:`-t` opens the URL in a new browser page ("tab"). The options are,
|
||||
parameters: ``-n`` opens the URL in a new browser window, if possible;
|
||||
``-t`` opens the URL in a new browser page ("tab"). The options are,
|
||||
naturally, mutually exclusive.
|
||||
|
||||
The following exception is defined:
|
||||
@ -64,7 +64,6 @@ The following functions are defined:
|
||||
Open *url* in a new window of the default browser, if possible, otherwise, open
|
||||
*url* in the only browser window.
|
||||
|
||||
|
||||
.. function:: open_new_tab(url)
|
||||
|
||||
Open *url* in a new page ("tab") of the default browser, if possible, otherwise
|
||||
|
||||
Loading…
Reference in New Issue
Block a user