but just some text embedded in the docs.
Also remove paragraph about implicit relative imports from tutorial.
...
}
- The dictionary *p* should not be mutated during iteration. It is safe (since
- Python 2.1) to modify the values of the keys as you iterate over the dictionary,
- but only so long as the set of keys does not change. For example::
+ The dictionary *p* should not be mutated during iteration. It is safe to
+ modify the values of the keys as you iterate over the dictionary, but only so
+ long as the set of keys does not change. For example::
PyObject *key, *value;
Py_ssize_t pos = 0;
.. % The descriptions for %zd and %zu are wrong, but the truth is complicated
.. % because not all compilers support the %z width modifier -- we fake it
.. % when necessary via interpolating PY_FORMAT_SIZE_T.
- .. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
+-------------------+---------------+--------------------------------+
| Format Characters | Type | Comment |
be the case. (Unfortunately, this has an additional side effect when *name* in
fact specifies a subpackage instead of a submodule: the submodules specified in
the package's ``__all__`` variable are loaded.) Return a new reference to the
- imported module, or *NULL* with an exception set on failure. Before Python 2.4,
- the module may still be created in the failure case --- examine ``sys.modules``
- to find out. Starting with Python 2.4, a failing import of a module no longer
- leaves the module in ``sys.modules``.
+ imported module, or *NULL* with an exception set on failure. A failing
+ import of a module doesn't leave the module in :data:`sys.modules`.
.. cfunction:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
function :func:`__import__`, as the standard :func:`__import__` function calls
this function directly.
- The return value is a new reference to the imported module or top-level package,
- or *NULL* with an exception set on failure (before Python 2.4, the module may
- still be created in this case). Like for :func:`__import__`, the return value
- when a submodule of a package was requested is normally the top-level package,
- unless a non-empty *fromlist* was given.
+ The return value is a new reference to the imported module or top-level
+ package, or *NULL* with an exception set on failure. Like for
+ :func:`__import__`, the return value when a submodule of a package was
+ requested is normally the top-level package, unless a non-empty *fromlist*
+ was given.
Failing imports remove incomplete module objects, like with
:cfunc:`PyImport_ImportModule`.
Given a module name (possibly of the form ``package.module``) and a code object
read from a Python bytecode file or obtained from the built-in function
:func:`compile`, load the module. Return a new reference to the module object,
- or *NULL* with an exception set if an error occurred. Before Python 2.4, the
- module could still be created in error cases. Starting with Python 2.4, *name*
- is removed from :attr:`sys.modules` in error cases, and even if *name* was already
+ or *NULL* with an exception set if an error occurred. *name*
+ is removed from :attr:`sys.modules` in error cases, even if *name* was already
in :attr:`sys.modules` on entry to :cfunc:`PyImport_ExecCodeModule`. Leaving
incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of
such modules have no way to know that the module object is an unknown (and
Cache the result in :data:`sys.path_importer_cache`. Return a new reference
to the importer object.
- .. versionadded:: 2.6
-
.. cfunction:: void _PyImport_Init()
Return the version of this Python interpreter. This is a string that looks
something like ::
- "1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
+ "3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"
.. index:: single: version (in module sys)
The first word (up to the first space character) is the current Python version;
the first three characters are the major and minor version separated by a
period. The returned string points into static storage; the caller should not
- modify its value. The value is available to Python code as ``sys.version``.
+ modify its value. The value is available to Python code as :data:`sys.version`.
.. cfunction:: const char* Py_GetBuildNumber()
using the Python/C API. When they are done, they should reset the thread state
pointer, release the lock, and finally free their thread state data structure.
-Beginning with version 2.3, threads can now take advantage of the
-:cfunc:`PyGILState_\*` functions to do all of the above automatically. The
-typical idiom for calling into Python from a C thread is now::
+Threads can take advantage of the :cfunc:`PyGILState_\*` functions to do all of
+the above automatically. The typical idiom for calling into Python from a C
+thread is now::
PyGILState_STATE gstate;
gstate = PyGILState_Ensure();
and execution tracing facilities. These are used for profiling, debugging, and
coverage analysis tools.
-Starting with Python 2.2, the implementation of this facility was substantially
-revised, and an interface from C was added. This C interface allows the
-profiling or tracing code to avoid the overhead of calling through Python-level
-callable objects, making a direct C function call instead. The essential
-attributes of the facility have not changed; the interface allows trace
-functions to be installed per-thread, and the basic events reported to the trace
-function are the same as had been reported to the Python-level trace functions
-in previous versions.
+This C interface allows the profiling or tracing code to avoid the overhead of
+calling through Python-level callable objects, making a direct C function call
+instead. The essential attributes of the facility have not changed; the
+interface allows trace functions to be installed per-thread, and the basic
+events reported to the trace function are the same as had been reported to the
+Python-level trace functions in previous versions.
.. ctype:: int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)
Numeric values are stored with the least significant byte first.
The module supports two versions of the data format: version 0 is the historical
-version, version 1 (new in Python 2.4) shares interned strings in the file, and
-upon unmarshalling. *Py_MARSHAL_VERSION* indicates the current file format
-(currently 1).
+version, version 1 shares interned strings in the file, and upon unmarshalling.
+Version 2 uses a binary format for floating point numbers.
+*Py_MARSHAL_VERSION* indicates the current file format (currently 2).
.. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
base. If *n* is not an int object, it is converted with
:cfunc:`PyNumber_Index` first.
- .. versionadded:: 2.6
-
.. cfunction:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
set on success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is
not actually iterable.
- .. versionchanged:: 2.6
- Now guaranteed to return a brand-new :class:`frozenset`. Formerly,
- frozensets of zero-length were a singleton. This got in the way of
- building-up new frozensets with :meth:`PySet_Add`.
The following functions and macros are available for instances of :class:`set`
or :class:`frozenset` or instances of their subtypes.
.. cfunction:: int PySet_Add(PyObject *set, PyObject *key)
- Add *key* to a :class:`set` instance. Does not apply to :class:`frozenset`
- instances. Return 0 on success or -1 on failure. Raise a :exc:`TypeError` if
- the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow.
- Raise a :exc:`SystemError` if *set* is an not an instance of :class:`set` or its
+ Add *key* to a :class:`set` instance. Also works with :class:`frozenset`
+ instances (like :cfunc:`PyTuple_SetItem` it can be used to fill-in the values
+ of brand new frozensets before they are exposed to other code). Return 0 on
+ success or -1 on failure. Raise a :exc:`TypeError` if the *key* is
+ unhashable. Raise a :exc:`MemoryError` if there is no room to grow. Raise a
+ :exc:`SystemError` if *set* is an not an instance of :class:`set` or its
subtype.
- .. versionchanged:: 2.6
- Now works with instances of :class:`frozenset` or its subtypes.
- Like :cfunc:`PyTuple_SetItem` in that it can be used to fill-in the
- values of brand new frozensets before they are exposed to other code.
The following functions are available for instances of :class:`set` or its
subtypes but not for instances of :class:`frozenset` or its subtypes.
indices was not :const:`None` and failed to be converted to an integer, in which
case -1 is returned with an exception set).
- You probably do not want to use this function. If you want to use slice objects
- in versions of Python prior to 2.3, you would probably do well to incorporate
- the source of :cfunc:`PySlice_GetIndicesEx`, suitably renamed, in the source of
- your extension.
+ You probably do not want to use this function.
.. cfunction:: int PySlice_GetIndicesEx(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)
.. % XXX: The descriptions for %zd and %zu are wrong, but the truth is complicated
.. % because not all compilers support the %z width modifier -- we fake it
.. % when necessary via interpolating PY_FORMAT_SIZE_T.
- .. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
+-------------------+---------------+--------------------------------+
| Format Characters | Type | Comment |
This should be done before any instances of the type are created.
:cfunc:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so,
- initializes it: in Python 2.2, it is set to ``&PyType_Type``; in Python 2.2.1
- and later it is initialized to the :attr:`ob_type` field of the base class.
+ initializes it to the :attr:`ob_type` field of the base class.
:cfunc:`PyType_Ready` will not change this field if it is non-zero.
- In Python 2.2, this field is not inherited by subtypes. In 2.2.1, and in 2.3
- and beyond, it is inherited by subtypes.
+ This field is inherited by subtypes.
.. cmember:: Py_ssize_t PyVarObject.ob_size
:attr:`_ob_next` fields if they are present. This means that the only correct
way to get an initializer for the :attr:`tp_basicsize` is to use the
``sizeof`` operator on the struct used to declare the instance layout.
- The basic size does not include the GC header size (this is new in Python 2.2;
- in 2.1 and 2.0, the GC header size was included in :attr:`tp_basicsize`).
+ The basic size does not include the GC header size.
These fields are inherited separately by subtypes. If the base type has a
non-zero :attr:`tp_itemsize`, it is generally not safe to set
structure. The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with
the :attr:`tp_traverse` and :attr:`tp_clear` fields, i.e. if the
:const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the
- :attr:`tp_traverse` and :attr:`tp_clear` fields in the subtype exist (as
- indicated by the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit) and have *NULL*
- values.
+ :attr:`tp_traverse` and :attr:`tp_clear` fields in the subtype exist and have
+ *NULL* values.
The following bit masks are currently defined; these can be ORed together using
the ``|`` operator to form the value of the :attr:`tp_flags` field. The macro
checks whether ``tp->tp_flags & f`` is non-zero.
- .. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
-
- If this bit is set, the :ctype:`PyBufferProcs` struct referenced by
- :attr:`tp_as_buffer` has the :attr:`bf_getcharbuffer` field.
-
-
- .. data:: Py_TPFLAGS_HAVE_SEQUENCE_IN
-
- If this bit is set, the :ctype:`PySequenceMethods` struct referenced by
- :attr:`tp_as_sequence` has the :attr:`sq_contains` field.
-
-
- .. data:: Py_TPFLAGS_GC
-
- This bit is obsolete. The bit it used to name is no longer in use. The symbol
- is now defined as zero.
-
-
- .. data:: Py_TPFLAGS_HAVE_INPLACEOPS
-
- If this bit is set, the :ctype:`PySequenceMethods` struct referenced by
- :attr:`tp_as_sequence` and the :ctype:`PyNumberMethods` structure referenced by
- :attr:`tp_as_number` contain the fields for in-place operators. In particular,
- this means that the :ctype:`PyNumberMethods` structure has the fields
- :attr:`nb_inplace_add`, :attr:`nb_inplace_subtract`,
- :attr:`nb_inplace_multiply`, :attr:`nb_inplace_divide`,
- :attr:`nb_inplace_remainder`, :attr:`nb_inplace_power`,
- :attr:`nb_inplace_lshift`, :attr:`nb_inplace_rshift`, :attr:`nb_inplace_and`,
- :attr:`nb_inplace_xor`, and :attr:`nb_inplace_or`; and the
- :ctype:`PySequenceMethods` struct has the fields :attr:`sq_inplace_concat` and
- :attr:`sq_inplace_repeat`.
-
-
- .. data:: Py_TPFLAGS_HAVE_RICHCOMPARE
-
- If this bit is set, the type object has the :attr:`tp_richcompare` field, as
- well as the :attr:`tp_traverse` and the :attr:`tp_clear` fields.
-
-
- .. data:: Py_TPFLAGS_HAVE_WEAKREFS
-
- If this bit is set, the :attr:`tp_weaklistoffset` field is defined. Instances
- of a type are weakly referenceable if the type's :attr:`tp_weaklistoffset` field
- has a value greater than zero.
-
-
- .. data:: Py_TPFLAGS_HAVE_ITER
-
- If this bit is set, the type object has the :attr:`tp_iter` and
- :attr:`tp_iternext` fields.
-
-
- .. data:: Py_TPFLAGS_HAVE_CLASS
-
- If this bit is set, the type object has several new fields defined starting in
- Python 2.2: :attr:`tp_methods`, :attr:`tp_members`, :attr:`tp_getset`,
- :attr:`tp_base`, :attr:`tp_dict`, :attr:`tp_descr_get`, :attr:`tp_descr_set`,
- :attr:`tp_dictoffset`, :attr:`tp_init`, :attr:`tp_alloc`, :attr:`tp_new`,
- :attr:`tp_free`, :attr:`tp_is_gc`, :attr:`tp_bases`, :attr:`tp_mro`,
- :attr:`tp_cache`, :attr:`tp_subclasses`, and :attr:`tp_weaklist`.
-
-
.. data:: Py_TPFLAGS_HEAPTYPE
This bit is set when the type object itself is allocated on the heap. In this
destroyed using :cfunc:`PyObject_GC_Del`. More information in section
:ref:`supporting-cycle-detection`. This bit also implies that the
GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in
- the type object; but those fields also exist when
- :const:`Py_TPFLAGS_HAVE_GC` is clear but
- :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` is set.
+ the type object.
.. data:: Py_TPFLAGS_DEFAULT
This is a bitmask of all the bits that pertain to the existence of certain
fields in the type object and its extension structures. Currently, it includes
- the following bits: :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`,
- :const:`Py_TPFLAGS_HAVE_SEQUENCE_IN`, :const:`Py_TPFLAGS_HAVE_INPLACEOPS`,
- :const:`Py_TPFLAGS_HAVE_RICHCOMPARE`, :const:`Py_TPFLAGS_HAVE_WEAKREFS`,
- :const:`Py_TPFLAGS_HAVE_ITER`, and :const:`Py_TPFLAGS_HAVE_CLASS`.
+ the following bits: :const:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`,
+ :const:`Py_TPFLAGS_HAVE_VERSION_TAG`.
.. cmember:: char* PyTypeObject.tp_doc
This field is *not* inherited by subtypes.
-The following three fields only exist if the
-:const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit is set.
-
.. cmember:: traverseproc PyTypeObject.tp_traverse
This field is inherited by subtypes together with :attr:`tp_clear` and the
:const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
:attr:`tp_clear` are all inherited from the base type if they are all zero in
- the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
- bit set.
+ the subtype.
.. cmember:: inquiry PyTypeObject.tp_clear
This field is inherited by subtypes together with :attr:`tp_traverse` and the
:const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
:attr:`tp_clear` are all inherited from the base type if they are all zero in
- the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
- bit set.
+ the subtype.
.. cmember:: richcmpfunc PyTypeObject.tp_richcompare
+----------------+------------+
-The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit is
-set.
-
.. cmember:: long PyTypeObject.tp_weaklistoffset
If the instances of this type are weakly referenceable, this field is greater
:attr:`__weakref__`, the type inherits its :attr:`tp_weaklistoffset` from its
base type.
-The next two fields only exist if the :const:`Py_TPFLAGS_HAVE_CLASS` flag bit is
-set.
-
.. cmember:: getiterfunc PyTypeObject.tp_iter
This field is inherited by subtypes.
-The next fields, up to and including :attr:`tp_weaklist`, only exist if the
-:const:`Py_TPFLAGS_HAVE_CLASS` flag bit is set.
-
.. cmember:: struct PyMethodDef* PyTypeObject.tp_methods
has returned an instance of the type. If the :attr:`tp_new` function returns an
instance of some other type that is not a subtype of the original type, no
:attr:`tp_init` function is called; if :attr:`tp_new` returns an instance of a
- subtype of the original type, the subtype's :attr:`tp_init` is called. (VERSION
- NOTE: described here is what is implemented in Python 2.2.1 and later. In
- Python 2.2, the :attr:`tp_init` of the type of the object returned by
- :attr:`tp_new` was always called, if not *NULL*.)
+ subtype of the original type, the subtype's :attr:`tp_init` is called.
This field is inherited by subtypes.
deferred to :attr:`tp_init`.
This field is inherited by subtypes, except it is not inherited by static types
- whose :attr:`tp_base` is *NULL* or ``&PyBaseObject_Type``. The latter exception
- is a precaution so that old extension types don't become callable simply by
- being linked with Python 2.2.
+ whose :attr:`tp_base` is *NULL* or ``&PyBaseObject_Type``.
.. cmember:: destructor PyTypeObject.tp_free
- An optional pointer to an instance deallocation function.
-
- The signature of this function has changed slightly: in Python 2.2 and 2.2.1,
- its signature is :ctype:`destructor`::
-
- void tp_free(PyObject *)
-
- In Python 2.3 and beyond, its signature is :ctype:`freefunc`::
+ An optional pointer to an instance deallocation function. Its signature is
+ :ctype:`freefunc`::
void tp_free(void *)
- The only initializer that is compatible with both versions is ``PyObject_Free``,
- whose definition has suitably adapted in Python 2.3.
+ An initializer that is compatible with this signature is :cfunc:`PyObject_Free`.
This field is inherited by static subtypes, but not by dynamic subtypes
(subtypes created by a class statement); in the latter, this field is set to a
:cdata:`PyType_Type`, defines this function to distinguish between statically
and dynamically allocated types.)
- This field is inherited by subtypes. (VERSION NOTE: in Python 2.2, it was not
- inherited. It is inherited in 2.2.1 and later versions.)
+ This field is inherited by subtypes.
.. cmember:: PyObject* PyTypeObject.tp_bases
did not have this member, so a new Python interpreter using an old extension
needs to be able to test for its presence before using it.
-
+.. XXX out of date!
.. ctype:: PyBufferProcs
Structure used to hold the function pointers which define an implementation of
characters present.
-.. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
-
- Flag bit set in the type structure to indicate that the :attr:`bf_getcharbuffer`
- slot is known. This being set does not indicate that the object supports the
- buffer interface or that the :attr:`bf_getcharbuffer` slot is non-*NULL*.
-
-
.. ctype:: Py_ssize_t (*readbufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)
Return a pointer to a readable segment of the buffer in ``*ptrptr``. This
This is not hard; the code for all extension types follows a pattern, but there
are some details that you need to understand before you can get started.
-.. note::
-
- The way new types are defined changed dramatically (and for the better) in
- Python 2.2. This document documents how to define new types for Python 2.2 and
- later. If you need to support older versions of Python, you will need to refer
- to `older versions of this documentation
- <http://www.python.org/doc/versions/>`_.
-
.. _dnt-basics:
*arg* passed to the traversal method. It returns an integer value that must be
returned if it is non-zero.
-Python 2.4 and higher provide a :cfunc:`Py_VISIT` macro that automates calling
-visit functions. With :cfunc:`Py_VISIT`, :cfunc:`Noddy_traverse` can be
-simplified::
+Python provides a :cfunc:`Py_VISIT` macro that automates calling visit
+functions. With :cfunc:`Py_VISIT`, :cfunc:`Noddy_traverse` can be simplified::
static int
Noddy_traverse(Noddy *self, visitproc visit, void *arg)
take a chance of having :cfunc:`Noddy_traverse` called when a member's reference
count has dropped to zero and its value hasn't been set to *NULL*.
-Python 2.4 and higher provide a :cfunc:`Py_CLEAR` that automates the careful
-decrementing of reference counts. With :cfunc:`Py_CLEAR`, the
-:cfunc:`Noddy_clear` function can be simplified::
+Python provides a :cfunc:`Py_CLEAR` that automates the careful decrementing of
+reference counts. With :cfunc:`Py_CLEAR`, the :cfunc:`Noddy_clear` function can
+be simplified::
static int
Noddy_clear(Noddy *self)
XXX some fields need to be added here... ::
- /* Added in release 2.2 */
/* Iterators */
getiterfunc tp_iter;
iternextfunc tp_iternext;
interface provides for encoding and decoding to and from file-like objects as
well as strings, but only using the Base64 standard alphabet.
-The modern interface, which was introduced in Python 2.4, provides:
-
+The modern interface provides:
.. function:: b64encode(s[, altchars])
:func:`compile_command`; the difference is that if the instance compiles program
text containing a ``__future__`` statement, the instance 'remembers' and
compiles all subsequent program texts with the statement in force.
-
-A note on version compatibility: the :class:`Compile` and
-:class:`CommandCompiler` are new in Python 2.2. If you want to enable the
-future-tracking features of 2.2 but also retain compatibility with 2.1 and
-earlier versions of Python you can either write ::
-
- try:
- from codeop import CommandCompiler
- compile_command = CommandCompiler()
- del CommandCompiler
- except ImportError:
- from codeop import compile_command
-
-which is a low-impact change, but introduces possibly unwanted global state into
-your program, or you can write::
-
- try:
- from codeop import CommandCompiler
- except ImportError:
- def CommandCompiler():
- from codeop import compile_command
- return compile_command
-
-and then call ``CommandCompiler`` every time you need a fresh compiler object.
-
.. exception:: LoadError
Instances of :class:`FileCookieJar` raise this exception on failure to load
- cookies from a file.
-
- .. note::
-
- For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`),
- :exc:`LoadError` is a subclass of :exc:`IOError`.
+ cookies from a file. :exc:`LoadError` is a subclass of :exc:`IOError`.
The following classes are provided:
:exc:`LoadError` will be raised. Also, :exc:`IOError` may be raised, for
example if the file does not exist.
- .. note::
-
- For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`),
- :exc:`LoadError` is a subclass of :exc:`IOError`.
-
.. method:: FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)
is zero. If the source buffer is not large enough a ValueError
is raised.
- .. versionadded:: 2.6
.. method:: _CData.from_buffer_copy(source[, offset])
in bytes; the default is zero. If the source buffer is not
large enough a ValueError is raised.
- .. versionadded:: 2.6
-
.. method:: from_address(address)
Set the current context for the active thread to *c*.
-Beginning with Python 2.5, you can also use the :keyword:`with` statement and
-the :func:`localcontext` function to temporarily change the active context.
-
+You can also use the :keyword:`with` statement and the :func:`localcontext`
+function to temporarily change the active context.
.. function:: localcontext([c])
Optional keyword parameters *linejunk* and *charjunk* are for filter functions
(or ``None``):
- *linejunk*: A function that accepts a single string argument, and returns true
- if the string is junk, or false if not. The default is (``None``), starting with
- Python 2.3. Before then, the default was the module-level function
- :func:`IS_LINE_JUNK`, which filters out lines without visible characters, except
- for at most one pound character (``'#'``). As of Python 2.3, the underlying
- :class:`SequenceMatcher` class does a dynamic analysis of which lines are so
- frequent as to constitute noise, and this usually works better than the pre-2.3
- default.
+ *linejunk*: A function that accepts a single string argument, and returns
+ true if the string is junk, or false if not. The default is ``None``. There
+ is also a module-level function :func:`IS_LINE_JUNK`, which filters out lines
+ without visible characters, except for at most one pound character (``'#'``)
+ -- however the underlying :class:`SequenceMatcher` class does a dynamic
+ analysis of which lines are so frequent as to constitute noise, and this
+ usually works better than using this function.
*charjunk*: A function that accepts a character (a string of length 1), and
returns if the character is junk, or false if not. The default is module-level
Return true for ignorable lines. The line *line* is ignorable if *line* is
blank or contains a single ``'#'``, otherwise it is not ignorable. Used as a
- default for parameter *linejunk* in :func:`ndiff` before Python 2.3.
+ default for parameter *linejunk* in :func:`ndiff` in older versions.
.. function:: IS_CHARACTER_JUNK(ch)
so long as the buffer you pass is as least as long as what the operating system
wants to put there, things should work.
- If *mutate_flag* is true, then the buffer is (in effect) passed to the
+ If *mutate_flag* is true (the default), then the buffer is (in effect) passed to the
underlying :func:`ioctl` system call, the latter's return code is passed back to
the calling Python, and the buffer's new contents reflect the action of the
:func:`ioctl`. This is a slight simplification, because if the supplied buffer
long which is then passed to :func:`ioctl` and copied back into the supplied
buffer.
- If *mutate_flag* is not supplied, then from Python 2.5 it defaults to true,
- which is a change from versions 2.3 and 2.4. Supply the argument explicitly if
- version portability is a priority.
-
An example::
>>> import array, fcntl, struct, termios, os
.. method:: FTP.set_pasv(boolean)
- Enable "passive" mode if *boolean* is true, other disable passive mode. (In
- Python 2.0 and before, passive mode was off by default; in Python 2.1 and later,
- it is on by default.)
+ Enable "passive" mode if *boolean* is true, other disable passive mode.
+ Passive mode is on by default.
.. method:: FTP.storbinary(command, file[, blocksize, callback])
.. function:: getpass([prompt[, stream]])
- Prompt the user for a password without echoing. The user is prompted using the
- string *prompt*, which defaults to ``'Password: '``. On Unix, the prompt is
- written to the file-like object *stream*. *stream* defaults to the
- controlling terminal (/dev/tty) or if that is unavailable to ``sys.stderr``
- (this argument is ignored on Windows).
+ Prompt the user for a password without echoing. The user is prompted using
+ the string *prompt*, which defaults to ``'Password: '``. On Unix, the prompt
+ is written to the file-like object *stream*. *stream* defaults to the
+ controlling terminal (:file:`/dev/tty`) or if that is unavailable to
+ ``sys.stderr`` (this argument is ignored on Windows).
If echo free input is unavailable getpass() falls back to printing
a warning message to *stream* and reading from ``sys.stdin`` and
Availability: Macintosh, Unix, Windows.
- .. versionchanged:: 2.6
- On Unix it defaults to using /dev/tty before falling back
- to ``sys.stdin`` and ``sys.stderr``.
.. note::
If you call getpass from within IDLE, the input may be done in the
terminal you launched IDLE from rather than the idle window itself.
Return true if the object is a method descriptor, but not if :func:`ismethod`
or :func:`isclass` or :func:`isfunction` are true.
- This is new as of Python 2.2, and, for example, is true of
- ``int.__add__``. An object passing this test has a :attr:`__get__` attribute
- but not a :attr:`__set__` attribute, but beyond that the set of attributes
- varies. :attr:`__name__` is usually sensible, and :attr:`__doc__` often is.
+ This, for example, is true of ``int.__add__``. An object passing this test
+ has a :attr:`__get__` attribute but not a :attr:`__set__` attribute, but
+ beyond that the set of attributes varies. :attr:`__name__` is usually
+ sensible, and :attr:`__doc__` often is.
Methods implemented via descriptors that also pass one of the other tests
return false from the :func:`ismethoddescriptor` test, simply because the
:synopsis: Encode and decode the JSON format.
.. moduleauthor:: Bob Ippolito <bob@redivi.com>
.. sectionauthor:: Bob Ippolito <bob@redivi.com>
-.. versionadded:: 2.6
JSON (JavaScript Object Notation) <http://json.org> is a subset of JavaScript
syntax (ECMA-262 3rd edition) used as a lightweight data interchange format.
.. data:: runtimemodel
- Always ``'macho'``, from Python 2.4 on. In earlier versions of Python the value
- could also be ``'ppc'`` for the classic Mac OS 8 runtime model or ``'carbon'``
- for the Mac OS 9 runtime model.
+ Always ``'macho'``.
.. data:: linkmodel
for working with the Extensible Markup Language (XML).
It is important to note that modules in the :mod:`xml` package require that
-there be at least one SAX-compliant XML parser available. Starting with Python
-2.3, the Expat parser is included with Python, so the :mod:`xml.parsers.expat`
-module will always be available. You may still want to be aware of the `PyXML
-add-on package <http://pyxml.sourceforge.net/>`_; that package provides an
-extended set of XML libraries for Python.
+there be at least one SAX-compliant XML parser available. The Expat parser is
+included with Python, so the :mod:`xml.parsers.expat` module will always be
+available.
The documentation for the :mod:`xml.dom` and :mod:`xml.sax` packages are the
definition of the Python bindings for the DOM and SAX interfaces.
xml.sax.utils.rst
xml.sax.reader.rst
xml.etree.elementtree.rst
-
-.. seealso::
-
- `Python/XML Libraries <http://pyxml.sourceforge.net/>`_
- Home page for the PyXML package, containing an extension of :mod:`xml` package
- bundled with Python.
-
.. data:: version
- Indicates the format that the module uses. Version 0 is the historical format,
- version 1 (added in Python 2.4) shares interned strings and version 2 (added in
- Python 2.5) uses a binary format for floating point numbers. The current version
- is 2.
+ Indicates the format that the module uses. Version 0 is the historical
+ format, version 1 shares interned strings and version 2 uses a binary format
+ for floating point numbers. The current version is 2.
.. rubric:: Footnotes
platform and libm implementation. It's usually :exc:`ValueError` for *EDOM*
and :exc:`OverflowError` for errno *ERANGE*.
- ..versionchanged:: 2.6
- In earlier versions of Python the outcome of an operation with NaN as
- input depended on platform and libm implementation.
-
.. seealso::
.. note::
- Passwords are limited to a subset of the ASCII character set. Versions of
- this module prior to 2.3 were extremely limited. Starting with 2.3, all
- ASCII punctuation is allowed in passwords. However, note that whitespace and
+ Passwords are limited to a subset of the ASCII character set. All ASCII
+ punctuation is allowed in passwords, however, note that whitespace and
non-printable characters are not allowed in passwords. This is a limitation
of the way the .netrc file is parsed and may be removed in the future.
If you're starting with a Python file object *f*, first do ``f.flush()``, and
then do ``os.fsync(f.fileno())``, to ensure that all internal buffers associated
- with *f* are written to disk. Availability: Macintosh, Unix, and Windows
- starting in 2.2.3.
+ with *f* are written to disk. Availability: Macintosh, Unix, and Windows.
.. function:: ftruncate(fd, length)
pickled by reference and not by value. This method is useful when re-using
picklers.
- .. note::
-
- Prior to Python 2.3, :meth:`clear_memo` was only available on the picklers
- created by :mod:`cPickle`. In the :mod:`pickle` module, picklers have an
- instance variable called :attr:`memo` which is a Python dictionary. So to clear
- the memo for a :mod:`pickle` module pickler, you could do the following::
-
- mypickler.memo.clear()
-
- Code that does not need to support older versions of Python should simply use
- :meth:`clear_memo`.
It is possible to make multiple calls to the :meth:`dump` method of the same
:class:`Pickler` instance. These must then be matched to the same number of
computer is *very* fast, or your timer function has poor resolution, you might
have to pass 100000, or even 1000000, to get consistent results.
-When you have a consistent answer, there are three ways you can use it: [#]_ ::
+When you have a consistent answer, there are three ways you can use it::
import profile
.. [#] Updated and converted to LaTeX by Guido van Rossum. Further updated by Armin
Rigo to integrate the documentation for the new :mod:`cProfile` module of Python
2.5.
-
-.. [#] Prior to Python 2.2, it was necessary to edit the profiler source code to embed
- the bias as a literal number. You still can, but that method is no longer
- described, because no longer needed.
-
Return an object capturing the current internal state of the generator. This
object can be passed to :func:`setstate` to restore the state.
- State values produced in Python 2.6 cannot be loaded into earlier versions.
-
.. function:: setstate(state)
You can often restructure your regular expression to avoid recursion.
-Starting with Python 2.3, simple uses of the ``*?`` pattern are special-cased to
-avoid recursion. Thus, the above regular expression can avoid recursion by
-being recast as ``Begin [a-zA-Z0-9_ ]*?end``. As a further benefit, such
-regular expressions will run faster than their recursive equivalents.
+Simple uses of the ``*?`` pattern are special-cased to avoid recursion. Thus,
+the above regular expression can avoid recursion by being recast as ``Begin
+[a-zA-Z0-9_ ]*?end``. As a further benefit, such regular expressions will run
+faster than their recursive equivalents.
search() vs. match()
A :class:`shlex` instance or subclass instance is a lexical analyzer object.
The initialization argument, if present, specifies where to read characters
from. It must be a file-/stream-like object with :meth:`read` and
- :meth:`readline` methods, or a string (strings are accepted since Python 2.3).
- If no argument is given, input will be taken from ``sys.stdin``. The second
- optional argument is a filename string, which sets the initial value of the
- :attr:`infile` member. If the *instream* argument is omitted or equal to
- ``sys.stdin``, this second argument defaults to "stdin". The *posix* argument
- was introduced in Python 2.3, and defines the operational mode. When *posix* is
- not true (default), the :class:`shlex` instance will operate in compatibility
- mode. When operating in POSIX mode, :class:`shlex` will try to be as close as
- possible to the POSIX shell parsing rules.
+ :meth:`readline` methods, or a string. If no argument is given, input will
+ be taken from ``sys.stdin``. The second optional argument is a filename
+ string, which sets the initial value of the :attr:`infile` member. If the
+ *instream* argument is omitted or equal to ``sys.stdin``, this second
+ argument defaults to "stdin". The *posix* argument defines the operational
+ mode: when *posix* is not true (default), the :class:`shlex` instance will
+ operate in compatibility mode. When operating in POSIX mode, :class:`shlex`
+ will try to be as close as possible to the POSIX shell parsing rules.
.. seealso::
A list of prefixes for site package directories
- .. versionadded:: 2.6
-
.. data:: ENABLE_USER_SITE
user site directory is enabled and added to sys.path. When the flag
is None the user site directory is disabled for security reasons.
- .. versionadded:: 2.6
-
.. data:: USER_SITE
Path to the user site directory for the current Python version or None
- .. versionadded:: 2.6
-
.. data:: USER_BASE
Path to the base directory for user site directories
- .. versionadded:: 2.6
-
.. envvar:: PYTHONNOUSERSITE
- .. versionadded:: 2.6
-
.. envvar:: PYTHONUSERBASE
- .. versionadded:: 2.6
-
.. function:: addsitedir(sitedir, known_paths=None)
Bind the socket to *address*. The socket must not already be bound. (The format
of *address* depends on the address family --- see above.)
- .. note::
-
- This method has historically accepted a pair of parameters for :const:`AF_INET`
- addresses instead of only a tuple. This was never intentional and is no longer
- available in Python 2.0 and later.
-
.. method:: socket.close()
Connect to a remote socket at *address*. (The format of *address* depends on the
address family --- see above.)
- .. note::
-
- This method has historically accepted a pair of parameters for :const:`AF_INET`
- addresses instead of only a tuple. This was never intentional and is no longer
- available in Python 2.0 and later.
-
.. method:: socket.connect_ex(address)
:cdata:`errno` variable. This is useful to support, for example, asynchronous
connects.
- .. note::
-
- This method has historically accepted a pair of parameters for :const:`AF_INET`
- addresses instead of only a tuple. This was never intentional and is no longer
- available in Python 2.0 and later.
-
.. method:: socket.fileno()
which requires that the file be open will raise a :exc:`ValueError` after the
file has been closed. Calling :meth:`close` more than once is allowed.
- As of Python 2.5, you can avoid having to call this method explicitly if you use
+ You can avoid having to call this method explicitly if you use
the :keyword:`with` statement. For example, the following code will
automatically close *f* when the :keyword:`with` block is exited::
.. warning::
- Assigning the *traceback* return value to a local variable in a function that is
- handling an exception will cause a circular reference. This will prevent
- anything referenced by a local variable in the same function or by the traceback
- from being garbage collected. Since most functions don't need access to the
- traceback, the best solution is to use something like ``exctype, value =
- sys.exc_info()[:2]`` to extract only the exception type and value. If you do
- need the traceback, make sure to delete it after use (best done with a
- :keyword:`try` ... :keyword:`finally` statement) or to call :func:`exc_info` in
- a function that does not itself handle an exception.
-
- .. note::
-
- Beginning with Python 2.2, such cycles are automatically reclaimed when garbage
- collection is enabled and they become unreachable, but it remains more efficient
- to avoid creating cycles.
+ Assigning the *traceback* return value to a local variable in a function
+ that is handling an exception will cause a circular reference. Since most
+ functions don't need access to the traceback, the best solution is to use
+ something like ``exctype, value = sys.exc_info()[:2]`` to extract only the
+ exception type and value. If you do need the traceback, make sure to
+ delete it after use (best done with a :keyword:`try`
+ ... :keyword:`finally` statement) or to call :func:`exc_info` in a
+ function that does not itself handle an exception.
+
+ Such cycles are normally automatically reclaimed when garbage collection
+ is enabled and they become unreachable, but it remains more efficient to
+ avoid creating cycles.
.. data:: exec_prefix
pair: temporary; file
This module generates temporary files and directories. It works on all
-supported platforms.
-
-In version 2.3 of Python, this module was overhauled for enhanced security. It
-now provides three new functions, :func:`NamedTemporaryFile`, :func:`mkstemp`,
-and :func:`mkdtemp`, which should eliminate all remaining need to use the
-insecure :func:`mktemp` function. Temporary file names created by this module
-no longer contain the process ID; instead a string of six random characters is
-used.
+supported platforms. It provides three new functions,
+:func:`NamedTemporaryFile`, :func:`mkstemp`, and :func:`mkdtemp`, which should
+eliminate all remaining need to use the insecure :func:`mktemp` function.
+Temporary file names created by this module no longer contain the process ID;
+instead a string of six random characters is used.
Also, all the user-callable functions now take additional arguments which
allow direct control over the location and name of temporary files. It is
On Windows, the default prefix is :file:`~T`; on all other systems it is
:file:`tmp`.
- Older versions of this module used to require that ``template`` be set to
- ``None`` after a call to :func:`os.fork`; this has not been necessary since
- version 1.5.2.
-
.. function:: gettempprefix()
Note that tabs and spaces are both treated as whitespace, but they are not
equal: the lines ``" hello"`` and ``"\thello"`` are considered to have no
- common leading whitespace. (This behaviour is new in Python 2.5; older versions
- of this module incorrectly expanded tabs before searching for common leading
- whitespace.)
+ common leading whitespace.
For example::
timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()
-Starting with version 2.6, the module also defines two convenience functions:
+The module also defines two convenience functions:
.. function:: repeat(stmt[, setup[, timer[, repeat=3 [, number=1000000]]]])
A shorthand for ``format_list(extract_stack(f, limit))``.
-.. function:: tb_lineno(tb)
-
- This function returns the current line number set in the traceback object. This
- function was necessary because in versions of Python prior to 2.3 when the
- :option:`-O` flag was passed to Python the ``tb.tb_lineno`` was not updated
- correctly. This function has no use in versions past 2.3.
-
-
.. _traceback-example:
Traceback Examples
linked, or building and installing the shared object if using dynamically-loaded
extensions.
-.. (lib-old is empty as of Python 2.5)
+.. XXX new explanation of lib-old necessary
Those which are written in Python will be installed into the directory
\file{lib-old/} installed as part of the standard library. To use
If the Python installation has SSL support (i.e., if the :mod:`ssl` module can be imported),
:class:`HTTPSHandler` will also be added.
- Beginning in Python 2.3, a :class:`BaseHandler` subclass may also change its
- :attr:`handler_order` member variable to modify its position in the handlers
- list.
+ A :class:`BaseHandler` subclass may also change its :attr:`handler_order`
+ member variable to modify its position in the handlers list.
The following exceptions are raised as appropriate:
parameter specifies the number of milliseconds the sound should last. If the
system is not able to beep the speaker, :exc:`RuntimeError` is raised.
- .. note::
-
- Under Windows 95 and 98, the Windows :cfunc:`Beep` function exists but is
- useless (it ignores its arguments). In that case Python simulates it via direct
- port manipulation (added in version 2.1). It's unknown whether that will work
- on all systems.
-
.. function:: PlaySound(sound, flags)
There's also an *encoding* argument; see :meth:`toxml`.
-The following standard DOM methods have special considerations with
-:mod:`xml.dom.minidom`:
-
-.. method:: Node.cloneNode(deep)
-
- Although this method was present in the version of :mod:`xml.dom.minidom`
- packaged with Python 2.0, it was seriously broken. This has been corrected for
- subsequent releases.
-
-
.. _dom-example:
DOM Example
:exc:`TypeError` and :exc:`AttributeError`.
* :class:`NodeList` objects are implemented using Python's built-in list type.
- Starting with Python 2.2, these objects provide the interface defined in the DOM
- specification, but with earlier versions of Python they do not support the
- official API. They are, however, much more "Pythonic" than the interface
- defined in the W3C recommendations.
+ These objects provide the interface defined in the DOM specification, but with
+ earlier versions of Python they do not support the official API. They are,
+ however, much more "Pythonic" than the interface defined in the W3C
+ recommendations.
The following interfaces have no implementation in :mod:`xml.dom.minidom`:
* :class:`DOMTimeStamp`
-* :class:`DocumentType` (added in Python 2.1)
+* :class:`DocumentType`
-* :class:`DOMImplementation` (added in Python 2.1)
+* :class:`DOMImplementation`
* :class:`CharacterData`
raise a special :exc:`Fault` instance, used to signal XML-RPC server errors, or
:exc:`ProtocolError` used to signal an error in the HTTP/HTTPS transport layer.
Both :exc:`Fault` and :exc:`ProtocolError` derive from a base class called
- :exc:`Error`. Note that even though starting with Python 2.2 you can subclass
- builtin types, the xmlrpclib module currently does not marshal instances of such
- subclasses.
+ :exc:`Error`. Note that the xmlrpclib module currently does not marshal
+ instances of subclasses of builtin types.
When passing strings, characters special to XML such as ``<``, ``>``, and ``&``
will be automatically escaped. However, it's the caller's responsibility to
is invoked, the function can proceed exactly as if the :keyword:`yield`
statement were just another external call.
-As of Python version 2.5, the :keyword:`yield` statement is now allowed in the
-:keyword:`try` clause of a :keyword:`try` ... :keyword:`finally` construct. If
-the generator is not resumed before it is finalized (by reaching a zero
-reference count or by being garbage collected), the generator-iterator's
-:meth:`close` method will be called, allowing any pending :keyword:`finally`
-clauses to execute.
-
+The :keyword:`yield` statement is allowed in the :keyword:`try` clause of a
+:keyword:`try` ... :keyword:`finally` construct. If the generator is not
+resumed before it is finalized (by reaching a zero reference count or by being
+garbage collected), the generator-iterator's :meth:`close` method will be
+called, allowing any pending :keyword:`finally` clauses to execute.
.. seealso::
been executed. The :keyword:`finally` clause is also executed "on the way out"
when any other clause of the :keyword:`try` statement is left via a
:keyword:`break`, :keyword:`continue` or :keyword:`return` statement. A more
-complicated example (having :keyword:`except` and :keyword:`finally` clauses in
-the same :keyword:`try` statement works as of Python 2.5)::
+complicated example::
>>> def divide(x, y):
... try:
Intra-package References
------------------------
-The submodules often need to refer to each other. For example, the
-:mod:`surround` module might use the :mod:`echo` module. In fact, such
-references are so common that the :keyword:`import` statement first looks in the
-containing package before looking in the standard module search path. Thus, the
-:mod:`surround` module can simply use ``import echo`` or ``from echo import
-echofilter``. If the imported module is not found in the current package (the
-package of which the current module is a submodule), the :keyword:`import`
-statement looks for a top-level module with the given name.
-
When packages are structured into subpackages (as with the :mod:`sound` package
in the example), you can use absolute imports to refer to submodules of siblings
packages. For example, if the module :mod:`sound.filters.vocoder` needs to use
the :mod:`echo` module in the :mod:`sound.effects` package, it can use ``from
sound.effects import echo``.
-Starting with Python 2.5, in addition to the implicit relative imports described
-above, you can write explicit relative imports with the ``from module import
-name`` form of import statement. These explicit relative imports use leading
-dots to indicate the current and parent packages involved in the relative
-import. From the :mod:`surround` module for example, you might use::
+You can also write relative imports, with the ``from module import name`` form
+of import statement. These imports use leading dots to indicate the current and
+parent packages involved in the relative import. From the :mod:`surround`
+module for example, you might use::
from . import echo
from .. import formats
from ..filters import equalizer
-Note that both explicit and implicit relative imports are based on the name of
-the current module. Since the name of the main module is always ``"__main__"``,
-modules intended for use as the main module of a Python application should
-always use absolute imports.
+Note that relative imports are based on the name of the current module. Since
+the name of the main module is always ``"__main__"``, modules intended for use
+as the main module of a Python application must always use absolute imports.
Packages in Multiple Directories
added to the start of :data:`sys.path` and the ``__main__.py`` file in
that location is executed as the :mod:`__main__` module.
- .. versionchanged:: 2.5
- Directories and zipfiles containing a ``__main__.py`` file at the top
- level are now considered valid Python scripts.
If no interface option is given, :option:`-i` is implied, ``sys.argv[0]`` is
an empty string (``""``) and the current directory will be added to the
Print the Python version number and exit. Example output could be::
- Python 2.5.1
+ Python 3.0
Miscellaneous options
If given, Python won't try to write ``.pyc`` or ``.pyo`` files on the
import of source modules. See also :envvar:`PYTHONDONTWRITEBYTECODE`.
- .. versionadded:: 2.6
-
.. cmdoption:: -d
Don't add user site directory to sys.path
- .. versionadded:: 2.6
-
.. seealso::
:pep:`370` -- Per user site-packages directory
If this is set, Python won't try to write ``.pyc`` or ``.pyo`` files on the
import of source modules.
- .. versionadded:: 2.6
-
.. envvar:: PYTHONNOUSERSITE
If set, Python will print threading debug info.
- .. versionchanged:: 2.6
- Previously, this variable was called ``THREADDEBUG``.
.. envvar:: PYTHONDUMPREFS
The Mac-specific modules are documented in :ref:`mac-specific-services`.
-Python on Mac OS 9 or earlier can be quite different from Python on Unix or
-Windows, but is beyond the scope of this manual, as that platform is no longer
-supported, starting with Python 2.4. See http://www.cwi.nl/~jack/macpython for
-installers for the latest 2.3 release for Mac OS 9 and related documentation.
-
.. _getting-osx:
Getting and Installing MacPython
================================
-Mac OS X 10.4 comes with Python 2.3 pre-installed by Apple. However, you are
+Mac OS X 10.5 comes with Python 2.5 pre-installed by Apple. However, you are
encouraged to install the most recent version of Python from the Python website
(http://www.python.org). A "universal binary" build of Python 2.5, which runs
natively on the Mac's new Intel and legacy PPC CPU's, is available there.
earlier are no longer supported (due to the lack of users or developers).
Check :pep:`11` for details on all unsupported platforms.
-* DOS and Windows 3.x are deprecated since Python 2.0 and code specific to these
- systems was removed in Python 2.1.
* Up to 2.5, Python was still compatible with Windows 95, 98 and ME (but already
raised a deprecation warning on installation). For Python 2.6 (and all
following releases), this support was dropped and new releases are just
projects / python / commitdiff