diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/c-api/import.rst | 9 | ||||
| -rw-r--r-- | Doc/data/refcounts.dat | 12 | ||||
| -rw-r--r-- | Doc/distutils/apiref.rst | 13 | ||||
| -rw-r--r-- | Doc/distutils/examples.rst | 97 | ||||
| -rw-r--r-- | Doc/glossary.rst | 4 | ||||
| -rw-r--r-- | Doc/library/functools.rst | 2 | ||||
| -rw-r--r-- | Doc/library/logging.rst | 78 | ||||
| -rw-r--r-- | Doc/library/math.rst | 6 | ||||
| -rw-r--r-- | Doc/library/os.rst | 4 | ||||
| -rw-r--r-- | Doc/library/socket.rst | 6 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 10 | ||||
| -rw-r--r-- | Doc/library/tarfile.rst | 2 | ||||
| -rw-r--r-- | Doc/library/test.rst | 72 | ||||
| -rw-r--r-- | Doc/library/unittest.rst | 2 | ||||
| -rw-r--r-- | Doc/library/warnings.rst | 17 | ||||
| -rw-r--r-- | Doc/reference/expressions.rst | 4 | ||||
| -rw-r--r-- | Doc/using/cmdline.rst | 4 | ||||
| -rw-r--r-- | Doc/whatsnew/2.6.rst | 2 | ||||
| -rw-r--r-- | Doc/whatsnew/2.7.rst | 140 |
19 files changed, 265 insertions, 219 deletions
diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst index ff79112..71c9d83 100644 --- a/Doc/c-api/import.rst +++ b/Doc/c-api/import.rst @@ -115,6 +115,9 @@ Importing Modules such modules have no way to know that the module object is an unknown (and probably damaged with respect to the module author's intents) state. + The module's :attr:`__file__` attribute will be set to the code object's + :cmember:`co_filename`. + This function will reload the module if it was already imported. See :cfunc:`PyImport_ReloadModule` for the intended way to reload a module. @@ -122,6 +125,12 @@ Importing Modules structures not already created will still not be created. +.. cfunction:: PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname) + + Like :cfunc:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of + the module object is set to *pathname* if it is non-``NULL``. + + .. cfunction:: long PyImport_GetMagicNumber() Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat index 721ea8c..6f16cad 100644 --- a/Doc/data/refcounts.dat +++ b/Doc/data/refcounts.dat @@ -499,6 +499,11 @@ PyImport_ExecCodeModule:PyObject*::+1: PyImport_ExecCodeModule:char*:name:: PyImport_ExecCodeModule:PyObject*:co:0: +PyImport_ExecCodeModuleEx:PyObject*::+1: +PyImport_ExecCodeModuleEx:char*:name:: +PyImport_ExecCodeModuleEx:PyObject*:co:0: +PyImport_ExecCodeModuleEx:char*:pathname:: + PyImport_GetMagicNumber:long::: PyImport_GetModuleDict:PyObject*::0: @@ -518,6 +523,13 @@ PyImport_ImportModuleEx:PyObject*:globals:0:??? PyImport_ImportModuleEx:PyObject*:locals:0:??? PyImport_ImportModuleEx:PyObject*:fromlist:0:??? +PyImport_ImportModuleLevel:PyObject*::+1: +PyImport_ImportModuleLevel:char*:name:: +PyImport_ImportModuleLevel:PyObject*:globals:0:??? +PyImport_ImportModuleLevel:PyObject*:locals:0:??? +PyImport_ImportModuleLevel:PyObject*:fromlist:0:??? +PyImport_ImportModuleLevel:int:level:: + PyImport_ReloadModule:PyObject*::+1: PyImport_ReloadModule:PyObject*:m:0: diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst index 69ec0de..6bcf3a7 100644 --- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@ -1944,19 +1944,6 @@ This is described in more detail in :pep:`301`. .. % todo -:mod:`distutils.command.check` --- Check the meta-data of a package -=================================================================== - -.. module:: distutils.command.check - :synopsis: Check the metadata of a package - - -The ``check`` command performs some tests on the meta-data of a package. -For example, it verifies that all required meta-data are provided as -the arguments passed to the :func:`setup` function. - -.. % todo - Creating a new Distutils command ================================ diff --git a/Doc/distutils/examples.rst b/Doc/distutils/examples.rst index a5a0239..b495928 100644 --- a/Doc/distutils/examples.rst +++ b/Doc/distutils/examples.rst @@ -233,103 +233,6 @@ With exactly the same source tree layout, this extension can be put in the ext_modules=[Extension('foopkg.foo', ['foo.c'])], ) -Checking a package -================== - -The ``check`` command allows you to verify if your package meta-data -meet the minimum requirements to build a distribution. - -To run it, just call it using your :file:`setup.py` script. If something is -missing, ``check`` will display a warning. - -Let's take an example with a simple script:: - - from distutils.core import setup - - setup(name='foobar') - -Running the ``check`` command will display some warnings:: - - $ python setup.py check - running check - warning: check: missing required meta-data: version, url - warning: check: missing meta-data: either (author and author_email) or - (maintainer and maintainer_email) must be supplied - - -If you use the reStructuredText syntax in the ``long_description`` field and -`docutils <http://docutils.sourceforge.net/>`_ is installed you can check if -the syntax is fine with the ``check`` command, using the ``restructuredtext`` -option. - -For example, if the :file:`setup.py` script is changed like this:: - - from distutils.core import setup - - desc = """\ - My description - ============= - - This is the description of the ``foobar`` package. - """ - - setup(name='foobar', version='1', author='tarek', - author_email='tarek@ziade.org', - url='http://example.com', long_description=desc) - -Where the long description is broken, ``check`` will be able to detect it -by using the :mod:`docutils` parser:: - - $ pythontrunk setup.py check --restructuredtext - running check - warning: check: Title underline too short. (line 2) - warning: check: Could not finish the parsing. - - -.. _reading-metadata: - -Reading the metadata -==================== - -The :func:`distutils.core.setup` function provides a command-line interface -that allows you to query the metadata fields of a project through the -:file:`setup.py` script of a given project:: - - $ python setup.py --name - distribute - -This call reads the ``name`` metadata by running the -:func:`distutils.core.setup` function. Although, when a source or binary -distribution is created with Distutils, the metadata fields are written -in a static file called :file:`PKG-INFO`. When a Distutils-based project is -installed in Python, the :file:`PKG-INFO` file is copied alongside the modules -and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`, -where ``NAME`` is the name of the project, ``VERSION`` its version as defined -in the Metadata, and ``pyX.X`` the major and minor version of Python like -``2.7`` or ``3.2``. - -You can read back this static file, by using the -:class:`distutils.dist.DistributionMetadata` class and its -:func:`read_pkg_file` method:: - - >>> from distutils.dist import DistributionMetadata - >>> metadata = DistributionMetadata() - >>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info')) - >>> metadata.name - 'distribute' - >>> metadata.version - '0.6.8' - >>> metadata.description - 'Easily download, build, install, upgrade, and uninstall Python packages' - -Notice that the class can also be instanciated with a metadata file path to -loads its values:: - - >>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info' - >>> DistributionMetadata(pkg_info_path).name - 'distribute' - - .. % \section{Multiple extension modules} .. % \label{multiple-ext} diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 8ec9e61..942f1e2 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -212,6 +212,8 @@ Glossary performs garbage collection via reference counting and a cyclic garbage collector that is able to detect and break reference cycles. + .. index:: single: generator + generator A function which returns an iterator. It looks like a normal function except that values are returned to the caller using a :keyword:`yield` @@ -225,7 +227,7 @@ Glossary .. index:: single: generator expression generator expression - An expression that returns a generator. It looks like a normal expression + An expression that returns an iterator. It looks like a normal expression followed by a :keyword:`for` expression defining a loop variable, range, and an optional :keyword:`if` expression. The combined expression generates values for an enclosing function:: diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 1511a25..6ae175a 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -40,7 +40,7 @@ The :mod:`functools` module defines the following functions: .. function:: total_ordering(cls) Given a class defining one or more rich comparison ordering methods, this - class decorator supplies the rest. This simplies the effort involved + class decorator supplies the rest. This simplifies the effort involved in specifying all of the possible rich comparison operations: The class must define one of :meth:`__lt__`, :meth:`__le__`, diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 347c72c..6324806 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -2012,6 +2012,84 @@ supports sending logging messages to a remote or local Unix syslog. or integers - if strings are passed, internal mapping dictionaries are used to convert them to integers. + **Priorities** + + +--------------------------+---------------+ + | Name (string) | Symbolic value| + +==========================+===============+ + | ``alert`` | LOG_ALERT | + +--------------------------+---------------+ + | ``crit`` or ``critical`` | LOG_CRIT | + +--------------------------+---------------+ + | ``debug`` | LOG_DEBUG | + +--------------------------+---------------+ + | ``emerg`` or ``panic`` | LOG_EMERG | + +--------------------------+---------------+ + | ``err`` or ``error`` | LOG_ERR | + +--------------------------+---------------+ + | ``info`` | LOG_INFO | + +--------------------------+---------------+ + | ``notice`` | LOG_NOTICE | + +--------------------------+---------------+ + | ``warn`` or ``warning`` | LOG_WARNING | + +--------------------------+---------------+ + + **Facilities** + + +---------------+---------------+ + | Name (string) | Symbolic value| + +===============+===============+ + | ``auth`` | LOG_AUTH | + +---------------+---------------+ + | ``authpriv`` | LOG_AUTHPRIV | + +---------------+---------------+ + | ``cron`` | LOG_CRON | + +---------------+---------------+ + | ``daemon`` | LOG_DAEMON | + +---------------+---------------+ + | ``ftp`` | LOG_FTP | + +---------------+---------------+ + | ``kern`` | LOG_KERN | + +---------------+---------------+ + | ``lpr`` | LOG_LPR | + +---------------+---------------+ + | ``mail`` | LOG_MAIL | + +---------------+---------------+ + | ``news`` | LOG_NEWS | + +---------------+---------------+ + | ``syslog`` | LOG_SYSLOG | + +---------------+---------------+ + | ``user`` | LOG_USER | + +---------------+---------------+ + | ``uucp`` | LOG_UUCP | + +---------------+---------------+ + | ``local0`` | LOG_LOCAL0 | + +---------------+---------------+ + | ``local1`` | LOG_LOCAL1 | + +---------------+---------------+ + | ``local2`` | LOG_LOCAL2 | + +---------------+---------------+ + | ``local3`` | LOG_LOCAL3 | + +---------------+---------------+ + | ``local4`` | LOG_LOCAL4 | + +---------------+---------------+ + | ``local5`` | LOG_LOCAL5 | + +---------------+---------------+ + | ``local6`` | LOG_LOCAL6 | + +---------------+---------------+ + | ``local7`` | LOG_LOCAL7 | + +---------------+---------------+ + + .. method:: mapPriority(levelname) + + Maps a logging level name to a syslog priority name. + You may need to override this if you are using custom levels, or + if the default algorithm is not suitable for your needs. The + default algorithm maps ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR`` and + ``CRITICAL`` to the equivalent syslog names, and all other level + names to "warning". + +.. _nt-eventlog-handler: NTEventLogHandler ^^^^^^^^^^^^^^^^^ diff --git a/Doc/library/math.rst b/Doc/library/math.rst index 09bccbc..9c3bd03 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -345,9 +345,9 @@ Constants :exc:`ValueError` for invalid operations like ``sqrt(-1.0)`` or ``log(0.0)`` (where C99 Annex F recommends signaling invalid operation or divide-by-zero), and :exc:`OverflowError` for results that overflow (for example, - ``exp(1000.0)``). A *NaN* will not be returned from any of the functions - above unless one or more of the input arguments was a *NaN*; in that case, - most functions will return a *NaN*, but (again following C99 Annex F) there + ``exp(1000.0)``). A NaN will not be returned from any of the functions + above unless one or more of the input arguments was a NaN; in that case, + most functions will return a NaN, but (again following C99 Annex F) there are some exceptions to this rule, for example ``pow(float('nan'), 0.0)`` or ``hypot(float('nan'), float('inf'))``. diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 0547154..dacf87a 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -437,6 +437,10 @@ process will then be assigned 3, 4, 5, and so forth. The name "file descriptor" is slightly deceptive; on Unix platforms, sockets and pipes are also referenced by file descriptors. +The :meth:`~file.fileno` method can be used to obtain the file descriptor +associated with a file object when required. Note that using the file +descriptor directly will bypass the file object methods, ignoring aspects such +as internal buffering of data. .. function:: close(fd) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 0fee6d5..e73aefb 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -622,9 +622,9 @@ correspond to Unix system calls applicable to sockets. Receive up to *nbytes* bytes from the socket, storing the data into a buffer rather than creating a new bytestring. If *nbytes* is not specified (or 0), - receive up to the size available in the given buffer. See the Unix manual page - :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults - to zero. + receive up to the size available in the given buffer. Returns the number of + bytes received. See the Unix manual page :manpage:`recv(2)` for the meaning + of the optional argument *flags*; it defaults to zero. .. method:: socket.send(bytes[, flags]) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 70eeca3..46a481a 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2143,12 +2143,12 @@ An example of dictionary view usage:: .. _typememoryview: -memoryview Types -================ +memoryview type +=============== -:class:`memoryview`\s allow Python code to access the internal data of an object -that supports the buffer protocol without copying. Memory can be interpreted as -simple bytes or complex data structures. +:class:`memoryview` objects allow Python code to access the internal data +of an object that supports the buffer protocol without copying. Memory +is generally interpreted as simple bytes. .. class:: memoryview(obj) diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index 8b53b57..50a5148 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -212,7 +212,7 @@ object, see :ref:`tarinfo-objects` for details. A :class:`TarFile` object can be used as a context manager in a :keyword:`with` statement. It will automatically be closed when the block is completed. Please note that in the event of an exception an archive opened for writing will not -be finalized, only the internally used file object will be closed. See the +be finalized; only the internally used file object will be closed. See the :ref:`tar-examples` section for a use case. .. versionadded:: 3.2 diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 9f013f8..cfd5b10 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -221,15 +221,15 @@ The :mod:`test.support` module defines the following constants: .. data:: TESTFN - Set to the name that a temporary file could use. Any temporary file that is - created should be closed and unlinked (removed). + Set to a name that is safe to use as the name of a temporary file. Any + temporary file that is created should be closed and unlinked (removed). The :mod:`test.support` module defines the following functions: .. function:: forget(module_name) - Remove the module named *module_name* from ``sys.modules`` and deletes any + Remove the module named *module_name* from ``sys.modules`` and delete any byte-compiled files of the module. @@ -272,49 +272,55 @@ The :mod:`test.support` module defines the following functions: This will run all tests defined in the named module. -.. function:: check_warnings(*filters, quiet=None) +.. function:: check_warnings(*filters, quiet=True) - A convenience wrapper for ``warnings.catch_warnings()`` that makes - it easier to test that a warning was correctly raised with a single - assertion. It is approximately equivalent to calling - ``warnings.catch_warnings(record=True)``. + A convenience wrapper for :func:`warnings.catch_warnings()` that makes it + easier to test that a warning was correctly raised. It is approximately + equivalent to calling ``warnings.catch_warnings(record=True)`` with + :meth:`warnings.simplefilter` set to ``always`` and with the option to + automatically validate the results that are recorded. - It accepts 2-tuples ``("message regexp", WarningCategory)`` as positional - arguments. If there's some ``*filters`` defined, or if the optional keyword - argument ``quiet`` is :const:`False`, it checks if the warnings are - effective. If some filter did not catch any warning, the test fails. If some - warnings are not caught, the test fails, too. To disable these checks, set - argument ``quiet`` to :const:`True`. + ``check_warnings`` accepts 2-tuples of the form ``("message regexp", + WarningCategory)`` as positional arguments. If one or more *filters* are + provided, or if the optional keyword argument *quiet* is :const:`False`, + it checks to make sure the warnings are as expected: each specified filter + must match at least one of the warnings raised by the enclosed code or the + test fails, and if any warnings are raised that do not match any of the + specified filters the test fails. To disable the first of these checks, + set *quiet* to :const:`True`. - Without argument, it defaults to:: + If no arguments are specified, it defaults to:: check_warnings(("", Warning), quiet=True) - Additionally, on entry to the context manager, a :class:`WarningRecorder` - instance is returned. The underlying warnings list is available via the - recorder object's :attr:`warnings` attribute, while the attributes of the - last raised warning are also accessible directly on the object. If no - warning has been raised, then the latter attributes will all be - :const:`None`. + In this case all warnings are caught and no errors are raised. - A :meth:`reset` method is also provided on the recorder object. This - method simply clears the warnings list. + On entry to the context manager, a :class:`WarningRecorder` instance is + returned. The underlying warnings list from + :func:`~warnings.catch_warnings` is available via the recorder object's + :attr:`warnings` attribute. As a convenience, the attributes of the object + representing the most recent warning can also be accessed directly through + the recorder object (see example below). If no warning has been raised, + then any of the attributes that would otherwise be expected on an object + representing a warning will return :const:`None`. - The context manager may be used like this:: + The recorder object also has a :meth:`reset` method, which clears the + warnings list. - import warnings - - with check_warnings(quiet=False): - exec('assert(False, "Hey!")') - warnings.warn(UserWarning("Hide me!")) + The context manager is designed to be used like this:: with check_warnings(("assertion is always true", SyntaxWarning), ("", UserWarning)): exec('assert(False, "Hey!")') warnings.warn(UserWarning("Hide me!")) + In this case if either warning was not raised, or some other warning was + raised, :func:`check_warnings` would raise an error. + + When a test needs to look more deeply into the warnings, rather than + just checking whether or not they occurred, code like this can be used:: + with check_warnings(quiet=True) as w: - warnings.simplefilter("always") warnings.warn("foo") assert str(w.args[0]) == "foo" warnings.warn("bar") @@ -324,8 +330,12 @@ The :mod:`test.support` module defines the following functions: w.reset() assert len(w.warnings) == 0 + + Here all warnings will be caught, and the test code tests the captured + warnings directly. + .. versionchanged:: 3.2 - New optional attributes ``*filters`` and ``quiet``. + New optional arguments *filters* and *quiet*. .. function:: captured_stdout() diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 5ed75d5..9bd85d5 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -661,6 +661,8 @@ Test cases Calling this during the a test method or :meth:`setUp` skips the current test. See :ref:`unittest-skipping` for more information. + .. versionadded:: 2.7 + .. method:: debug() diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst index 36d47ad..67d93fa 100644 --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -180,7 +180,10 @@ the warning using the :class:`catch_warnings` context manager:: While within the context manager all warnings will simply be ignored. This allows you to use known-deprecated code without having to see the warning while not suppressing the warning for other code that might not be aware of its use -of deprecated code. +of deprecated code. Note: this can only be guaranteed in a single-threaded +application. If two or more threads use the :class:`catch_warnings` context +manager at the same time, the behavior is undefined. + .. _warning-testing: @@ -218,7 +221,9 @@ Once the context manager exits, the warnings filter is restored to its state when the context was entered. This prevents tests from changing the warnings filter in unexpected ways between tests and leading to indeterminate test results. The :func:`showwarning` function in the module is also restored to -its original value. +its original value. Note: this can only be guaranteed in a single-threaded +application. If two or more threads use the :class:`catch_warnings` context +manager at the same time, the behavior is undefined. When testing multiple operations that raise the same kind of warning, it is important to test them in a manner that confirms each operation is raising @@ -337,3 +342,11 @@ Available Context Managers module returned when you import :mod:`warnings` whose filter will be protected. This argument exists primarily for testing the :mod:`warnings` module itself. + + .. note:: + + The :class:`catch_warnings` manager works by replacing and + then later restoring the module's + :func:`showwarning` function and internal list of filter + specifications. This means the context manager is modifying + global state and therefore is not thread-safe. diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 07647b3..e568ddf 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -914,7 +914,9 @@ the left or right by the number of bits given by the second argument. A right shift by *n* bits is defined as division by ``pow(2,n)``. A left shift by *n* bits is defined as multiplication with ``pow(2,n)``. -.. note:: In the current implementation, the right-hand operand is required +.. note:: + + In the current implementation, the right-hand operand is required to be at most :attr:`sys.maxsize`. If the right-hand operand is larger than :attr:`sys.maxsize` an :exc:`OverflowError` exception is raised. diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index e0f3a3a..260794d 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -297,7 +297,7 @@ Miscellaneous options the remaining fields. Empty fields match all values; trailing empty fields may be omitted. The *message* field matches the start of the warning message printed; this match is case-insensitive. The *category* field matches the - warning category. This must be a class name; the match test whether the + warning category. This must be a class name; the match tests whether the actual warning category of the message is a subclass of the specified warning category. The full class name must be given. The *module* field matches the (fully-qualified) module name; this match is case-sensitive. The *line* @@ -476,7 +476,7 @@ These environment variables influence Python's behavior. .. envvar:: PYTHONWARNINGS - This is the equivalent to the :option:`-W` option. If set to a comma + This is equivalent to the :option:`-W` option. If set to a comma separated string, it is equivalent to specifying :option:`-W` multiple times. diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index cb5837a..fa237ca 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -1792,7 +1792,7 @@ changes, or look through the Subversion logs for all the details. were applied. (Maintained by Josiah Carlson; see :issue:`1736190` for one patch.) -* The :mod:`bsddb` module also has a new maintainer, Jesús Cea, and the package +* The :mod:`bsddb` module also has a new maintainer, Jesús Cea Avion, and the package is now available as a standalone package. The web page for the package is `www.jcea.es/programacion/pybsddb.htm <http://www.jcea.es/programacion/pybsddb.htm>`__. diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst index dcea4f2..593c9fa 100644 --- a/Doc/whatsnew/2.7.rst +++ b/Doc/whatsnew/2.7.rst @@ -10,6 +10,7 @@ .. Big jobs: argparse, ElementTree 1.3, pep 391, 3106, sysconfig .. unittest test discovery +.. hyperlink all the methods & functions. .. $Id$ Rules for maintenance: @@ -238,10 +239,33 @@ module, but it's easier to use. PEP 389: The argparse Module for Parsing Command Lines ====================================================== -XXX write this section. +The :mod:`argparse` module for parsing command-line arguments was +added, intended as a more powerful replacement for the +:mod:`optparse` module. + +This means Python now supports three different modules for parsing +command-line arguments: :mod:`getopt`, :mod:`optparse`, and +:mod:`argparse`. The :mod:`getopt` module closely resembles the C +:cfunc:`getopt` function, so it remains useful if you're writing a +Python prototype that will eventually be rewritten in C. +:mod:`optparse` becomes redundant, but there are no plans to remove it +because there are many scripts still using it, and there's no +automated way to update these scripts. (Making the :mod:`argparse` +API consistent with :mod:`optparse`'s interface was discussed but +rejected as too messy and difficult.) + +To summarize, if you're writing a new script and don't need to worry +about compatibility with earlier versions of Python, use +:mod:`argparse` instead of :mod:`optparse`. + +XXX need an example .. seealso:: + `argparse module documentation <http://docs.python.org/dev/library/argparse.html>`__ + + `Upgrading optparse code to use argparse <http://docs.python.org/dev/library/argparse.html#upgrading-optparse-code>`__ + :pep:`389` - argparse - New Command Line Parsing Module PEP written and implemented by Steven Bethard. @@ -478,6 +502,29 @@ Some smaller changes made to the core Python language are: .. ====================================================================== +.. _new-27-interpreter: + +Interpreter Changes +------------------------------- + +A new environment variable, :envvar:`PYTHONWARNINGS`, +allows controlling warnings. It should be set to a string +containing warning settings, equivalent to those +used with the :option:`-W` switch, separated by commas. +(Contributed by Brian Curtin; :issue:`7301`.) + +For example, the following setting will print warnings every time +they occur, but turn warnings from the :mod:`Cookie` module into an +error. (The exact syntax for setting an environment variable varies +across operating systems and shells, so it may be different for you.) + +:: + + export PYTHONWARNINGS=all,error:::Cookie:0 + + +.. ====================================================================== + Optimizations ------------- @@ -671,10 +718,13 @@ changes, or look through the Subversion logs for all the details. (Added by Raymond Hettinger; :issue:`1818`.) - The :class:`~collections.deque` data type now exposes its maximum length as the - read-only :attr:`~collections.deque.maxlen` attribute, and has a - :meth:`~collections.deque.reverse` method that reverses the elements of the deque in-place. - (Added by Raymond Hettinger.) + The :class:`~collections.deque` data type now has a + :meth:`~collections.deque.count` method that returns the number of + contained elements equal to the supplied argument *x*, and a + :meth:`~collections.deque.reverse` method that reverses the elements + of the deque in-place. :class:`deque` also exposes its maximum + length as the read-only :attr:`~collections.deque.maxlen` attribute. + (Both features added by Raymond Hettinger.) * The :mod:`copy` module's :func:`~copy.deepcopy` function will now correctly copy bound instance methods. (Implemented by @@ -720,6 +770,12 @@ changes, or look through the Subversion logs for all the details. as arguments to its constructor. (Implemented by Mark Dickinson; :issue:`5812`.) + An oversight was fixed, making the :class:`Fraction` match the other + numeric types; ordering comparisons (``<``, ``<=``, ``>``, ``>=``) between + fractions and complex numbers now raise a :exc:`TypeError`. + + .. revision 79455 + * New class: a new :class:`~ftplib.FTP_TLS` class in the :mod:`ftplib` module provides secure FTP connections using TLS encapsulation of authentication as well as @@ -730,6 +786,21 @@ changes, or look through the Subversion logs for all the details. uploads thanks to an added *rest* parameter (patch by Pablo Mouzo; :issue:`6845`.) +* New class decorator: :func:`total_ordering` in the :mod:`functools` + module takes a class that defines an :meth:`__eq__` method and one of + :meth:`__lt__`, :meth:`__le__`, :meth:`__gt__`, or :meth:`__ge__`, + and generates the missing comparison methods. Since the + :meth:`__cmp__` method is being deprecated in Python 3.x, + this decorator makes it easier to define ordered classes. + (Added by Raymond Hettinger; :issue:`5479`.) + + New function: :func:`cmp_to_key` will take an old-style comparison + function that expects two arguments and return a new callable that + can be used as the *key* parameter to functions such as + :func:`sorted`, :func:`min` and :func:`max`, etc. The primary + intended use is to help with making code compatible with Python 3.x. + (Added by Raymond Hettinger.) + * New function: the :mod:`gc` module's :func:`~gc.is_tracked` returns true if a given instance is tracked by the garbage collector, false otherwise. (Contributed by Antoine Pitrou; :issue:`4688`.) @@ -905,7 +976,12 @@ changes, or look through the Subversion logs for all the details. * The :mod:`socket` module's :class:`~ssl.SSL` objects now support the buffer API, which fixed a test suite failure. (Fixed by Antoine - Pitrou; :issue:`7133`.) + Pitrou; :issue:`7133`.) The version of OpenSSL being used is + now available as the module attributes + :attr:`OPENSSL_VERSION` (a string), + :attr:`OPENSSL_VERSION_INFO` (a 5-tuple), and + :attr:`OPENSSL_VERSION_NUMBER` (an integer). (Added by Antoine Pitrou; + :issue:`8321`.) The :func:`~socket.create_connection` function gained a *source_address* parameter, a ``(host, port)`` 2-tuple @@ -1057,58 +1133,6 @@ XXX write this. .. whole new modules get described in subsections here -Distutils Enhancements ---------------------------------- - -XXX all of this work has been moved to Distutils2 -XXX Not sure what we should say here - -Distutils is being more actively developed, thanks to Tarek Ziadé -who has taken over maintenance of the package, so there are a number -of fixes and improvements. - -A new :file:`setup.py` subcommand, ``check``, will check that the -arguments being passed to the :func:`setup` function are complete -and correct (:issue:`5732`). - -Byte-compilation by the ``install_lib`` subcommand is now only done -if the ``sys.dont_write_bytecode`` setting allows it (:issue:`7071`). - -:func:`distutils.sdist.add_defaults` now uses -*package_dir* and *data_files* to create the MANIFEST file. -:mod:`distutils.sysconfig` now reads the :envvar:`AR` and -:envvar:`ARFLAGS` environment variables. - -.. ARFLAGS done in #5941 - -It is no longer mandatory to store clear-text passwords in the -:file:`.pypirc` file when registering and uploading packages to PyPI. As long -as the username is present in that file, the :mod:`distutils` package will -prompt for the password if not present. (Added by Tarek Ziadé, -based on an initial contribution by Nathan Van Gheem; :issue:`4394`.) - -A Distutils setup can now specify that a C extension is optional by -setting the *optional* option setting to true. If this optional is -supplied, failure to build the extension will not abort the build -process, but instead simply not install the failing extension. -(Contributed by Georg Brandl; :issue:`5583`.) - -The :class:`distutils.dist.DistributionMetadata` class' -:meth:`read_pkg_file` method will read the contents of a package's -:file:`PKG-INFO` metadata file. For an example of its use, see -:ref:`reading-metadata`. -(Contributed by Tarek Ziadé; :issue:`7457`.) - -:file:`setup.py` files will now accept a :option:`--no-user-cfg` switch -to skip reading the :file:`~/.pydistutils.cfg` file. (Suggested by -by Michael Hoffman, and implemented by Paul Winkler; :issue:`1180`.) - -When creating a tar-format archive, the ``sdist`` subcommand now -allows specifying the user id and group that will own the files in the -archives using the :option:`--owner` and :option:`--group` switches -(:issue:`6516`). - - Unit Testing Enhancements --------------------------------- |