mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-07-24 11:44:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Merge doc changes from 3.2.

Browse source 
rstlint complains about packaging docs but I’m working on those in
another patch.
This commit is contained in:
Éric Araujo 2011-09-01 05:57:12 +02:00
commit b8edbdf4b9
12 changed files with 37 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

4
Doc/c-api/init.rst
View file

@ -122,7 +122,7 @@ Process-wide parameters
program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The
returned string points into static storage; the caller should not modify its
value. This corresponds to the :makevar:`prefix` variable in the top-level
:file:`Makefile` and the :option:`--prefix` argument to the :program:`configure`
:file:`Makefile` and the ``--prefix`` argument to the :program:`configure`
script at build time. The value is available to Python code as ``sys.prefix``.
It is only useful on Unix. See also the next function.
@ -135,7 +135,7 @@ Process-wide parameters
program name is ``'/usr/local/bin/python'``, the exec-prefix is
``'/usr/local'``. The returned string points into static storage; the caller
should not modify its value. This corresponds to the :makevar:`exec_prefix`
variable in the top-level :file:`Makefile` and the :option:`--exec-prefix`
variable in the top-level :file:`Makefile` and the ``--exec-prefix``
argument to the :program:`configure` script at build time. The value is
available to Python code as ``sys.exec_prefix``. It is only useful on Unix.

2
Doc/faq/design.rst
View file

@ -667,7 +667,7 @@ construction of large programs.
Python 2.6 adds an :mod:`abc` module that lets you define Abstract Base Classes
(ABCs). You can then use :func:`isinstance` and :func:`issubclass` to check
whether an instance or a class implements a particular ABC. The
:mod:`collections` modules defines a set of useful ABCs such as
:mod:`collections.abc` module defines a set of useful ABCs such as
:class:`Iterable`, :class:`Container`, and :class:`MutableMapping`.
For Python, many of the advantages of interface specifications can be obtained

9
Doc/faq/programming.rst
View file

@ -473,15 +473,6 @@ calling another function by using ``*`` and ``**``::
...
g(x, *args, **kwargs)
In the unlikely case that you care about Python versions older than 2.0, use
:func:`apply`::
def f(x, *args, **kwargs):
...
kwargs['width'] = '14.3c'
...
apply(g, (x,)+args, kwargs)
How do I write a function with output parameters (call by reference)?
---------------------------------------------------------------------

4
Doc/faq/windows.rst
View file

@ -543,10 +543,10 @@ with multithreading-DLL options (``/MD``).
If you can't change compilers or flags, try using :c:func:`Py_RunSimpleString`.
A trick to get it to run an arbitrary file is to construct a call to
:func:`execfile` with the name of your file as argument.
:func:`exec` and :func:`open` with the name of your file as argument.
Also note that you can not mix-and-match Debug and Release versions. If you
wish to use the Debug Multithreaded DLL, then your module *must* have an "_d"
wish to use the Debug Multithreaded DLL, then your module *must* have ``_d``
appended to the base name.

6
Doc/glossary.rst
View file

@ -434,8 +434,8 @@ Glossary
mapping
A container object that supports arbitrary key lookups and implements the
methods specified in the :class:`~collections.Mapping` or
:class:`~collections.MutableMapping`
methods specified in the :class:`~collections.abc.Mapping` or
:class:`~collections.abc.MutableMapping`
:ref:`abstract base classes <collections-abstract-base-classes>`. Examples
include :class:`dict`, :class:`collections.defaultdict`,
:class:`collections.OrderedDict` and :class:`collections.Counter`.
@ -492,7 +492,7 @@ Glossary
:func:`builtins.open` and :func:`os.open` are distinguished by their
namespaces. Namespaces also aid readability and maintainability by making
it clear which module implements a function. For instance, writing
:func:`random.seed` or :func:`itertools.izip` makes it clear that those
:func:`random.seed` or :func:`itertools.islice` makes it clear that those
functions are implemented by the :mod:`random` and :mod:`itertools`
modules, respectively.

6
Doc/howto/logging.rst
View file

