diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/documenting/markup.rst | 13 | ||||
| -rw-r--r-- | Doc/library/codecs.rst | 6 | ||||
| -rw-r--r-- | Doc/library/copy.rst | 4 | ||||
| -rw-r--r-- | Doc/library/ctypes.rst | 11 | ||||
| -rw-r--r-- | Doc/library/mutex.rst | 5 | ||||
| -rw-r--r-- | Doc/library/queue.rst | 5 | ||||
| -rw-r--r-- | Doc/library/re.rst | 7 | ||||
| -rw-r--r-- | Doc/library/readline.rst | 16 | ||||
| -rw-r--r-- | Doc/library/smtplib.rst | 2 | ||||
| -rw-r--r-- | Doc/library/socket.rst | 2 | ||||
| -rw-r--r-- | Doc/library/ssl.rst | 81 | ||||
| -rw-r--r-- | Doc/library/thread.rst | 6 | ||||
| -rw-r--r-- | Doc/library/threading.rst | 1 | ||||
| -rw-r--r-- | Doc/whatsnew/2.6.rst | 67 |
14 files changed, 172 insertions, 54 deletions
diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst index 1bb2185..f85158b 100644 --- a/Doc/documenting/markup.rst +++ b/Doc/documenting/markup.rst @@ -707,7 +707,7 @@ consists of a type and a value, separated by a colon. For example:: .. index:: - single: execution!context + single: execution; context module: __main__ module: sys triple: module; search; path @@ -720,8 +720,8 @@ The possible entry types are: single Creates a single index entry. Can be made a subentry by separating the - subentry text with a semicolon (this is also used below to describe what - entries are created). + subentry text with a semicolon (this notation is also used below to describe + what entries are created). pair ``pair: loop; statement`` is a shortcut that creates two index entries, namely ``loop; statement`` and ``statement; loop``. @@ -733,6 +733,13 @@ module, keyword, operator, object, exception, statement, builtin These all create two index entries. For example, ``module: hashlib`` creates the entries ``module; hashlib`` and ``hashlib; module``. +For index directives containing only "single" entries, there is a shorthand +notation:: + + .. index:: BNF, grammar, syntax, notation + +This creates four index entries. + Grammar production displays --------------------------- diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index f35ef76..238c80e 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -186,12 +186,12 @@ functions which use :func:`lookup` for the codec lookup: Implements the ``ignore`` error handling. -.. function:: xmlcharrefreplace_errors_errors(exception) +.. function:: xmlcharrefreplace_errors(exception) Implements the ``xmlcharrefreplace`` error handling. -.. function:: backslashreplace_errors_errors(exception) +.. function:: backslashreplace_errors(exception) Implements the ``backslashreplace`` error handling. @@ -833,7 +833,7 @@ Without external information it's impossible to reliably determine which encoding was used for encoding a Unicode string. Each charmap encoding can decode any random byte sequence. However that's not possible with UTF-8, as UTF-8 byte sequences have a structure that doesn't allow arbitrary byte -sequence. To increase the reliability with which a UTF-8 encoding can be +sequences. To increase the reliability with which a UTF-8 encoding can be detected, Microsoft invented a variant of UTF-8 (that Python 2.5 calls ``"utf-8-sig"``) for its Notepad program: Before any of the Unicode characters is written to the file, a UTF-8 encoded BOM (which looks like this as a byte diff --git a/Doc/library/copy.rst b/Doc/library/copy.rst index ea59613..0abee4d 100644 --- a/Doc/library/copy.rst +++ b/Doc/library/copy.rst @@ -54,6 +54,10 @@ file, socket, window, array, or any similar types. It does "copy" functions and classes (shallow and deeply), by returning the original object unchanged; this is compatible with the way these are treated by the :mod:`pickle` module. +Shallow copies of dictionaries can be made using :meth:`dict.copy`, and +of lists by assigning a slice of the entire list, for example, +``copied_list = original_list[:]``. + .. index:: module: pickle Classes can use the same interfaces to control copying that they use to control diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index e9acedf..4b1934d 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -247,6 +247,8 @@ Fundamental data types +----------------------+--------------------------------+----------------------------+ | :class:`c_double` | ``double`` | float | +----------------------+--------------------------------+----------------------------+ + | :class:`c_longdouble`| ``long double`` | float | + +----------------------+--------------------------------+----------------------------+ | :class:`c_char_p` | ``char *`` (NUL terminated) | string or ``None`` | +----------------------+--------------------------------+----------------------------+ | :class:`c_wchar_p` | ``wchar_t *`` (NUL terminated) | unicode or ``None`` | @@ -2065,9 +2067,16 @@ These are the fundamental ctypes data types: initializer. +.. class:: c_longdouble + + Represents the C long double datatype. The constructor accepts an + optional float initializer. On platforms where ``sizeof(long + double) == sizeof(double)`` it is an alias to :class:`c_double`. + + .. class:: c_float - Represents the C double datatype. The constructor accepts an optional float + Represents the C float datatype. The constructor accepts an optional float initializer. diff --git a/Doc/library/mutex.rst b/Doc/library/mutex.rst index 523692f..151f0c1 100644 --- a/Doc/library/mutex.rst +++ b/Doc/library/mutex.rst @@ -8,8 +8,9 @@ The :mod:`mutex` module defines a class that allows mutual-exclusion via -acquiring and releasing locks. It does not require (or imply) threading or -multi-tasking, though it could be useful for those purposes. +acquiring and releasing locks. It does not require (or imply) +:mod:`threading` or multi-tasking, though it could be useful for those +purposes. The :mod:`mutex` module defines the following class: diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst index c183860..e9da905 100644 --- a/Doc/library/queue.rst +++ b/Doc/library/queue.rst @@ -7,10 +7,11 @@ The :mod:`Queue` module implements a multi-producer, multi-consumer FIFO queue. -It is especially useful in threads programming when information must be +It is especially useful in threaded programming when information must be exchanged safely between multiple threads. The :class:`Queue` class in this module implements all the required locking semantics. It depends on the -availability of thread support in Python. +availability of thread support in Python; see the :mod:`threading` +module. The :mod:`Queue` module defines the following class and exception: diff --git a/Doc/library/re.rst b/Doc/library/re.rst index fef6d2d..a3d3dea 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -546,6 +546,13 @@ form. >>> re.split('\W+', 'Words, words, words.', 1) ['Words', 'words, words.'] + Note that *split* will never split a string on an empty pattern match. + For example :: + + >>> re.split('x*', 'foo') + ['foo'] + >>> re.split("(?m)^$", "foo\n\nbar\n") + ['foo\n\nbar\n'] .. function:: findall(pattern, string[, flags]) diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst index 7727c3b..7e6eccf 100644 --- a/Doc/library/readline.rst +++ b/Doc/library/readline.rst @@ -128,6 +128,12 @@ The :mod:`readline` module defines the following functions: Get the completer function, or ``None`` if no completer function has been set. +.. function:: get_completion_type() + + Get the type of completion being attempted. + + .. versionadded:: 2.6 + .. function:: get_begidx() Get the beginning index of the readline tab-completion scope. @@ -147,6 +153,16 @@ The :mod:`readline` module defines the following functions: Get the readline word delimiters for tab-completion. +.. function:: set_completion_display_matches_hook([function]) + + Set or remove the completion display function. If *function* is + specified, it will be used as the new completion display function; + if omitted or ``None``, any completion display function already + installed is removed. The completion display function is called as + ``function(substitution, [matches], longest_match_length)`` once + each time matches need to be displayed. + + .. versionadded:: 2.6 .. function:: add_history(line) diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index 3173f35..286a725 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -47,7 +47,7 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). .. class:: LMTP([host[, port[, local_hostname]]]) The LMTP protocol, which is very similar to ESMTP, is heavily based on the - standard SMTP client. It's common to use Unix sockets for LMTP, so our connect() + standard SMTP client. It's common to use Unix sockets for LMTP, so our :meth:`connect` method must support that as well as a regular host:port server. To specify a Unix socket, you must use an absolute path for *host*, starting with a '/'. diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index a445b54..758cfb1 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -165,7 +165,7 @@ The module :mod:`socket` exports the following constants and functions: .. function:: create_connection(address[, timeout]) Connects to the *address* received (as usual, a ``(host, port)`` pair), with an - optional timeout for the connection. Specially useful for higher-level + optional timeout for the connection. Especially useful for higher-level protocols, it is not normally used directly from application-level code. Passing the optional *timeout* parameter will set the timeout on the socket instance (if it is not given or ``None``, the global default timeout setting is diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 5072caf..852a905 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -170,6 +170,8 @@ use the first chain it finds in the file which matches. Some "standard" root certificates are available at http://www.thawte.com/roots/ (for Thawte roots) and http://www.verisign.com/support/roots.html (for Verisign roots). +See also :rfc:`4158` for more discussion of the way in which +certification chains can be built. sslsocket Objects @@ -239,23 +241,23 @@ sslsocket Objects the certificate), ``notBefore`` (the time before which the certificate should not be trusted), and ``notAfter`` (the time after which the certificate should not be trusted) filled in. - The "subject" and "issuer" fields are themselves dictionaries containing the fields given - in the certificate's data structure for each principal:: - - {'issuer': {'commonName': u'somemachine.python.org', - 'countryName': u'US', - 'localityName': u'Wilmington', - 'organizationName': u'Python Software Foundation', - 'organizationalUnitName': u'SSL', - 'stateOrProvinceName': u'Delaware'}, - 'subject': {'commonName': u'somemachine.python.org', - 'countryName': u'US', - 'localityName': u'Wilmington', - 'organizationName': u'Python Software Foundation', - 'organizationalUnitName': u'SSL', - 'stateOrProvinceName': u'Delaware'}, - 'notAfter': 'Sep 4 21:54:26 2007 GMT', - 'notBefore': 'Aug 25 21:54:26 2007 GMT', + The "subject" and "issuer" fields are tuples containing the name-value fields + given in the certificate's data structure for each principal:: + + {'issuer': (('countryName', u'US'), + ('stateOrProvinceName', u'Delaware'), + ('localityName', u'Wilmington'), + ('organizationName', u'Python Software Foundation'), + ('organizationalUnitName', u'SSL'), + ('commonName', u'somemachine.python.org')), + 'notAfter': 'Feb 16 16:54:50 2013 GMT', + 'notBefore': 'Aug 27 16:54:50 2007 GMT', + 'subject': (('countryName', u'US'), + ('stateOrProvinceName', u'Delaware'), + ('localityName', u'Wilmington'), + ('organizationName', u'Python Software Foundation'), + ('organizationalUnitName', u'SSL'), + ('commonName', u'somemachine.python.org')), 'version': 2} This certificate is said to be *self-signed*, because the subject @@ -311,27 +313,32 @@ sends some bytes, and reads part of the response:: # note that closing the sslsocket will also close the underlying socket ssl_sock.close() -As of August 25, 2007, the certificate printed by this program +As of September 4, 2007, the certificate printed by this program looked like this:: - {'issuer': {'commonName': u'VeriSign Class 3 Extended Validation SSL SGC CA', - 'countryName': u'US', - 'organizationName': u'VeriSign, Inc.', - 'organizationalUnitName': u'Terms of use at https://www.verisign.com/rpa (c)06'}, - 'subject': {'1.3.6.1.4.1.311.60.2.1.2': u'Delaware', - '1.3.6.1.4.1.311.60.2.1.3': u'US', - 'commonName': u'www.verisign.com', - 'countryName': u'US', - 'localityName': u'Mountain View', - 'organizationName': u'VeriSign, Inc.', - 'organizationalUnitName': u'Terms of use at www.verisign.com/rpa (c)06', - 'postalCode': u'94043', - 'serialNumber': u'2497886', - 'stateOrProvinceName': u'California', - 'streetAddress': u'487 East Middlefield Road'}, - 'notAfter': 'May 8 23:59:59 2009 GMT', - 'notBefore': 'May 9 00:00:00 2007 GMT', - 'version': 2} + {'issuer': (('countryName', u'US'), + ('organizationName', u'VeriSign, Inc.'), + ('organizationalUnitName', u'VeriSign Trust Network'), + ('organizationalUnitName', + u'Terms of use at https://www.verisign.com/rpa (c)06'), + ('commonName', + u'VeriSign Class 3 Extended Validation SSL SGC CA')), + 'notAfter': 'May 8 23:59:59 2009 GMT', + 'notBefore': 'May 9 00:00:00 2007 GMT', + 'subject': (('serialNumber', u'2497886'), + ('1.3.6.1.4.1.311.60.2.1.3', u'US'), + ('1.3.6.1.4.1.311.60.2.1.2', u'Delaware'), + ('countryName', u'US'), + ('postalCode', u'94043'), + ('stateOrProvinceName', u'California'), + ('localityName', u'Mountain View'), + ('streetAddress', u'487 East Middlefield Road'), + ('organizationName', u'VeriSign, Inc.'), + ('organizationalUnitName', u'Production Security Services'), + ('organizationalUnitName', + u'Terms of use at www.verisign.com/rpa (c)06'), + ('commonName', u'www.verisign.com')), + 'version': 2} Server-side operation ^^^^^^^^^^^^^^^^^^^^^ @@ -383,3 +390,5 @@ Class :class:`socket.socket` `Introducing SSL and Certificates using OpenSSL <http://old.pseudonym.org/ssl/wwwj-index.html>`_, by Frederick J. Hirsch `Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management`, :rfc:`1422`, by Steve Kent + +`Internet X.509 Public Key Infrastructure Certificate and CRL Profile`, :rfc:`3280`, Housley et. al. diff --git a/Doc/library/thread.rst b/Doc/library/thread.rst index 32437dc..6c59954 100644 --- a/Doc/library/thread.rst +++ b/Doc/library/thread.rst @@ -13,9 +13,11 @@ single: semaphores, binary This module provides low-level primitives for working with multiple threads -(a.k.a. :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of +(also called :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of control sharing their global data space. For synchronization, simple locks -(a.k.a. :dfn:`mutexes` or :dfn:`binary semaphores`) are provided. +(also called :dfn:`mutexes` or :dfn:`binary semaphores`) are provided. +The :mod:`threading` module provides an easier to use and higher-level +threading API built on top of this module. .. index:: single: pthreads diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 828d42b..1b82e4b 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -8,6 +8,7 @@ This module constructs higher-level threading interfaces on top of the lower level :mod:`thread` module. +See also the :mod:`mutex` and :mod:`Queue` modules. The :mod:`dummy_threading` module is provided for situations where :mod:`threading` cannot be used because :mod:`thread` is missing. diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index b0e731a..dd537d3 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -73,6 +73,20 @@ Other Language Changes Here are all of the changes that Python 2.6 makes to the core Python language. +* The :func:`complex` constructor now accepts strings containing + parenthesized complex numbers, letting ``complex(repr(cmplx))`` + will now round-trip values. For example, ``complex('(3+4j)')`` + now returns the value (3+4j). + + .. % Patch 1491866 + +* The string :meth:`translate` method now accepts ``None`` as the + translation table parameter, which is treated as the identity + transformation. This makes it easier to carry out operations + that only delete characters. (Contributed by Bengt Richter.) + + .. % Patch 1193128 + * An obscure change: when you use the the :func:`locals` function inside a :keyword:`class` statement, the resulting dictionary no longer returns free variables. (Free variables, in this case, are variables referred to in the @@ -124,6 +138,11 @@ complete list of changes, or look through the CVS logs for all the details. (Contributed by Fabian Kreutz.) +* An optional ``timeout`` parameter was added to the + :class:`ftplib.FTP` class constructor as well as the :meth:`connect` + method, specifying a timeout measured in seconds. (Added by Facundo + Batista.) + * The :func:`glob.glob` function can now return Unicode filenames if a Unicode path was used and Unicode filenames are matched within the directory. @@ -157,6 +176,21 @@ complete list of changes, or look through the CVS logs for all the details. .. % Patch #1490190 +* In the :mod:`os.path` module, the :func:`splitext` function + has been changed to not split on leading period characters. + This produces better results when operating on Unix's dot-files. + For example, ``os.path.splitext('.ipython')`` + now returns ``('.ipython', '')`` instead of ``('', '.ipython')``. + + .. % Bug #115886 + + A new function, :func:`relpath(path, start)` returns a relative path + from the ``start`` path, if it's supplied, or from the current + working directory to the destination ``path``. (Contributed by + Richard Barran.) + + .. % Patch 1339796 + * New functions in the :mod:`posix` module: :func:`chflags` and :func:`lchflags` are wrappers for the corresponding system calls (where they're available). Constants for the flag values are defined in the :mod:`stat` module; some @@ -166,14 +200,41 @@ complete list of changes, or look through the CVS logs for all the details. * The :mod:`rgbimg` module has been removed. -* The :mod:`smtplib` module now supports SMTP over SSL thanks to the addition - of the :class:`SMTP_SSL` class. This class supports an interface identical to - the existing :class:`SMTP` class. (Contributed by Monty Taylor.) +* The :mod:`smtplib` module now supports SMTP over SSL thanks to the + addition of the :class:`SMTP_SSL` class. This class supports an + interface identical to the existing :class:`SMTP` class. Both + class constructors also have an optional ``timeout`` parameter + that specifies a timeout for the initial connection attempt, measured in + seconds. + + An implementation of the LMTP protocol (:rfc:`2033`) was also added to + the module. LMTP is used in place of SMTP when transferring e-mail + between agents that don't manage a mail queue. + + (SMTP over SSL contributed by Monty Taylor; timeout parameter + added by Facundo Batista; LMTP implemented by Leif + Hedstrom.) + + .. % Patch #957003 + +* An optional ``timeout`` parameter was added to the + :class:`telnetlib.Telnet` class constructor, specifying a timeout + measured in seconds. (Added by Facundo Batista.) * The :mod:`test.test_support` module now contains a :func:`EnvironmentVarGuard` context manager that supports temporarily changing environment variables and automatically restores them to their old values. (Contributed by Brett Cannon.) +* The :mod:`timeit` module now accepts callables as well as strings + for the statement being timed and for the setup code. + Two convenience functions were added for creating + :class:`Timer` instances: + ``repeat(stmt, setup, time, repeat, number)`` and + ``timeit(stmt, setup, time, number)`` create an instance and call + the corresponding method. (Contributed by Erik Demaine.) + + .. % Patch #1533909 + .. % ====================================================================== .. % whole new modules get described in \subsections here |