diff options
Diffstat (limited to 'Doc/library')
44 files changed, 524 insertions, 457 deletions
diff --git a/Doc/library/_ast.rst b/Doc/library/_ast.rst index d3cdfb99f5..9f56156275 100644 --- a/Doc/library/_ast.rst +++ b/Doc/library/_ast.rst @@ -12,7 +12,7 @@ Abstract Syntax Trees The ``_ast`` module helps Python applications to process trees of the Python abstract syntax grammar. The Python compiler currently provides read-only access to such trees, meaning that applications can only create a tree for a given -piece of Python source code; generating byte code from a (potentially modified) +piece of Python source code; generating :term:`bytecode` from a (potentially modified) tree is not supported. The abstract syntax itself might change with each Python release; this module helps to find out programmatically what the current grammar looks like. diff --git a/Doc/library/asynchat.rst b/Doc/library/asynchat.rst index b651c40399..8e9437d226 100644 --- a/Doc/library/asynchat.rst +++ b/Doc/library/asynchat.rst @@ -9,72 +9,90 @@ This module builds on the :mod:`asyncore` infrastructure, simplifying -asynchronous clients and servers and making it easier to handle protocols whose -elements are terminated by arbitrary strings, or are of variable length. +asynchronous clients and servers and making it easier to handle protocols +whose elements are terminated by arbitrary strings, or are of variable length. :mod:`asynchat` defines the abstract class :class:`async_chat` that you subclass, providing implementations of the :meth:`collect_incoming_data` and :meth:`found_terminator` methods. It uses the same asynchronous loop as -:mod:`asyncore`, and the two types of channel, :class:`asyncore.dispatcher` and -:class:`asynchat.async_chat`, can freely be mixed in the channel map. Typically -an :class:`asyncore.dispatcher` server channel generates new -:class:`asynchat.async_chat` channel objects as it receives incoming connection -requests. +:mod:`asyncore`, and the two types of channel, :class:`asyncore.dispatcher` +and :class:`asynchat.async_chat`, can freely be mixed in the channel map. +Typically an :class:`asyncore.dispatcher` server channel generates new +:class:`asynchat.async_chat` channel objects as it receives incoming +connection requests. .. class:: async_chat() This class is an abstract subclass of :class:`asyncore.dispatcher`. To make practical use of the code you must subclass :class:`async_chat`, providing - meaningful :meth:`collect_incoming_data` and :meth:`found_terminator` methods. + meaningful :meth:`collect_incoming_data` and :meth:`found_terminator` + methods. The :class:`asyncore.dispatcher` methods can be used, although not all make sense in a message/response context. - Like :class:`asyncore.dispatcher`, :class:`async_chat` defines a set of events - that are generated by an analysis of socket conditions after a :cfunc:`select` - call. Once the polling loop has been started the :class:`async_chat` object's - methods are called by the event-processing framework with no action on the part - of the programmer. + Like :class:`asyncore.dispatcher`, :class:`async_chat` defines a set of + events that are generated by an analysis of socket conditions after a + :cfunc:`select` call. Once the polling loop has been started the + :class:`async_chat` object's methods are called by the event-processing + framework with no action on the part of the programmer. - Unlike :class:`asyncore.dispatcher`, :class:`async_chat` allows you to define a - first-in-first-out queue (fifo) of *producers*. A producer need have only one - method, :meth:`more`, which should return data to be transmitted on the channel. + Two class attributes can be modified, to improve performance, or possibly + even to conserve memory. + + + .. data:: ac_in_buffer_size + + The asynchronous input buffer size (default ``4096``). + + + .. data:: ac_out_buffer_size + + The asynchronous output buffer size (default ``4096``). + + Unlike :class:`asyncore.dispatcher`, :class:`async_chat` allows you to + define a first-in-first-out queue (fifo) of *producers*. A producer need + have only one method, :meth:`more`, which should return data to be + transmitted on the channel. The producer indicates exhaustion (*i.e.* that it contains no more data) by having its :meth:`more` method return the empty string. At this point the - :class:`async_chat` object removes the producer from the fifo and starts using - the next producer, if any. When the producer fifo is empty the + :class:`async_chat` object removes the producer from the fifo and starts + using the next producer, if any. When the producer fifo is empty the :meth:`handle_write` method does nothing. You use the channel object's - :meth:`set_terminator` method to describe how to recognize the end of, or an - important breakpoint in, an incoming transmission from the remote endpoint. + :meth:`set_terminator` method to describe how to recognize the end of, or + an important breakpoint in, an incoming transmission from the remote + endpoint. To build a functioning :class:`async_chat` subclass your input methods - :meth:`collect_incoming_data` and :meth:`found_terminator` must handle the data - that the channel receives asynchronously. The methods are described below. + :meth:`collect_incoming_data` and :meth:`found_terminator` must handle the + data that the channel receives asynchronously. The methods are described + below. .. method:: async_chat.close_when_done() - Pushes a ``None`` on to the producer fifo. When this producer is popped off the - fifo it causes the channel to be closed. + Pushes a ``None`` on to the producer fifo. When this producer is popped off + the fifo it causes the channel to be closed. .. method:: async_chat.collect_incoming_data(data) - Called with *data* holding an arbitrary amount of received data. The default - method, which must be overridden, raises a :exc:`NotImplementedError` exception. + Called with *data* holding an arbitrary amount of received data. The + default method, which must be overridden, raises a + :exc:`NotImplementedError` exception. .. method:: async_chat.discard_buffers() - In emergencies this method will discard any data held in the input and/or output - buffers and the producer fifo. + In emergencies this method will discard any data held in the input and/or + output buffers and the producer fifo. .. method:: async_chat.found_terminator() - Called when the incoming data stream matches the termination condition set by - :meth:`set_terminator`. The default method, which must be overridden, raises a - :exc:`NotImplementedError` exception. The buffered input data should be - available via an instance attribute. + Called when the incoming data stream matches the termination condition set + by :meth:`set_terminator`. The default method, which must be overridden, + raises a :exc:`NotImplementedError` exception. The buffered input data + should be available via an instance attribute. .. method:: async_chat.get_terminator() @@ -90,59 +108,59 @@ requests. .. method:: async_chat.handle_read() - Called when a read event fires on the channel's socket in the asynchronous loop. - The default method checks for the termination condition established by - :meth:`set_terminator`, which can be either the appearance of a particular - string in the input stream or the receipt of a particular number of characters. - When the terminator is found, :meth:`handle_read` calls the - :meth:`found_terminator` method after calling :meth:`collect_incoming_data` with - any data preceding the terminating condition. + Called when a read event fires on the channel's socket in the asynchronous + loop. The default method checks for the termination condition established + by :meth:`set_terminator`, which can be either the appearance of a + particular string in the input stream or the receipt of a particular number + of characters. When the terminator is found, :meth:`handle_read` calls the + :meth:`found_terminator` method after calling :meth:`collect_incoming_data` + with any data preceding the terminating condition. .. method:: async_chat.handle_write() - Called when the application may write data to the channel. The default method - calls the :meth:`initiate_send` method, which in turn will call - :meth:`refill_buffer` to collect data from the producer fifo associated with the - channel. + Called when the application may write data to the channel. The default + method calls the :meth:`initiate_send` method, which in turn will call + :meth:`refill_buffer` to collect data from the producer fifo associated + with the channel. .. method:: async_chat.push(data) - Creates a :class:`simple_producer` object (*see below*) containing the data and - pushes it on to the channel's ``producer_fifo`` to ensure its transmission. This - is all you need to do to have the channel write the data out to the network, - although it is possible to use your own producers in more complex schemes to - implement encryption and chunking, for example. + Creates a :class:`simple_producer` object (*see below*) containing the data + and pushes it on to the channel's ``producer_fifo`` to ensure its + transmission. This is all you need to do to have the channel write the + data out to the network, although it is possible to use your own producers + in more complex schemes to implement encryption and chunking, for example. .. method:: async_chat.push_with_producer(producer) - Takes a producer object and adds it to the producer fifo associated with the - channel. When all currently-pushed producers have been exhausted the channel - will consume this producer's data by calling its :meth:`more` method and send - the data to the remote endpoint. + Takes a producer object and adds it to the producer fifo associated with + the channel. When all currently-pushed producers have been exhausted the + channel will consume this producer's data by calling its :meth:`more` + method and send the data to the remote endpoint. .. method:: async_chat.readable() - Should return ``True`` for the channel to be included in the set of channels - tested by the :cfunc:`select` loop for readability. + Should return ``True`` for the channel to be included in the set of + channels tested by the :cfunc:`select` loop for readability. .. method:: async_chat.refill_buffer() - Refills the output buffer by calling the :meth:`more` method of the producer at - the head of the fifo. If it is exhausted then the producer is popped off the - fifo and the next producer is activated. If the current producer is, or becomes, - ``None`` then the channel is closed. + Refills the output buffer by calling the :meth:`more` method of the + producer at the head of the fifo. If it is exhausted then the producer is + popped off the fifo and the next producer is activated. If the current + producer is, or becomes, ``None`` then the channel is closed. .. method:: async_chat.set_terminator(term) - Sets the terminating condition to be recognised on the channel. ``term`` may be - any of three types of value, corresponding to three different ways to handle - incoming protocol data. + Sets the terminating condition to be recognized on the channel. ``term`` + may be any of three types of value, corresponding to three different ways + to handle incoming protocol data. +-----------+---------------------------------------------+ | term | Description | @@ -158,8 +176,8 @@ requests. | | forever | +-----------+---------------------------------------------+ - Note that any data following the terminator will be available for reading by the - channel after :meth:`found_terminator` is called. + Note that any data following the terminator will be available for reading + by the channel after :meth:`found_terminator` is called. .. method:: async_chat.writable() @@ -174,29 +192,29 @@ asynchat - Auxiliary Classes and Functions .. class:: simple_producer(data[, buffer_size=512]) - A :class:`simple_producer` takes a chunk of data and an optional buffer size. - Repeated calls to its :meth:`more` method yield successive chunks of the data no - larger than *buffer_size*. + A :class:`simple_producer` takes a chunk of data and an optional buffer + size. Repeated calls to its :meth:`more` method yield successive chunks of + the data no larger than *buffer_size*. .. method:: simple_producer.more() - Produces the next chunk of information from the producer, or returns the empty - string. + Produces the next chunk of information from the producer, or returns the + empty string. .. class:: fifo([list=None]) - Each channel maintains a :class:`fifo` holding data which has been pushed by the - application but not yet popped for writing to the channel. A :class:`fifo` is a - list used to hold data and/or producers until they are required. If the *list* - argument is provided then it should contain producers or data items to be - written to the channel. + Each channel maintains a :class:`fifo` holding data which has been pushed + by the application but not yet popped for writing to the channel. A + :class:`fifo` is a list used to hold data and/or producers until they are + required. If the *list* argument is provided then it should contain + producers or data items to be written to the channel. .. method:: fifo.is_empty() - Returns ``True`` iff the fifo is empty. + Returns ``True`` if and only if the fifo is empty. .. method:: fifo.first() @@ -206,14 +224,14 @@ asynchat - Auxiliary Classes and Functions .. method:: fifo.push(data) - Adds the given data (which may be a string or a producer object) to the producer - fifo. + Adds the given data (which may be a string or a producer object) to the + producer fifo. .. method:: fifo.pop() - If the fifo is not empty, returns ``True, first()``, deleting the popped item. - Returns ``False, None`` for an empty fifo. + If the fifo is not empty, returns ``True, first()``, deleting the popped + item. Returns ``False, None`` for an empty fifo. The :mod:`asynchat` module also defines one utility function, which may be of use in network and textual analysis operations. @@ -221,8 +239,8 @@ use in network and textual analysis operations. .. function:: find_prefix_at_end(haystack, needle) - Returns ``True`` if string *haystack* ends with any non-empty prefix of string - *needle*. + Returns ``True`` if string *haystack* ends with any non-empty prefix of + string *needle*. .. _asynchat-example: @@ -231,19 +249,20 @@ asynchat Example ---------------- The following partial example shows how HTTP requests can be read with -:class:`async_chat`. A web server might create an :class:`http_request_handler` -object for each incoming client connection. Notice that initially the channel -terminator is set to match the blank line at the end of the HTTP headers, and a -flag indicates that the headers are being read. +:class:`async_chat`. A web server might create an +:class:`http_request_handler` object for each incoming client connection. +Notice that initially the channel terminator is set to match the blank line at +the end of the HTTP headers, and a flag indicates that the headers are being +read. -Once the headers have been read, if the request is of type POST (indicating that -further data are present in the input stream) then the ``Content-Length:`` -header is used to set a numeric terminator to read the right amount of data from -the channel. +Once the headers have been read, if the request is of type POST (indicating +that further data are present in the input stream) then the +``Content-Length:`` header is used to set a numeric terminator to read the +right amount of data from the channel. The :meth:`handle_request` method is called once all relevant input has been -marshalled, after setting the channel terminator to ``None`` to ensure that any -extraneous data sent by the web client are ignored. :: +marshalled, after setting the channel terminator to ``None`` to ensure that +any extraneous data sent by the web client are ignored. :: class http_request_handler(asynchat.async_chat): @@ -281,4 +300,3 @@ extraneous data sent by the web client are ignored. :: self.handling = True self.ibuffer = [] self.handle_request() - diff --git a/Doc/library/asyncore.rst b/Doc/library/asyncore.rst index db98195506..2ed3c9254a 100644 --- a/Doc/library/asyncore.rst +++ b/Doc/library/asyncore.rst @@ -3,7 +3,8 @@ =============================================== .. module:: asyncore - :synopsis: A base class for developing asynchronous socket handling services. + :synopsis: A base class for developing asynchronous socket handling + services. .. moduleauthor:: Sam Rushing <rushing@nightmare.com> .. sectionauthor:: Christopher Petrilli <petrilli@amber.org> .. sectionauthor:: Steve Holden <sholden@holdenweb.com> @@ -16,76 +17,67 @@ service clients and servers. There are only two ways to have a program on a single processor do "more than one thing at a time." Multi-threaded programming is the simplest and most -popular way to do it, but there is another very different technique, that lets +popular way to do it, but there is another very different technique, that lets you have nearly all the advantages of multi-threading, without actually using multiple threads. It's really only practical if your program is largely I/O -bound. If your program is processor bound, then pre-emptive scheduled threads -are probably what you really need. Network servers are rarely processor bound, -however. +bound. If your program is processor bound, then pre-emptive scheduled threads +are probably what you really need. Network servers are rarely processor +bound, however. If your operating system supports the :cfunc:`select` system call in its I/O library (and nearly all do), then you can use it to juggle multiple -communication channels at once; doing other work while your I/O is taking place -in the "background." Although this strategy can seem strange and complex, -especially at first, it is in many ways easier to understand and control than -multi-threaded programming. The :mod:`asyncore` module solves many of the -difficult problems for you, making the task of building sophisticated -high-performance network servers and clients a snap. For "conversational" -applications and protocols the companion :mod:`asynchat` module is invaluable. - -The basic idea behind both modules is to create one or more network *channels*, -instances of class :class:`asyncore.dispatcher` and -:class:`asynchat.async_chat`. Creating the channels adds them to a global map, -used by the :func:`loop` function if you do not provide it with your own *map*. +communication channels at once; doing other work while your I/O is taking +place in the "background." Although this strategy can seem strange and +complex, especially at first, it is in many ways easier to understand and +control than multi-threaded programming. The :mod:`asyncore` module solves +many of the difficult problems for you, making the task of building +sophisticated high-performance network servers and clients a snap. For +"conversational" applications and protocols the companion :mod:`asynchat` +module is invaluable. + +The basic idea behind both modules is to create one or more network +*channels*, instances of class :class:`asyncore.dispatcher` and +:class:`asynchat.async_chat`. Creating the channels adds them to a global +map, used by the :func:`loop` function if you do not provide it with your own +*map*. Once the initial channel(s) is(are) created, calling the :func:`loop` function -activates channel service, which continues until the last channel (including any -that have been added to the map during asynchronous service) is closed. +activates channel service, which continues until the last channel (including +any that have been added to the map during asynchronous service) is closed. .. function:: loop([timeout[, use_poll[, map[,count]]]]) - Enter a polling loop that terminates after count passes or all open channels - have been closed. All arguments are optional. The *count* parameter defaults - to None, resulting in the loop terminating only when all channels have been - closed. The *timeout* argument sets the timeout parameter for the appropriate - :func:`select` or :func:`poll` call, measured in seconds; the default is 30 - seconds. The *use_poll* parameter, if true, indicates that :func:`poll` should - be used in preference to :func:`select` (the default is ``False``). + Enter a polling loop that terminates after count passes or all open + channels have been closed. All arguments are optional. The *count* + parameter defaults to None, resulting in the loop terminating only when all + channels have been closed. The *timeout* argument sets the timeout + parameter for the appropriate :func:`select` or :func:`poll` call, measured + in seconds; the default is 30 seconds. The *use_poll* parameter, if true, + indicates that :func:`poll` should be used in preference to :func:`select` + (the default is ``False``). - The *map* parameter is a dictionary whose items are the channels to watch. As - channels are closed they are deleted from their map. If *map* is omitted, a - global map is used. Channels (instances of :class:`asyncore.dispatcher`, - :class:`asynchat.async_chat` and subclasses thereof) can freely be mixed in the - map. + The *map* parameter is a dictionary whose items are the channels to watch. + As channels are closed they are deleted from their map. If *map* is + omitted, a global map is used. Channels (instances of + :class:`asyncore.dispatcher`, :class:`asynchat.async_chat` and subclasses + thereof) can freely be mixed in the map. .. class:: dispatcher() The :class:`dispatcher` class is a thin wrapper around a low-level socket - object. To make it more useful, it has a few methods for event-handling which - are called from the asynchronous loop. Otherwise, it can be treated as a - normal non-blocking socket object. - - Two class attributes can be modified, to improve performance, or possibly even - to conserve memory. - - - .. data:: ac_in_buffer_size - - The asynchronous input buffer size (default ``4096``). - - - .. data:: ac_out_buffer_size - - The asynchronous output buffer size (default ``4096``). - - The firing of low-level events at certain times or in certain connection states - tells the asynchronous loop that certain higher-level events have taken place. - For example, if we have asked for a socket to connect to another host, we know - that the connection has been made when the socket becomes writable for the first - time (at this point you know that you may write to it with the expectation of - success). The implied higher-level events are: + object. To make it more useful, it has a few methods for event-handling + which are called from the asynchronous loop. Otherwise, it can be treated + as a normal non-blocking socket object. + + The firing of low-level events at certain times or in certain connection + states tells the asynchronous loop that certain higher-level events have + taken place. For example, if we have asked for a socket to connect to + another host, we know that the connection has been made when the socket + becomes writable for the first time (at this point you know that you may + write to it with the expectation of success). The implied higher-level + events are: +----------------------+----------------------------------------+ | Event | Description | @@ -101,11 +93,11 @@ that have been added to the map during asynchronous service) is closed. During asynchronous processing, each mapped channel's :meth:`readable` and :meth:`writable` methods are used to determine whether the channel's socket - should be added to the list of channels :cfunc:`select`\ ed or :cfunc:`poll`\ ed - for read and write events. + should be added to the list of channels :cfunc:`select`\ ed or + :cfunc:`poll`\ ed for read and write events. -Thus, the set of channel events is larger than the basic socket events. The full -set of methods that can be overridden in your subclass follows: +Thus, the set of channel events is larger than the basic socket events. The +full set of methods that can be overridden in your subclass follows: .. method:: dispatcher.handle_read() @@ -116,9 +108,9 @@ set of methods that can be overridden in your subclass follows: .. method:: dispatcher.handle_write() - Called when the asynchronous loop detects that a writable socket can be written. - Often this method will implement the necessary buffering for performance. For - example:: + Called when the asynchronous loop detects that a writable socket can be + written. Often this method will implement the necessary buffering for + performance. For example:: def handle_write(self): sent = self.send(self.buffer) @@ -127,15 +119,15 @@ set of methods that can be overridden in your subclass follows: .. method:: dispatcher.handle_expt() - Called when there is out of band (OOB) data for a socket connection. This will - almost never happen, as OOB is tenuously supported and rarely used. + Called when there is out of band (OOB) data for a socket connection. This + will almost never happen, as OOB is tenuously supported and rarely used. .. method:: dispatcher.handle_connect() - Called when the active opener's socket actually makes a connection. Might send a - "welcome" banner, or initiate a protocol negotiation with the remote endpoint, - for example. + Called when the active opener's socket actually makes a connection. Might + send a "welcome" banner, or initiate a protocol negotiation with the remote + endpoint, for example. .. method:: dispatcher.handle_close() @@ -152,40 +144,40 @@ set of methods that can be overridden in your subclass follows: .. method:: dispatcher.handle_accept() Called on listening channels (passive openers) when a connection can be - established with a new remote endpoint that has issued a :meth:`connect` call - for the local endpoint. + established with a new remote endpoint that has issued a :meth:`connect` + call for the local endpoint. .. method:: dispatcher.readable() - Called each time around the asynchronous loop to determine whether a channel's - socket should be added to the list on which read events can occur. The default - method simply returns ``True``, indicating that by default, all channels will - be interested in read events. + Called each time around the asynchronous loop to determine whether a + channel's socket should be added to the list on which read events can + occur. The default method simply returns ``True``, indicating that by + default, all channels will be interested in read events. .. method:: dispatcher.writable() - Called each time around the asynchronous loop to determine whether a channel's - socket should be added to the list on which write events can occur. The default - method simply returns ``True``, indicating that by default, all channels will - be interested in write events. + Called each time around the asynchronous loop to determine whether a + channel's socket should be added to the list on which write events can + occur. The default method simply returns ``True``, indicating that by + default, all channels will be interested in write events. -In addition, each channel delegates or extends many of the socket methods. Most -of these are nearly identical to their socket partners. +In addition, each channel delegates or extends many of the socket methods. +Most of these are nearly identical to their socket partners. .. method:: dispatcher.create_socket(family, type) - This is identical to the creation of a normal socket, and will use the same - options for creation. Refer to the :mod:`socket` documentation for information - on creating sockets. + This is identical to the creation of a normal socket, and will use the same + options for creation. Refer to the :mod:`socket` documentation for + information on creating sockets. .. method:: dispatcher.connect(address) - As with the normal socket object, *address* is a tuple with the first element - the host to connect to, and the second the port number. + As with the normal socket object, *address* is a tuple with the first + element the host to connect to, and the second the port number. .. method:: dispatcher.send(data) @@ -195,38 +187,41 @@ of these are nearly identical to their socket partners. .. method:: dispatcher.recv(buffer_size) - Read at most *buffer_size* bytes from the socket's remote end-point. An empty - string implies that the channel has been closed from the other end. + Read at most *buffer_size* bytes from the socket's remote end-point. + An empty string implies that the channel has been closed from the other + end. .. method:: dispatcher.listen(backlog) - Listen for connections made to the socket. The *backlog* argument specifies the - maximum number of queued connections and should be at least 1; the maximum value - is system-dependent (usually 5). + Listen for connections made to the socket. The *backlog* argument + specifies the maximum number of queued connections and should be at least + 1; the maximum value is system-dependent (usually 5). .. method:: dispatcher.bind(address) Bind the socket to *address*. The socket must not already be bound. (The - format of *address* depends on the address family --- see above.) To mark the - socket as re-usable (setting the :const:`SO_REUSEADDR` option), call the - :class:`dispatcher` object's :meth:`set_reuse_addr` method. + format of *address* depends on the address family --- see above.) To mark + the socket as re-usable (setting the :const:`SO_REUSEADDR` option), call + the :class:`dispatcher` object's :meth:`set_reuse_addr` method. .. method:: dispatcher.accept() - Accept a connection. The socket must be bound to an address and listening for - connections. The return value is a pair ``(conn, address)`` where *conn* is a - *new* socket object usable to send and receive data on the connection, and - *address* is the address bound to the socket on the other end of the connection. + Accept a connection. The socket must be bound to an address and listening + for connections. The return value is a pair ``(conn, address)`` where + *conn* is a *new* socket object usable to send and receive data on the + connection, and *address* is the address bound to the socket on the other + end of the connection. .. method:: dispatcher.close() - Close the socket. All future operations on the socket object will fail. The - remote end-point will receive no more data (after queued data is flushed). - Sockets are automatically closed when they are garbage-collected. + Close the socket. All future operations on the socket object will fail. + The remote end-point will receive no more data (after queued data is + flushed). Sockets are automatically closed when they are + garbage-collected. .. _asyncore-example: @@ -266,4 +261,3 @@ implement its socket handling:: c = http_client('www.python.org', '/') asyncore.loop() - diff --git a/Doc/library/autogil.rst b/Doc/library/autogil.rst index 93f0d0460b..7625be65a6 100644 --- a/Doc/library/autogil.rst +++ b/Doc/library/autogil.rst @@ -9,8 +9,8 @@ The :mod:`autoGIL` module provides a function :func:`installAutoGIL` that -automatically locks and unlocks Python's Global Interpreter Lock when running an -event loop. +automatically locks and unlocks Python's :term:`Global Interpreter Lock` when +running an event loop. .. exception:: AutoGILError diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index 238c80ea7a..72d6734306 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -238,15 +238,15 @@ utility functions: .. function:: iterencode(iterable, encoding[, errors]) Uses an incremental encoder to iteratively encode the input provided by - *iterable*. This function is a generator. *errors* (as well as any other keyword - argument) is passed through to the incremental encoder. + *iterable*. This function is a :term:`generator`. *errors* (as well as any + other keyword argument) is passed through to the incremental encoder. .. function:: iterdecode(iterable, encoding[, errors]) Uses an incremental decoder to iteratively decode the input provided by - *iterable*. This function is a generator. *errors* (as well as any other keyword - argument) is passed through to the incremental decoder. + *iterable*. This function is a :term:`generator`. *errors* (as well as any + other keyword argument) is passed through to the incremental decoder. The module also provides the following constants which are useful for reading and writing to platform dependent files: diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 274ca15054..ba3ce31d1c 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -10,7 +10,7 @@ This module implements high-performance container datatypes. Currently, there are two datatypes, :class:`deque` and :class:`defaultdict`, and -one datatype factory function, :func:`NamedTuple`. Python already +one datatype factory function, :func:`named_tuple`. Python already includes built-in containers, :class:`dict`, :class:`list`, :class:`set`, and :class:`tuple`. In addition, the optional :mod:`bsddb` module has a :meth:`bsddb.btopen` method that can be used to create in-memory @@ -75,7 +75,7 @@ particular functionality, for example:: ---------------------- -.. class:: deque([iterable]) +.. class:: deque([iterable[, maxlen]]) Returns a new deque object initialized left-to-right (using :meth:`append`) with data from *iterable*. If *iterable* is not specified, the new deque is empty. @@ -91,6 +91,17 @@ particular functionality, for example:: position of the underlying data representation. + If *maxlen* is not specified or is *None*, deques may grow to an + arbitrary length. Otherwise, the deque is bounded to the specified maximum + length. Once a bounded length deque is full, when new items are added, a + corresponding number of items are discarded from the opposite end. Bounded + length deques provide functionality similar to the ``tail`` filter in + Unix. They are also useful for tracking transactions and other pools of data + where only the most recent activity is of interest. + + .. versionchanged:: 2.6 + Added *maxlen* + Deque objects support the following methods: .. method:: deque.append(x) @@ -205,8 +216,8 @@ Example:: .. _deque-recipes: -Recipes -^^^^^^^ +:class:`deque` Recipes +^^^^^^^^^^^^^^^^^^^^^^ This section shows various approaches to working with deques. @@ -223,42 +234,14 @@ To implement :class:`deque` slicing, use a similar approach applying :meth:`rotate` to bring a target element to the left side of the deque. Remove old entries with :meth:`popleft`, add new entries with :meth:`extend`, and then reverse the rotation. - With minor variations on that approach, it is easy to implement Forth style stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``, ``rot``, and ``roll``. -A roundrobin task server can be built from a :class:`deque` using -:meth:`popleft` to select the current task and :meth:`append` to add it back to -the tasklist if the input stream is not exhausted:: - - >>> def roundrobin(*iterables): - ... pending = deque(iter(i) for i in iterables) - ... while pending: - ... task = pending.popleft() - ... try: - ... yield next(task) - ... except StopIteration: - ... continue - ... pending.append(task) - ... - >>> for value in roundrobin('abc', 'd', 'efgh'): - ... print(value) - - a - d - e - b - f - c - g - h - - Multi-pass data reduction algorithms can be succinctly expressed and efficiently coded by extracting elements with multiple calls to :meth:`popleft`, applying -the reduction function, and calling :meth:`append` to add the result back to the -queue. +a reduction function, and calling :meth:`append` to add the result back to the +deque. For example, building a balanced binary tree of nested lists entails reducing two adjacent nodes into one by grouping them in a list:: @@ -273,7 +256,12 @@ two adjacent nodes into one by grouping them in a list:: >>> print(maketree('abcdefgh')) [[[['a', 'b'], ['c', 'd']], [['e', 'f'], ['g', 'h']]]] +Bounded length deques provide functionality similar to the ``tail`` filter +in Unix:: + def tail(filename, n=10): + 'Return the last n lines of a file' + return deque(open(filename), n) .. _defaultdict-objects: @@ -395,14 +383,14 @@ Setting the :attr:`default_factory` to :class:`set` makes the .. _named-tuple-factory: -:func:`NamedTuple` Factory Function for Tuples with Named Fields ----------------------------------------------------------------- +:func:`named_tuple` Factory Function for Tuples with Named Fields +----------------------------------------------------------------- Named tuples assign meaning to each position in a tuple and allow for more readable, self-documenting code. They can be used wherever regular tuples are used, and they add the ability to access fields by name instead of position index. -.. function:: NamedTuple(typename, fieldnames, [verbose]) +.. function:: named_tuple(typename, fieldnames, [verbose]) Returns a new tuple subclass named *typename*. The new subclass is used to create tuple-like objects that have fields accessable by attribute lookup as @@ -410,17 +398,24 @@ they add the ability to access fields by name instead of position index. helpful docstring (with typename and fieldnames) and a helpful :meth:`__repr__` method which lists the tuple contents in a ``name=value`` format. - The *fieldnames* are specified in a single string with each fieldname separated by - a space and/or comma. Any valid Python identifier may be used for a fieldname. + The *fieldnames* are a single string with each fieldname separated by whitespace + and/or commas (for example 'x y' or 'x, y'). Alternatively, the *fieldnames* + can be specified as a list of strings (such as ['x', 'y']). + + Any valid Python identifier may be used for a fieldname except for names + starting and ending with double underscores. Valid identifiers consist of + letters, digits, and underscores but do not start with a digit and cannot be + a :mod:`keyword` such as *class*, *for*, *return*, *global*, *pass*, *print*, + or *raise*. If *verbose* is true, will print the class definition. - *NamedTuple* instances do not have per-instance dictionaries, so they are + Named tuple instances do not have per-instance dictionaries, so they are lightweight and require no more memory than regular tuples. Example:: - >>> Point = NamedTuple('Point', 'x y', True) + >>> Point = named_tuple('Point', 'x y', verbose=True) class Point(tuple): 'Point(x, y)' __slots__ = () @@ -429,6 +424,9 @@ Example:: return tuple.__new__(cls, (x, y)) def __repr__(self): return 'Point(x=%r, y=%r)' % self + def __asdict__(self): + 'Return a new dict mapping field names to their values' + return dict(zip(('x', 'y'), self)) def __replace__(self, field, value): 'Return a new Point object replacing one field with a new value' return Point(**dict(zip(('x', 'y'), self) + [(field, value)])) @@ -449,23 +447,46 @@ Example:: Named tuples are especially useful for assigning field names to result tuples returned by the :mod:`csv` or :mod:`sqlite3` modules:: + EmployeeRecord = named_tuple('EmployeeRecord', 'name, age, title, department, paygrade') + from itertools import starmap import csv - EmployeeRecord = NamedTuple('EmployeeRecord', 'name age title department paygrade') for record in starmap(EmployeeRecord, csv.reader(open("employees.csv", "rb"))): print(emp.name, emp.title) -When casting a single record to a *NamedTuple*, use the star-operator [#]_ to unpack + import sqlite3 + conn = sqlite3.connect('/companydata') + cursor = conn.cursor() + cursor.execute('SELECT name, age, title, department, paygrade FROM employees') + for emp in starmap(EmployeeRecord, cursor.fetchall()): + print emp.name, emp.title + +When casting a single record to a named tuple, use the star-operator [#]_ to unpack the values:: >>> t = [11, 22] >>> Point(*t) # the star-operator unpacks any iterable object Point(x=11, y=22) +When casting a dictionary to a named tuple, use the double-star-operator:: + + >>> d = {'x': 11, 'y': 22} + >>> Point(**d) + Point(x=11, y=22) + In addition to the methods inherited from tuples, named tuples support -an additonal method and an informational read-only attribute. +two additonal methods and a read-only attribute. + +.. method:: somenamedtuple.__asdict__() + + Return a new dict which maps field names to their corresponding values: + +:: -.. method:: somenamedtuple.replace(field, value) + >>> p.__asdict__() + {'x': 11, 'y': 22} + +.. method:: somenamedtuple.__replace__(field, value) Return a new instance of the named tuple replacing the named *field* with a new *value*: @@ -480,20 +501,16 @@ an additonal method and an informational read-only attribute. .. attribute:: somenamedtuple.__fields__ - Return a tuple of strings listing the field names. This is useful for introspection, - for converting a named tuple instance to a dictionary, and for combining named tuple - types to create new named tuple types: + Return a tuple of strings listing the field names. This is useful for introspection + and for creating new named tuple types from existing named tuples. :: - >>> p.__fields__ # view the field names + >>> p.__fields__ # view the field names ('x', 'y') - >>> dict(zip(p.__fields__, p)) # convert to a dictionary - {'y': 22, 'x': 11} - >>> Color = NamedTuple('Color', 'red green blue') - >>> pixel_fields = ' '.join(Point.__fields__ + Color.__fields__) # combine fields - >>> Pixel = NamedTuple('Pixel', pixel_fields) + >>> Color = named_tuple('Color', 'red green blue') + >>> Pixel = named_tuple('Pixel', Point.__fields__ + Color.__fields__) >>> Pixel(11, 22, 128, 255, 0) Pixel(x=11, y=22, red=128, green=255, blue=0)' diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index decac44df7..6a4fd3d5af 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -37,9 +37,9 @@ Functions provided: foo </h1> - The function being decorated must return a generator-iterator when called. This - iterator must yield exactly one value, which will be bound to the targets in the - :keyword:`with` statement's :keyword:`as` clause, if any. + The function being decorated must return a :term:`generator`-iterator when + called. This iterator must yield exactly one value, which will be bound to + the targets in the :keyword:`with` statement's :keyword:`as` clause, if any. At the point where the generator yields, the block nested in the :keyword:`with` statement is executed. The generator is then resumed after the block is exited. diff --git a/Doc/library/cookielib.rst b/Doc/library/cookielib.rst index 18f471e50f..bc14051a58 100644 --- a/Doc/library/cookielib.rst +++ b/Doc/library/cookielib.rst @@ -140,7 +140,7 @@ The following classes are provided: CookieJar and FileCookieJar Objects ----------------------------------- -:class:`CookieJar` objects support the iterator protocol for iterating over +:class:`CookieJar` objects support the :term:`iterator` protocol for iterating over contained :class:`Cookie` objects. :class:`CookieJar` has the following methods: diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index 11df7c28bd..598dc502cd 100644 --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -60,7 +60,7 @@ The :mod:`csv` module defines the following functions: .. function:: reader(csvfile[, dialect='excel'][, fmtparam]) Return a reader object which will iterate over lines in the given *csvfile*. - *csvfile* can be any object which supports the iterator protocol and returns a + *csvfile* can be any object which supports the :term:`iterator` protocol and returns a string each time its :meth:`next` method is called --- file objects and list objects are both suitable. If *csvfile* is a file object, it must be opened with the 'b' flag on platforms where that makes a difference. An optional @@ -138,7 +138,7 @@ The :mod:`csv` module defines the following functions: The :mod:`csv` module defines the following classes: -.. class:: DictReader(csvfile[, fieldnames=:const:None,[, restkey=:const:None[, restval=None[, dialect='excel'[, *args, **kwds]]]]]) +.. class:: DictReader(csvfile[, fieldnames=None[, restkey=None[, restval=None[, dialect='excel'[, *args, **kwds]]]]]) Create an object which operates like a regular reader but maps the information read into a dict whose keys are given by the optional *fieldnames* parameter. @@ -436,9 +436,9 @@ it is 8-bit-clean save for some problems with ASCII NUL characters. So you can write functions or classes that handle the encoding and decoding for you as long as you avoid encodings like UTF-16 that use NULs. UTF-8 is recommended. -:func:`unicode_csv_reader` below is a generator that wraps :class:`csv.reader` +:func:`unicode_csv_reader` below is a :term:`generator` that wraps :class:`csv.reader` to handle Unicode CSV data (a list of Unicode strings). :func:`utf_8_encoder` -is a generator that encodes the Unicode strings as UTF-8, one string (or row) at +is a :term:`generator` that encodes the Unicode strings as UTF-8, one string (or row) at a time. The encoded strings are parsed by the CSV reader, and :func:`unicode_csv_reader` decodes the UTF-8-encoded cells back into Unicode:: diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 4b1934d687..7f3f87595f 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -584,8 +584,8 @@ Nested structures can also be initialized in the constructor in several ways:: >>> r = RECT(POINT(1, 2), POINT(3, 4)) >>> r = RECT((1, 2), (3, 4)) -Fields descriptors can be retrieved from the *class*, they are useful for -debugging because they can provide useful information:: +Field :term:`descriptor`\s can be retrieved from the *class*, they are useful +for debugging because they can provide useful information:: >>> print(POINT.x) <Field type=c_long, ofs=0, size=4> @@ -1195,10 +1195,10 @@ Another example that may behave different from what one would expect is this:: >>> Why is it printing ``False``? ctypes instances are objects containing a memory -block plus some descriptors accessing the contents of the memory. Storing a -Python object in the memory block does not store the object itself, instead the -``contents`` of the object is stored. Accessing the contents again constructs a -new Python each time! +block plus some :term:`descriptor`\s accessing the contents of the memory. +Storing a Python object in the memory block does not store the object itself, +instead the ``contents`` of the object is stored. Accessing the contents again +constructs a new Python object each time! .. _ctypes-variable-sized-data-types: @@ -1366,8 +1366,8 @@ way is to instantiate one of the following classes: :class:`WinDLL` and :class:`OleDLL` use the standard calling convention on this platform. -The Python GIL is released before calling any function exported by these -libraries, and reacquired afterwards. +The Python :term:`global interpreter lock` is released before calling any +function exported by these libraries, and reacquired afterwards. .. class:: PyDLL(name, mode=DEFAULT_MODE, handle=None) @@ -1948,7 +1948,7 @@ Data types in case the memory block contains pointers. Common methods of ctypes data types, these are all class methods (to be exact, -they are methods of the metaclass): +they are methods of the :term:`metaclass`): .. method:: _CData.from_address(address) @@ -2263,7 +2263,7 @@ other data types containing pointer type fields. Concrete structure and union types must be created by subclassing one of these types, and at least define a :attr:`_fields_` class variable. ``ctypes`` will -create descriptors which allow reading and writing the fields by direct +create :term:`descriptor`\s which allow reading and writing the fields by direct attribute accesses. These are the diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 1616848250..d4065d717d 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -174,7 +174,7 @@ floating point flying circus:: >>> c % a Decimal("0.77") -And some mathematic functions are also available to Decimal:: +And some mathematical functions are also available to Decimal:: >>> Decimal(2).sqrt() Decimal("1.414213562373095048801688724") diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst index ee973bcb97..d3724ddc77 100644 --- a/Doc/library/difflib.rst +++ b/Doc/library/difflib.rst @@ -10,6 +10,11 @@ .. % LaTeXification by Fred L. Drake, Jr. <fdrake@acm.org>. +This module provides classes and functions for comparing sequences. It +can be used for example, for comparing files, and can produce difference +information in various formats, including HTML and context and unified +diffs. For comparing directories and files, see also, the :mod:`filecmp` module. + .. class:: SequenceMatcher This is a flexible class for comparing pairs of sequences of any type, so long @@ -117,8 +122,8 @@ .. function:: context_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm]) - Compare *a* and *b* (lists of strings); return a delta (a generator generating - the delta lines) in context diff format. + Compare *a* and *b* (lists of strings); return a delta (a :term:`generator` + generating the delta lines) in context diff format. Context diffs are a compact way of showing just the lines that have changed plus a few lines of context. The changes are shown in a before/after style. The @@ -170,8 +175,8 @@ .. function:: ndiff(a, b[, linejunk][, charjunk]) - Compare *a* and *b* (lists of strings); return a :class:`Differ`\ -style delta - (a generator generating the delta lines). + Compare *a* and *b* (lists of strings); return a :class:`Differ`\ -style + delta (a :term:`generator` generating the delta lines). Optional keyword parameters *linejunk* and *charjunk* are for filter functions (or ``None``): @@ -231,8 +236,8 @@ .. function:: unified_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm]) - Compare *a* and *b* (lists of strings); return a delta (a generator generating - the delta lines) in unified diff format. + Compare *a* and *b* (lists of strings); return a delta (a :term:`generator` + generating the delta lines) in unified diff format. Unified diffs are a compact way of showing just the lines that have changed plus a few lines of context. The changes are shown in a inline style (instead of @@ -423,7 +428,7 @@ use :meth:`set_seq2` to set the commonly used sequence once and call .. method:: SequenceMatcher.get_grouped_opcodes([n]) - Return a generator of groups with up to *n* lines of context. + Return a :term:`generator` of groups with up to *n* lines of context. Starting with the groups returned by :meth:`get_opcodes`, this method splits out smaller change clusters and eliminates intervening ranges which have no changes. diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 2a14263302..2616295554 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -1,14 +1,14 @@ -:mod:`dis` --- Disassembler for Python byte code -================================================ +:mod:`dis` --- Disassembler for Python bytecode +=============================================== .. module:: dis - :synopsis: Disassembler for Python byte code. + :synopsis: Disassembler for Python bytecode. -The :mod:`dis` module supports the analysis of Python byte code by disassembling +The :mod:`dis` module supports the analysis of Python :term:`bytecode` by disassembling it. Since there is no Python assembler, this module defines the Python assembly -language. The Python byte code which this module takes as an input is defined +language. The Python bytecode which this module takes as an input is defined in the file :file:`Include/opcode.h` and used by the compiler and the interpreter. @@ -35,7 +35,7 @@ The :mod:`dis` module defines the following functions and constants: Disassemble the *bytesource* object. *bytesource* can denote either a module, a class, a method, a function, or a code object. For a module, it disassembles all functions. For a class, it disassembles all methods. For a single code - sequence, it prints one line per byte code instruction. If no object is + sequence, it prints one line per bytecode instruction. If no object is provided, it disassembles the last traceback. @@ -70,12 +70,12 @@ The :mod:`dis` module defines the following functions and constants: .. data:: opname - Sequence of operation names, indexable using the byte code. + Sequence of operation names, indexable using the bytecode. .. data:: opmap - Dictionary mapping byte codes to operation names. + Dictionary mapping bytecodes to operation names. .. data:: cmp_op @@ -85,45 +85,45 @@ The :mod:`dis` module defines the following functions and constants: .. data:: hasconst - Sequence of byte codes that have a constant parameter. + Sequence of bytecodes that have a constant parameter. .. data:: hasfree - Sequence of byte codes that access a free variable. + Sequence of bytecodes that access a free variable. .. data:: hasname - Sequence of byte codes that access an attribute by name. + Sequence of bytecodes that access an attribute by name. .. data:: hasjrel - Sequence of byte codes that have a relative jump target. + Sequence of bytecodes that have a relative jump target. .. data:: hasjabs - Sequence of byte codes that have an absolute jump target. + Sequence of bytecodes that have an absolute jump target. .. data:: haslocal - Sequence of byte codes that access a local variable. + Sequence of bytecodes that access a local variable. .. data:: hascompare - Sequence of byte codes of Boolean operations. + Sequence of bytecodes of Boolean operations. .. _bytecodes: -Python Byte Code Instructions ------------------------------ +Python Bytecode Instructions +---------------------------- -The Python compiler currently generates the following byte code instructions. +The Python compiler currently generates the following bytecode instructions. .. opcode:: STOP_CODE () @@ -381,7 +381,7 @@ Miscellaneous opcodes. .. opcode:: YIELD_VALUE () - Pops ``TOS`` and yields it from a generator. + Pops ``TOS`` and yields it from a :term:`generator`. .. opcode:: IMPORT_STAR () @@ -416,9 +416,9 @@ Miscellaneous opcodes. context manager's :meth:`__exit__` bound method. Below that are 1--3 values indicating how/why the finally clause was entered: - * SECOND = None - * (SECOND, THIRD) = (WHY_{RETURN,CONTINUE}), retval - * SECOND = WHY_\*; no retval below it + * SECOND = ``None`` + * (SECOND, THIRD) = (``WHY_{RETURN,CONTINUE}``), retval + * SECOND = ``WHY_*``; no retval below it * (SECOND, THIRD, FOURTH) = exc_info() In the last case, ``TOS(SECOND, THIRD, FOURTH)`` is called, otherwise @@ -428,6 +428,8 @@ Miscellaneous opcodes. returns a 'true' value, this information is "zapped", to prevent ``END_FINALLY`` from re-raising the exception. (But non-local gotos should still be resumed.) + .. XXX explain the WHY stuff! + All of the following opcodes expect arguments. An argument is two bytes, with the more significant byte last. @@ -548,32 +550,32 @@ the more significant byte last. .. opcode:: JUMP_FORWARD (delta) - Increments byte code counter by *delta*. + Increments bytecode counter by *delta*. .. opcode:: JUMP_IF_TRUE (delta) - If TOS is true, increment the byte code counter by *delta*. TOS is left on the + If TOS is true, increment the bytecode counter by *delta*. TOS is left on the stack. .. opcode:: JUMP_IF_FALSE (delta) - If TOS is false, increment the byte code counter by *delta*. TOS is not + If TOS is false, increment the bytecode counter by *delta*. TOS is not changed. .. opcode:: JUMP_ABSOLUTE (target) - Set byte code counter to *target*. + Set bytecode counter to *target*. .. opcode:: FOR_ITER (delta) - ``TOS`` is an iterator. Call its :meth:`__next__` method. If this yields a new - value, push it on the stack (leaving the iterator below it). If the iterator - indicates it is exhausted ``TOS`` is popped, and the byte code counter is - incremented by *delta*. + ``TOS`` is an :term:`iterator`. Call its :meth:`__next__` method. If this + yields a new value, push it on the stack (leaving the iterator below it). If + the iterator indicates it is exhausted ``TOS`` is popped, and the byte code + counter is incremented by *delta*. .. % \begin{opcodedesc}{FOR_LOOP}{delta} .. % This opcode is obsolete. diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index c35d7d43ee..34fb429ff4 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -135,7 +135,7 @@ The following exceptions are the exceptions that are actually raised. .. exception:: GeneratorExit - Raise when a generator's :meth:`close` method is called. + Raise when a :term:`generator`\'s :meth:`close` method is called. .. exception:: IOError @@ -241,8 +241,8 @@ The following exceptions are the exceptions that are actually raised. .. exception:: StopIteration - Raised by builtin :func:`next` and an iterator's :meth:`__next__` method to - signal that there are no further values. + Raised by builtin :func:`next` and an :term:`iterator`\'s :meth:`__next__` + method to signal that there are no further values. .. exception:: SyntaxError diff --git a/Doc/library/filecmp.rst b/Doc/library/filecmp.rst index 600421412d..141889e29f 100644 --- a/Doc/library/filecmp.rst +++ b/Doc/library/filecmp.rst @@ -8,7 +8,8 @@ The :mod:`filecmp` module defines functions to compare files and directories, -with various optional time/correctness trade-offs. +with various optional time/correctness trade-offs. For comparing files, +see also the :mod:`difflib` module. The :mod:`filecmp` module defines the following functions: diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index dab83e1b4c..c7e689d953 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -41,7 +41,7 @@ available. They are listed here in alphabetical order. top-level package (the name up till the first dot) is returned, *not* the module named by *name*. However, when a non-empty *fromlist* argument is given, the module named by *name* is returned. This is done for - compatibility with the bytecode generated for the different kinds of import + compatibility with the :term:`bytecode` generated for the different kinds of import statement; when using ``import spam.ham.eggs``, the top-level package :mod:`spam` must be placed in the importing namespace, but when using ``from spam.ham import eggs``, the ``spam.ham`` subpackage must be used to find the @@ -317,7 +317,7 @@ available. They are listed here in alphabetical order. .. function:: enumerate(iterable) - Return an enumerate object. *iterable* must be a sequence, an iterator, or some + Return an enumerate object. *iterable* must be a sequence, an :term:`iterator`, or some other object which supports iteration. The :meth:`__next__` method of the iterator returned by :func:`enumerate` returns a tuple containing a count (from zero) and the corresponding value obtained from iterating over *iterable*. @@ -340,7 +340,7 @@ available. They are listed here in alphabetical order. The *expression* argument is parsed and evaluated as a Python expression (technically speaking, a condition list) using the *globals* and *locals* - dictionaries as global and local name space. If the *globals* dictionary is + dictionaries as global and local namespace. If the *globals* dictionary is present and lacks '__builtins__', the current globals are copied into *globals* before *expression* is parsed. This means that *expression* normally has full access to the standard :mod:`__builtin__` module and restricted environments are @@ -408,10 +408,9 @@ available. They are listed here in alphabetical order. Construct an iterator from those elements of *iterable* for which *function* returns true. *iterable* may be either a sequence, a container which - supports iteration, or an iterator, If *iterable* is a string or a tuple, the - result also has that type; otherwise it is always a list. If *function* is - ``None``, the identity function is assumed, that is, all elements of - *iterable* that are false are removed. + supports iteration, or an iterator. If *function* is ``None``, the identity + function is assumed, that is, all elements of *iterable* that are false are + removed. Note that ``filter(function, iterable)`` is equivalent to the generator expression ``(item for item in iterable if function(item))`` if function is @@ -543,15 +542,15 @@ available. They are listed here in alphabetical order. .. function:: int([x[, radix]]) Convert a string or number to an integer. If the argument is a string, it - must contain a possibly signed number of arbitrary size, - possibly embedded in whitespace. The *radix* parameter gives the base for the - conversion and may be any integer in the range [2, 36], or zero. If *radix* is - zero, the interpretation is the same as for integer literals. If *radix* is - specified and *x* is not a string, :exc:`TypeError` is raised. Otherwise, the - argument may be another integer, a floating point number or any other object - that has an :meth:`__int__` method. Conversion - of floating point numbers to integers truncates (towards zero). If no - arguments are given, returns ``0``. + must contain a possibly signed number of arbitrary size, possibly embedded in + whitespace. The *radix* parameter gives the base for the conversion (which + is 10 by default) and may be any integer in the range [2, 36], or zero. If + *radix* is zero, the interpretation is the same as for integer literals. If + *radix* is specified and *x* is not a string, :exc:`TypeError` is raised. + Otherwise, the argument may be another integer, a floating point number or + any other object that has an :meth:`__int__` method. Conversion of floating + point numbers to integers truncates (towards zero). If no arguments are + given, returns ``0``. The integer type is described in :ref:`typesnumeric`. @@ -577,7 +576,7 @@ available. They are listed here in alphabetical order. .. function:: iter(o[, sentinel]) - Return an iterator object. The first argument is interpreted very differently + Return an :term:`iterator` object. The first argument is interpreted very differently depending on the presence of the second argument. Without a second argument, *o* must be a collection object which supports the iteration protocol (the :meth:`__iter__` method), or it must support the sequence protocol (the @@ -857,9 +856,9 @@ available. They are listed here in alphabetical order. .. function:: reversed(seq) - Return a reverse iterator. *seq* must be an object which supports the sequence - protocol (the :meth:`__len__` method and the :meth:`__getitem__` method with - integer arguments starting at ``0``). + Return a reverse :term:`iterator`. *seq* must be an object which supports + the sequence protocol (the :meth:`__len__` method and the :meth:`__getitem__` + method with integer arguments starting at ``0``). .. function:: round(x[, n]) diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index f4a7295adb..b87a826a97 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -28,8 +28,8 @@ subshell. (For tilde and shell variable expansion, use .. function:: iglob(pathname) - Return an iterator which yields the same values as :func:`glob` without actually - storing them all simultaneously. + Return an :term:`iterator` which yields the same values as :func:`glob` + without actually storing them all simultaneously. For example, consider a directory containing only the following files: diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst index 1cd71ba4ec..e3b145c459 100644 --- a/Doc/library/heapq.rst +++ b/Doc/library/heapq.rst @@ -90,8 +90,8 @@ The module also offers three general purpose functions based on heaps. .. function:: merge(*iterables) Merge multiple sorted inputs into a single sorted output (for example, merge - timestamped entries from multiple log files). Returns an iterator over over the - sorted values. + timestamped entries from multiple log files). Returns an :term:`iterator` + over over the sorted values. Similar to ``sorted(itertools.chain(*iterables))`` but returns an iterable, does not pull the data into memory all at once, and assumes that each of the input diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 7adb716fa6..cf14de9720 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -67,7 +67,7 @@ attributes: +-----------+-----------------+---------------------------+ | | __code__ | code object containing | | | | compiled function | -| | | bytecode | +| | | :term:`bytecode` | +-----------+-----------------+---------------------------+ | | __defaults__ | tuple of any default | | | | values for arguments | @@ -253,30 +253,31 @@ attributes: .. function:: ismethoddescriptor(object) - Return true if the object is a method descriptor, but not if ismethod() or - isclass() or isfunction() are true. + Return true if the object is a method descriptor, but not if :func:`ismethod` + or :func:`isclass` or :func:`isfunction` are true. - This is new as of Python 2.2, and, for example, is true of int.__add__. An - object passing this test has a __get__ attribute but not a __set__ attribute, - but beyond that the set of attributes varies. __name__ is usually sensible, and - __doc__ often is. + This is new as of Python 2.2, and, for example, is true of + ``int.__add__``. An object passing this test has a :attr:`__get__` attribute + but not a :attr:`__set__` attribute, but beyond that the set of attributes + varies. :attr:`__name__` is usually sensible, and :attr:`__doc__` often is. - Methods implemented via descriptors that also pass one of the other tests return - false from the ismethoddescriptor() test, simply because the other tests promise - more -- you can, e.g., count on having the im_func attribute (etc) when an - object passes ismethod(). + Methods implemented via descriptors that also pass one of the other tests + return false from the :func:`ismethoddescriptor` test, simply because the + other tests promise more -- you can, e.g., count on having the + :attr:`im_func` attribute (etc) when an object passes :func:`ismethod`. .. function:: isdatadescriptor(object) Return true if the object is a data descriptor. - Data descriptors have both a __get__ and a __set__ attribute. Examples are - properties (defined in Python), getsets, and members. The latter two are - defined in C and there are more specific tests available for those types, which - is robust across Python implementations. Typically, data descriptors will also - have __name__ and __doc__ attributes (properties, getsets, and members have both - of these attributes), but this is not guaranteed. + Data descriptors have both a :attr:`__get__` and a :attr:`__set__` attribute. + Examples are properties (defined in Python), getsets, and members. The + latter two are defined in C and there are more specific tests available for + those types, which is robust across Python implementations. Typically, data + descriptors will also have :attr:`__name__` and :attr:`__doc__` attributes + (properties, getsets, and members have both of these attributes), but this is + not guaranteed. .. function:: isgetsetdescriptor(object) @@ -293,8 +294,8 @@ attributes: Return true if the object is a member descriptor. Member descriptors are attributes defined in extension modules via - ``PyMemberDef`` structures. For Python implementations without such types, this - method will always return ``False``. + ``PyMemberDef`` structures. For Python implementations without such types, + this method will always return ``False``. .. _inspect-source: diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index 97399f5cd2..7c7442b62b 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -8,7 +8,7 @@ .. sectionauthor:: Raymond Hettinger <python@rcn.com> -This module implements a number of iterator building blocks inspired by +This module implements a number of :term:`iterator` building blocks inspired by constructs from the Haskell and SML programming languages. Each has been recast in a form suitable for Python. @@ -77,19 +77,15 @@ loops that truncate the stream. .. function:: count([n]) Make an iterator that returns consecutive integers starting with *n*. If not - specified *n* defaults to zero. Does not currently support python long - integers. Often used as an argument to :func:`imap` to generate consecutive - data points. Also, used with :func:`izip` to add sequence numbers. Equivalent - to:: + specified *n* defaults to zero. Often used as an argument to :func:`imap` to + generate consecutive data points. Also, used with :func:`izip` to add sequence + numbers. Equivalent to:: def count(n=0): while True: yield n n += 1 - Note, :func:`count` does not check for overflow and will return negative numbers - after exceeding ``sys.maxint``. This behavior may change in the future. - .. function:: cycle(iterable) @@ -451,8 +447,8 @@ The superior memory performance is kept by processing elements one at a time rather than bringing the whole iterable into memory all at once. Code volume is kept small by linking the tools together in a functional style which helps eliminate temporary variables. High speed is retained by preferring -"vectorized" building blocks over the use of for-loops and generators which -incur interpreter overhead. :: +"vectorized" building blocks over the use of for-loops and :term:`generator`\s +which incur interpreter overhead. :: def take(n, seq): return list(islice(seq, n)) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index fb2116458d..b8610cc4c8 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -20,7 +20,7 @@ logging system for applications. Logging is performed by calling methods on instances of the :class:`Logger` class (hereafter called :dfn:`loggers`). Each instance has a name, and they are -conceptually arranged in a name space hierarchy using dots (periods) as +conceptually arranged in a namespace hierarchy using dots (periods) as separators. For example, a logger named "scan" is the parent of loggers "scan.text", "scan.html" and "scan.pdf". Logger names can be anything you want, and indicate the area of an application in which a logged message originates. @@ -430,7 +430,7 @@ instantiated directly, but always through the module-level function FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s" logging.basicConfig(format=FORMAT) - dict = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' } + d = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' } logger = logging.getLogger("tcpserver") logger.warning("Protocol problem: %s", "connection reset", extra=d) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index fc0ce8b4da..5bff4086b1 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -805,7 +805,7 @@ follows: A message is typically moved from :file:`new` to :file:`cur` after its mailbox has been accessed, whether or not the message is has been read. A message - ``msg`` has been read if ``"S" not in msg.get_flags()`` is ``True``. + ``msg`` has been read if ``"S" in msg.get_flags()`` is ``True``. .. method:: MaildirMessage.set_subdir(subdir) diff --git a/Doc/library/marshal.rst b/Doc/library/marshal.rst index 00bbab1780..0cf69b4ff9 100644 --- a/Doc/library/marshal.rst +++ b/Doc/library/marshal.rst @@ -25,7 +25,9 @@ transfer of Python objects through RPC calls, see the modules :mod:`pickle` and writing the "pseudo-compiled" code for Python modules of :file:`.pyc` files. Therefore, the Python maintainers reserve the right to modify the marshal format in backward incompatible ways should the need arise. If you're serializing and -de-serializing Python objects, use the :mod:`pickle` module instead. +de-serializing Python objects, use the :mod:`pickle` module instead -- the +performance is comparable, version independence is guaranteed, and pickle +supports a substantially wider range of objects than marshal. .. warning:: @@ -36,13 +38,19 @@ de-serializing Python objects, use the :mod:`pickle` module instead. Not all Python object types are supported; in general, only objects whose value is independent from a particular invocation of Python can be written and read by this module. The following types are supported: ``None``, integers, long -integers, floating point numbers, strings, Unicode objects, tuples, lists, +integers, floating point numbers, strings, Unicode objects, tuples, lists, sets, dictionaries, and code objects, where it should be understood that tuples, lists and dictionaries are only supported as long as the values contained therein are themselves supported; and recursive lists and dictionaries should not be written (they will cause infinite loops). .. warning:: + + Some unsupported types such as subclasses of builtins will appear to marshal + and unmarshal correctly, but in fact, their type will change and the + additional subclass functionality and instance attributes will be lost. + +.. warning:: On machines where C's ``long int`` type has more than 32 bits (such as the DEC Alpha), it is possible to create plain Python integers that are longer diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst index 533034f3be..26748c490a 100644 --- a/Doc/library/mmap.rst +++ b/Doc/library/mmap.rst @@ -38,7 +38,7 @@ not update the underlying file. To map anonymous memory, -1 should be passed as the fileno along with the length. -.. function:: mmap(fileno, length[, tagname[, access]]) +.. function:: mmap(fileno, length[, tagname[, access[, offset]]]) **(Windows version)** Maps *length* bytes from the file specified by the file handle *fileno*, and returns a mmap object. If *length* is larger than the @@ -54,8 +54,12 @@ To map anonymous memory, -1 should be passed as the fileno along with the length the mapping is created without a name. Avoiding the use of the tag parameter will assist in keeping your code portable between Unix and Windows. + *offset* may be specified as a non-negative integer offset. mmap references will + be relative to the offset from the beginning of the file. *offset* defaults to 0. + *offset* must be a multiple of the ALLOCATIONGRANULARITY. -.. function:: mmap(fileno, length[, flags[, prot[, access]]]) + +.. function:: mmap(fileno, length[, flags[, prot[, access[, offset]]]]) :noindex: **(Unix version)** Maps *length* bytes from the file specified by the file @@ -77,6 +81,10 @@ To map anonymous memory, -1 should be passed as the fileno along with the length parameter. It is an error to specify both *flags*, *prot* and *access*. See the description of *access* above for information on how to use this parameter. + *offset* may be specified as a non-negative integer offset. mmap references will + be relative to the offset from the beginning of the file. *offset* defaults to 0. + *offset* must be a multiple of the PAGESIZE or ALLOCATIONGRANULARITY. + Memory-mapped file objects support the following methods: @@ -169,3 +177,4 @@ Memory-mapped file objects support the following methods: created with :const:`ACCESS_READ`, then writing to it will throw a :exc:`TypeError` exception. + diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index 8809c59332..4c0f0da51f 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -950,7 +950,7 @@ must specify for any option using that action. * ``append_const`` [required: ``const``; relevant: :attr:`dest`] Like ``store_const``, but the value ``const`` is appended to :attr:`dest`; as - with ``append``, :attr:`dest` defaults to ``None``, and an an empty list is + with ``append``, :attr:`dest` defaults to ``None``, and an empty list is automatically created the first time the option is encountered. * ``count`` [relevant: :attr:`dest`] @@ -1116,7 +1116,7 @@ Integer arguments (type ``int`` or ``long``) are parsed as follows: * if the number starts with ``0``, it is parsed as an octal number -* if the number starts with ``0b``, is is parsed as a binary number +* if the number starts with ``0b``, it is parsed as a binary number * otherwise, the number is parsed as a decimal number diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index 667cb9036f..b176524fbf 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -279,8 +279,8 @@ write files see :func:`open`, and for accessing the filesystem see the .. note:: - The newer :func:`os.walk` generator supplies similar functionality and can be - easier to use. + The newer :func:`os.walk` :term:`generator` supplies similar functionality + and can be easier to use. .. data:: supports_unicode_filenames diff --git a/Doc/library/os.rst b/Doc/library/os.rst index b5f2bdf4f5..e627498f48 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -107,9 +107,14 @@ process and user. passed to the appropriate process-creation functions to cause child processes to use a modified environment. - If the platform supports the :func:`unsetenv` function, you can delete items in + If the platform supports the :func:`unsetenv` function, you can delete items in this mapping to unset environment variables. :func:`unsetenv` will be called - automatically when an item is deleted from ``os.environ``. + automatically when an item is deleted from ``os.environ``, and when + one of the :meth:`pop` or :meth:`clear` methods is called. + + .. versionchanged:: 2.6 + Also unset environment variables when calling :meth:`os.environ.clear` + and :meth:`os.environ.pop`. .. function:: chdir(path) @@ -541,7 +546,7 @@ by file descriptors. .. function:: ttyname(fd) Return a string which specifies the terminal device associated with - file-descriptor *fd*. If *fd* is not associated with a terminal device, an + file descriptor *fd*. If *fd* is not associated with a terminal device, an exception is raised. Availability:Macintosh, Unix. diff --git a/Doc/library/parser.rst b/Doc/library/parser.rst index e361a26c68..9323090ca3 100644 --- a/Doc/library/parser.rst +++ b/Doc/library/parser.rst @@ -321,7 +321,7 @@ Examples .. index:: builtin: compile The parser modules allows operations to be performed on the parse tree of Python -source code before the bytecode is generated, and provides for inspection of the +source code before the :term:`bytecode` is generated, and provides for inspection of the parse tree for information gathering purposes. Two examples are presented. The simple example demonstrates emulation of the :func:`compile` built-in function and the complex example shows the use of a parse tree for information discovery. diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst index c9abbf207d..017fbd6ea6 100644 --- a/Doc/library/pdb.rst +++ b/Doc/library/pdb.rst @@ -239,7 +239,7 @@ commands [*bpnumber*] Specifying any command resuming execution (currently continue, step, next, return, jump, quit and their abbreviations) terminates the command list (as if that command was immediately followed by end). This is because any time you - resume execution (even with a simple next or step), you may encounter· another + resume execution (even with a simple next or step), you may encounter another breakpoint--which could have its own command list, leading to ambiguities about which list to execute. @@ -323,7 +323,7 @@ unalias *name* (Pdb) run [*args* ...] - Restart the debugged python program. If an argument is supplied, it is splitted + Restart the debugged python program. If an argument is supplied, it is split with "shlex" and the result is used as the new sys.argv. History, breakpoints, actions and debugger options are preserved. "restart" is an alias for "run". diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index 9bbb1d3b7c..e18693735c 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -122,7 +122,7 @@ There are currently 3 different protocols which can be used for pickling. earlier versions of Python. * Protocol version 2 was introduced in Python 2.3. It provides much more - efficient pickling of new-style classes. + efficient pickling of :term:`new-style class`\es. Refer to :pep:`307` for more information. @@ -418,8 +418,8 @@ New-style types can provide a :meth:`__getnewargs__` method that is used for protocol 2. Implementing this method is needed if the type establishes some internal invariants when the instance is created, or if the memory allocation is affected by the values passed to the :meth:`__new__` method for the type (as it -is for tuples and strings). Instances of a new-style type :class:`C` are -created using :: +is for tuples and strings). Instances of a :term:`new-style class` :class:`C` +are created using :: obj = C.__new__(C, *args) @@ -447,8 +447,8 @@ can do what they want. [#]_ .. warning:: - For new-style classes, if :meth:`__getstate__` returns a false value, the - :meth:`__setstate__` method will not be called. + For :term:`new-style class`\es, if :meth:`__getstate__` returns a false + value, the :meth:`__setstate__` method will not be called. Pickling and unpickling extension types diff --git a/Doc/library/pickletools.rst b/Doc/library/pickletools.rst index 6202a0e392..3fc38ff237 100644 --- a/Doc/library/pickletools.rst +++ b/Doc/library/pickletools.rst @@ -27,9 +27,9 @@ probably won't find the :mod:`pickletools` module relevant. .. function:: genops(pickle) - Provides an iterator over all of the opcodes in a pickle, returning a sequence - of ``(opcode, arg, pos)`` triples. *opcode* is an instance of an - :class:`OpcodeInfo` class; *arg* is the decoded value, as a Python object, of - the opcode's argument; *pos* is the position at which this opcode is located. + Provides an :term:`iterator` over all of the opcodes in a pickle, returning a + sequence of ``(opcode, arg, pos)`` triples. *opcode* is an instance of an + :class:`OpcodeInfo` class; *arg* is the decoded value, as a Python object, of + the opcode's argument; *pos* is the position at which this opcode is located. *pickle* can be a string or a file-like object. diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst index 5e1da225dc..ec1c75f22a 100644 --- a/Doc/library/pty.rst +++ b/Doc/library/pty.rst @@ -43,6 +43,6 @@ The :mod:`pty` module defines the following functions: reading from the controlling terminal. The functions *master_read* and *stdin_read* should be functions which read from - a file-descriptor. The defaults try to read 1024 bytes each time they are + a file descriptor. The defaults try to read 1024 bytes each time they are called. diff --git a/Doc/library/pyclbr.rst b/Doc/library/pyclbr.rst index 5a77b4e876..a052a69d19 100644 --- a/Doc/library/pyclbr.rst +++ b/Doc/library/pyclbr.rst @@ -19,10 +19,10 @@ in Python, including many standard and optional extension modules. .. function:: readmodule(module[, path]) 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. + 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.... diff --git a/Doc/library/re.rst b/Doc/library/re.rst index a3d3deaa8e..2d9fa328b5 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -28,14 +28,14 @@ The solution is to use Python's raw string notation for regular expression patterns; backslashes are not handled in any special way in a string literal prefixed with ``'r'``. So ``r"\n"`` is a two-character string containing ``'\'`` and ``'n'``, while ``"\n"`` is a one-character string containing a -newline. Usually patterns will be expressed in Python code using this raw string -notation. +newline. Usually patterns will be expressed in Python code using this raw +string notation. .. seealso:: Mastering Regular Expressions Book on regular expressions by Jeffrey Friedl, published by O'Reilly. The - second edition of the book no longer covers Python at all, but the first + second edition of the book no longer covers Python at all, but the first edition covered writing good regular expression patterns in great detail. @@ -427,8 +427,8 @@ form. .. function:: compile(pattern[, flags]) - Compile a regular expression pattern into a regular expression object, which can - be used for matching using its :func:`match` and :func:`search` methods, + Compile a regular expression pattern into a regular expression object, which + can be used for matching using its :func:`match` and :func:`search` methods, described below. The expression's behaviour can be modified by specifying a *flags* value. @@ -444,8 +444,8 @@ form. result = re.match(pat, str) - but the version using :func:`compile` is more efficient when the expression will - be used several times in a single program. + but the version using :func:`compile` is more efficient when the expression + will be used several times in a single program. .. % (The compiled version of the last pattern passed to .. % \function{re.match()} or \function{re.search()} is cached, so @@ -463,8 +463,8 @@ form. .. data:: L LOCALE - Make ``\w``, ``\W``, ``\b``, ``\B``, ``\s`` and ``\S`` dependent on the current - locale. + Make ``\w``, ``\W``, ``\b``, ``\B``, ``\s`` and ``\S`` dependent on the + current locale. .. data:: M @@ -556,17 +556,18 @@ form. .. function:: findall(pattern, string[, flags]) - Return a list of all non-overlapping matches of *pattern* in *string*. If one - or more groups are present in the pattern, return a list of groups; this will be - a list of tuples if the pattern has more than one group. Empty matches are - included in the result unless they touch the beginning of another match. + Return all non-overlapping matches of *pattern* in *string*, as a list of + strings. If one or more groups are present in the pattern, return a list of + groups; this will be a list of tuples if the pattern has more than one group. + Empty matches are included in the result unless they touch the beginning of + another match. .. function:: finditer(pattern, string[, flags]) - Return an iterator over all non-overlapping matches for the RE *pattern* in - *string*. For each match, the iterator returns a match object. Empty matches - are included in the result unless they touch the beginning of another match. + Return an :term:`iterator` yielding :class:`MatchObject` instances over all + non-overlapping matches for the RE *pattern* in *string*. Empty matches are + included in the result unless they touch the beginning of another match. .. function:: sub(pattern, repl, string[, count]) @@ -729,7 +730,9 @@ attributes: Match Objects ------------- -:class:`MatchObject` instances support the following methods and attributes: +Match objects always have a boolean value of :const:`True`, so that you can test +whether e.g. :func:`match` resulted in a match with a simple if statement. They +support the following methods and attributes: .. method:: MatchObject.expand(template) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 514c71e8b4..eddf470beb 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -69,10 +69,10 @@ may use a different placeholder, such as ``%s`` or ``:1``.) For example:: ): c.execute('insert into stocks values (?,?,?,?,?)', t) -To retrieve data after executing a SELECT statement, you can either treat the -cursor as an iterator, call the cursor's :meth:`fetchone` method to retrieve a -single matching row, or call :meth:`fetchall` to get a list of the matching -rows. +To retrieve data after executing a SELECT statement, you can either treat the +cursor as an :term:`iterator`, call the cursor's :meth:`fetchone` method to +retrieve a single matching row, or call :meth:`fetchall` to get a list of the +matching rows. This example uses the iterator form:: @@ -408,13 +408,13 @@ A :class:`Cursor` instance has the following attributes and methods: .. method:: Cursor.executemany(sql, seq_of_parameters) - Executes a SQL command against all parameter sequences or mappings found in the - sequence *sql*. The :mod:`sqlite3` module also allows using an iterator yielding - parameters instead of a sequence. + Executes a SQL command against all parameter sequences or mappings found in + the sequence *sql*. The :mod:`sqlite3` module also allows using an + :term:`iterator` yielding parameters instead of a sequence. .. literalinclude:: ../includes/sqlite3/executemany_1.py - Here's a shorter example using a generator: + Here's a shorter example using a :term:`generator`: .. literalinclude:: ../includes/sqlite3/executemany_2.py diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 851f742462..d700229eca 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -223,7 +223,7 @@ Functions, Constants, and Exceptions .. data:: PROTOCOL_TLSv1 - Selects SSL version 2 as the channel encryption protocol. This is + Selects TLS version 1 as the channel encryption protocol. This is the most modern version, and probably the best choice for maximum protection, if both sides can speak it. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index e4452f6be6..fb278fa779 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -449,10 +449,10 @@ Once an iterator's :meth:`__next__` method raises :exc:`StopIteration`, it must continue to do so on subsequent calls. Implementations that do not obey this property are deemed broken. -Python's generators provide a convenient way to implement the iterator protocol. -If a container object's :meth:`__iter__` method is implemented as a generator, -it will automatically return an iterator object (technically, a generator -object) supplying the :meth:`__iter__` and :meth:`__next__` methods. +Python's :term:`generator`\s provide a convenient way to implement the iterator +protocol. If a container object's :meth:`__iter__` method is implemented as a +generator, it will automatically return an iterator object (technically, a +generator object) supplying the :meth:`__iter__` and :meth:`__next__` methods. .. _typesseq: @@ -655,9 +655,9 @@ functions based on regular expressions. .. method:: str.count(sub[, start[, end]]) - Return the number of occurrences of substring *sub* in string S\ - ``[start:end]``. Optional arguments *start* and *end* are interpreted as in - slice notation. + Return the number of occurrences of substring *sub* in the range [*start*, + *end*]. Optional arguments *start* and *end* are interpreted as in slice + notation. .. method:: str.encode([encoding[, errors]]) @@ -682,8 +682,11 @@ functions based on regular expressions. .. method:: str.expandtabs([tabsize]) - Return a copy of the string where all tab characters are expanded using spaces. - If *tabsize* is not given, a tab size of ``8`` characters is assumed. + Return a copy of the string where all tab characters are replaced by one or + more spaces, depending on the current column and the given tab size. The + column number is reset to zero after each newline occurring in the string. + If *tabsize* is not given, a tab size of ``8`` characters is assumed. This + doesn't understand other non-printing characters or escape sequences. .. method:: str.find(sub[, start[, end]]) @@ -869,19 +872,23 @@ functions based on regular expressions. string. If *maxsplit* is given, at most *maxsplit* splits are done (thus, the list will have at most ``maxsplit+1`` elements). If *maxsplit* is not specified, then there is no limit on the number of splits (all possible - splits are made). Consecutive delimiters are not grouped together and are + splits are made). + + If *sep is given, consecutive delimiters are not grouped together and are deemed to delimit empty strings (for example, ``'1,,2'.split(',')`` returns ``['1', '', '2']``). The *sep* argument may consist of multiple characters - (for example, ``'1, 2, 3'.split(', ')`` returns ``['1', '2', '3']``). + (for example, ``'1<>2<>3'.split('<>')`` returns ``['1', '2', '3']``). Splitting an empty string with a specified separator returns ``['']``. If *sep* is not specified or is ``None``, a different splitting algorithm is - applied. First, whitespace characters (spaces, tabs, newlines, returns, and - formfeeds) are stripped from both ends. Then, words are separated by arbitrary - length strings of whitespace characters. Consecutive whitespace delimiters are - treated as a single delimiter (``'1 2 3'.split()`` returns ``['1', '2', - '3']``). Splitting an empty string or a string consisting of just whitespace - returns an empty list. + applied: runs of consecutive whitespace are regarded as a single separator, + and the result will contain no empty strings at the start or end if the + string has leading or trailing whitespace. Consequently, splitting an empty + string or a string consisting of just whitespace with a ``None`` separator + returns ``[]``. + + For example, ``' 1 2 3 '.split()`` returns ``['1', '2', '3']``, and + ``' 1 2 3 '.split(None, 1)`` returns ``['1', '2 3 ']``. .. method:: str.splitlines([keepends]) @@ -947,8 +954,10 @@ functions based on regular expressions. .. method:: str.zfill(width) - Return the numeric string left filled with zeros in a string of length *width*. - The original string is returned if *width* is less than ``len(s)``. + Return the numeric string left filled with zeros in a string of length + *width*. A sign prefix is handled correctly. The original string is + returned if *width* is less than ``len(s)``. + .. _old-string-formatting: @@ -1865,8 +1874,7 @@ Files have the following methods: .. method:: file.fileno() .. index:: - single: file descriptor - single: descriptor, file + pair: file; descriptor module: fcntl Return the integer "file descriptor" that is used by the underlying @@ -2091,7 +2099,7 @@ to be provided for a context manager object to define a runtime context: .. method:: contextmanager.__exit__(exc_type, exc_val, exc_tb) - Exit the runtime context and return a Boolean flag indicating if any expection + Exit the runtime context and return a Boolean flag indicating if any exception that occurred should be suppressed. If an exception occurred while executing the body of the :keyword:`with` statement, the arguments contain the exception type, value and traceback information. Otherwise, all three arguments are ``None``. @@ -2115,7 +2123,7 @@ decimal arithmetic context. The specific types are not treated specially beyond their implementation of the context management protocol. See the :mod:`contextlib` module for some examples. -Python's generators and the ``contextlib.contextfactory`` decorator provide a +Python's :term:`generator`\s and the ``contextlib.contextfactory`` decorator provide a convenient way to implement these protocols. If a generator function is decorated with the ``contextlib.contextfactory`` decorator, it will return a context manager implementing the necessary :meth:`__enter__` and diff --git a/Doc/library/tokenize.rst b/Doc/library/tokenize.rst index 0359f84d42..19a5a35019 100644 --- a/Doc/library/tokenize.rst +++ b/Doc/library/tokenize.rst @@ -13,7 +13,7 @@ implemented in Python. The scanner in this module returns comments as tokens as well, making it useful for implementing "pretty-printers," including colorizers for on-screen displays. -The primary entry point is a generator: +The primary entry point is a :term:`generator`: .. function:: generate_tokens(readline) diff --git a/Doc/library/types.rst b/Doc/library/types.rst index ec271e4f50..d291fd017f 100644 --- a/Doc/library/types.rst +++ b/Doc/library/types.rst @@ -113,8 +113,8 @@ The module defines the following names: .. data:: GeneratorType - The type of generator-iterator objects, produced by calling a generator - function. + The type of :term:`generator`-iterator objects, produced by calling a + generator function. .. data:: CodeType diff --git a/Doc/library/urllib.rst b/Doc/library/urllib.rst index 3d28c45ce3..f4c85bcdff 100644 --- a/Doc/library/urllib.rst +++ b/Doc/library/urllib.rst @@ -29,7 +29,7 @@ It defines the following public functions: :exc:`IOError` exception is raised. If all went well, a file-like object is returned. This supports the following methods: :meth:`read`, :meth:`readline`, :meth:`readlines`, :meth:`fileno`, :meth:`close`, :meth:`info` and - :meth:`geturl`. It also has proper support for the iterator protocol. One + :meth:`geturl`. It also has proper support for the :term:`iterator` protocol. One caveat: the :meth:`read` method, if the size argument is omitted or negative, may not read until the end of the data stream; there is no good way to determine that the entire stream from a socket has been read in the general case. diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 299b818879..6c7c919f9d 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -51,9 +51,9 @@ is exposed by the :mod:`weakref` module for the benefit of advanced uses. Not all objects can be weakly referenced; those objects which can include class instances, functions written in Python (but not in C), methods (both bound and -unbound), sets, frozensets, file objects, generators, type objects, DBcursor -objects from the :mod:`bsddb` module, sockets, arrays, deques, and regular -expression pattern objects. +unbound), sets, frozensets, file objects, :term:`generator`\s, type objects, +:class:`DBcursor` objects from the :mod:`bsddb` module, sockets, arrays, deques, +and regular expression pattern objects. Several builtin types such as :class:`list` and :class:`dict` do not directly support weak references but can add support through subclassing:: @@ -146,7 +146,7 @@ than needed. .. method:: WeakKeyDictionary.iterkeyrefs() - Return an iterator that yields the weak references to the keys. + Return an :term:`iterator` that yields the weak references to the keys. .. method:: WeakKeyDictionary.keyrefs() @@ -174,7 +174,7 @@ methods of :class:`WeakKeyDictionary` objects. .. method:: WeakValueDictionary.itervaluerefs() - Return an iterator that yields the weak references to the values. + Return an :term:`iterator` that yields the weak references to the values. .. method:: WeakValueDictionary.valuerefs() diff --git a/Doc/library/wsgiref.rst b/Doc/library/wsgiref.rst index b93b653377..73acf84979 100644 --- a/Doc/library/wsgiref.rst +++ b/Doc/library/wsgiref.rst @@ -124,7 +124,7 @@ also provides these miscellaneous utilities: .. class:: FileWrapper(filelike [, blksize=8192]) - A wrapper to convert a file-like object to an iterator. The resulting objects + A wrapper to convert a file-like object to an :term:`iterator`. The resulting objects support both :meth:`__getitem__` and :meth:`__iter__` iteration styles, for compatibility with Python 2.1 and Jython. As the object is iterated over, the optional *blksize* parameter will be repeatedly passed to the *filelike* diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 5143320382..81a93169cb 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -87,7 +87,7 @@ Functions Parses an XML section into an element tree incrementally, and reports what's going on to the user. *source* is a filename or file object containing XML data. *events* is a list of events to report back. If omitted, only "end" events are - reported. Returns an iterator providing ``(event, elem)`` pairs. + reported. Returns an :term:`iterator` providing ``(event, elem)`` pairs. .. function:: parse(source[, parser]) @@ -316,7 +316,7 @@ ElementTree Objects .. method:: ElementTree.findall(path) Finds all toplevel elements with the given tag. Same as getroot().findall(path). - *path* is the element to look for. Returns a list or iterator containing all + *path* is the element to look for. Returns a list or :term:`iterator` containing all matching elements, in document order. diff --git a/Doc/library/xmlrpclib.rst b/Doc/library/xmlrpclib.rst index 3b4dbbdf8d..0fda8933de 100644 --- a/Doc/library/xmlrpclib.rst +++ b/Doc/library/xmlrpclib.rst @@ -314,7 +314,8 @@ encapsulate multiple calls to a remote server into a single request. return ``None``, and only store the call name and parameters in the :class:`MultiCall` object. Calling the object itself causes all stored calls to be transmitted as a single ``system.multicall`` request. The result of this call - is a generator; iterating over this generator yields the individual results. + is a :term:`generator`; iterating over this generator yields the individual + results. A usage example of this class is :: |