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.
: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
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
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
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
.. 2to3fixer:: exec
- Converts the :keyword:`exec` statement to the :func:`exec` function.
+ Converts the ``exec`` statement to the :func:`exec` function.
.. 2to3fixer:: execfile
.. 2to3fixer:: print
- Converts the :keyword:`print` statement to the :func:`print` function.
+ Converts the ``print`` statement to the :func:`print` function.
.. 2to3fixer:: raise
`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
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
.. 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.
.. 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.
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)
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.
.. 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.
: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
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`.
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:
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
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.
.. _comparisons:
.. _is:
-.. _isnot:
+.. _is not:
.. _in:
-.. _notin:
+.. _not in:
Comparisons
===========
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::
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
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
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
# 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::
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
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
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).
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
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).
(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.)
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)
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"``.
``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.
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
* :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`.
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
projects / thirdparty / Python / cpython.git / commitdiff
