mirror of https://github.com/python/cpython
Fix a few doc errors, mostly undefined keywords.
This commit is contained in:
parent
6dc50f34dd
commit
375aec2315
|
@ -47,4 +47,4 @@ bound into a function.
|
|||
|
||||
Return a new empty code object with the specified filename,
|
||||
function name, and first line number. It is illegal to
|
||||
:keyword:`exec` or :func:`eval` the resulting code object.
|
||||
:func:`exec` or :func:`eval` the resulting code object.
|
||||
|
|
|
@ -6,7 +6,8 @@ Logging Cookbook
|
|||
|
||||
:Author: Vinay Sajip <vinay_sajip at red-dove dot com>
|
||||
|
||||
This page contains a number of recipes related to logging, which have been found useful in the past.
|
||||
This page contains a number of recipes related to logging, which have been found
|
||||
useful in the past.
|
||||
|
||||
.. currentmodule:: logging
|
||||
|
||||
|
@ -283,7 +284,7 @@ One solution is to use a two-part approach. For the first part, attach only a
|
|||
performance-critical threads. They simply write to their queue, which can be
|
||||
sized to a large enough capacity or initialized with no upper bound to their
|
||||
size. The write to the queue will typically be accepted quickly, though you
|
||||
will probably need to catch the :ref:`queue.Full` exception as a precaution
|
||||
will probably need to catch the :exc:`queue.Full` exception as a precaution
|
||||
in your code. If you are a library developer who has performance-critical
|
||||
threads in their code, be sure to document this (together with a suggestion to
|
||||
attach only ``QueueHandlers`` to your loggers) for the benefit of other
|
||||
|
|
|
@ -214,8 +214,8 @@ multiple modules, using the pattern in *mylib.py*. Note that for this simple
|
|||
usage pattern, you won't know, by looking in the log file, *where* in your
|
||||
application your messages came from, apart from looking at the event
|
||||
description. If you want to track the location of your messages, you'll need
|
||||
to refer to the documentation beyond the tutorial level - see
|
||||
:ref:`advanced-logging-tutorial`.
|
||||
to refer to the documentation beyond the tutorial level -- see
|
||||
:ref:`logging-advanced-tutorial`.
|
||||
|
||||
|
||||
Logging variable data
|
||||
|
@ -549,9 +549,9 @@ Programmers can configure logging in three ways:
|
|||
3. Creating a dictionary of configuration information and passing it
|
||||
to the :func:`dictConfig` function.
|
||||
|
||||
For the reference documentation on the last two options, see :ref:`config-ref`.
|
||||
The following example configures a very simple logger, a console handler, and
|
||||
a simple formatter using Python code::
|
||||
For the reference documentation on the last two options, see
|
||||
:ref:`logging-config-api`. The following example configures a very simple
|
||||
logger, a console handler, and a simple formatter using Python code::
|
||||
|
||||
import logging
|
||||
|
||||
|
|
|
@ -141,7 +141,7 @@ and off individually. They are described here in more detail.
|
|||
|
||||
.. 2to3fixer:: exec
|
||||
|
||||
Converts the :keyword:`exec` statement to the :func:`exec` function.
|
||||
Converts the ``exec`` statement to the :func:`exec` function.
|
||||
|
||||
.. 2to3fixer:: execfile
|
||||
|
||||
|
@ -293,7 +293,7 @@ and off individually. They are described here in more detail.
|
|||
|
||||
.. 2to3fixer:: print
|
||||
|
||||
Converts the :keyword:`print` statement to the :func:`print` function.
|
||||
Converts the ``print`` statement to the :func:`print` function.
|
||||
|
||||
.. 2to3fixer:: raise
|
||||
|
||||
|
|
|
@ -32,7 +32,7 @@ Details on custom importers can be found in :pep:`302`.
|
|||
|
||||
`Packages specification <http://www.python.org/doc/essays/packages.html>`__
|
||||
Original specification of packages. Some semantics have changed since
|
||||
the writing of this document (e.g. redirecting based on :keyword:`None`
|
||||
the writing of this document (e.g. redirecting based on ``None``
|
||||
in :data:`sys.modules`).
|
||||
|
||||
The :func:`.__import__` function
|
||||
|
@ -109,7 +109,7 @@ are also provided to help in implementing the core ABCs.
|
|||
module. If the :term:`finder` is found on :data:`sys.meta_path` and the
|
||||
module to be searched for is a subpackage or module then *path* will
|
||||
be the value of :attr:`__path__` from the parent package. If a loader
|
||||
cannot be found, :keyword:`None` is returned.
|
||||
cannot be found, ``None`` is returned.
|
||||
|
||||
|
||||
.. class:: Loader
|
||||
|
@ -185,14 +185,14 @@ are also provided to help in implementing the core ABCs.
|
|||
.. method:: get_code(fullname)
|
||||
|
||||
An abstract method to return the :class:`code` object for a module.
|
||||
:keyword:`None` is returned if the module does not have a code object
|
||||
``None`` is returned if the module does not have a code object
|
||||
(e.g. built-in module). :exc:`ImportError` is raised if loader cannot
|
||||
find the requested module.
|
||||
|
||||
.. method:: get_source(fullname)
|
||||
|
||||
An abstract method to return the source of a module. It is returned as
|
||||
a text string with universal newlines. Returns :keyword:`None` if no
|
||||
a text string with universal newlines. Returns ``None`` if no
|
||||
source is available (e.g. a built-in module). Raises :exc:`ImportError`
|
||||
if the loader cannot find the module specified.
|
||||
|
||||
|
@ -320,7 +320,7 @@ are also provided to help in implementing the core ABCs.
|
|||
.. method:: source_path(fullname)
|
||||
|
||||
An abstract method that returns the path to the source code for a
|
||||
module. Should return :keyword:`None` if there is no source code.
|
||||
module. Should return ``None`` if there is no source code.
|
||||
Raises :exc:`ImportError` if the loader knows it cannot handle the
|
||||
module.
|
||||
|
||||
|
@ -329,7 +329,7 @@ are also provided to help in implementing the core ABCs.
|
|||
A concrete implementation of
|
||||
:meth:`importlib.abc.ExecutionLoader.get_filename` that
|
||||
relies on :meth:`source_path`. If :meth:`source_path` returns
|
||||
:keyword:`None`, then :exc:`ImportError` is raised.
|
||||
``None``, then :exc:`ImportError` is raised.
|
||||
|
||||
.. method:: load_module(fullname)
|
||||
|
||||
|
@ -374,13 +374,13 @@ are also provided to help in implementing the core ABCs.
|
|||
|
||||
An abstract method which returns the modification time for the source
|
||||
code of the specified module. The modification time should be an
|
||||
integer. If there is no source code, return :keyword:`None`. If the
|
||||
integer. If there is no source code, return ``None``. If the
|
||||
module cannot be found then :exc:`ImportError` is raised.
|
||||
|
||||
.. method:: bytecode_path(fullname)
|
||||
|
||||
An abstract method which returns the path to the bytecode for the
|
||||
specified module, if it exists. It returns :keyword:`None`
|
||||
specified module, if it exists. It returns ``None``
|
||||
if no bytecode exists (yet).
|
||||
Raises :exc:`ImportError` if the loader knows it cannot handle the
|
||||
module.
|
||||
|
@ -398,8 +398,8 @@ are also provided to help in implementing the core ABCs.
|
|||
.. method:: write_bytecode(fullname, bytecode)
|
||||
|
||||
An abstract method which has the loader write *bytecode* for future
|
||||
use. If the bytecode is written, return :keyword:`True`. Return
|
||||
:keyword:`False` if the bytecode could not be written. This method
|
||||
use. If the bytecode is written, return ``True``. Return
|
||||
``False`` if the bytecode could not be written. This method
|
||||
should not be called if :data:`sys.dont_write_bytecode` is true.
|
||||
The *bytecode* argument should be a bytes string or bytes array.
|
||||
|
||||
|
@ -457,7 +457,7 @@ find and load modules.
|
|||
:data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is
|
||||
searched for a finder for the path entry and, if found, is stored in
|
||||
:data:`sys.path_importer_cache` along with being queried about the
|
||||
module. If no finder is ever found then :keyword:`None` is returned.
|
||||
module. If no finder is ever found then ``None`` is returned.
|
||||
|
||||
|
||||
:mod:`importlib.util` -- Utility code for importers
|
||||
|
@ -506,7 +506,7 @@ an :term:`importer`.
|
|||
|
||||
A :term:`decorator` for a :term:`loader` to set the :attr:`__package__`
|
||||
attribute on the module returned by the loader. If :attr:`__package__` is
|
||||
set and has a value other than :keyword:`None` it will not be changed.
|
||||
set and has a value other than ``None`` it will not be changed.
|
||||
Note that the module returned by the loader is what has the attribute
|
||||
set on and not the module found in :data:`sys.modules`.
|
||||
|
||||
|
|
|
@ -197,8 +197,8 @@ exception.
|
|||
operator: in
|
||||
operator: not in
|
||||
|
||||
Two more operations with the same syntactic priority, ``in`` and ``not in``, are
|
||||
supported only by sequence types (below).
|
||||
Two more operations with the same syntactic priority, :keyword:`in` and
|
||||
:keyword:`not in`, are supported only by sequence types (below).
|
||||
|
||||
|
||||
.. _typesnumeric:
|
||||
|
|
|
@ -634,7 +634,7 @@ always available.
|
|||
imported. The :meth:`find_module` method is called at least with the
|
||||
absolute name of the module being imported. If the module to be imported is
|
||||
contained in package then the parent package's :attr:`__path__` attribute
|
||||
is passed in as a second argument. The method returns :keyword:`None` if
|
||||
is passed in as a second argument. The method returns ``None`` if
|
||||
the module cannot be found, else returns a :term:`loader`.
|
||||
|
||||
:data:`sys.meta_path` is searched before any implicit default finders or
|
||||
|
@ -687,7 +687,7 @@ always available.
|
|||
A dictionary acting as a cache for :term:`finder` objects. The keys are
|
||||
paths that have been passed to :data:`sys.path_hooks` and the values are
|
||||
the finders that are found. If a path is a valid file system path but no
|
||||
explicit finder is found on :data:`sys.path_hooks` then :keyword:`None` is
|
||||
explicit finder is found on :data:`sys.path_hooks` then ``None`` is
|
||||
stored to represent the implicit default finder should be used. If the path
|
||||
is not an existing path then :class:`imp.NullImporter` is set.
|
||||
|
||||
|
|
|
@ -963,9 +963,9 @@ must be integers.
|
|||
|
||||
.. _comparisons:
|
||||
.. _is:
|
||||
.. _isnot:
|
||||
.. _is not:
|
||||
.. _in:
|
||||
.. _notin:
|
||||
.. _not in:
|
||||
|
||||
Comparisons
|
||||
===========
|
||||
|
|
|
@ -678,7 +678,7 @@ Once the name of the module is known (unless otherwise specified, the term
|
|||
for the module or package can begin. The first place checked is
|
||||
:data:`sys.modules`, the cache of all modules that have been imported
|
||||
previously. If the module is found there then it is used in step (2) of import
|
||||
unless :keyword:`None` is found in :data:`sys.modules`, in which case
|
||||
unless ``None`` is found in :data:`sys.modules`, in which case
|
||||
:exc:`ImportError` is raised.
|
||||
|
||||
.. index::
|
||||
|
@ -696,7 +696,7 @@ within a package (as denoted by the existence of a dot in the name), then a
|
|||
second argument to :meth:`find_module` is given as the value of the
|
||||
:attr:`__path__` attribute from the parent package (everything up to the last
|
||||
dot in the name of the module being imported). If a finder can find the module
|
||||
it returns a :term:`loader` (discussed later) or returns :keyword:`None`.
|
||||
it returns a :term:`loader` (discussed later) or returns ``None``.
|
||||
|
||||
.. index::
|
||||
single: sys.path_hooks
|
||||
|
@ -723,11 +723,11 @@ finder cached then :data:`sys.path_hooks` is searched by calling each object in
|
|||
the list with a single argument of the path, returning a finder or raises
|
||||
:exc:`ImportError`. If a finder is returned then it is cached in
|
||||
:data:`sys.path_importer_cache` and then used for that path entry. If no finder
|
||||
can be found but the path exists then a value of :keyword:`None` is
|
||||
can be found but the path exists then a value of ``None`` is
|
||||
stored in :data:`sys.path_importer_cache` to signify that an implicit,
|
||||
file-based finder that handles modules stored as individual files should be
|
||||
used for that path. If the path does not exist then a finder which always
|
||||
returns :keyword:`None` is placed in the cache for the path.
|
||||
returns ``None`` is placed in the cache for the path.
|
||||
|
||||
.. index::
|
||||
single: loader
|
||||
|
|
|
@ -189,7 +189,7 @@ support Unicode:
|
|||
ignored and ``'replace'`` uses U+FFFD, the official replacement character, in
|
||||
case of any problems.
|
||||
|
||||
* The :keyword:`exec` statement, and various built-ins such as ``eval()``,
|
||||
* The ``exec`` statement, and various built-ins such as ``eval()``,
|
||||
``getattr()``, and ``setattr()`` will also accept Unicode strings as well as
|
||||
regular strings. (It's possible that the process of fixing this missed some
|
||||
built-ins; if you find a built-in function that accepts strings but doesn't
|
||||
|
@ -515,11 +515,11 @@ functions::
|
|||
# kw is a dictionary of keyword args
|
||||
...
|
||||
|
||||
The :keyword:`print` statement can now have its output directed to a file-like
|
||||
object by following the :keyword:`print` with ``>> file``, similar to the
|
||||
The ``print`` statement can now have its output directed to a file-like
|
||||
object by following the ``print`` with ``>> file``, similar to the
|
||||
redirection operator in Unix shells. Previously you'd either have to use the
|
||||
:meth:`write` method of the file-like object, which lacks the convenience and
|
||||
simplicity of :keyword:`print`, or you could assign a new value to
|
||||
simplicity of ``print``, or you could assign a new value to
|
||||
``sys.stdout`` and then restore the old value. For sending output to standard
|
||||
error, it's much easier to write this::
|
||||
|
||||
|
@ -581,7 +581,7 @@ Consult the README in the Python source distribution for more instructions.
|
|||
An attempt has been made to alleviate one of Python's warts, the often-confusing
|
||||
:exc:`NameError` exception when code refers to a local variable before the
|
||||
variable has been assigned a value. For example, the following code raises an
|
||||
exception on the :keyword:`print` statement in both 1.5.2 and 2.0; in 1.5.2 a
|
||||
exception on the ``print`` statement in both 1.5.2 and 2.0; in 1.5.2 a
|
||||
:exc:`NameError` exception is raised, while 2.0 raises a new
|
||||
:exc:`UnboundLocalError` exception. :exc:`UnboundLocalError` is a subclass of
|
||||
:exc:`NameError`, so any existing code that expects :exc:`NameError` to be
|
||||
|
|
|
@ -81,13 +81,13 @@ though, since such code would have been pretty confusing to read in the first
|
|||
place.
|
||||
|
||||
One side effect of the change is that the ``from module import *`` and
|
||||
:keyword:`exec` statements have been made illegal inside a function scope under
|
||||
``exec`` statements have been made illegal inside a function scope under
|
||||
certain conditions. The Python reference manual has said all along that ``from
|
||||
module import *`` is only legal at the top level of a module, but the CPython
|
||||
interpreter has never enforced this before. As part of the implementation of
|
||||
nested scopes, the compiler which turns Python source into bytecodes has to
|
||||
generate different code to access variables in a containing scope. ``from
|
||||
module import *`` and :keyword:`exec` make it impossible for the compiler to
|
||||
module import *`` and ``exec`` make it impossible for the compiler to
|
||||
figure this out, because they add names to the local namespace that are
|
||||
unknowable at compile time. Therefore, if a function contains function
|
||||
definitions or :keyword:`lambda` expressions with free variables, the compiler
|
||||
|
@ -102,11 +102,11 @@ To make the preceding explanation a bit clearer, here's an example::
|
|||
def g():
|
||||
return x
|
||||
|
||||
Line 4 containing the :keyword:`exec` statement is a syntax error, since
|
||||
:keyword:`exec` would define a new local variable named ``x`` whose value should
|
||||
Line 4 containing the ``exec`` statement is a syntax error, since
|
||||
``exec`` would define a new local variable named ``x`` whose value should
|
||||
be accessed by :func:`g`.
|
||||
|
||||
This shouldn't be much of a limitation, since :keyword:`exec` is rarely used in
|
||||
This shouldn't be much of a limitation, since ``exec`` is rarely used in
|
||||
most Python code (and when it is used, it's often a sign of a poor design
|
||||
anyway).
|
||||
|
||||
|
|
|
@ -892,13 +892,13 @@ though, since such code would have been pretty confusing to read in the first
|
|||
place.
|
||||
|
||||
One side effect of the change is that the ``from module import *`` and
|
||||
:keyword:`exec` statements have been made illegal inside a function scope under
|
||||
``exec`` statements have been made illegal inside a function scope under
|
||||
certain conditions. The Python reference manual has said all along that ``from
|
||||
module import *`` is only legal at the top level of a module, but the CPython
|
||||
interpreter has never enforced this before. As part of the implementation of
|
||||
nested scopes, the compiler which turns Python source into bytecodes has to
|
||||
generate different code to access variables in a containing scope. ``from
|
||||
module import *`` and :keyword:`exec` make it impossible for the compiler to
|
||||
module import *`` and ``exec`` make it impossible for the compiler to
|
||||
figure this out, because they add names to the local namespace that are
|
||||
unknowable at compile time. Therefore, if a function contains function
|
||||
definitions or :keyword:`lambda` expressions with free variables, the compiler
|
||||
|
@ -913,11 +913,11 @@ To make the preceding explanation a bit clearer, here's an example::
|
|||
def g():
|
||||
return x
|
||||
|
||||
Line 4 containing the :keyword:`exec` statement is a syntax error, since
|
||||
:keyword:`exec` would define a new local variable named ``x`` whose value should
|
||||
Line 4 containing the ``exec`` statement is a syntax error, since
|
||||
``exec`` would define a new local variable named ``x`` whose value should
|
||||
be accessed by :func:`g`.
|
||||
|
||||
This shouldn't be much of a limitation, since :keyword:`exec` is rarely used in
|
||||
This shouldn't be much of a limitation, since ``exec`` is rarely used in
|
||||
most Python code (and when it is used, it's often a sign of a poor design
|
||||
anyway).
|
||||
|
||||
|
|
|
@ -896,7 +896,7 @@ Here are all of the changes that Python 2.4 makes to the core Python language.
|
|||
(Contributed by Nick Coghlan.)
|
||||
|
||||
* The :func:`eval(expr, globals, locals)` and :func:`execfile(filename, globals,
|
||||
locals)` functions and the :keyword:`exec` statement now accept any mapping type
|
||||
locals)` functions and the ``exec`` statement now accept any mapping type
|
||||
for the *locals* parameter. Previously this had to be a regular Python
|
||||
dictionary. (Contributed by Raymond Hettinger.)
|
||||
|
||||
|
|
|
@ -96,9 +96,9 @@ up if you're used to Python 2.5.
|
|||
Print Is A Function
|
||||
-------------------
|
||||
|
||||
The :keyword:`print` statement has been replaced with a :func:`print`
|
||||
The ``print`` statement has been replaced with a :func:`print`
|
||||
function, with keyword arguments to replace most of the special syntax
|
||||
of the old :keyword:`print` statement (:pep:`3105`). Examples::
|
||||
of the old ``print`` statement (:pep:`3105`). Examples::
|
||||
|
||||
Old: print "The answer is", 2*2
|
||||
New: print("The answer is", 2*2)
|
||||
|
@ -126,7 +126,7 @@ which produces::
|
|||
Note:
|
||||
|
||||
* The :func:`print` function doesn't support the "softspace" feature of
|
||||
the old :keyword:`print` statement. For example, in Python 2.x,
|
||||
the old ``print`` statement. For example, in Python 2.x,
|
||||
``print "A\n", "B"`` would write ``"A\nB\n"``; but in Python 3.0,
|
||||
``print("A\n", "B")`` writes ``"A\n B\n"``.
|
||||
|
||||
|
@ -135,7 +135,7 @@ Note:
|
|||
``print(x)`` instead!
|
||||
|
||||
* When using the ``2to3`` source-to-source conversion tool, all
|
||||
:keyword:`print` statements are automatically converted to
|
||||
``print`` statements are automatically converted to
|
||||
:func:`print` function calls, so this is mostly a non-issue for
|
||||
larger projects.
|
||||
|
||||
|
@ -178,7 +178,7 @@ Python 3.0 has simplified the rules for ordering comparisons:
|
|||
meaningful natural ordering. Thus, expressions like ``1 < ''``, ``0
|
||||
> None`` or ``len <= len`` are no longer valid, and e.g. ``None <
|
||||
None`` raises :exc:`TypeError` instead of returning
|
||||
:keyword:`False`. A corollary is that sorting a heterogeneous list
|
||||
``False``. A corollary is that sorting a heterogeneous list
|
||||
no longer makes sense -- all the elements must be comparable to each
|
||||
other. Note that this does not apply to the ``==`` and ``!=``
|
||||
operators: objects of different incomparable types always compare
|
||||
|
@ -397,9 +397,8 @@ Changed Syntax
|
|||
* :keyword:`as` and :keyword:`with` are now reserved words. (Since
|
||||
2.6, actually.)
|
||||
|
||||
* :keyword:`True`, :keyword:`False`, and :keyword:`None` are reserved
|
||||
words. (2.6 partially enforced the restrictions on :keyword:`None`
|
||||
already.)
|
||||
* ``True``, ``False``, and ``None`` are reserved words. (2.6 partially enforced
|
||||
the restrictions on ``None`` already.)
|
||||
|
||||
* Change from :keyword:`except` *exc*, *var* to
|
||||
:keyword:`except` *exc* :keyword:`as` *var*. See :pep:`3110`.
|
||||
|
@ -906,7 +905,7 @@ best strategy is the following:
|
|||
|
||||
It is not recommended to try to write source code that runs unchanged
|
||||
under both Python 2.6 and 3.0; you'd have to use a very contorted
|
||||
coding style, e.g. avoiding :keyword:`print` statements, metaclasses,
|
||||
coding style, e.g. avoiding ``print`` statements, metaclasses,
|
||||
and much more. If you are maintaining a library that needs to support
|
||||
both Python 2.6 and Python 3.0, the best approach is to modify step 3
|
||||
above by editing the 2.6 version of the source code and running the
|
||||
|
|
Loading…
Reference in New Issue