The Python interpreter needs to keep some bookkeeping information separate per
thread --- for this it uses a data structure called :ctype:`PyThreadState`.
There's one global variable, however: the pointer to the current
-:ctype:`PyThreadState` structure. While most thread packages have a way to
-store "per-thread global data," Python's internal platform independent thread
-abstraction doesn't support this yet. Therefore, the current thread state must
-be manipulated explicitly.
+:ctype:`PyThreadState` structure. Before the addition of :dfn:`thread-local
+storage` (:dfn:`TLS`) the current thread state had to be manipulated
+explicitly.
This is easy enough in most cases. Most code manipulating the global
interpreter lock has the following simple structure::
``<string.h>``, ``<errno.h>``, ``<limits.h>``, and ``<stdlib.h>`` (if
available).
-.. warning::
+.. note::
Since Python may define some pre-processor definitions which affect the standard
headers on some systems, you *must* include :file:`Python.h` before any standard
prefix of all files and directories in the archive. *root_dir* and *base_dir*
both default to the current directory. Returns the name of the archive file.
- .. warning::
-
- This should be changed to support bz2 files
+ .. XXX This should be changed to support bz2 files.
.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])
possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2`
or :file:`.Z`). Return the output filename.
- .. warning::
-
- This should be replaced with calls to the :mod:`tarfile` module.
+ .. XXX This should be replaced with calls to the :mod:`tarfile` module.
.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])
Wraps *text* to less than *width* wide.
- .. warning::
-
- Should be replaced with :mod:`textwrap` (which is available in Python 2.3 and
- later).
+ .. XXX Should be replaced with :mod:`textwrap` (which is available in Python
+ 2.3 and later).
.. class:: FancyGetopt([option_table=None])
================================================
.. module:: distutils.filelist
- :synopsis: The FileList class, used for poking about the file system and building lists of
- files.
+ :synopsis: The FileList class, used for poking about the file system and
+ building lists of files.
This module provides the :class:`FileList` class, used for poking about the
:synopsis: A simple logging mechanism, 282-style
-.. warning::
-
- Should be replaced with standard :mod:`logging` module.
+.. XXX Should be replaced with standard :mod:`logging` module.
-.. % \subsubsection{\module{} --- }
-.. % \declaremodule{standard}{distutils.magic}
-.. % \modulesynopsis{ }
:mod:`distutils.spawn` --- Spawn a sub-process
.. describe:: warning
- An important bit of information about an API that a user should be very aware
- of when using whatever bit of API the warning pertains to. The content of
- the directive should be written in complete sentences and include all
- appropriate punctuation. This differs from ``note`` in that it is recommended
- over ``note`` for information regarding security.
+ An important bit of information about an API that a user should be aware of
+ when using whatever bit of API the warning pertains to. The content of the
+ directive should be written in complete sentences and include all appropriate
+ punctuation. This should only be chosen over ``note`` for information
+ regarding the possibility of crashes, data loss, or security implications.
.. describe:: versionadded
which pulls in the Python API (you can add a comment describing the purpose of
the module and a copyright notice if you like).
-.. warning::
+.. note::
Since Python may define some pre-processor definitions which affect the standard
headers on some systems, you *must* include :file:`Python.h` before any standard
.. moduleauthor:: Collin Winter
-.. warning::
+.. note::
The :mod:`lib2to3` API should be considered unstable and may change
drastically in the future.
AppleEvent descriptor is handled by Python objects of built-in type
:class:`AEDesc`, defined in module :mod:`Carbon.AE`.
-.. warning::
+.. note::
- This module is removed in 3.0.
+ This module has been removed in Python 3.x.
The :mod:`aepack` module defines the following functions:
manager, see section :ref:`osx-gui-scripts` for details. This restriction may be
lifted in future releases.
-.. warning::
+.. note::
- This module is removed in 3.0.
+ This module has been removed in Python 3.x.
The :mod:`aetools` module defines the following functions:
contains object specifiers for a number of common OSA classes such as
``Document``, ``Window``, ``Character``, etc.
-.. warning::
+.. note::
- This module is removed in 3.0.
+ This module has been removed in Python 3.x.
-
:mod:`aifc` --- Read and write AIFF and AIFC files
==================================================
samples in a file. AIFF-C is a newer version of the format that includes the
ability to compress the audio data.
-.. warning::
+.. note::
Some operations may only work under IRIX; these will raise :exc:`ImportError`
- when attempting to import the :mod:`cl` module, which is only available on IRIX.
+ when attempting to import the :mod:`cl` module, which is only available on
+ IRIX.
Audio files have a number of parameters that describe the audio data. The
sampling rate or frame rate is the number of times per second the sound is
automatically locks and unlocks Python's :term:`Global Interpreter Lock` when
running an event loop.
-.. warning::
+.. note::
- This module has been removed in 3.0.
+ This module has been removed in Python 3.x.
.. exception:: AutoGILError
.. versionchanged:: 2.3
Disabled module.
-.. warning::
+.. note::
The documentation has been left in place to help in reading old code that uses
the module.
-
:mod:`binhex` --- Encode and decode binhex4 files
=================================================
file and the finder information are encoded (or decoded), on other platforms
only the data fork is handled.
-.. warning::
+.. note::
- In 3.0, special Macintosh support is removed.
+ In Python 3.x, special Macintosh support has been removed.
The :mod:`binhex` module defines the following functions:
from Carbon import AE
-.. warning::
+.. note::
- The Carbon modules are removed in 3.0.
+ The Carbon modules have been removed in Python 3.0.
:mod:`Carbon.AE` --- Apple Events
(``'single'``, the default) or as an :term:`expression` (``'eval'``). Any
other value will cause :exc:`ValueError` to be raised.
- .. warning::
+ .. note::
It is possible (but not likely) that the parser stops parsing with a
successful outcome before reaching the end of the source; in this case,
The :mod:`ColorPicker` module provides access to the standard color picker
dialog.
-.. warning::
+.. note::
- This module is removed in 3.0.
+ This module has been removed in Python 3.x.
.. function:: GetColor(prompt, rgb)
processes and retrieving their results. Using the :mod:`subprocess` module is
preferable to using the :mod:`commands` module.
-.. warning::
+.. note::
- In 3.x, :func:`getstatus` and two undocumented functions (:func:`mk2arg` and
- :func:`mkarg`) have been removed. Also, :func:`getstatusoutput` and
- :func:`getoutput` have been moved to the :mod:`subprocess` module.
+ In Python 3.x, :func:`getstatus` and two undocumented functions
+ (:func:`mk2arg` and :func:`mkarg`) have been removed. Also,
+ :func:`getstatusoutput` and :func:`getoutput` have been moved to the
+ :mod:`subprocess` module.
The :mod:`commands` module defines the following functions:
can use this to write Python programs which can be customized by end users
easily.
-.. warning::
+.. note::
- This library does *not* interpret or write the value-type prefixes used in the
- Windows Registry extended version of INI syntax.
+ This library does *not* interpret or write the value-type prefixes used in
+ the Windows Registry extended version of INI syntax.
The configuration file consists of sections, led by a ``[section]`` header and
followed by ``name: value`` entries, with continuations in the style of
type and item number) to those in the default :const:`DLOG` resource. See source
code for details.
-.. warning::
+.. note::
- This module is removed in 3.0.
+ This module has been removed in Python 3.x.
The :mod:`EasyDialogs` module defines the following functions:
it is deleted when the output file is closed. In-place filtering is disabled
when standard input is read.
-.. warning::
+.. note::
The current implementation does not work for MS-DOS 8+3 filesystems.
dialog window in a non-standard way it is not necessary to override the complete
event handling.
-.. warning::
+.. note::
- This module is removed in 3.0.
+ This module has been removed in Python 3.x.
Work on the :mod:`FrameWork` has pretty much stopped, now that :mod:`PyObjC` is
available for full Cocoa access from Python, and the documentation describes
If both dictionaries are omitted, the expression is executed in the environment
where :func:`execfile` is called. The return value is ``None``.
- .. warning::
+ .. note::
The default *locals* act as described for function :func:`locals` below:
modifications to the default *locals* dictionary should not be attempted. Pass
Update and return a dictionary representing the current local symbol table.
- .. warning::
+ .. note::
The contents of this dictionary should not be modified; changes may not affect
the values of local variables used by the interpreter.
else that has a :attr:`__dict__` attribute), returns a dictionary corresponding
to the object's symbol table.
- .. warning::
+ .. note::
The returned dictionary should not be modified:
the effects on the corresponding symbol table are undefined. [#]_
-
:mod:`gl` --- *Graphics Library* interface
==========================================
.. warning::
- Some illegal calls to the GL library cause the Python interpreter to dump core.
- In particular, the use of most GL calls is unsafe before the first window is
- opened.
+ Some illegal calls to the GL library cause the Python interpreter to dump
+ core. In particular, the use of most GL calls is unsafe before the first
+ window is opened.
The module is too large to document here in its entirety, but the following
should help you to get started. The parameter conventions for the C functions
The results should be more meaningful than in the past: the timing core
contained a critical bug.
-.. warning::
+.. note::
The :mod:`hotshot` profiler does not yet work well with threads. It is useful to
use an unthreaded script to run the profiler over the code you're interested in
formatted file that contains your private key. *cert_file* is a PEM formatted
certificate chain file.
- .. warning::
+ .. note::
- This does not do any certificate verification!
+ This does not do any certificate verification.
.. versionadded:: 2.0
-
:mod:`ic` --- Access to the Mac OS X Internet Config
====================================================
This module provides access to various internet-related preferences set through
:program:`System Preferences` or the :program:`Finder`.
-.. warning::
+.. note::
- This module is removed in 3.0.
+ This module has been removed in Python 3.x.
.. index:: module: icglue
the function name, a list of lines of context from the source code, and the
index of the current line within that list.
-.. warning::
+.. note::
Keeping references to frame objects, as found in the first element of the frame
records these functions return, can cause your program to create reference
Return name of the n-th day of the week.
- .. warning::
+ .. note::
This follows the US convention of :const:`DAY_1` being Sunday, not the
international convention (ISO 8601) that Monday is the first day of the week.
Return a regular expression that can be used with the regex function to
recognize a positive response to a yes/no question.
- .. warning::
+ .. note::
The expression is in the syntax suitable for the :cfunc:`regex` function from
the C library, which might differ from the syntax used in :mod:`re`.
modules, and the HOWTO :ref:`using-on-mac` for a general introduction to
Mac-specific Python programming.
-.. warning::
+.. note::
- These modules are deprecated and are removed in 3.0.
+ These modules are deprecated and have been removed in Python 3.x.
.. toctree::
interpreter, such as how the interpreter eventloop functions and the like. Use
with care.
-.. warning::
+.. note::
- This module is removed in 3.0.
+ This module has been removed in Python 3.x.
Note the capitalization of the module name; this is a historical artifact.
:class:`FSSpec` objects. This module expects a filesystem which supports forked
files, so it should not be used on UFS partitions.
-.. warning::
+.. note::
- This module is removed in 3.0.
+ This module has been removed in Python 3.0.
The :mod:`macostools` module defines the following functions:
file must be an open file object opened in binary mode (``'rb'`` or
``'r+b'``).
- .. warning::
+ .. note::
If an object containing an unsupported type was marshalled with :func:`dump`,
:func:`load` will substitute ``None`` for the unmarshallable type.
write files see :func:`open`, and for accessing the filesystem see the
:mod:`os` module.
-.. warning::
+.. note::
On Windows, many of these functions do not properly support UNC pathnames.
:func:`splitunc` and :func:`ismount` do handle them correctly.
identify them with ``os.path.islink(file)`` and ``os.path.isdir(file)``, and
invoke :func:`walk` as necessary.
- .. warning::
+ .. note::
This function is deprecated and has been removed in 3.0 in favor of
:func:`os.walk`.
.. warning::
The :mod:`pickle` module is not intended to be secure against erroneous or
- maliciously constructed data. Never unpickle data received from an untrusted or
- unauthenticated source.
+ maliciously constructed data. Never unpickle data received from an untrusted
+ or unauthenticated source.
Note that serialization is a more primitive notion than persistence; although
:mod:`pickle` reads and writes file objects, it does not handle the issue of
:meth:`__getstate__` and :meth:`__setstate__`, the state object needn't be a
dictionary and these methods can do what they want. [#]_
- .. warning::
+ .. note::
For :term:`new-style class`\es, if :meth:`__getstate__` returns a false
value, the :meth:`__setstate__` method will not be called.
Read a plist from the resource with type *restype* from the resource fork of
*path*. Availability: Mac OS X.
- .. warning::
-
- In 3.0, this function is removed.
+ .. note::
+ In Python 3.x, this function has been removed.
.. function:: writePlistToResource(rootObject, path[, restype='plst'[, resid=0]])
Write *rootObject* as a resource with type *restype* to the resource fork of
*path*. Availability: Mac OS X.
- .. warning::
+ .. note::
- In 3.0, this function is removed.
+ In Python 3.x, this function has been removed.
-
:mod:`rexec` --- Restricted execution framework
===============================================
map each character in *from* into the character at the same position in *to*;
*from* and *to* must have the same length.
- .. warning::
+ .. note::
Don't use strings derived from :const:`lowercase` and :const:`uppercase` as
arguments; in some locales, these don't have the same length. For case
.. warning::
- Use :meth:`communicate` rather than :meth:`.stdin.write`,
- :meth:`.stdout.read` or :meth:`.stderr.read` to avoid deadlocks due
- to any of the other OS pipe buffers filling up and blocking the child
- process.
+ Use :meth:`communicate` rather than :attr:`.stdin.write <stdin>`,
+ :attr:`.stdout.read <stdout>` or :attr:`.stderr.read <stderr>` to avoid
+ deadlocks due to any of the other OS pipe buffers filling up and blocking the
+ child process.
.. attribute:: Popen.stdin
-
:mod:`tabnanny` --- Detection of ambiguous indentation
======================================================
is possible to import it into an IDE and use the function :func:`check`
described below.
-.. warning::
+.. note::
- The API provided by this module is likely to change in future releases; such
+ The API provided by this module is likely to change in future releases; such
changes may not be backward compatible.
-
:mod:`traceback` --- Print or retrieve a stack traceback
========================================================
This last example demonstrates the final few formatting functions::
>>> import traceback
- >>> format_list([('spam.py', 3, '<module>', 'spam.eggs()'),
- ... ('eggs.py', 42, 'eggs', 'return "bacon"')])
+ >>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),
+ ... ('eggs.py', 42, 'eggs', 'return "bacon"')])
[' File "spam.py", line 3, in <module>\n spam.eggs()\n',
' File "eggs.py", line 42, in eggs\n return "bacon"\n']
- >>> theError = IndexError('tuple indx out of range')
- >>> traceback.format_exception_only(type(theError), theError)
+ >>> an_error = IndexError('tuple index out of range')
+ >>> traceback.format_exception_only(type(an_error), an_error)
['IndexError: tuple index out of range\n']
Some of these are very old and/or not very robust; marked with "hmm."
:mod:`ihooks`
- --- Import hook support (for :mod:`rexec`; may become obsolete).
-
- .. warning:: The :mod:`ihooks` module has been removed in Python 3.0.
+ --- Import hook support (for :mod:`rexec`; may become obsolete). Removed in
+ Python 3.x.
Platform specific modules
==========
:mod:`audiodev`
- --- Platform-independent API for playing audio data.
-
- .. warning:: The :mod:`audiodev` module has been removed in 3.0.
+ --- Platform-independent API for playing audio data. Removed in Python 3.x.
:mod:`linuxaudiodev`
--- Play audio data on the Linux audio device. Replaced in Python 2.3 by the
- :mod:`ossaudiodev` module.
-
- .. warning:: The :mod:`linuxaudiodev` module has been removed in Python 3.0.
+ :mod:`ossaudiodev` module. Removed in Python 3.x.
:mod:`sunaudio`
--- Interpret Sun audio headers (may become obsolete or a tool/demo).
-
- .. warning:: The :mod:`sunaudio` module has been removed in Python 3.0.
+ Removed in Python 3.x.
:mod:`toaiff`
--- Convert "arbitrary" sound files to AIFF files; should probably become a tool
- or demo. Requires the external program :program:`sox`.
-
-
- .. warning:: The :mod:`toaiff` module has been removed in 3.0.
+ or demo. Requires the external program :program:`sox`. Removed in Python 3.x.
.. _undoc-mac-modules:
\envvar{PYTHONPATH}.
:mod:`timing`
- --- Measure time intervals to high resolution (use :func:`time.clock` instead).
-
- .. warning:: The :mod:`timing` module has been removed in Python 3.0.
+ --- Measure time intervals to high resolution (use :func:`time.clock`
+ instead). Removed in Python 3.x.
SGI-specific Extension modules
:mod:`sv`
--- Interface to the "simple video" board on SGI Indigo (obsolete hardware).
-
- .. warning:: The :mod:`sv` module has been removed in Python 3.0.
-
+ Removed in Python 3.x.
effect of Pascal's ``for i := a to b do``; e.g., ``range(3)`` returns the list
``[0, 1, 2]``.
-.. warning::
+.. note::
.. index::
single: loop; over mutable sequence
:keyword:`except` clause is selected by object identity. An arbitrary value can
be raised along with the identifying string which can be passed to the handler.
-.. warning::
+.. note::
Messages to exceptions are not part of the Python API. Their contents may
change from one version of Python to the next without warning and should not be
Skip the first line of the source, allowing use of non-Unix forms of
``#!cmd``. This is intended for a DOS specific hack only.
- .. warning:: The line numbers in error messages will be off by one!
+ .. note:: The line numbers in error messages will be off by one.
.. cmdoption:: -3
projects / python / commitdiff