* Ross Moore
* Sjoerd Mullender
* Dale Nagata
+ * Michal Nowikowski
* Ng Pheng Siong
* Koray Oner
* Tomas Oppelstrup
.. method:: ArgumentParser.print_usage(file=None)
Print a brief description of how the :class:`ArgumentParser` should be
- invoked on the command line. If *file* is ``None``, :data:`sys.stderr` is
+ invoked on the command line. If *file* is ``None``, :data:`sys.stdout` is
assumed.
.. method:: ArgumentParser.print_help(file=None)
Print a help message, including the program usage and information about the
arguments registered with the :class:`ArgumentParser`. If *file* is
- ``None``, :data:`sys.stderr` is assumed.
+ ``None``, :data:`sys.stdout` is assumed.
There are also variants of these methods that simply return a string instead of
printing it:
This module provides some utility functions to support installing Python
-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.
+libraries. These functions compile Python source files in a directory tree.
+This module can be used to create the cached byte-code files at library
+installation time, which makes them available for use even by users who don't
+have write permission to the library directories.
Command-line use
.. cmdoption:: -l
- Do not recurse.
+ Do not recurse into subdirectories, only compile source code files directly
+ contained in the named or implied directories.
.. cmdoption:: -f
.. cmdoption:: -q
- Do not print the list of files compiled.
+ Do not print the list of files compiled, print only error messages.
.. cmdoption:: -d destdir
- Purported directory name for error messages.
+ Directory prepended to the path to each file being compiled. This will
+ appear in compilation time tracebacks, and is also compiled in to the
+ byte-code file, where it will be used in tracebacks and other messages in
+ cases where the source file does not exist at the time the byte-code file is
+ executed.
.. cmdoption:: -x regex
- Skip files with a full path that matches given regular expression.
+ regex is used to search the full path to each file considered for
+ compilation, and if the regex produces a match, the file is skipped.
.. cmdoption:: -i list
- Expand list with its content (file and directory names).
+ Read the file ``list`` and add each line that it contains to the list of
+ files and directories to compile. If ``list`` is ``-``, read lines from
+ ``stdin``.
.. versionchanged:: 2.7
Added the ``-i`` option.
.. function:: compile_dir(dir[, maxlevels[, ddir[, force[, rx[, quiet]]]]])
Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
- files along the way. The *maxlevels* parameter is used to limit the depth of
- the recursion; it defaults to ``10``. If *ddir* is given, it is used as the
- base path from which the filenames used in error messages will be generated.
+ files along the way.
+
+ The *maxlevels* parameter is used to limit the depth of the recursion; it
+ defaults to ``10``.
+
+ If *ddir* is given, it is prepended to the path to each file being compiled
+ for use in compilation time tracebacks, and is also compiled in to the
+ byte-code file, where it will be used in tracebacks and other messages in
+ cases where the source file does not exist at the time the byte-code file is
+ executed.
+
If *force* is true, modules are re-compiled even if the timestamps are up to
date.
- If *rx* is given, it specifies a regular expression of file names to exclude
- from the search; that expression is searched for in the full path.
+ If *rx* is given, its search method is called on the complete path to each
+ file considered for compilation, and if it returns a true value, the file
+ is skipped.
- If *quiet* is true, nothing is printed to the standard output in normal
- operation.
+ If *quiet* is true, nothing is printed to the standard output unless errors
+ occur.
.. function:: compile_file(fullname[, ddir[, force[, rx[, quiet]]]])
- Compile the file with path *fullname*. If *ddir* is given, it is used as the
- base path from which the filename used in error messages will be generated.
- If *force* is true, modules are re-compiled even if the timestamp is up to
- date.
+ Compile the file with path *fullname*.
+
+ If *ddir* is given, it is prepended to the path to the file being compiled
+ for use in compilation time tracebacks, and is also compiled in to the
+ byte-code file, where it will be used in tracebacks and other messages in
+ cases where the source file does not exist at the time the byte-code file is
+ executed.
- If *rx* is given, it specifies a regular expression which, if matched, will
- prevent compilation; that expression is searched for in the full path.
+ If *ra* is given, its search method is passed the full path name to the
+ file being compiled, and if it returns a true value, the file is not
+ compiled and ``True`` is returned.
- If *quiet* is true, nothing is printed to the standard output in normal
- operation.
+ If *quiet* is true, nothing is printed to the standard output unless errors
+ occur.
.. versionadded:: 2.7
.. function:: compile_path([skip_curdir[, maxlevels[, force]]])
Byte-compile all the :file:`.py` files found along ``sys.path``. If
- *skip_curdir* is true (the default), the current directory is not included in
- the search. The *maxlevels* and *force* parameters default to ``0`` and are
- passed to the :func:`compile_dir` function.
+ *skip_curdir* is true (the default), the current directory is not included
+ in the search. All other parameters are passed to the :func:`compile_dir`
+ function. Note that unlike the other compile functions, ``maxlevels``
+ defaults to ``0``.
To force a recompile of all the :file:`.py` files in the :file:`Lib/`
subdirectory and all its subdirectories::
def load_tests(loader, tests, ignore):
tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
- return test
+ return tests
There are two main functions for creating :class:`unittest.TestSuite` instances
from text files and modules with doctests:
character set is used both as *s*'s initial charset and as the default for
subsequent :meth:`append` calls.
- The maximum line length can be specified explicit via *maxlinelen*. For
+ The maximum line length can be specified explicitly via *maxlinelen*. For
splitting the first line to a shorter value (to account for the field header
which isn't included in *s*, e.g. :mailheader:`Subject`) pass in the name of the
field in *header_name*. The default *maxlinelen* is 76, and the default value
.. function:: fstat(fd)
- Return status for file descriptor *fd*, like :func:`stat`.
+ Return status for file descriptor *fd*, like :func:`~os.stat`.
Availability: Unix, Windows.
.. function:: lstat(path)
- Like :func:`stat`, but do not follow symbolic links. This is an alias for
- :func:`stat` on platforms that do not support symbolic links, such as
- Windows.
+ Perform the equivalent of an :c:func:`lstat` system call on the given path.
+ Similar to :func:`~os.stat`, but does not follow symbolic links. On
+ platforms that do not support symbolic links, this is an alias for
+ :func:`~os.stat`.
.. function:: mkfifo(path[, mode])
.. function:: stat(path)
- Perform a :cfunc:`stat` system call on the given path. The return value is an
- object whose attributes correspond to the members of the :ctype:`stat`
- structure, namely: :attr:`st_mode` (protection bits), :attr:`st_ino` (inode
- number), :attr:`st_dev` (device), :attr:`st_nlink` (number of hard links),
- :attr:`st_uid` (user id of owner), :attr:`st_gid` (group id of owner),
- :attr:`st_size` (size of file, in bytes), :attr:`st_atime` (time of most recent
- access), :attr:`st_mtime` (time of most recent content modification),
- :attr:`st_ctime` (platform dependent; time of most recent metadata change on
- Unix, or the time of creation on Windows)::
+ Perform the equivalent of a :c:func:`stat` system call on the given path.
+ (This function follows symlinks; to stat a symlink use :func:`lstat`.)
- >>> import os
- >>> statinfo = os.stat('somefile.txt')
- >>> statinfo
- (33188, 422511L, 769L, 1, 1032, 100, 926L, 1105022698,1105022732, 1105022732)
- >>> statinfo.st_size
- 926L
- >>>
+ The return value is an object whose attributes correspond to the members
+ of the :c:type:`stat` structure, namely:
+
+ * :attr:`st_mode` - protection bits,
+ * :attr:`st_ino` - inode number,
+ * :attr:`st_dev` - device,
+ * :attr:`st_nlink` - number of hard links,
+ * :attr:`st_uid` - user id of owner,
+ * :attr:`st_gid` - group id of owner,
+ * :attr:`st_size` - size of file, in bytes,
+ * :attr:`st_atime` - time of most recent access,
+ * :attr:`st_mtime` - time of most recent content modification,
+ * :attr:`st_ctime` - platform dependent; time of most recent metadata change on
+ Unix, or the time of creation on Windows)
.. versionchanged:: 2.3
If :func:`stat_float_times` returns ``True``, the time values are floats, measuring
discussion.
On some Unix systems (such as Linux), the following attributes may also be
- available: :attr:`st_blocks` (number of blocks allocated for file),
- :attr:`st_blksize` (filesystem blocksize), :attr:`st_rdev` (type of device if an
- inode device). :attr:`st_flags` (user defined flags for file).
+ available:
+
+ * :attr:`st_blocks` - number of blocks allocated for file
+ * :attr:`st_blksize` - filesystem blocksize
+ * :attr:`st_rdev` - type of device if an inode device
+ * :attr:`st_flags` - user defined flags for file
On other Unix systems (such as FreeBSD), the following attributes may be
- available (but may be only filled out if root tries to use them): :attr:`st_gen`
- (file generation number), :attr:`st_birthtime` (time of file creation).
+ available (but may be only filled out if root tries to use them):
+
+ * :attr:`st_gen` - file generation number
+ * :attr:`st_birthtime` - time of file creation
On Mac OS systems, the following attributes may also be available:
- :attr:`st_rsize`, :attr:`st_creator`, :attr:`st_type`.
- On RISCOS systems, the following attributes are also available: :attr:`st_ftype`
- (file type), :attr:`st_attrs` (attributes), :attr:`st_obtype` (object type).
+ * :attr:`st_rsize`
+ * :attr:`st_creator`
+ * :attr:`st_type`
- .. index:: module: stat
+ On RISCOS systems, the following attributes are also available:
+
+ * :attr:`st_ftype` (file type)
+ * :attr:`st_attrs` (attributes)
+ * :attr:`st_obtype` (object type).
+
+ .. note::
+
+ The exact meaning and resolution of the :attr:`st_atime`, :attr:`st_mtime`, and
+ :attr:`st_ctime` members depends on the operating system and the file system.
+ For example, on Windows systems using the FAT or FAT32 file systems,
+ :attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day
+ resolution. See your operating system documentation for details.
- For backward compatibility, the return value of :func:`stat` is also accessible
+ For backward compatibility, the return value of :func:`~os.stat` is also accessible
as a tuple of at least 10 integers giving the most important (and portable)
members of the :ctype:`stat` structure, in the order :attr:`st_mode`,
:attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
:attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
:attr:`st_ctime`. More items may be added at the end by some implementations.
+
+ .. index:: module: stat
+
The standard module :mod:`stat` defines functions and constants that are useful
for extracting information from a :ctype:`stat` structure. (On Windows, some
items are filled with dummy values.)
- .. note::
+ Example::
- The exact meaning and resolution of the :attr:`st_atime`, :attr:`st_mtime`, and
- :attr:`st_ctime` members depends on the operating system and the file system.
- For example, on Windows systems using the FAT or FAT32 file systems,
- :attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day
- resolution. See your operating system documentation for details.
+ >>> import os
+ >>> statinfo = os.stat('somefile.txt')
+ >>> statinfo
+ (33188, 422511, 769, 1, 1032, 100, 926, 1105022698,1105022732, 1105022732)
+ >>> statinfo.st_size
+ 926
Availability: Unix, Windows.
.. function:: stat_float_times([newvalue])
Determine whether :class:`stat_result` represents time stamps as float objects.
- If *newvalue* is ``True``, future calls to :func:`stat` return floats, if it is
+ If *newvalue* is ``True``, future calls to :func:`~os.stat` return floats, if it is
``False``, future calls return ints. If *newvalue* is omitted, return the
current setting.
respectively. Whether a directory can be given for *path* depends on whether
the operating system implements directories as files (for example, Windows
does not). Note that the exact times you set here may not be returned by a
- subsequent :func:`stat` call, depending on the resolution with which your
- operating system records access and modification times; see :func:`stat`.
+ subsequent :func:`~os.stat` call, depending on the resolution with which your
+ operating system records access and modification times; see :func:`~os.stat`.
.. versionchanged:: 2.0
Added support for ``None`` for *times*.
----------------
When known to the interpreter, the script name and additional arguments
-thereafter are passed to the script in the variable ``sys.argv``, which is a
-list of strings. Its length is at least one; when no script and no arguments
+thereafter are turned into a list of strings and assigned to the ``argv``
+variable in the ``sys`` module. You can access this list by executing ``import
+sys``. The length of the list is at least one; when no script and no arguments
are given, ``sys.argv[0]`` is an empty string. When the script name is given as
``'-'`` (meaning standard input), ``sys.argv[0]`` is set to ``'-'``. When
:option:`-c` *command* is used, ``sys.argv[0]`` is set to ``'-c'``. When
def tests_and_args():
for test in tests:
args_tuple = (
- (test, verbose, quiet, testdir),
+ (test, verbose, quiet),
dict(huntrleaks=huntrleaks, use_resources=use_resources)
)
yield (test, args_tuple)
if trace:
# If we're tracing code coverage, then we don't exit with status
# if on a false return value from main.
- tracer.runctx('runtest(test, verbose, quiet, testdir)',
+ tracer.runctx('runtest(test, verbose, quiet)',
globals=globals(), locals=vars())
else:
try:
- result = runtest(test, verbose, quiet,
- testdir, huntrleaks)
+ result = runtest(test, verbose, quiet, huntrleaks)
accumulate_result(test, result)
if verbose3 and result[0] == FAILED:
print "Re-running test %r in verbose mode" % test
- runtest(test, True, quiet, testdir, huntrleaks)
+ runtest(test, True, quiet, huntrleaks)
except KeyboardInterrupt:
interrupted = True
break
sys.stdout.flush()
try:
test_support.verbose = True
- ok = runtest(test, True, quiet, testdir,
- huntrleaks)
+ ok = runtest(test, True, quiet, huntrleaks)
except KeyboardInterrupt:
# print a newline separate from the ^C
print
return stdtests + sorted(tests)
def runtest(test, verbose, quiet,
- testdir=None, huntrleaks=False, use_resources=None):
+ huntrleaks=False, use_resources=None):
"""Run a single test.
test -- the name of the test
verbose -- if true, print more messages
quiet -- if true, don't print 'skipped' messages (probably redundant)
test_times -- a list of (time, test_name) pairs
- testdir -- test directory
huntrleaks -- run multiple times to test for leaks; requires a debug
build; a triple corresponding to -R's three arguments
Returns one of the test result constants:
if use_resources is not None:
test_support.use_resources = use_resources
try:
- return runtest_inner(test, verbose, quiet,
- testdir, huntrleaks)
+ return runtest_inner(test, verbose, quiet, huntrleaks)
finally:
cleanup_test_droppings(test, verbose)
return False
-def runtest_inner(test, verbose, quiet,
- testdir=None, huntrleaks=False):
+def runtest_inner(test, verbose, quiet, huntrleaks=False):
test_support.unload(test)
- testdir = findtestdir(testdir)
if verbose:
capture_stdout = None
else:
import sys
import os
+import re
import os.path
import tempfile
import subprocess
import shutil
import zipfile
+from test.test_support import strip_python_stderr
+
# Executing the interpreter in a subprocess
def _assert_python(expected_success, *args, **env_vars):
cmd_line = [sys.executable]
p.stdout.close()
p.stderr.close()
rc = p.returncode
+ err = strip_python_stderr(err)
if (rc and expected_success) or (not rc and not expected_success):
raise AssertionError(
"Process return code is %d, "
# ArgumentTypeError tests
# =======================
-class TestArgumentError(TestCase):
+class TestArgumentTypeError(TestCase):
def test_argument_type_error(self):
}
PyDoc_STRVAR(tzset_doc,
-"tzset(zone)\n\
+"tzset()\n\
\n\
Initialize, or reinitialize, the local timezone to the value stored in\n\
os.environ['TZ']. The TZ environment variable should be specified in\n\
@rem Used by the buildbot "test" step.\r
cd PCbuild\r
-call rt.bat -d -q -uall -rw\r
+call rt.bat -d -q -uall -rwW\r
projects / python / commitdiff