diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/c-api/init.rst | 7 | ||||
| -rw-r--r-- | Doc/howto/functional.rst | 2 | ||||
| -rw-r--r-- | Doc/howto/regex.rst | 2 | ||||
| -rw-r--r-- | Doc/library/2to3.rst | 1 | ||||
| -rw-r--r-- | Doc/library/collections.rst | 6 | ||||
| -rw-r--r-- | Doc/library/decimal.rst | 2 | ||||
| -rw-r--r-- | Doc/library/json.rst | 4 | ||||
| -rw-r--r-- | Doc/library/shelve.rst | 3 | ||||
| -rw-r--r-- | Doc/library/subprocess.rst | 4 | ||||
| -rw-r--r-- | Doc/library/traceback.rst | 2 | ||||
| -rw-r--r-- | Doc/library/unittest.rst | 84 | ||||
| -rw-r--r-- | Doc/whatsnew/2.7.rst | 94 |
12 files changed, 169 insertions, 42 deletions
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 299af7f..6e185fa 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -416,10 +416,9 @@ the I/O is waiting for the I/O operation to complete. The Python interpreter needs to keep some bookkeeping information separate per thread --- for this it uses a data structure called :ctype:`PyThreadState`. There's one global variable, however: the pointer to the current -:ctype:`PyThreadState` structure. While most thread packages have a way to -store "per-thread global data," Python's internal platform independent thread -abstraction doesn't support this yet. Therefore, the current thread state must -be manipulated explicitly. +:ctype:`PyThreadState` structure. Before the addition of :dfn:`thread-local +storage` (:dfn:`TLS`) the current thread state had to be manipulated +explicitly. This is easy enough in most cases. Most code manipulating the global interpreter lock has the following simple structure:: diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst index 9aa0aed..920dc2d 100644 --- a/Doc/howto/functional.rst +++ b/Doc/howto/functional.rst @@ -473,7 +473,7 @@ Here's a sample usage of the ``generate_ints()`` generator: >>> gen = generate_ints(3) >>> gen - <generator object at ...> + <generator object generate_ints at ...> >>> next(gen) 0 >>> next(gen) diff --git a/Doc/howto/regex.rst b/Doc/howto/regex.rst index 2623867..7144298 100644 --- a/Doc/howto/regex.rst +++ b/Doc/howto/regex.rst @@ -264,7 +264,7 @@ performing string substitutions. :: >>> import re >>> p = re.compile('ab*') >>> p - <re.RegexObject instance at 80b4150> + <_sre.SRE_Pattern object at 80b4150> :func:`re.compile` also accepts an optional *flags* argument, used to enable various special features and syntax variations. We'll go over the available diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst index 90284af..9b2b4e4 100644 --- a/Doc/library/2to3.rst +++ b/Doc/library/2to3.rst @@ -352,6 +352,7 @@ and off individually. They are described here in more detail. :synopsis: the 2to3 library .. moduleauthor:: Guido van Rossum .. moduleauthor:: Collin Winter +.. moduleauthor:: Benjamin Peterson <benjamin@python.org> .. note:: diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index c334dc7..fca84bd 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -169,7 +169,7 @@ For example:: class is similar to bags or multisets in other languages. Elements are counted from an *iterable* or initialized from another - *mapping* (or counter):: + *mapping* (or counter): >>> c = Counter() # a new, empty counter >>> c = Counter('gallahad') # a new counter from an iterable @@ -177,7 +177,7 @@ For example:: >>> c = Counter(cats=4, dogs=8) # a new counter from keyword args Counter objects have a dictionary interface except that they return a zero - count for missing items instead of raising a :exc:`KeyError`:: + count for missing items instead of raising a :exc:`KeyError`: >>> c = Counter(['eggs', 'ham']) >>> c['bacon'] # count of a missing element is zero @@ -210,7 +210,7 @@ For example:: Return a list of the *n* most common elements and their counts from the most common to the least. If *n* is not specified, :func:`most_common` returns *all* elements in the counter. Elements with equal counts are - ordered arbitrarily:: + ordered arbitrarily: >>> Counter('abracadabra').most_common(3) [('a', 5), ('r', 2), ('b', 2)] diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index 2b4d156..a27fbf4 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -1746,7 +1746,7 @@ the :const:`Inexact` trap is set, it is also useful for validation: >>> Decimal('3.214').quantize(TWOPLACES, context=Context(traps=[Inexact])) Traceback (most recent call last): ... - Inexact + Inexact: None Q. Once I have valid two place inputs, how do I maintain that invariant throughout an application? diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 819c339..955c25b 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -165,12 +165,12 @@ Basic Usage document) to a Python object. *object_hook* is an optional function that will be called with the result of - any object literal decode (a :class:`dict`). The return value of + any object literal decoded (a :class:`dict`). The return value of *object_hook* will be used instead of the :class:`dict`. This feature can be used to implement custom decoders (e.g. JSON-RPC class hinting). *object_pairs_hook* is an optional function that will be called with the - result of any object literal decode with an ordered list of pairs. The + result of any object literal decoded with an ordered list of pairs. The return value of *object_pairs_hook* will be used instead of the :class:`dict`. This feature can be used to implement custom decoders that rely on the order that the key and value pairs are decoded (for example, diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst index 8121004..8c1f08b 100644 --- a/Doc/library/shelve.rst +++ b/Doc/library/shelve.rst @@ -1,4 +1,3 @@ - :mod:`shelve` --- Python object persistence =========================================== @@ -35,7 +34,7 @@ lots of shared sub-objects. The keys are ordinary strings. accessed entries are written back (there is no way to determine which accessed entries are mutable, nor which ones were actually mutated). -Shelve objects support all methods supported by dictionaries. This eases the +Shelf objects support all methods supported by dictionaries. This eases the transition from dictionary based scripts to those requiring persistent storage. One additional method is supported: diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 3b6c8cc..7952f68 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -174,13 +174,13 @@ This module also defines four shortcut functions: :attr:`returncode` attribute and output in the :attr:`output` attribute. - The arguments are the same as for the :class:`Popen` constructor. Example: + The arguments are the same as for the :class:`Popen` constructor. Example:: >>> subprocess.check_output(["ls", "-l", "/dev/null"]) 'crw-rw-rw- 1 root root 1, 3 Oct 18 2007 /dev/null\n' The stdout argument is not allowed as it is used internally. - To capture standard error in the result, use stderr=subprocess.STDOUT. + To capture standard error in the result, use ``stderr=subprocess.STDOUT``:: >>> subprocess.check_output( ["/bin/sh", "-c", "ls non_existent_file ; exit 0"], diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 6929c1d..5c42740 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -228,7 +228,7 @@ The output for the example would look similar to this: *** extract_tb: [('<doctest...>', 10, '<module>', 'lumberjack()'), ('<doctest...>', 4, 'lumberjack', 'bright_side_of_death()'), - (u'<doctest...>', 7, 'bright_side_of_death', 'return tuple()[0]')] + ('<doctest...>', 7, 'bright_side_of_death', 'return tuple()[0]')] *** format_tb: [' File "<doctest...>", line 10, in <module>\n lumberjack()\n', ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n', diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 675114a..abeb8a0 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -954,7 +954,6 @@ Test cases along with the method name. .. versionchanged:: 3.1 - In earlier versions this only returned the first line of the test method's docstring, if available or the :const:`None`. That led to undesirable behavior of not printing the test name when someone was @@ -978,6 +977,36 @@ Test cases .. versionadded:: 3.1 + .. method:: addCleanup(function[, *args[, **kwargs]]) + + Add a function to be called after :meth:`tearDown` to cleanup resources + used during the test. Functions will be called in reverse order to the + order they are added (LIFO). They are called with any arguments and + keyword arguments passed into :meth:`addCleanup` when they are + added. + + If :meth:`setUp` fails, meaning that :meth:`tearDown` is not called, + then any cleanup functions added will still be called. + + .. versionadded:: 2.7 + + + .. method:: doCleanups() + + This method is called uncoditionally after :meth:`tearDown`, or + after :meth:`setUp` if :meth:`setUp` raises an exception. + + It is responsible for calling all the cleanup functions added by + :meth:`addCleanup`. If you need cleanup functions to be called + *prior* to :meth:`tearDown` then you can call :meth:`doCleanups` + yourself. + + :meth:`doCleanups` pops methods off the stack of cleanup + functions one at a time, so it can be called at any time. + + .. versionadded:: 2.7 + + .. class:: FunctionTestCase(testFunc[, setUp[, tearDown[, description]]]) This class implements the portion of the :class:`TestCase` interface which @@ -1046,6 +1075,20 @@ Grouping tests Return the number of tests represented by this test object, including all individual tests and sub-suites. + + .. method:: __iter__() + + Tests grouped by a :class:`TestSuite` are always accessed by iteration. + Subclasses can lazily provide tests by overriding :meth:`__iter__`. Note + that this method maybe called several times on a single suite + (for example when counting tests or comparing for equality) + so the tests returned must be the same for repeated iterations. + + .. versionchanged:: 2.7 + In earlier versions the :class:`TestSuite` accessed tests directly rather + than through iteration, so overriding :meth:`__iter__` wasn't sufficient + for providing tests. + In the typical usage of a :class:`TestSuite` object, the :meth:`run` method is invoked by a :class:`TestRunner` rather than by the end-user test harness. @@ -1190,7 +1233,6 @@ Loading and running tests holding formatted tracebacks. Each tuple represents a test which raised an unexpected exception. - .. attribute:: failures A list containing 2-tuples of :class:`TestCase` instances and strings @@ -1266,6 +1308,20 @@ Loading and running tests The default implementation does nothing. + .. method:: startTestRun(test) + + Called once before any tests are executed. + + .. versionadded:: 2.7 + + + .. method:: stopTestRun(test) + + Called once before any tests are executed. + + .. versionadded:: 2.7 + + .. method:: addError(test, err) Called when the test case *test* raises an unexpected exception *err* is a @@ -1335,8 +1391,14 @@ Loading and running tests has a few configurable parameters, but is essentially very simple. Graphical applications which run test suites should provide alternate implementations. + .. method:: _makeResult() + + This method returns the instance of ``TestResult`` used by :meth:`run`. + It is not intended to be called directly, but can be overridden in + subclasses to provide a custom ``TestResult``. -.. function:: main([module[, defaultTest[, argv[, testRunner[, testLoader]]]]]) + +.. function:: main([module[, defaultTest[, argv[, testRunner[, testLoader[, exit]]]]]]) A command-line program that runs a set of tests; this is primarily for making test modules conveniently executable. The simplest use for this function is to @@ -1346,4 +1408,18 @@ Loading and running tests unittest.main() The *testRunner* argument can either be a test runner class or an already - created instance of it. + created instance of it. By default ``main`` calls :func:`sys.exit` with + an exit code indicating success or failure of the tests run. + + ``main`` supports being used from the interactive interpreter by passing in the + argument ``exit=False``. This displays the result on standard output without + calling :func:`sys.exit`:: + + >>> from unittest import main + >>> main(module='test_module', exit=False) + + Calling ``main`` actually returns an instance of the ``TestProgram`` class. + This stores the result of the tests run as the ``result`` attribute. + + .. versionchanged:: 2.7 + The ``exit`` parameter was added. diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst index f7dab79..9182c453 100644 --- a/Doc/whatsnew/2.7.rst +++ b/Doc/whatsnew/2.7.rst @@ -121,6 +121,31 @@ Some smaller changes made to the core Python language are: (Contributed by Fredrik Johansson and Victor Stinner; :issue:`3439`.) +* Conversions from long integers and regular integers to floating + point now round differently, returning the floating-point number + closest to the number. This doesn't matter for small integers that + can be converted exactly, but for large numbers that will + unavoidably lose precision, Python 2.7 will now approximate more + closely. For example, Python 2.6 computed the following:: + + >>> n = 295147905179352891391 + >>> float(n) + 2.9514790517935283e+20 + >>> n - long(float(n)) + 65535L + + Python 2.7's floating-point result is larger, but much closer to the + true value:: + + >>> n = 295147905179352891391 + >>> float(n) + 2.9514790517935289e+20 + >>> n-long(float(n) + ... ) + -1L + + (Implemented by Mark Dickinson; :issue:`3166`.) + * The :class:`bytearray` type's :meth:`translate` method will now accept ``None`` as its first argument. (Fixed by Georg Brandl; :issue:`4759`.) @@ -220,21 +245,24 @@ changes, or look through the Subversion logs for all the details. * New class: the :class:`Counter` class in the :mod:`collections` module is useful for tallying data. :class:`Counter` instances behave mostly like dictionaries but return zero for missing keys instead of - raising a :exc:`KeyError`:: - - >>> from collections import Counter - >>> c=Counter() - >>> for letter in 'here is a sample of english text': - ... c[letter] += 1 - ... - >>> c - Counter({' ': 6, 'e': 5, 's': 3, 'a': 2, 'i': 2, 'h': 2, - 'l': 2, 't': 2, 'g': 1, 'f': 1, 'm': 1, 'o': 1, 'n': 1, - 'p': 1, 'r': 1, 'x': 1}) - >>> c['e'] - 5 - >>> c['z'] - 0 + raising a :exc:`KeyError`: + + .. doctest:: + :options: +NORMALIZE_WHITESPACE + + >>> from collections import Counter + >>> c = Counter() + >>> for letter in 'here is a sample of english text': + ... c[letter] += 1 + ... + >>> c + Counter({' ': 6, 'e': 5, 's': 3, 'a': 2, 'i': 2, 'h': 2, + 'l': 2, 't': 2, 'g': 1, 'f': 1, 'm': 1, 'o': 1, 'n': 1, + 'p': 1, 'r': 1, 'x': 1}) + >>> c['e'] + 5 + >>> c['z'] + 0 There are two additional :class:`Counter` methods: :meth:`most_common` returns the N most common elements and their counts, and :meth:`elements` @@ -247,7 +275,7 @@ changes, or look through the Subversion logs for all the details. 'a', 'a', ' ', ' ', ' ', ' ', ' ', ' ', 'e', 'e', 'e', 'e', 'e', 'g', 'f', 'i', 'i', 'h', 'h', 'm', 'l', 'l', 'o', 'n', 'p', 's', - 's', 's', 'r', 't', 't', 'x'] + 's', 's', 'r', 't', 't', 'x' Contributed by Raymond Hettinger; :issue:`1696199`. @@ -257,7 +285,8 @@ changes, or look through the Subversion logs for all the details. renamed to legal names that are derived from the field's position within the list of fields: - >>> T=namedtuple('T', ['field1', '$illegal', 'for', 'field2'], rename=True) + >>> from collections import namedtuple + >>> T = namedtuple('T', ['field1', '$illegal', 'for', 'field2'], rename=True) >>> T._fields ('field1', '_1', '_2', 'field2') @@ -294,6 +323,10 @@ changes, or look through the Subversion logs for all the details. ``Decimal('0.1000000000000000055511151231257827021181583404541015625')``. (Implemented by Raymond Hettinger; :issue:`4796`.) +* The :class:`Fraction` class will now accept two rational numbers + as arguments to its constructor. + (Implemented by Mark Dickinson; :issue:`5812`.) + * New function: the :mod:`gc` module's :func:`is_tracked` returns true if a given instance is tracked by the garbage collector, false otherwise. (Contributed by Antoine Pitrou; :issue:`4688`.) @@ -419,6 +452,13 @@ changes, or look through the Subversion logs for all the details. (Implemented by Antoine Pitrou; :issue:`4444`.) + The methods :meth:`addCleanup` and :meth:`doCleanups` were added. + :meth:`addCleanup` allows you to add cleanup functions that + will be called unconditionally (after :meth:`setUp` if + :meth:`setUp` fails, otherwise after :meth:`tearDown`). This allows + for much simpler resource allocation and deallocation during tests. + :issue:`5679` + A number of new methods were added that provide more specialized tests. Many of these methods were written by Google engineers for use in their test suites; Gregory P. Smith, Michael Foord, and @@ -473,6 +513,14 @@ changes, or look through the Subversion logs for all the details. to provide additional information about why the two objects are matching, much as the new sequence comparison methods do. + :func:`unittest.main` now takes an optional ``exit`` argument. + If False ``main`` doesn't call :func:`sys.exit` allowing it to + be used from the interactive interpreter. :issue:`3379`. + + :class:`TestResult` has new :meth:`startTestRun` and + :meth:`stopTestRun` methods; called immediately before + and after a test run. :issue:`5728` by Robert Collins. + * The :func:`is_zipfile` function in the :mod:`zipfile` module will now accept a file object, in addition to the path names accepted in earlier versions. (Contributed by Gabriel Genellina; :issue:`4756`.) @@ -553,6 +601,10 @@ Changes to Python's build process and to the C API include: is particularly useful for asynchronous IO operations. (Contributed by Kristjan Valur Jonsson; :issue:`4293`.) +* Global symbols defined by the :mod:`ctypes` module are now prefixed + with ``Py`, or with ``_ctypes``. (Implemented by Thomas + Heller; :issue:`3102`.) + * The :program:`configure` script now checks for floating-point rounding bugs on certain 32-bit Intel chips and defines a :cmacro:`X87_DOUBLE_ROUNDING` preprocessor definition. No code currently uses this definition, @@ -591,10 +643,10 @@ Other Changes and Fixes * When importing a module from a :file:`.pyc` or :file:`.pyo` file with an existing :file:`.py` counterpart, the :attr:`co_filename` - attributes of all code objects if the original filename is obsolete, - which can happen if the file has been renamed, moved, or is accessed - through different paths. (Patch by Ziga Seilnacht and Jean-Paul - Calderone; :issue:`1180193`.) + attributes of the resulting code objects are overwritten when the + original filename is obsolete. This can happen if the file has been + renamed, moved, or is accessed through different paths. (Patch by + Ziga Seilnacht and Jean-Paul Calderone; :issue:`1180193`.) * The :file:`regrtest.py` script now takes a :option:`--randseed=` switch that takes an integer that will be used as the random seed |