diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/ACKS.txt | 1 | ||||
| -rw-r--r-- | Doc/library/compileall.rst | 51 | ||||
| -rw-r--r-- | Doc/library/email.header.rst | 2 | ||||
| -rw-r--r-- | Doc/library/http.client.rst | 6 | ||||
| -rw-r--r-- | Doc/library/os.rst | 92 | ||||
| -rw-r--r-- | Doc/tutorial/interpreter.rst | 5 |
6 files changed, 98 insertions, 59 deletions
diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt index eca54f6..6154fb9 100644 --- a/Doc/ACKS.txt +++ b/Doc/ACKS.txt @@ -139,6 +139,7 @@ docs@python.org), and we'll be glad to correct the problem. * Ross Moore * Sjoerd Mullender * Dale Nagata + * Michal Nowikowski * Ng Pheng Siong * Koray Oner * Tomas Oppelstrup diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst index c359676..8a93f9b 100644 --- a/Doc/library/compileall.rst +++ b/Doc/library/compileall.rst @@ -6,9 +6,10 @@ 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 @@ -27,7 +28,8 @@ compile Python sources. .. 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 @@ -35,15 +37,20 @@ compile Python sources. .. 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. Public functions @@ -52,24 +59,34 @@ Public functions .. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=False) 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_path(skip_curdir=True, maxlevels=0, force=False) 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:: diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst index 05acae7..2202637 100644 --- a/Doc/library/email.header.rst +++ b/Doc/library/email.header.rst @@ -63,7 +63,7 @@ Here is the :class:`Header` class description: 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 diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index f8aedcc..cbe4f05 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -381,8 +381,10 @@ HTTPConnection Objects .. method:: HTTPConnection.set_debuglevel(level) - Set the debugging level (the amount of debugging output printed). The default - debug level is ``0``, meaning no debugging output is printed. + Set the debugging level. The default debug level is ``0``, meaning no + debugging output is printed. Any value greater than ``0`` will cause all + currently defined debug output to be printed to stdout. The ``debuglevel`` + is passed to any new :class:`HTTPResponse` objects that are created. .. versionadded:: 3.1 diff --git a/Doc/library/os.rst b/Doc/library/os.rst index d5aa6fe..cf012ff 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -534,7 +534,7 @@ as internal buffering of data. .. 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. @@ -952,9 +952,10 @@ Files and Directories .. 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]) @@ -1138,56 +1139,73 @@ Files and Directories .. 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, 422511, 769, 1, 1032, 100, 926, 1105022698,1105022732, 1105022732) - >>> statinfo.st_size - 926 - >>> + 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) 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`. - .. index:: module: stat + * :attr:`st_rsize` + * :attr:`st_creator` + * :attr:`st_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. @@ -1195,7 +1213,7 @@ Files and Directories .. 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. @@ -1255,8 +1273,8 @@ Files and Directories 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`. Availability: Unix, Windows. diff --git a/Doc/tutorial/interpreter.rst b/Doc/tutorial/interpreter.rst index bca02ed..9d376e6 100644 --- a/Doc/tutorial/interpreter.rst +++ b/Doc/tutorial/interpreter.rst @@ -78,8 +78,9 @@ Argument Passing ---------------- 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 |