summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
Diffstat (limited to 'Doc')
-rw-r--r--Doc/c-api/init.rst7
-rw-r--r--Doc/howto/functional.rst2
-rw-r--r--Doc/howto/regex.rst2
-rw-r--r--Doc/library/2to3.rst1
-rw-r--r--Doc/library/collections.rst6
-rw-r--r--Doc/library/decimal.rst2
-rw-r--r--Doc/library/json.rst4
-rw-r--r--Doc/library/shelve.rst3
-rw-r--r--Doc/library/subprocess.rst4
-rw-r--r--Doc/library/traceback.rst2
-rw-r--r--Doc/library/unittest.rst84
-rw-r--r--Doc/whatsnew/2.7.rst94
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