diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/collections.rst | 38 | ||||
| -rw-r--r-- | Doc/library/contextlib.rst | 2 | ||||
| -rw-r--r-- | Doc/library/decimal.rst | 1 | ||||
| -rw-r--r-- | Doc/library/fcntl.rst | 2 | ||||
| -rw-r--r-- | Doc/library/functions.rst | 7 | ||||
| -rw-r--r-- | Doc/library/msilib.rst | 2 | ||||
| -rw-r--r-- | Doc/library/msvcrt.rst | 2 | ||||
| -rw-r--r-- | Doc/library/numbers.rst | 2 | ||||
| -rw-r--r-- | Doc/library/os.rst | 145 | ||||
| -rw-r--r-- | Doc/library/socket.rst | 39 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 33 | ||||
| -rw-r--r-- | Doc/library/thread.rst | 1 | ||||
| -rw-r--r-- | Doc/library/threading.rst | 1 | ||||
| -rw-r--r-- | Doc/library/winsound.rst | 2 |
14 files changed, 169 insertions, 108 deletions
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index b650462..5b625ee 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -419,10 +419,18 @@ Example:: __slots__ = () + _fields = ('x', 'y') + def __new__(cls, x, y): return tuple.__new__(cls, (x, y)) - _cast = classmethod(tuple.__new__) + @classmethod + def _make(cls, iterable): + 'Make a new Point object from a sequence or iterable' + result = tuple.__new__(cls, iterable) + if len(result) != 2: + raise TypeError('Expected 2 arguments, got %d' % len(result)) + return result def __repr__(self): return 'Point(x=%r, y=%r)' % self @@ -433,11 +441,10 @@ Example:: def _replace(self, **kwds): 'Return a new Point object replacing specified fields with new values' - return Point._cast(map(kwds.get, ('x', 'y'), self)) - - @property - def _fields(self): - return ('x', 'y') + result = self._make(map(kwds.pop, ('x', 'y'), self)) + if kwds: + raise ValueError('Got unexpected field names: %r' % kwds.keys()) + return result x = property(itemgetter(0)) y = property(itemgetter(1)) @@ -459,29 +466,28 @@ by the :mod:`csv` or :mod:`sqlite3` modules:: EmployeeRecord = namedtuple('EmployeeRecord', 'name, age, title, department, paygrade') import csv - for emp in map(EmployeeRecord._cast, csv.reader(open("employees.csv", "rb"))): + for emp in map(EmployeeRecord._make, csv.reader(open("employees.csv", "rb"))): print(emp.name, emp.title) import sqlite3 conn = sqlite3.connect('/companydata') cursor = conn.cursor() cursor.execute('SELECT name, age, title, department, paygrade FROM employees') - for emp in map(EmployeeRecord._cast, cursor.fetchall()): + for emp in map(EmployeeRecord._make, cursor.fetchall()): print emp.name, emp.title In addition to the methods inherited from tuples, named tuples support -three additonal methods and a read-only attribute. +three additional methods and one attribute. -.. method:: namedtuple._cast(iterable) +.. method:: namedtuple._make(iterable) - Class method returning a new instance taking the positional arguments from the *iterable*. - Useful for casting existing sequences and iterables to named tuples: + Class method that makes a new instance from an existing sequence or iterable. :: - >>> t = [11, 22] - >>> Point._cast(t) - Point(x=11, y=22) + >>> t = [11, 22] + >>> Point._make(t) + Point(x=11, y=22) .. method:: somenamedtuple._asdict() @@ -507,7 +513,7 @@ three additonal methods and a read-only attribute. .. attribute:: somenamedtuple._fields - Return a tuple of strings listing the field names. This is useful for introspection + Tuple of strings listing the field names. This is useful for introspection and for creating new named tuple types from existing named tuples. :: diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index cab2e8c..54d2a19 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -21,7 +21,6 @@ Functions provided: A simple example (this is not recommended as a real way of generating HTML!):: - from __future__ import with_statement from contextlib import contextmanager @contextmanager @@ -98,7 +97,6 @@ Functions provided: And lets you write code like this:: - from __future__ import with_statement from contextlib import closing import urllib diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 218d1c8..e29e4ea 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -794,7 +794,6 @@ the :func:`localcontext` function to temporarily change the active context. For example, the following code sets the current decimal precision to 42 places, performs a calculation, and then automatically restores the previous context:: - from __future__ import with_statement from decimal import localcontext with localcontext() as ctx: diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index 2d7bb9c..5050a7f 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -109,7 +109,7 @@ The module defines the following functions: * :const:`LOCK_EX` -- acquire an exclusive lock When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be - bit-wise OR'd with :const:`LOCK_NB` to avoid blocking on lock acquisition. + bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition. If :const:`LOCK_NB` is used and the lock cannot be acquired, an :exc:`IOError` will be raised and the exception will have an *errno* attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index ebb7a6c..9463ba7 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -227,7 +227,7 @@ available. They are listed here in alphabetical order. the *flags* argument is it -- the future statements in effect around the call to compile are ignored. - Future statements are specified by bits which can be bitwise or-ed together to + Future statements are specified by bits which can be bitwise ORed together to specify multiple statements. The bitfield required to specify a given feature can be found as the :attr:`compiler_flag` attribute on the :class:`_Feature` instance in the :mod:`__future__` module. @@ -966,10 +966,11 @@ available. They are listed here in alphabetical order. *cmp* specifies a custom comparison function of two arguments (iterable elements) which should return a negative, zero or positive number depending on whether the first argument is considered smaller than, equal to, or larger than - the second argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())`` + the second argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())``. The default + value is ``None``. *key* specifies a function of one argument that is used to extract a comparison - key from each list element: ``key=str.lower`` + key from each list element: ``key=str.lower``. The default value is ``None``. *reverse* is a boolean value. If set to ``True``, then the list elements are sorted as if each comparison were reversed. diff --git a/Doc/library/msilib.rst b/Doc/library/msilib.rst index 1c50d82..93e7b84 100644 --- a/Doc/library/msilib.rst +++ b/Doc/library/msilib.rst @@ -40,7 +40,7 @@ structures. exposed. -.. function:: UUIDCreate() +.. function:: UuidCreate() Return the string representation of a new unique identifier. This wraps the Windows API functions :cfunc:`UuidCreate` and :cfunc:`UuidToString`. diff --git a/Doc/library/msvcrt.rst b/Doc/library/msvcrt.rst index 678ba7a..8a0452f 100644 --- a/Doc/library/msvcrt.rst +++ b/Doc/library/msvcrt.rst @@ -67,7 +67,7 @@ File Operations .. function:: open_osfhandle(handle, flags) Create a C runtime file descriptor from the file handle *handle*. The *flags* - parameter should be a bit-wise OR of :const:`os.O_APPEND`, :const:`os.O_RDONLY`, + parameter should be a bitwise OR of :const:`os.O_APPEND`, :const:`os.O_RDONLY`, and :const:`os.O_TEXT`. The returned file descriptor may be used as a parameter to :func:`os.fdopen` to create a file object. diff --git a/Doc/library/numbers.rst b/Doc/library/numbers.rst index d0f9c3b..4202a50 100644 --- a/Doc/library/numbers.rst +++ b/Doc/library/numbers.rst @@ -1,10 +1,10 @@ - :mod:`numbers` --- Numeric abstract base classes ================================================ .. module:: numbers :synopsis: Numeric abstract base classes (Complex, Real, Integral, etc.). + The :mod:`numbers` module (:pep:`3141`) defines a hierarchy of numeric abstract base classes which progressively define more operations. These concepts also provide a way to distinguish exact from inexact types. None of the types defined diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 71e5f36..ee0cf48 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -7,7 +7,7 @@ This module provides a more portable way of using operating system dependent -functionality than importing a operating system dependent built-in module like +functionality than importing an operating system dependent built-in module like :mod:`posix` or :mod:`nt`. If you just want to read or write a file see :func:`open`, if you want to manipulate paths, see the :mod:`os.path` module, and if you want to read all the lines in all the files on the @@ -17,7 +17,7 @@ file and directory handling see the :mod:`shutil` module. This module searches for an operating system dependent built-in module like :mod:`mac` or :mod:`posix` and exports the same functions and data as found -there. The design of all Python's built-in operating system dependent modules +there. The design of all built-in operating system dependent modules of Python is such that as long as the same functionality is available, it uses the same interface; for example, the function ``os.stat(path)`` returns stat information about *path* in the same format (which happens to have originated with the POSIX @@ -132,7 +132,7 @@ process and user. .. function:: getegid() Return the effective group id of the current process. This corresponds to the - 'set id' bit on the file being executed in the current process. Availability: + "set id" bit on the file being executed in the current process. Availability: Unix. @@ -140,7 +140,7 @@ process and user. .. index:: single: user; effective id - Return the current process' effective user id. Availability: Unix. + Return the current process's effective user id. Availability: Unix. .. function:: getgid() @@ -162,7 +162,7 @@ process and user. process. For most purposes, it is more useful to use the environment variable :envvar:`LOGNAME` to find out who the user is, or ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the currently - effective user ID. Availability: Unix. + effective user id. Availability: Unix. .. function:: getpgid(pid) @@ -196,7 +196,7 @@ process and user. .. index:: single: user; id - Return the current process' user id. Availability: Unix. + Return the current process's user id. Availability: Unix. .. function:: getenv(varname[, value]) @@ -245,20 +245,20 @@ process and user. Set the list of supplemental group ids associated with the current process to *groups*. *groups* must be a sequence, and each element must be an integer - identifying a group. This operation is typical available only to the superuser. + identifying a group. This operation is typically available only to the superuser. Availability: Unix. .. function:: setpgrp() - Calls the system call :cfunc:`setpgrp` or :cfunc:`setpgrp(0, 0)` depending on + Call the system call :cfunc:`setpgrp` or :cfunc:`setpgrp(0, 0)` depending on which version is implemented (if any). See the Unix manual for the semantics. Availability: Unix. .. function:: setpgid(pid, pgrp) - Calls the system call :cfunc:`setpgid` to set the process group id of the + Call the system call :cfunc:`setpgid` to set the process group id of the process with id *pid* to the process group with id *pgrp*. See the Unix manual for the semantics. Availability: Unix. @@ -275,13 +275,13 @@ process and user. .. function:: getsid(pid) - Calls the system call :cfunc:`getsid`. See the Unix manual for the semantics. + Call the system call :cfunc:`getsid`. See the Unix manual for the semantics. Availability: Unix. .. function:: setsid() - Calls the system call :cfunc:`setsid`. See the Unix manual for the semantics. + Call the system call :cfunc:`setsid`. See the Unix manual for the semantics. Availability: Unix. @@ -289,7 +289,7 @@ process and user. .. index:: single: user; id, setting - Set the current process' user id. Availability: Unix. + Set the current process's user id. Availability: Unix. .. placed in this section since it relates to errno.... a little weak @@ -301,7 +301,7 @@ process and user. .. function:: umask(mask) - Set the current numeric umask and returns the previous umask. Availability: + Set the current numeric umask and return the previous umask. Availability: Unix, Windows. @@ -491,9 +491,10 @@ by file descriptors. .. function:: lseek(fd, pos, how) - Set the current position of file descriptor *fd* to position *pos*, modified by - *how*: ``0`` to set the position relative to the beginning of the file; ``1`` to - set it relative to the current position; ``2`` to set it relative to the end of + Set the current position of file descriptor *fd* to position *pos*, modified + by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the + beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the + current position; :const:`os.SEEK_END` or ``2`` to set it relative to the end of the file. Availability: Macintosh, Unix, Windows. @@ -522,7 +523,7 @@ by file descriptors. Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master, slave)`` for the pty and the tty, respectively. For a (slightly) more portable - approach, use the :mod:`pty` module. Availability: Macintosh, Some flavors of + approach, use the :mod:`pty` module. Availability: Macintosh, some flavors of Unix. @@ -543,7 +544,7 @@ by file descriptors. This function is intended for low-level I/O and must be applied to a file descriptor as returned by :func:`open` or :func:`pipe`. To read a "file object" returned by the built-in function :func:`open` or by :func:`popen` or - :func:`fdopen`, or ``sys.stdin``, use its :meth:`read` or :meth:`readline` + :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`read` or :meth:`readline` methods. @@ -576,7 +577,7 @@ by file descriptors. This function is intended for low-level I/O and must be applied to a file descriptor as returned by :func:`open` or :func:`pipe`. To write a "file object" returned by the built-in function :func:`open` or by :func:`popen` or - :func:`fdopen`, or ``sys.stdout`` or ``sys.stderr``, use its :meth:`write` + :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its :meth:`write` method. The following data items are available for use in constructing the *flags* @@ -594,7 +595,7 @@ platforms. For descriptions of their availability and use, consult O_TRUNC Options for the *flag* argument to the :func:`open` function. These can be - bit-wise OR'd together. Availability: Macintosh, Unix, Windows. + combined using the bitwise OR operator ``|``. Availability: Macintosh, Unix, Windows. .. data:: O_DSYNC @@ -619,7 +620,7 @@ platforms. For descriptions of their availability and use, consult O_TEXT Options for the *flag* argument to the :func:`open` function. These can be - bit-wise OR'd together. Availability: Windows. + combined using the bitwise OR operator ``|``. Availability: Windows. .. data:: O_DIRECT @@ -749,7 +750,7 @@ Files and Directories .. function:: chmod(path, mode) Change the mode of *path* to the numeric *mode*. *mode* may take one of the - following values (as defined in the :mod:`stat` module) or bitwise or-ed + following values (as defined in the :mod:`stat` module) or bitwise ORed combinations of them: * ``stat.S_ISUID`` @@ -803,7 +804,7 @@ Files and Directories .. function:: lchown(path, uid, gid) - Change the owner and group id of *path* to the numeric *uid* and gid. This + Change the owner and group id of *path* to the numeric *uid* and *gid*. This function will not follow symbolic links. Availability: Macintosh, Unix. @@ -857,19 +858,19 @@ Files and Directories .. function:: major(device) - Extracts the device major number from a raw device number (usually the + Extract the device major number from a raw device number (usually the :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`). .. function:: minor(device) - Extracts the device minor number from a raw device number (usually the + Extract the device minor number from a raw device number (usually the :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`). .. function:: makedev(major, minor) - Composes a raw device number from the major and minor device numbers. + Compose a raw device number from the major and minor device numbers. .. function:: mkdir(path[, mode]) @@ -897,7 +898,7 @@ Files and Directories .. note:: :func:`makedirs` will become confused if the path elements to create include - *os.pardir*. + :data:`os.pardir`. This function handles UNC paths correctly. @@ -954,7 +955,7 @@ Files and Directories .. index:: single: directory; deleting - Removes directories recursively. Works like :func:`rmdir` except that, if the + Remove directories recursively. Works like :func:`rmdir` except that, if the leaf directory is successfully removed, :func:`removedirs` tries to successively remove every parent directory mentioned in *path* until an error is raised (which is ignored, because it generally means that a parent directory @@ -968,7 +969,7 @@ Files and Directories Rename the file or directory *src* to *dst*. If *dst* is a directory, :exc:`OSError` will be raised. On Unix, if *dst* exists and is a file, it will - be removed silently if the user has permission. The operation may fail on some + be replaced silently if the user has permission. The operation may fail on some Unix flavors if *src* and *dst* are on different filesystems. If successful, the renaming will be an atomic operation (this is a POSIX requirement). On Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a @@ -1000,7 +1001,7 @@ Files and Directories 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_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 @@ -1014,10 +1015,6 @@ Files and Directories 926L >>> - If :func:`stat_float_times` returns true, the time values are floats, measuring - seconds. Fractions of a second may be reported if the system supports that. On - Mac OS, the times are always floats. See :func:`stat_float_times` for further - discussion. On some Unix systems (such as Linux), the following attributes may also be available: :attr:`st_blocks` (number of blocks allocated for file), @@ -1131,8 +1128,8 @@ Files and Directories single: directory; walking single: directory; traversal - :func:`walk` generates the file names in a directory tree, by walking the tree - either top down or bottom up. For each directory in the tree rooted at directory + Generate the file names in a directory tree by walking the tree + either top-down or bottom-up. For each directory in the tree rooted at directory *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames, filenames)``. @@ -1143,34 +1140,34 @@ Files and Directories (which begins with *top*) to a file or directory in *dirpath*, do ``os.path.join(dirpath, name)``. - If optional argument *topdown* is true or not specified, the triple for a + If optional argument *topdown* is ``True`` or not specified, the triple for a directory is generated before the triples for any of its subdirectories - (directories are generated top down). If *topdown* is false, the triple for a + (directories are generated top-down). If *topdown* is ``False``, the triple for a directory is generated after the triples for all of its subdirectories - (directories are generated bottom up). + (directories are generated bottom-up). - When *topdown* is true, the caller can modify the *dirnames* list in-place + When *topdown* is ``True``, the caller can modify the *dirnames* list in-place (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only recurse into the subdirectories whose names remain in *dirnames*; this can be used to prune the search, impose a specific order of visiting, or even to inform :func:`walk` about directories the caller creates or renames before it resumes - :func:`walk` again. Modifying *dirnames* when *topdown* is false is + :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` is ineffective, because in bottom-up mode the directories in *dirnames* are generated before *dirpath* itself is generated. - By default errors from the ``os.listdir()`` call are ignored. If optional + By default errors from the :func:`listdir` call are ignored. If optional argument *onerror* is specified, it should be a function; it will be called with one argument, an :exc:`OSError` instance. It can report the error to continue with the walk, or raise the exception to abort the walk. Note that the filename is available as the ``filename`` attribute of the exception object. By default, :func:`walk` will not walk down into symbolic links that resolve to - directories. Set *followlinks* to True to visit directories pointed to by + directories. Set *followlinks* to ``True`` to visit directories pointed to by symlinks, on systems that support them. .. note:: - Be aware that setting *followlinks* to true can lead to infinite recursion if a + Be aware that setting *followlinks* to ``True`` can lead to infinite recursion if a link points to a parent directory of itself. :func:`walk` does not keep track of the directories it visited already. @@ -1193,10 +1190,10 @@ Files and Directories if 'CVS' in dirs: dirs.remove('CVS') # don't visit CVS directories - In the next example, walking the tree bottom up is essential: :func:`rmdir` + In the next example, walking the tree bottom-up is essential: :func:`rmdir` doesn't allow deleting a directory before the directory is empty:: - # Delete everything reachable from the directory named in 'top', + # Delete everything reachable from the directory named in "top", # assuming there are no symbolic links. # CAUTION: This is dangerous! For example, if top == '/', it # could delete all your disk files. @@ -1244,19 +1241,19 @@ to be ignored. These functions all execute a new program, replacing the current process; they do not return. On Unix, the new executable is loaded into the current process, - and will have the same process ID as the caller. Errors will be reported as + and will have the same process id as the caller. Errors will be reported as :exc:`OSError` exceptions. - The ``'l'`` and ``'v'`` variants of the :func:`exec\*` functions differ in how - command-line arguments are passed. The ``'l'`` variants are perhaps the easiest + The "l" and "v" variants of the :func:`exec\*` functions differ in how + command-line arguments are passed. The "l" variants are perhaps the easiest to work with if the number of parameters is fixed when the code is written; the individual parameters simply become additional parameters to the :func:`execl\*` - functions. The ``'v'`` variants are good when the number of parameters is + functions. The "v" variants are good when the number of parameters is variable, with the arguments being passed in a list or tuple as the *args* parameter. In either case, the arguments to the child process should start with the name of the command being run, but this is not enforced. - The variants which include a ``'p'`` near the end (:func:`execlp`, + The variants which include a "p" near the end (:func:`execlp`, :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the :envvar:`PATH` environment variable to locate the program *file*. When the environment is being replaced (using one of the :func:`exec\*e` variants, @@ -1267,7 +1264,7 @@ to be ignored. path. For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note - that these all end in ``'e'``), the *env* parameter must be a mapping which is + that these all end in "e"), the *env* parameter must be a mapping which is used to define the environment variables for the new process; the :func:`execl`, :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to inherit the environment of the current process. Availability: Macintosh, Unix, @@ -1284,7 +1281,7 @@ to be ignored. The standard way to exit is ``sys.exit(n)``. :func:`_exit` should normally only be used in the child process after a :func:`fork`. -The following exit codes are a defined, and can be used with :func:`_exit`, +The following exit codes are defined and can be used with :func:`_exit`, although they are not required. These are typically used for system programs written in Python, such as a mail server's external command delivery program. @@ -1400,7 +1397,7 @@ written in Python, such as a mail server's external command delivery program. .. function:: fork() - Fork a child process. Return ``0`` in the child, the child's process id in the + Fork a child process. Return ``0`` in the child and the child's process id in the parent. Availability: Macintosh, Unix. @@ -1410,7 +1407,7 @@ written in Python, such as a mail server's external command delivery program. terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the new child's process id in the parent, and *fd* is the file descriptor of the master end of the pseudo-terminal. For a more portable approach, use the - :mod:`pty` module. Availability: Macintosh, Some flavors of Unix. + :mod:`pty` module. Availability: Macintosh, some flavors of Unix. .. function:: kill(pid, sig) @@ -1469,22 +1466,22 @@ written in Python, such as a mail server's external command delivery program. spawning new processes and retrieving their results; using that module is preferable to using these functions.) - If *mode* is :const:`P_NOWAIT`, this function returns the process ID of the new + If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it exits normally, or ``-signal``, where *signal* is the signal that killed the - process. On Windows, the process ID will actually be the process handle, so can + process. On Windows, the process id will actually be the process handle, so can be used with the :func:`waitpid` function. - The ``'l'`` and ``'v'`` variants of the :func:`spawn\*` functions differ in how - command-line arguments are passed. The ``'l'`` variants are perhaps the easiest + The "l" and "v" variants of the :func:`spawn\*` functions differ in how + command-line arguments are passed. The "l" variants are perhaps the easiest to work with if the number of parameters is fixed when the code is written; the individual parameters simply become additional parameters to the - :func:`spawnl\*` functions. The ``'v'`` variants are good when the number of + :func:`spawnl\*` functions. The "v" variants are good when the number of parameters is variable, with the arguments being passed in a list or tuple as the *args* parameter. In either case, the arguments to the child process must start with the name of the command being run. - The variants which include a second ``'p'`` near the end (:func:`spawnlp`, + The variants which include a second "p" near the end (:func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the :envvar:`PATH` environment variable to locate the program *file*. When the environment is being replaced (using one of the :func:`spawn\*e` variants, @@ -1495,7 +1492,7 @@ written in Python, such as a mail server's external command delivery program. appropriate absolute or relative path. For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe` - (note that these all end in ``'e'``), the *env* parameter must be a mapping + (note that these all end in "e"), the *env* parameter must be a mapping which is used to define the environment variables for the new process; the :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause the new process to inherit the environment of the current process. @@ -1518,7 +1515,7 @@ written in Python, such as a mail server's external command delivery program. Possible values for the *mode* parameter to the :func:`spawn\*` family of functions. If either of these values is given, the :func:`spawn\*` functions - will return as soon as the new process has been created, with the process ID as + will return as soon as the new process has been created, with the process id as the return value. Availability: Macintosh, Unix, Windows. @@ -1569,8 +1566,8 @@ written in Python, such as a mail server's external command delivery program. Execute the command (a string) in a subshell. This is implemented by calling the Standard C function :cfunc:`system`, and has the same limitations. Changes - to ``posix.environ``, ``sys.stdin``, etc. are not reflected in the environment - of the executed command. + to :data:`os.environ`, :data:`sys.stdin`, etc. are not reflected in the + environment of the executed command. On Unix, the return value is the exit status of the process encoded in the format specified for :func:`wait`. Note that POSIX does not specify the meaning @@ -1681,32 +1678,32 @@ used to determine the disposition of a process. .. function:: WCOREDUMP(status) - Returns ``True`` if a core dump was generated for the process, otherwise it - returns ``False``. Availability: Macintosh, Unix. + Return ``True`` if a core dump was generated for the process, otherwise + return ``False``. Availability: Macintosh, Unix. .. function:: WIFCONTINUED(status) - Returns ``True`` if the process has been continued from a job control stop, - otherwise it returns ``False``. Availability: Unix. + Return ``True`` if the process has been continued from a job control stop, + otherwise return ``False``. Availability: Unix. .. function:: WIFSTOPPED(status) - Returns ``True`` if the process has been stopped, otherwise it returns + Return ``True`` if the process has been stopped, otherwise return ``False``. Availability: Unix. .. function:: WIFSIGNALED(status) - Returns ``True`` if the process exited due to a signal, otherwise it returns + Return ``True`` if the process exited due to a signal, otherwise return ``False``. Availability: Macintosh, Unix. .. function:: WIFEXITED(status) - Returns ``True`` if the process exited using the :manpage:`exit(2)` system call, - otherwise it returns ``False``. Availability: Macintosh, Unix. + Return ``True`` if the process exited using the :manpage:`exit(2)` system call, + otherwise return ``False``. Availability: Macintosh, Unix. .. function:: WEXITSTATUS(status) @@ -1783,7 +1780,7 @@ Miscellaneous System Information defined for those names by the host operating system. This can be used to determine the set of names known to the system. Availability: Macintosh, Unix. -The follow data values are used to support path manipulation operations. These +The following data values are used to support path manipulation operations. These are defined for all platforms. Higher-level operations on pathnames are defined in the :mod:`os.path` module. diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index a6557e1..cc16150 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -155,6 +155,12 @@ The module :mod:`socket` exports the following constants and functions: in the Unix header files are defined; for a few symbols, default values are provided. +.. data:: SIO_* + RCVALL_* + + Constants for Windows' WSAIoctl(). The constants are used as arguments to the + :meth:`ioctl` method of socket objects. + .. data:: has_ipv6 @@ -524,6 +530,14 @@ correspond to Unix system calls applicable to sockets. contents of the buffer (see the optional built-in module :mod:`struct` for a way to decode C structures encoded as strings). + +.. method:: socket.ioctl(control, option) + + :platform: Windows + + The `meth:ioctl` method is a limited interface to the WSAIoctl system + interface. Please refer to the MSDN documentation for more information. + .. method:: socket.listen(backlog) @@ -822,3 +836,28 @@ sends traffic to the first one connected successfully. :: s.close() print('Received', repr(data)) + +The last example shows how to write a very simple network sniffer with raw +sockets on Windows. The example requires administrator priviliges to modify +the interface:: + + import socket + + # the public network interface + HOST = socket.gethostbyname(socket.gethostname()) + + # create a raw socket and bind it to the public interface + s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP) + s.bind((HOST, 0)) + + # Include IP headers + s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1) + + # receive all packages + s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON) + + # receive a package + print s.recvfrom(65565) + + # disabled promiscous mode + s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 554cbc5..92183a4 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -352,6 +352,23 @@ Notes: or "-" for Not a Number (NaN) and positive or negative infinity. +All :class:`numbers.Real` types (:class:`int` and +:class:`float`) also include the following operations: + ++--------------------+--------------------------------+--------+ +| Operation | Result | Notes | ++====================+================================+========+ +| ``trunc(x)`` | *x* truncated to Integral | | ++--------------------+--------------------------------+--------+ +| ``round(x[, n])`` | *x* rounded to n digits, | | +| | rounding half to even. If n is | | +| | omitted, it defaults to 0. | | ++--------------------+--------------------------------+--------+ +| ``math.floor(x)`` | the greatest Integral <= *x* | | ++--------------------+--------------------------------+--------+ +| ``math.ceil(x)`` | the least Integral >= *x* | | ++--------------------+--------------------------------+--------+ + .. XXXJH exceptions: overflow (when? what operations?) zerodivision @@ -366,7 +383,7 @@ Integers support additional operations that make sense only for bit-strings. Negative numbers are treated as their 2's complement value (this assumes a sufficiently large number of bits that no overflow occurs during the operation). -The priorities of the binary bit-wise operations are all lower than the numeric +The priorities of the binary bitwise operations are all lower than the numeric operations and higher than the comparisons; the unary operation ``~`` has the same priority as the other unary numeric operations (``+`` and ``-``). @@ -1319,10 +1336,11 @@ Notes: *cmp* specifies a custom comparison function of two arguments (list items) which should return a negative, zero or positive number depending on whether the first argument is considered smaller than, equal to, or larger than the second - argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())`` + argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())``. The default value + is ``None``. *key* specifies a function of one argument that is used to extract a comparison - key from each list element: ``key=str.lower`` + key from each list element: ``key=str.lower``. The default value is ``None``. *reverse* is a boolean value. If set to ``True``, then the list elements are sorted as if each comparison were reversed. @@ -2005,7 +2023,12 @@ Files have the following methods: argument is optional and defaults to ``os.SEEK_SET`` or ``0`` (absolute file positioning); other values are ``os.SEEK_CUR`` or ``1`` (seek relative to the current position) and ``os.SEEK_END`` or ``2`` (seek relative to the file's - end). There is no return value. Note that if the file is opened for appending + end). There is no return value. + + For example, ``f.seek(2, os.SEEK_CUR)`` advances the position by two and + ``f.seek(-3, os.SEEK_END)`` sets the position to the third to last. + + Note that if the file is opened for appending (mode ``'a'`` or ``'a+'``), any :meth:`seek` operations will be undone at the next write. If the file is only opened for writing in append mode (mode ``'a'``), this method is essentially a no-op, but it remains useful for files @@ -2138,7 +2161,7 @@ to be provided for a context manager object to define a runtime context: the context expression in a :keyword:`with` statement. An example of a context manager that returns a related object is the one - returned by ``decimal.Context.get_manager()``. These managers set the active + returned by :func:`decimal.localcontext`. These managers set the active decimal context to a copy of the original decimal context and then return the copy. This allows changes to be made to the current decimal context in the body of the :keyword:`with` statement without affecting code outside the diff --git a/Doc/library/thread.rst b/Doc/library/thread.rst index 867a1ff..31d58e7 100644 --- a/Doc/library/thread.rst +++ b/Doc/library/thread.rst @@ -132,7 +132,6 @@ Lock objects have the following methods: In addition to these methods, lock objects can also be used via the :keyword:`with` statement, e.g.:: - from __future__ import with_statement import thread a_lock = thread.allocate_lock() diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 1b82e4b..c015372 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -716,7 +716,6 @@ Currently, :class:`Lock`, :class:`RLock`, :class:`Condition`, :class:`Semaphore`, and :class:`BoundedSemaphore` objects may be used as :keyword:`with` statement context managers. For example:: - from __future__ import with_statement import threading some_rlock = threading.RLock() diff --git a/Doc/library/winsound.rst b/Doc/library/winsound.rst index 923c7c4..3088848 100644 --- a/Doc/library/winsound.rst +++ b/Doc/library/winsound.rst @@ -32,7 +32,7 @@ provided by Windows platforms. It includes functions and several constants. Call the underlying :cfunc:`PlaySound` function from the Platform API. The *sound* parameter may be a filename, audio data as a string, or ``None``. Its - interpretation depends on the value of *flags*, which can be a bit-wise ORed + interpretation depends on the value of *flags*, which can be a bitwise ORed combination of the constants described below. If the system indicates an error, :exc:`RuntimeError` is raised. |