diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/carbon.rst | 2 | ||||
| -rw-r--r-- | Doc/library/ctypes.rst | 22 | ||||
| -rw-r--r-- | Doc/library/getpass.rst | 20 | ||||
| -rw-r--r-- | Doc/library/io.rst | 131 | ||||
| -rw-r--r-- | Doc/library/optparse.rst | 2 | ||||
| -rw-r--r-- | Doc/library/pkgutil.rst | 4 | ||||
| -rw-r--r-- | Doc/library/pyclbr.rst | 91 | ||||
| -rw-r--r-- | Doc/library/robotparser.rst | 21 | ||||
| -rw-r--r-- | Doc/library/simplehttpserver.rst | 25 | ||||
| -rw-r--r-- | Doc/library/socket.rst | 2 | ||||
| -rw-r--r-- | Doc/library/sqlite3.rst | 13 | ||||
| -rw-r--r-- | Doc/library/subprocess.rst | 2 | ||||
| -rw-r--r-- | Doc/library/sys.rst | 22 | ||||
| -rw-r--r-- | Doc/library/tempfile.rst | 184 | ||||
| -rw-r--r-- | Doc/library/unittest.rst | 1 | ||||
| -rw-r--r-- | Doc/library/xmlrpclib.rst | 13 |
16 files changed, 305 insertions, 250 deletions
diff --git a/Doc/library/carbon.rst b/Doc/library/carbon.rst index ecaf3bb..886fa82 100644 --- a/Doc/library/carbon.rst +++ b/Doc/library/carbon.rst @@ -70,7 +70,7 @@ The ``CFBase``, ``CFArray``, ``CFData``, ``CFDictionary``, ``CFString`` and .. module:: Carbon.CG :platform: Mac - :synopsis: Interface to the Component Manager. + :synopsis: Interface to Core Graphics. diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 8d38050..6968f42 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1948,6 +1948,28 @@ Data types exact, they are methods of the :term:`metaclass`): + .. method:: _CData.from_buffer(source[, offset]) + + This method returns a ctypes instance that shares the buffer of + the ``source`` object. The ``source`` object must support the + writeable buffer interface. The optional ``offset`` parameter + specifies an offset into the source buffer in bytes; the default + is zero. If the source buffer is not large enough a ValueError + is raised. + + .. versionadded:: 2.6 + + .. method:: _CData.from_buffer_copy(source[, offset]) + + This method creates a ctypes instance, the buffer is copied from + the source object buffer which must be readable. The optional + ``offset`` parameter specifies an offset into the source buffer + in bytes; the default is zero. If the source buffer is not + large enough a ValueError is raised. + + .. versionadded:: 2.6 + + .. method:: from_address(address) This method returns a ctypes type instance using the memory specified by diff --git a/Doc/library/getpass.rst b/Doc/library/getpass.rst index bd384b4..91c811b 100644 --- a/Doc/library/getpass.rst +++ b/Doc/library/getpass.rst @@ -14,11 +14,27 @@ The :mod:`getpass` module provides two functions: Prompt the user for a password without echoing. The user is prompted using the string *prompt*, which defaults to ``'Password: '``. On Unix, the prompt is - written to the file-like object *stream*, which defaults to ``sys.stdout`` (this - argument is ignored on Windows). + written to the file-like object *stream*. *stream* defaults to the + controlling terminal (/dev/tty) or if that is unavailable to ``sys.stderr`` + (this argument is ignored on Windows). + + If echo free input is unavailable getpass() falls back to printing + a warning message to *stream* and reading from ``sys.stdin`` and + issuing a :exc:`GetPassWarning`. Availability: Macintosh, Unix, Windows. + .. versionchanged:: 2.6 + On Unix it defaults to using /dev/tty before falling back + to ``sys.stdin`` and ``sys.stderr``. + .. note:: + If you call getpass from within IDLE, the input may be done in the + terminal you launched IDLE from rather than the idle window itself. + +.. exception:: GetPassWarning + + A :exc:`UserWarning` subclass issued when password input may be echoed. + .. function:: getuser() diff --git a/Doc/library/io.rst b/Doc/library/io.rst index d0f82a3..d80d265 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -222,7 +222,7 @@ I/O Base Classes .. method:: fileno() - Return the underlying file descriptor (an integer) of the stream, if it + Return the underlying file descriptor (an integer) of the stream if it exists. An :exc:`IOError` is raised if the IO object does not use a file descriptor. @@ -233,18 +233,18 @@ I/O Base Classes .. method:: isatty() - Returns ``True`` if the stream is interactive (i.e., connected to + Return ``True`` if the stream is interactive (i.e., connected to a terminal/tty device). .. method:: readable() - Returns ``True`` if the stream can be read from. If False, - :meth:`read` will raise :exc:`IOError`. + Return ``True`` if the stream can be read from. If False, :meth:`read` + will raise :exc:`IOError`. .. method:: readline([limit]) - Reads and returns one line from the stream. If *limit* is - specified, at most *limit* bytes will be read. + Read and return one line from the stream. If *limit* is specified, at + most *limit* bytes will be read. The line terminator is always ``b'\n'`` for binary files; for text files, the *newlines* argument to :func:`open` can be used to select the line @@ -252,9 +252,9 @@ I/O Base Classes .. method:: readlines([hint]) - Returns a list of lines from the stream. *hint* can be specified to - control the number of lines read: no more lines will be read if the total - size (in bytes/characters) of all lines so far exceeds *hint*. + Read and return a list of lines from the stream. *hint* can be specified + to control the number of lines read: no more lines will be read if the + total size (in bytes/characters) of all lines so far exceeds *hint*. .. method:: seek(offset[, whence]) @@ -266,33 +266,32 @@ I/O Base Classes * ``1`` -- current stream position; *offset* may be negative * ``2`` -- end of the stream; *offset* is usually negative - Returns the new absolute position. + Return the new absolute position. .. method:: seekable() - Returns ``True`` if the stream supports random access. If - ``False``, :meth:`seek`, :meth:`tell` and :meth:`truncate` will - raise :exc:`IOError`. + Return ``True`` if the stream supports random access. If ``False``, + :meth:`seek`, :meth:`tell` and :meth:`truncate` will raise :exc:`IOError`. .. method:: tell() - Returns the current stream position. + Return the current stream position. .. method:: truncate([size]) - Truncates the file to at most *size* bytes. *size* defaults to the current + Truncate the file to at most *size* bytes. *size* defaults to the current file position, as returned by :meth:`tell`. .. method:: writable() - Returns ``True`` if the stream supports writing. If ``False``, + Return ``True`` if the stream supports writing. If ``False``, :meth:`write` and :meth:`truncate` will raise :exc:`IOError`. .. method:: writelines(lines) - Writes a list of lines to the stream. Line separators are not - added, so it is usual for each of the lines provided to have a - line separator at the end. + Write a list of lines to the stream. Line separators are not added, so it + is usual for each of the lines provided to have a line separator at the + end. .. class:: RawIOBase @@ -305,27 +304,26 @@ I/O Base Classes .. method:: read([n]) - Reads and returns all the bytes from the stream until EOF, or if *n* is - specified, up to *n* bytes. An empty bytes object is returned on EOF; - ``None`` is returned if the object is set not to block and has no data to - read. + Read and return all the bytes from the stream until EOF, or if *n* is + specified, up to *n* bytes. Only one system call is ever made. An empty + bytes object is returned on EOF; ``None`` is returned if the object is set + not to block and has no data to read. .. method:: readall() - Reads and returns all the bytes from the stream until EOF, using - multiple calls to the stream if necessary. + Read and return all the bytes from the stream until EOF, using multiple + calls to the stream if necessary. .. method:: readinto(b) - Reads up to len(b) bytes into bytearray *b* and returns the number - of bytes read. + Read up to len(b) bytes into bytearray *b* and return the number of bytes + read. .. method:: write(b) - Writes the given bytes or bytearray object, *b*, to the underlying - raw stream and returns the number of bytes written (never less - than ``len(b)``, since if the write fails an :exc:`IOError` will - be raised). + Write the given bytes or bytearray object, *b*, to the underlying raw + stream and return the number of bytes written (This is never less than + ``len(b)``, since if the write fails, an :exc:`IOError` will be raised). Raw File I/O @@ -352,22 +350,21 @@ Raw File I/O .. attribute:: name - The file name. + The file name. This is the file descriptor of the file when no name is + given in the constructor. .. method:: read([n]) - Reads and returns at most *n* bytes. Only one system call is made, so - it is possible that less data than was requested is returned. Call - :func:`len` on the returned bytes object to see how many bytes - were actually returned (In non-blocking mode, ``None`` is returned - when no data is available.) + Read and return at most *n* bytes. Only one system call is made, so it is + possible that less data than was requested is returned. Use :func:`len` + on the returned bytes object to see how many bytes were actually returned. + (In non-blocking mode, ``None`` is returned when no data is available.) .. method:: readall() - Reads and returns the entire file's contents in a single bytes - object. As much as immediately available is returned in - non-blocking mode. If the EOF has been reached, ``b''`` is - returned. + Read and return the entire file's contents in a single bytes object. As + much as immediately available is returned in non-blocking mode. If the + EOF has been reached, ``b''`` is returned. .. method:: write(b) @@ -405,7 +402,7 @@ Buffered Streams .. method:: read([n]) - Reads and returns up to *n* bytes. If the argument is omitted, ``None``, or + Read and return up to *n* bytes. If the argument is omitted, ``None``, or negative, data is read and returned until EOF is reached. An empty bytes object is returned if the stream is already at EOF. @@ -420,7 +417,7 @@ Buffered Streams .. method:: readinto(b) - Reads up to len(b) bytes into bytearray *b* and returns the number of bytes + Read up to len(b) bytes into bytearray *b* and return the number of bytes read. Like :meth:`read`, multiple reads may be issued to the underlying raw @@ -431,10 +428,9 @@ Buffered Streams .. method:: write(b) - Writes the given bytes or bytearray object, *b*, to the underlying - raw stream and returns the number of bytes written (never less than - ``len(b)``, since if the write fails an :exc:`IOError` will - be raised). + Write the given bytes or bytearray object, *b*, to the underlying raw + stream and return the number of bytes written (never less than ``len(b)``, + since if the write fails an :exc:`IOError` will be raised). A :exc:`BlockingIOError` is raised if the buffer is full, and the underlying raw stream cannot accept more data at the moment. @@ -452,8 +448,7 @@ Buffered Streams .. method:: getvalue() - Returns a bytes object containing the entire contents of the - buffer. + Return ``bytes`` containing the entire contents of the buffer. .. method:: read1() @@ -461,8 +456,8 @@ Buffered Streams .. method:: truncate([size]) - Truncates the buffer to at most *size* bytes. *size* defaults to the current - stream position, as returned by :meth:`tell`. + Truncate the buffer to at most *size* bytes. *size* defaults to the + current stream position, as returned by :meth:`tell`. .. class:: BufferedReader(raw[, buffer_size]) @@ -479,20 +474,20 @@ Buffered Streams .. method:: peek([n]) - Returns 1 (or *n* if specified) bytes from a buffer without - advancing the position. Only a single read on the raw stream is done to - satisfy the call. The number of bytes returned may be less than - requested since at most all the buffer's bytes from the current - position to the end are returned. + Return 1 (or *n* if specified) bytes from a buffer without advancing the + position. Only a single read on the raw stream is done to satisfy the + call. The number of bytes returned may be less than requested since at + most all the buffer's bytes from the current position to the end are + returned. .. method:: read([n]) - Reads and returns *n* bytes, or if *n* is not given or negative, until EOF + Read and return *n* bytes, or if *n* is not given or negative, until EOF or if the read call would block in non-blocking mode. .. method:: read1(n) - Reads and returns up to *n* bytes with only one call on the raw stream. If + Read and return up to *n* bytes with only one call on the raw stream. If at least one byte is buffered, only buffered bytes are returned. Otherwise, one raw stream read call is made. @@ -517,9 +512,9 @@ Buffered Streams .. method:: write(b) - Writes the bytes or bytearray object, *b*, onto the raw stream and - returns the number of bytes written. A :exc:`BlockingIOError` is - raised when the raw stream blocks. + Write the bytes or bytearray object, *b*, onto the raw stream and return + the number of bytes written. A :exc:`BlockingIOError` is raised when the + raw stream blocks. .. class:: BufferedRWPair(reader, writer[, buffer_size[, max_buffer_size]]) @@ -576,18 +571,18 @@ Text I/O .. method:: read(n) - Reads and returns at most *n* characters from the stream as a - single :class:`str`. If *n* is negative or ``None``, reads to EOF. + Read and return at most *n* characters from the stream as a single + :class:`str`. If *n* is negative or ``None``, reads to EOF. .. method:: readline() - Reads until newline or EOF and returns a single :class:`str`. If - the stream is already at EOF, an empty string is returned. + Read until newline or EOF and return a single ``str``. If the stream is + already at EOF, an empty string is returned. .. method:: write(s) - Writes the string *s* to the stream and returns the number of - characters written. + Write the string *s* to the stream and return the number of characters + written. .. class:: TextIOWrapper(buffer[, encoding[, errors[, newline[, line_buffering]]]]) @@ -646,7 +641,7 @@ Text I/O .. method:: getvalue() - Returns a :class:`str` containing the entire contents of the buffer. + Return a ``str`` containing the entire contents of the buffer. .. class:: IncrementalNewlineDecoder diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index 7903ae8..3bdfab4 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -1633,7 +1633,7 @@ arguments:: [...] parser.add_option("-c", "--callback", - action="callback", callback=varargs) + action="callback", callback=vararg_callback) The main weakness with this particular implementation is that negative numbers in the arguments following ``"-c"`` will be interpreted as further options diff --git a/Doc/library/pkgutil.rst b/Doc/library/pkgutil.rst index 72daa84..48d53e3 100644 --- a/Doc/library/pkgutil.rst +++ b/Doc/library/pkgutil.rst @@ -42,13 +42,13 @@ This module provides functions to manipulate packages: Get a resource from a package. - This is a wrapper round the PEP 302 loader :func:`get_data` API. The package + This is a wrapper for the PEP 302 loader :func:`get_data` API. The package argument should be the name of a package, in standard module format (foo.bar). The resource argument should be in the form of a relative filename, using ``/`` as the path separator. The parent directory name ``..`` is not allowed, and nor is a rooted name (starting with a ``/``). - The function returns a binary string, which is the contents of the + The function returns a binary string that is the contents of the specified resource. For packages located in the filesystem, which have already been imported, diff --git a/Doc/library/pyclbr.rst b/Doc/library/pyclbr.rst index 788c60c..a5d8494 100644 --- a/Doc/library/pyclbr.rst +++ b/Doc/library/pyclbr.rst @@ -7,75 +7,75 @@ .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> -The :mod:`pyclbr` can be used to determine some limited information about the -classes, methods and top-level functions defined in a module. The information -provided is sufficient to implement a traditional three-pane class browser. The -information is extracted from the source code rather than by importing the -module, so this module is safe to use with untrusted source code. This -restriction makes it impossible to use this module with modules not implemented -in Python, including many standard and optional extension modules. +The :mod:`pyclbr` module can be used to determine some limited information +about the classes, methods and top-level functions defined in a module. The +information provided is sufficient to implement a traditional three-pane +class browser. The information is extracted from the source code rather +than by importing the module, so this module is safe to use with untrusted +code. This restriction makes it impossible to use this module with modules +not implemented in Python, including all standard and optional extension +modules. -.. function:: readmodule(module[, path]) +.. function:: readmodule(module[, path=None]) - Read a module and return a dictionary mapping class names to class descriptor - objects. The parameter *module* should be the name of a module as a string; - it may be the name of a module within a package. The *path* parameter should - be a sequence, and is used to augment the value of ``sys.path``, which is - used to locate module source code. + Read a module and return a dictionary mapping class names to class + descriptor objects. The parameter *module* should be the name of a + module as a string; it may be the name of a module within a package. The + *path* parameter should be a sequence, and is used to augment the value + of ``sys.path``, which is used to locate module source code. - .. The 'inpackage' parameter appears to be for internal use only.... +.. function:: readmodule_ex(module[, path=None]) -.. function:: readmodule_ex(module[, path]) - - Like :func:`readmodule`, but the returned dictionary, in addition to mapping - class names to class descriptor objects, also maps top-level function names to - function descriptor objects. Moreover, if the module being read is a package, - the key ``'__path__'`` in the returned dictionary has as its value a list which - contains the package search path. - - .. The 'inpackage' parameter appears to be for internal use only.... + Like :func:`readmodule`, but the returned dictionary, in addition to + mapping class names to class descriptor objects, also maps top-level + function names to function descriptor objects. Moreover, if the module + being read is a package, the key ``'__path__'`` in the returned + dictionary has as its value a list which contains the package search + path. .. _pyclbr-class-objects: -Class Descriptor Objects ------------------------- +Class Objects +------------- -The class descriptor objects used as values in the dictionary returned by -:func:`readmodule` and :func:`readmodule_ex` provide the following data members: +The :class:`Class` objects used as values in the dictionary returned by +:func:`readmodule` and :func:`readmodule_ex` provide the following data +members: -.. attribute:: class_descriptor.module +.. attribute:: Class.module The name of the module defining the class described by the class descriptor. -.. attribute:: class_descriptor.name +.. attribute:: Class.name The name of the class. -.. attribute:: class_descriptor.super +.. attribute:: Class.super - A list of class descriptors which describe the immediate base classes of the - class being described. Classes which are named as superclasses but which are - not discoverable by :func:`readmodule` are listed as a string with the class - name instead of class descriptors. + A list of :class:`Class` objects which describe the immediate base + classes of the class being described. Classes which are named as + superclasses but which are not discoverable by :func:`readmodule` are + listed as a string with the class name instead of as :class:`Class` + objects. -.. attribute:: class_descriptor.methods +.. attribute:: Class.methods A dictionary mapping method names to line numbers. -.. attribute:: class_descriptor.file +.. attribute:: Class.file Name of the file containing the ``class`` statement defining the class. -.. attribute:: class_descriptor.lineno +.. attribute:: Class.lineno The line number of the ``class`` statement within the file named by :attr:`file`. @@ -83,30 +83,31 @@ The class descriptor objects used as values in the dictionary returned by .. _pyclbr-function-objects: -Function Descriptor Objects ---------------------------- +Function Objects +---------------- -The function descriptor objects used as values in the dictionary returned by +The :class:`Function` objects used as values in the dictionary returned by :func:`readmodule_ex` provide the following data members: -.. attribute:: function_descriptor.module +.. attribute:: Function.module The name of the module defining the function described by the function descriptor. -.. attribute:: function_descriptor.name +.. attribute:: Function.name The name of the function. -.. attribute:: function_descriptor.file +.. attribute:: Function.file Name of the file containing the ``def`` statement defining the function. -.. attribute:: function_descriptor.lineno +.. attribute:: Function.lineno - The line number of the ``def`` statement within the file named by :attr:`file`. + The line number of the ``def`` statement within the file named by + :attr:`file`. diff --git a/Doc/library/robotparser.rst b/Doc/library/robotparser.rst index b3a9a60..cce7966 100644 --- a/Doc/library/robotparser.rst +++ b/Doc/library/robotparser.rst @@ -3,7 +3,8 @@ ============================================= .. module:: robotparser - :synopsis: Loads a robots.txt file and answers questions about fetchability of other URLs. + :synopsis: Loads a robots.txt file and answers questions about + fetchability of other URLs. .. sectionauthor:: Skip Montanaro <skip@pobox.com> @@ -21,8 +22,8 @@ structure of :file:`robots.txt` files, see http://www.robotstxt.org/orig.html. .. class:: RobotFileParser() - This class provides a set of methods to read, parse and answer questions about a - single :file:`robots.txt` file. + This class provides a set of methods to read, parse and answer questions + about a single :file:`robots.txt` file. .. method:: set_url(url) @@ -42,20 +43,22 @@ structure of :file:`robots.txt` files, see http://www.robotstxt.org/orig.html. .. method:: can_fetch(useragent, url) - Returns ``True`` if the *useragent* is allowed to fetch the *url* according to - the rules contained in the parsed :file:`robots.txt` file. + Returns ``True`` if the *useragent* is allowed to fetch the *url* + according to the rules contained in the parsed :file:`robots.txt` + file. .. method:: mtime() - Returns the time the ``robots.txt`` file was last fetched. This is useful for - long-running web spiders that need to check for new ``robots.txt`` files - periodically. + Returns the time the ``robots.txt`` file was last fetched. This is + useful for long-running web spiders that need to check for new + ``robots.txt`` files periodically. .. method:: modified() - Sets the time the ``robots.txt`` file was last fetched to the current time. + Sets the time the ``robots.txt`` file was last fetched to the current + time. The following example demonstrates basic use of the RobotFileParser class. :: diff --git a/Doc/library/simplehttpserver.rst b/Doc/library/simplehttpserver.rst index 2f1af89..7d99681 100644 --- a/Doc/library/simplehttpserver.rst +++ b/Doc/library/simplehttpserver.rst @@ -7,39 +7,40 @@ .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> -The :mod:`SimpleHTTPServer` module defines a request-handler class, -interface-compatible with :class:`BaseHTTPServer.BaseHTTPRequestHandler`, that -serves files only from a base directory. +The :mod:`SimpleHTTPServer` module defines a single class, +:class:`SimpleHTTPRequestHandler`, which is interface-compatible with +:class:`BaseHTTPServer.BaseHTTPRequestHandler`. The :mod:`SimpleHTTPServer` module defines the following class: .. class:: SimpleHTTPRequestHandler(request, client_address, server) - This class is used to serve files from the current directory and below, directly + This class serves files from the current directory and below, directly mapping the directory structure to HTTP requests. A lot of the work, such as parsing the request, is done by the base class :class:`BaseHTTPServer.BaseHTTPRequestHandler`. This class implements the :func:`do_GET` and :func:`do_HEAD` functions. - The :class:`SimpleHTTPRequestHandler` defines the following member variables: + The following are defined as class-level attributes of + :class:`SimpleHTTPRequestHandler`: .. attribute:: server_version - This will be ``"SimpleHTTP/" + __version__``, where ``__version__`` is - defined in the module. + This will be ``"SimpleHTTP/" + __version__``, where ``__version__`` is + defined at the module level. .. attribute:: extensions_map - A dictionary mapping suffixes into MIME types. The default is signified by - an empty string, and is considered to be ``application/octet-stream``. The - mapping is used case-insensitively, and so should contain only lower-cased - keys. + A dictionary mapping suffixes into MIME types. The default is + signified by an empty string, and is considered to be + ``application/octet-stream``. The mapping is used case-insensitively, + and so should contain only lower-cased keys. - The :class:`SimpleHTTPRequestHandler` defines the following methods: + The :class:`SimpleHTTPRequestHandler` class defines the following methods: .. method:: do_HEAD() diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 971e316..2f89758 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -765,7 +765,7 @@ The first two examples support IPv4 only. :: # Echo server program import socket - HOST = '' # Symbolic name meaning the local host + HOST = '' # Symbolic name meaning all available interfaces PORT = 50007 # Arbitrary non-privileged port s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) s.bind((HOST, PORT)) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index bf9b186..baf12e8 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -112,10 +112,11 @@ Module functions and constants :func:`connect` function. Setting it makes the :mod:`sqlite3` module parse the declared type for each - column it returns. It will parse out the first word of the declared type, i. e. - for "integer primary key", it will parse out "integer". Then for that column, it - will look into the converters dictionary and use the converter function - registered for that type there. Converter names are case-sensitive! + column it returns. It will parse out the first word of the declared type, + i. e. for "integer primary key", it will parse out "integer", or for + "number(10)" it will parse out "number". Then for that column, it will look + into the converters dictionary and use the converter function registered for + that type there. .. data:: PARSE_COLNAMES @@ -654,10 +655,6 @@ and constructs a :class:`Point` object from it. Converter functions **always** get called with a string, no matter under which data type you sent the value to SQLite. -.. note:: - - Converter names are looked up in a case-sensitive manner. - :: def convert_point(s): diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 25aa008..b08b4ef 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -216,7 +216,7 @@ Instances of the :class:`Popen` class have the following methods: .. method:: Popen.terminate() Stop the child. On Posix OSs the method sends SIGTERM to the - child. On Windows the Win32 API function TerminateProcess is called + child. On Windows the Win32 API function :cfunc:`TerminateProcess` is called to stop the child. diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 9963dbd..f66899c 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -379,17 +379,17 @@ always available. *platform* may be one of the following values: - +-----------------------------------------+-----------------------+ - | Constant | Platform | - +=========================================+=======================+ - | :const:`0 (VER_PLATFORM_WIN32s)` | Win32s on Windows 3.1 | - +-----------------------------------------+-----------------------+ - | :const:`1 (VER_PLATFORM_WIN32_WINDOWS)` | Windows 95/98/ME | - +-----------------------------------------+-----------------------+ - | :const:`2 (VER_PLATFORM_WIN32_NT)` | Windows NT/2000/XP | - +-----------------------------------------+-----------------------+ - | :const:`3 (VER_PLATFORM_WIN32_CE)` | Windows CE | - +-----------------------------------------+-----------------------+ + +-----------------------------------------+-------------------------+ + | Constant | Platform | + +=========================================+=========================+ + | :const:`0 (VER_PLATFORM_WIN32s)` | Win32s on Windows 3.1 | + +-----------------------------------------+-------------------------+ + | :const:`1 (VER_PLATFORM_WIN32_WINDOWS)` | Windows 95/98/ME | + +-----------------------------------------+-------------------------+ + | :const:`2 (VER_PLATFORM_WIN32_NT)` | Windows NT/2000/XP/x64 | + +-----------------------------------------+-------------------------+ + | :const:`3 (VER_PLATFORM_WIN32_CE)` | Windows CE | + +-----------------------------------------+-------------------------+ This function wraps the Win32 :cfunc:`GetVersionEx` function; see the Microsoft documentation for more information about these fields. diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst index cc3318f..4de9236 100644 --- a/Doc/library/tempfile.rst +++ b/Doc/library/tempfile.rst @@ -23,147 +23,155 @@ insecure :func:`mktemp` function. Temporary file names created by this module no longer contain the process ID; instead a string of six random characters is used. -Also, all the user-callable functions now take additional arguments which allow -direct control over the location and name of temporary files. It is no longer -necessary to use the global *tempdir* and *template* variables. To maintain -backward compatibility, the argument order is somewhat odd; it is recommended to -use keyword arguments for clarity. +Also, all the user-callable functions now take additional arguments which +allow direct control over the location and name of temporary files. It is +no longer necessary to use the global *tempdir* and *template* variables. +To maintain backward compatibility, the argument order is somewhat odd; it +is recommended to use keyword arguments for clarity. The module defines the following user-callable functions: -.. function:: TemporaryFile([mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir]]]]]) +.. function:: TemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]]) - Return a file-like object that can be used as a temporary storage - area. The file is created using :func:`mkstemp`. It will be destroyed as soon + Return a file-like object that can be used as a temporary storage area. + The file is created using :func:`mkstemp`. It will be destroyed as soon as it is closed (including an implicit close when the object is garbage - collected). Under Unix, the directory entry for the file is removed immediately - after the file is created. Other platforms do not support this; your code - should not rely on a temporary file created using this function having or not - having a visible name in the file system. + collected). Under Unix, the directory entry for the file is removed + immediately after the file is created. Other platforms do not support + this; your code should not rely on a temporary file created using this + function having or not having a visible name in the file system. - The *mode* parameter defaults to ``'w+b'`` so that the file created can be read - and written without being closed. Binary mode is used so that it behaves - consistently on all platforms without regard for the data that is stored. - *bufsize* defaults to ``-1``, meaning that the operating system default is used. + The *mode* parameter defaults to ``'w+b'`` so that the file created can + be read and written without being closed. Binary mode is used so that it + behaves consistently on all platforms without regard for the data that is + stored. *bufsize* defaults to ``-1``, meaning that the operating system + default is used. The *dir*, *prefix* and *suffix* parameters are passed to :func:`mkstemp`. The returned object is a true file object on POSIX platforms. On other platforms, it is a file-like object whose :attr:`file` attribute is the - underlying true file object. This file-like object can be used in a :keyword:`with` - statement, just like a normal file. + underlying true file object. This file-like object can be used in a + :keyword:`with` statement, just like a normal file. -.. function:: NamedTemporaryFile([mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir[, delete]]]]]]) +.. function:: NamedTemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None[, delete=True]]]]]]) - This function operates exactly as :func:`TemporaryFile` does, except that the - file is guaranteed to have a visible name in the file system (on Unix, the - directory entry is not unlinked). That name can be retrieved from the - :attr:`name` member of the file object. Whether the name can be used to open - the file a second time, while the named temporary file is still open, varies - across platforms (it can be so used on Unix; it cannot on Windows NT or later). - If *delete* is true (the default), the file is deleted as soon as it is closed. - The returned object is always a file-like object whose :attr:`file` attribute - is the underlying true file object. This file-like object can be used in a :keyword:`with` - statement, just like a normal file. + This function operates exactly as :func:`TemporaryFile` does, except that + the file is guaranteed to have a visible name in the file system (on + Unix, the directory entry is not unlinked). That name can be retrieved + from the :attr:`name` member of the file object. Whether the name can be + used to open the file a second time, while the named temporary file is + still open, varies across platforms (it can be so used on Unix; it cannot + on Windows NT or later). If *delete* is true (the default), the file is + deleted as soon as it is closed. + The returned object is always a file-like object whose :attr:`file` + attribute is the underlying true file object. This file-like object can + be used in a :keyword:`with` statement, just like a normal file. -.. function:: SpooledTemporaryFile([max_size=0, [mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir]]]]]]) +.. function:: SpooledTemporaryFile([max_size=0, [mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]]]) - This function operates exactly as :func:`TemporaryFile` does, except that data - is spooled in memory until the file size exceeds *max_size*, or until the file's - :func:`fileno` method is called, at which point the contents are written to disk - and operation proceeds as with :func:`TemporaryFile`. + This function operates exactly as :func:`TemporaryFile` does, except that + data is spooled in memory until the file size exceeds *max_size*, or + until the file's :func:`fileno` method is called, at which point the + contents are written to disk and operation proceeds as with + :func:`TemporaryFile`. - The resulting file has one additional method, :func:`rollover`, which causes the - file to roll over to an on-disk file regardless of its size. + The resulting file has one additional method, :func:`rollover`, which + causes the file to roll over to an on-disk file regardless of its size. The returned object is a file-like object whose :attr:`_file` attribute is either a :class:`StringIO` object or a true file object, depending on - whether :func:`rollover` has been called. This file-like object can be used in a - :keyword:`with` statement, just like a normal file. + whether :func:`rollover` has been called. This file-like object can be + used in a :keyword:`with` statement, just like a normal file. -.. function:: mkstemp([suffix[, prefix[, dir[, text]]]]) +.. function:: mkstemp([suffix=''[, prefix='tmp'[, dir=None[, text=False]]]]) - Creates a temporary file in the most secure manner possible. There are no - race conditions in the file's creation, assuming that the platform properly - implements the :const:`os.O_EXCL` flag for :func:`os.open`. The file is - readable and writable only by the creating user ID. If the platform uses - permission bits to indicate whether a file is executable, the file is - executable by no one. The file descriptor is not inherited by child - processes. + Creates a temporary file in the most secure manner possible. There are + no race conditions in the file's creation, assuming that the platform + properly implements the :const:`os.O_EXCL` flag for :func:`os.open`. The + file is readable and writable only by the creating user ID. If the + platform uses permission bits to indicate whether a file is executable, + the file is executable by no one. The file descriptor is not inherited + by child processes. - Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible for - deleting the temporary file when done with it. + Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible + for deleting the temporary file when done with it. - If *suffix* is specified, the file name will end with that suffix, otherwise - there will be no suffix. :func:`mkstemp` does not put a dot between the file - name and the suffix; if you need one, put it at the beginning of *suffix*. + If *suffix* is specified, the file name will end with that suffix, + otherwise there will be no suffix. :func:`mkstemp` does not put a dot + between the file name and the suffix; if you need one, put it at the + beginning of *suffix*. - If *prefix* is specified, the file name will begin with that prefix; otherwise, - a default prefix is used. + If *prefix* is specified, the file name will begin with that prefix; + otherwise, a default prefix is used. - If *dir* is specified, the file will be created in that directory; otherwise, - a default directory is used. The default directory is chosen from a - platform-dependent list, but the user of the application can control the - directory location by setting the *TMPDIR*, *TEMP* or *TMP* environment - variables. There is thus no guarantee that the generated filename will have - any nice properties, such as not requiring quoting when passed to external - commands via ``os.popen()``. + If *dir* is specified, the file will be created in that directory; + otherwise, a default directory is used. The default directory is chosen + from a platform-dependent list, but the user of the application can + control the directory location by setting the *TMPDIR*, *TEMP* or *TMP* + environment variables. There is thus no guarantee that the generated + filename will have any nice properties, such as not requiring quoting + when passed to external commands via ``os.popen()``. - If *text* is specified, it indicates whether to open the file in binary mode - (the default) or text mode. On some platforms, this makes no difference. + If *text* is specified, it indicates whether to open the file in binary + mode (the default) or text mode. On some platforms, this makes no + difference. - :func:`mkstemp` returns a tuple containing an OS-level handle to an open file - (as would be returned by :func:`os.open`) and the absolute pathname of that - file, in that order. + :func:`mkstemp` returns a tuple containing an OS-level handle to an open + file (as would be returned by :func:`os.open`) and the absolute pathname + of that file, in that order. -.. function:: mkdtemp([suffix[, prefix[, dir]]]) +.. function:: mkdtemp([suffix=''[, prefix='tmp'[, dir=None]]]) - Creates a temporary directory in the most secure manner possible. There are no - race conditions in the directory's creation. The directory is readable, - writable, and searchable only by the creating user ID. + Creates a temporary directory in the most secure manner possible. There + are no race conditions in the directory's creation. The directory is + readable, writable, and searchable only by the creating user ID. - The user of :func:`mkdtemp` is responsible for deleting the temporary directory - and its contents when done with it. + The user of :func:`mkdtemp` is responsible for deleting the temporary + directory and its contents when done with it. - The *prefix*, *suffix*, and *dir* arguments are the same as for :func:`mkstemp`. + The *prefix*, *suffix*, and *dir* arguments are the same as for + :func:`mkstemp`. :func:`mkdtemp` returns the absolute pathname of the new directory. -.. function:: mktemp([suffix[, prefix[, dir]]]) +.. function:: mktemp([suffix=''[, prefix='tmp'[, dir=None]]]) .. deprecated:: 2.3 Use :func:`mkstemp` instead. - Return an absolute pathname of a file that did not exist at the time the call is - made. The *prefix*, *suffix*, and *dir* arguments are the same as for - :func:`mkstemp`. + Return an absolute pathname of a file that did not exist at the time the + call is made. The *prefix*, *suffix*, and *dir* arguments are the same + as for :func:`mkstemp`. .. warning:: - Use of this function may introduce a security hole in your program. By the time - you get around to doing anything with the file name it returns, someone else may - have beaten you to the punch. + Use of this function may introduce a security hole in your program. + By the time you get around to doing anything with the file name it + returns, someone else may have beaten you to the punch. -The module uses two global variables that tell it how to construct a temporary -name. They are initialized at the first call to any of the functions above. -The caller may change them, but this is discouraged; use the appropriate -function arguments, instead. +The module uses two global variables that tell it how to construct a +temporary name. They are initialized at the first call to any of the +functions above. The caller may change them, but this is discouraged; use +the appropriate function arguments, instead. .. data:: tempdir - When set to a value other than ``None``, this variable defines the default value - for the *dir* argument to all the functions defined in this module. + When set to a value other than ``None``, this variable defines the + default value for the *dir* argument to all the functions defined in this + module. - If ``tempdir`` is unset or ``None`` at any call to any of the above functions, - Python searches a standard list of directories and sets *tempdir* to the first - one which the calling user can create files in. The list is: + If ``tempdir`` is unset or ``None`` at any call to any of the above + functions, Python searches a standard list of directories and sets + *tempdir* to the first one which the calling user can create files in. + The list is: #. The directory named by the :envvar:`TMPDIR` environment variable. diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 8188e70..5efcc32 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -260,7 +260,6 @@ Such a working environment for the testing code is called a :dfn:`fixture`. Often, many small test cases will use the same fixture. In this case, we would end up subclassing :class:`SimpleWidgetTestCase` into many small one-method classes such as :class:`DefaultWidgetSizeTestCase`. This is time-consuming and - discouraging, so in the same vein as JUnit, :mod:`unittest` provides a simpler mechanism:: diff --git a/Doc/library/xmlrpclib.rst b/Doc/library/xmlrpclib.rst index 3f0bf3b..dd6a0cc 100644 --- a/Doc/library/xmlrpclib.rst +++ b/Doc/library/xmlrpclib.rst @@ -111,6 +111,14 @@ between conformable Python objects and XML on the wire. `XML-RPC Introspection <http://xmlrpc-c.sourceforge.net/introspection.html>`_ Describes the XML-RPC protocol extension for introspection. + `XML-RPC Specification <http://www.xmlrpc.com/spec>`_ + The official specification. + + `Unofficial XML-RPC Errata <http://effbot.org/zone/xmlrpc-errata.htm>`_ + Fredrik Lundh's "unofficial errata, intended to clarify certain + details in the XML-RPC specification, as well as hint at + 'best practices' to use when designing your own XML-RPC + implementations." .. _serverproxy-objects: @@ -280,6 +288,11 @@ internal use by the marshalling/unmarshalling code: Write the XML-RPC base 64 encoding of this binary item to the out stream object. + The encoded data will have newlines every 76 characters as per + `RFC 2045 section 6.8 <http://tools.ietf.org/html/rfc2045#section-6.8>`_, + which was the de facto standard base64 specification when the + XML-RPC spec was written. + It also supports certain of Python's built-in operators through a :meth:`__cmp__` method. |