diff options
| -rw-r--r-- | Doc/c-api/init.rst | 4 | ||||
| -rw-r--r-- | Doc/documenting/markup.rst | 5 | ||||
| -rw-r--r-- | Doc/faq/design.rst | 2 | ||||
| -rw-r--r-- | Doc/faq/programming.rst | 9 | ||||
| -rw-r--r-- | Doc/faq/windows.rst | 4 | ||||
| -rw-r--r-- | Doc/glossary.rst | 2 | ||||
| -rw-r--r-- | Doc/howto/logging.rst | 6 | ||||
| -rw-r--r-- | Doc/library/argparse.rst | 2 | ||||
| -rw-r--r-- | Doc/library/base64.rst | 4 | ||||
| -rw-r--r-- | Doc/library/configparser.rst | 6 | ||||
| -rw-r--r-- | Doc/library/email.header.rst | 4 | ||||
| -rw-r--r-- | Doc/library/functions.rst | 36 | ||||
| -rw-r--r-- | Doc/library/inspect.rst | 8 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 4 | ||||
| -rw-r--r-- | Doc/library/string.rst | 2 | ||||
| -rw-r--r-- | Doc/library/unittest.rst | 30 | ||||
| -rw-r--r-- | Lib/compileall.py | 14 | ||||
| -rw-r--r-- | Lib/distutils/tests/support.py | 7 | ||||
| -rw-r--r-- | Lib/pipes.py | 2 |
19 files changed, 83 insertions, 68 deletions
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 4b70ec2..94f8c05 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -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. diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst index c005d0c..ce39d3b 100644 --- a/Doc/documenting/markup.rst +++ b/Doc/documenting/markup.rst @@ -513,7 +513,10 @@ in a different style: .. describe:: keyword - The name of a keyword in Python. + The name of a Python keyword. Using this role will generate a link to the + documentation of the keyword. ``True``, ``False`` and ``None`` do not use + this role, but simple code markup (````True````), given that they're + fundamental to the language and should be known to any programmer. .. describe:: mailheader diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst index b9faf57..02417b1 100644 --- a/Doc/faq/design.rst +++ b/Doc/faq/design.rst @@ -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` 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 diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 8b2f047..d1a3daf 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -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)? --------------------------------------------------------------------- diff --git a/Doc/faq/windows.rst b/Doc/faq/windows.rst index 8a20950..68a1b5c 100644 --- a/Doc/faq/windows.rst +++ b/Doc/faq/windows.rst @@ -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. diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 63d4c2b..3b211ae 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -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. diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst index a7d6024..5ff0d74 100644 --- a/Doc/howto/logging.rst +++ b/Doc/howto/logging.rst @@ -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 diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 38e52fb..88270ed 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -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) diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst index 2401ae7..06f3ab1 100644 --- a/Doc/library/base64.rst +++ b/Doc/library/base64.rst @@ -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``, diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst index c84e423..0c68b03 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -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!" diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst index c385cf3..47a0749 100644 --- a/Doc/library/email.header.rst +++ b/Doc/library/email.header.rst @@ -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) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 3b6fdc3..4ed3ec5 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -10,7 +10,7 @@ are always available. They are listed here in alphabetical order. =================== ================= ================== ================ ==================== .. .. Built-in Functions .. .. =================== ================= ================== ================ ==================== -:func:`abs` :func:`dict` :func:`help` :func:`min` :func:`setattr` +:func:`abs` |func-dict|_ :func:`help` :func:`min` :func:`setattr` :func:`all` :func:`dir` :func:`hex` :func:`next` :func:`slice` :func:`any` :func:`divmod` :func:`id` :func:`object` :func:`sorted` :func:`ascii` :func:`enumerate` :func:`input` :func:`oct` :func:`staticmethod` @@ -19,13 +19,22 @@ are always available. They are listed here in alphabetical order. :func:`bytearray` :func:`filter` :func:`issubclass` :func:`pow` :func:`super` :func:`bytes` :func:`float` :func:`iter` :func:`print` :func:`tuple` :func:`callable` :func:`format` :func:`len` :func:`property` :func:`type` -:func:`chr` :func:`frozenset` :func:`list` :func:`range` :func:`vars` +:func:`chr` |func-frozenset|_ :func:`list` :func:`range` :func:`vars` :func:`classmethod` :func:`getattr` :func:`locals` :func:`repr` :func:`zip` :func:`compile` :func:`globals` :func:`map` :func:`reversed` :func:`__import__` :func:`complex` :func:`hasattr` :func:`max` :func:`round` -:func:`delattr` :func:`hash` :func:`memoryview` :func:`set` +:func:`delattr` :func:`hash` |func-memoryview|_ |func-set|_ =================== ================= ================== ================ ==================== +.. using :func:`dict` would create a link to another page, so local targets are + used, with replacement texts to make the output in the table consistent + +.. |func-dict| replace:: ``dict()`` +.. |func-frozenset| replace:: ``frozenset()`` +.. |func-memoryview| replace:: ``memoryview()`` +.. |func-set| replace:: ``set()`` + + .. function:: abs(x) Return the absolute value of a number. The argument may be an @@ -74,11 +83,12 @@ are always available. They are listed here in alphabetical order. .. function:: bool([x]) - Convert a value to a Boolean, using the standard truth testing procedure. If - *x* is false or omitted, this returns :const:`False`; otherwise it returns - :const:`True`. :class:`bool` is also a class, which is a subclass of - :class:`int`. Class :class:`bool` cannot be subclassed further. Its only - instances are :const:`False` and :const:`True`. + Convert a value to a Boolean, using the standard :ref:`truth testing + procedure <truth>`. If *x* is false or omitted, this returns ``False``; + otherwise it returns ``True``. :class:`bool` is also a class, which is a + subclass of :class:`int` (see :ref:`typesnumeric`). Class :class:`bool` + cannot be subclassed further. Its only instances are ``False`` and + ``True`` (see :ref:`bltin-boolean-values`). .. index:: pair: Boolean; type @@ -248,6 +258,7 @@ are always available. They are listed here in alphabetical order. example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``. +.. _func-dict: .. function:: dict([arg]) :noindex: @@ -491,6 +502,7 @@ are always available. They are listed here in alphabetical order. The float type is described in :ref:`typesnumeric`. + .. function:: format(value[, format_spec]) .. index:: @@ -511,6 +523,8 @@ are always available. They are listed here in alphabetical order. :exc:`TypeError` exception is raised if the method is not found or if either the *format_spec* or the return value are not strings. + +.. _func-frozenset: .. function:: frozenset([iterable]) :noindex: @@ -717,6 +731,8 @@ are always available. They are listed here in alphabetical order. such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and ``heapq.nlargest(1, iterable, key=keyfunc)``. + +.. _func-memoryview: .. function:: memoryview(obj) :noindex: @@ -1040,7 +1056,7 @@ are always available. They are listed here in alphabetical order. Range objects implement the :class:`collections.Sequence` ABC, and provide features such as containment tests, element index lookup, slicing and - support for negative indices: + support for negative indices (see :ref:`typesseq`): >>> r = range(0, 20, 2) >>> r @@ -1108,6 +1124,8 @@ are always available. They are listed here in alphabetical order. can't be represented exactly as a float. See :ref:`tut-fp-issues` for more information. + +.. _func-set: .. function:: set([iterable]) :noindex: diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 7a57a0d..d127ce8 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -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. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 2a9f640..f98a5f1 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2712,6 +2712,8 @@ special operations. There is exactly one ellipsis object, named It is written as ``Ellipsis`` or ``...``. +.. _bltin-notimplemented-object: + The NotImplemented Object ------------------------- @@ -2722,6 +2724,8 @@ information. It is written as ``NotImplemented``. +.. _bltin-boolean-values: + Boolean Values -------------- diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 2443180..78f2b4d 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -216,6 +216,8 @@ keyword. If it's a number, it refers to a positional argument, and if it's a ke it refers to a named keyword argument. If the numerical arg_names in a format string are 0, 1, 2, ... in sequence, they can all be omitted (not just some) and the numbers 0, 1, 2, ... will be automatically inserted in that order. +Because *arg_name* is not quote-delimited, it is not possible to specify arbitrary +dictionary keys (e.g., the strings ``'10'`` or ``':-]'``) within a format string. The *arg_name* can be followed by any number of index or attribute expressions. An expression of the form ``'.name'`` selects the named attribute using :func:`getattr`, while an expression of the form ``'[index]'`` diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index beed4de..32f66fe 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -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 @@ -723,9 +723,9 @@ Test cases Here, we create two instances of :class:`WidgetTestCase`, each of which runs a single test. - .. versionchanged:: - `TestCase` can be instantiated successfully without providing a method - name. This makes it easier to experiment with `TestCase` from the + .. versionchanged:: 3.2 + :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`. @@ -940,17 +940,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) @@ -1092,7 +1092,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 | | +---------------------------------------+--------------------------------+--------------+ @@ -1887,7 +1887,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. @@ -1904,7 +1904,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() diff --git a/Lib/compileall.py b/Lib/compileall.py index 743be27..d3cff6a 100644 --- a/Lib/compileall.py +++ b/Lib/compileall.py @@ -142,7 +142,7 @@ def compile_path(skip_curdir=1, maxlevels=0, force=False, quiet=False, Arguments (all optional): - skip_curdir: if true, skip current directory (default true) + skip_curdir: if true, skip current directory (default True) maxlevels: max recursion level (default 0) force: as for compile_dir() (default False) quiet: as for compile_dir() (default False) @@ -177,17 +177,17 @@ def main(): help='use legacy (pre-PEP3147) compiled file locations') parser.add_argument('-d', metavar='DESTDIR', dest='ddir', default=None, help=('directory to prepend to file paths for use in ' - 'compile time tracebacks and in runtime ' + 'compile-time tracebacks and in runtime ' 'tracebacks in cases where the source file is ' 'unavailable')) parser.add_argument('-x', metavar='REGEXP', dest='rx', default=None, - help=('skip files matching the regular expression. ' - 'The regexp is searched for in the full path ' - 'to each file considered for compilation.')) + help=('skip files matching the regular expression; ' + 'the regexp is searched for in the full path ' + 'of each file considered for compilation')) parser.add_argument('-i', metavar='FILE', dest='flist', help=('add all the files and directories listed in ' - 'FILE to the list considered for compilation. ' - 'If "-", names are read from stdin.')) + 'FILE to the list considered for compilation; ' + 'if "-", names are read from stdin')) parser.add_argument('compile_dest', metavar='FILE|DIR', nargs='*', help=('zero or more file and directory names ' 'to compile; if no arguments given, defaults ' diff --git a/Lib/distutils/tests/support.py b/Lib/distutils/tests/support.py index 44fcd6b..d77bbee 100644 --- a/Lib/distutils/tests/support.py +++ b/Lib/distutils/tests/support.py @@ -175,10 +175,9 @@ def _get_xxmodule_path(): def fixup_build_ext(cmd): """Function needed to make build_ext tests pass. - When Python was build with --enable-shared on Unix, -L. is not good - enough to find the libpython<blah>.so. This is because regrtest runs - it under a tempdir, not in the top level where the .so lives. By the - time we've gotten here, Python's already been chdir'd to the tempdir. + When Python was built with --enable-shared on Unix, -L. is not enough to + find libpython<blah>.so, because regrtest runs in a tempdir, not in the + source directory where the .so lives. When Python was built with in debug mode on Windows, build_ext commands need their debug attribute set, and it is not done automatically for diff --git a/Lib/pipes.py b/Lib/pipes.py index 51666a8..4297053 100644 --- a/Lib/pipes.py +++ b/Lib/pipes.py @@ -54,8 +54,6 @@ for the built-in function open() or for os.popen(). To create a new template object initialized to a given one: t2 = t.clone() - -For an example, see the function test() at the end of the file. """ # ' |