@ -412,10 +412,10 @@ With the logger object configured, the following methods create log messages:
:meth:`Logger.error`, and :meth:`Logger.critical` all create log records with
a message and a level that corresponds to their respective method names. The
message is actually a format string, which may contain the standard string
substitution syntax of :const:`%s`, :const:`%d`, :const:`%f`, and so on. The
substitution syntax of ``%s``, ``%d``, ``%f``, and so on. The
rest of their arguments is a list of objects that correspond with the
substitution fields in the message. With regard to :const:`**kwargs`, the
logging methods care only about a keyword of :const:`exc_info` and use it to
substitution fields in the message. With regard to ``**kwargs``, the
logging methods care only about a keyword of ``exc_info`` and use it to
determine whether to log exception information.
* :meth:`Logger.exception` creates a log message similar to

2
Doc/library/argparse.rst
View file

@ -155,7 +155,7 @@ ArgumentParser objects
conflicting optionals.
* prog_ - The name of the program (default:
:data:`sys.argv[0]`)
``sys.argv[0]``)
* usage_ - The string describing the program usage (default: generated)

4
Doc/library/base64.rst
View file

@ -45,8 +45,8 @@ The modern interface provides:
at least length 2 (additional characters are ignored) which specifies the
alternative alphabet used instead of the ``+`` and ``/`` characters.
The decoded string is returned. A `binascii.Error` is raised if *s* is
incorrectly padded.
The decoded string is returned. A :exc:`binascii.Error` exception is raised
if *s* is incorrectly padded.
If *validate* is ``False`` (the default), non-base64-alphabet characters are
discarded prior to the padding check. If *validate* is ``True``,

6
Doc/library/configparser.rst
View file

@ -806,17 +806,17 @@ To get interpolation, use :class:`ConfigParser`::
cfg = configparser.ConfigParser()
cfg.read('example.cfg')
# Set the optional `raw` argument of get() to True if you wish to disable
# Set the optional *raw* argument of get() to True if you wish to disable
# interpolation in a single get operation.
print(cfg.get('Section1', 'foo', raw=False)) # -> "Python is fun!"
print(cfg.get('Section1', 'foo', raw=True)) # -> "%(bar)s is %(baz)s!"
# The optional `vars` argument is a dict with members that will take
# The optional *vars* argument is a dict with members that will take
# precedence in interpolation.
print(cfg.get('Section1', 'foo', vars={'bar': 'Documentation',
'baz': 'evil'}))
# The optional `fallback` argument can be used to provide a fallback value
# The optional *fallback* argument can be used to provide a fallback value
print(cfg.get('Section1', 'foo'))
# -> "Python is fun!"

4
Doc/library/email.header.rst
View file

@ -141,11 +141,11 @@ Here is the :class:`Header` class description:
Returns an approximation of the :class:`Header` as a string, using an
unlimited line length. All pieces are converted to unicode using the
specified encoding and joined together appropriately. Any pieces with a
charset of `unknown-8bit` are decoded as `ASCII` using the `replace`
charset of ``'unknown-8bit'`` are decoded as ASCII using the ``'replace'``
error handler.
.. versionchanged:: 3.2
Added handling for the `unknown-8bit` charset.
Added handling for the ``'unknown-8bit'`` charset.
.. method:: __eq__(other)

8
Doc/library/inspect.rst
View file

@ -575,13 +575,13 @@ properties, will be invoked and :meth:`__getattr__` and :meth:`__getattribute__`
may be called.
For cases where you want passive introspection, like documentation tools, this
can be inconvenient. `getattr_static` has the same signature as :func:`getattr`
can be inconvenient. :func:`getattr_static` has the same signature as :func:`getattr`
but avoids executing code when it fetches attributes.
.. function:: getattr_static(obj, attr, default=None)
Retrieve attributes without triggering dynamic lookup via the
descriptor protocol, `__getattr__` or `__getattribute__`.
descriptor protocol, :meth:`__getattr__` or :meth:`__getattribute__`.
Note: this function may not be able to retrieve all attributes
that getattr can fetch (like dynamically created attributes)
@ -589,12 +589,12 @@ but avoids executing code when it fetches attributes.
that raise AttributeError). It can also return descriptors objects
instead of instance members.
If the instance `__dict__` is shadowed by another member (for example a
If the instance :attr:`__dict__` is shadowed by another member (for example a
property) then this function will be unable to find instance members.
.. versionadded:: 3.2
`getattr_static` does not resolve descriptors, for example slot descriptors or
:func:`getattr_static` does not resolve descriptors, for example slot descriptors or
getset descriptors on objects implemented in C. The descriptor object
is returned instead of the underlying attribute.

28
Doc/library/unittest.rst
View file

@ -293,7 +293,7 @@ used from the command line. The basic command-line usage is::
As a shortcut, ``python -m unittest`` is the equivalent of
``python -m unittest discover``. If you want to pass arguments to test
discovery the `discover` sub-command must be used explicitly.
discovery the ``discover`` sub-command must be used explicitly.
The ``discover`` sub-command has the following options:
@ -305,11 +305,11 @@ The ``discover`` sub-command has the following options:
.. cmdoption:: -s directory
Directory to start discovery ('.' default)
Directory to start discovery (``.`` default)
.. cmdoption:: -p pattern
Pattern to match test files ('test*.py' default)
Pattern to match test files (``test*.py`` default)
.. cmdoption:: -t directory
@ -724,8 +724,8 @@ Test cases
single test.
.. versionchanged:: 3.2
`TestCase` can be instantiated successfully without providing a method
name. This makes it easier to experiment with `TestCase` from the
:class:`TestCase` can be instantiated successfully without providing a method
name. This makes it easier to experiment with :class:`TestCase` from the
interactive interpreter.
*methodName* defaults to :meth:`runTest`.
@ -944,17 +944,17 @@ Test cases
+---------------------------------------------------------+--------------------------------------+------------+
| Method | Checks that | New in |
+=========================================================+======================================+============+
| :meth:`assertRaises(exc, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises `exc` | |
| :meth:`assertRaises(exc, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises *exc* | |
| <TestCase.assertRaises>` | | |
+---------------------------------------------------------+--------------------------------------+------------+
| :meth:`assertRaisesRegex(exc, re, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises `exc` | 3.1 |
| <TestCase.assertRaisesRegex>` | and the message matches `re` | |
| :meth:`assertRaisesRegex(exc, re, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises *exc* | 3.1 |
| <TestCase.assertRaisesRegex>` | and the message matches *re* | |
+---------------------------------------------------------+--------------------------------------+------------+
| :meth:`assertWarns(warn, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises `warn` | 3.2 |
| :meth:`assertWarns(warn, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises *warn* | 3.2 |
| <TestCase.assertWarns>` | | |
+---------------------------------------------------------+--------------------------------------+------------+
| :meth:`assertWarnsRegex(warn, re, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises `warn` | 3.2 |
| <TestCase.assertWarnsRegex>` | and the message matches `re` | |
| :meth:`assertWarnsRegex(warn, re, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises *warn* | 3.2 |
| <TestCase.assertWarnsRegex>` | and the message matches *re* | |
+---------------------------------------------------------+--------------------------------------+------------+
.. method:: assertRaises(exception, callable, *args, **kwds)
@ -1116,7 +1116,7 @@ Test cases
| :meth:`assertNotRegex(s, re) | ``not regex.search(s)`` | 3.2 |
| <TestCase.assertNotRegex>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertCountEqual(a, b) | `a` and `b` have the same | 3.2 |
| :meth:`assertCountEqual(a, b) | *a* and *b* have the same | 3.2 |
| <TestCase.assertCountEqual>` | elements in the same number, | |
| | regardless of their order | |
+---------------------------------------+--------------------------------+--------------+
@ -1911,7 +1911,7 @@ Loading and running tests
.. class:: TextTestRunner(stream=None, descriptions=True, verbosity=1, runnerclass=None, warnings=None)
A basic test runner implementation that outputs results to a stream. If *stream*
is `None`, the default, `sys.stderr` is used as the output stream. This class
is ``None``, the default, :data:`sys.stderr` is used as the output stream. This class
has a few configurable parameters, but is essentially very simple. Graphical
applications which run test suites should provide alternate implementations.
@ -1928,7 +1928,7 @@ Loading and running tests
Added the ``warnings`` argument.
.. versionchanged:: 3.2
The default stream is set to `sys.stderr` at instantiation time rather
The default stream is set to :data:`sys.stderr` at instantiation time rather
than import time.
.. method:: _makeResult()