in decreasing order of complexity. Note that each flag contains all bits
of the flags below it.
+.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|
+-----------------------------+-------+---------+------------+
| Request | shape | strides | suboffsets |
C or Fortran contiguity can be explicitly requested, with and without stride
information. Without stride information, the buffer must be C-contiguous.
+.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|
+
+-----------------------------------+-------+---------+------------+--------+
| Request | shape | strides | suboffsets | contig |
+===================================+=======+=========+============+========+
In the following table *U* stands for undefined contiguity. The consumer would
have to call :c:func:`PyBuffer_IsContiguous` to determine contiguity.
-
+.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|l|l|
+-------------------------------+-------+---------+------------+--------+----------+--------+
| Request | shape | strides | suboffsets | contig | readonly | format |
.. % because not all compilers support the %z width modifier -- we fake it
.. % when necessary via interpolating PY_FORMAT_SIZE_T.
+ .. tabularcolumns:: |l|l|L|
+
+-------------------+---------------+--------------------------------+
| Format Characters | Type | Comment |
+===================+===============+================================+
.. % Similar comments apply to the %ll width modifier and
.. % PY_FORMAT_LONG_LONG.
+ .. tabularcolumns:: |l|l|L|
+
+-------------------+---------------------+--------------------------------+
| Format Characters | Type | Comment |
+===================+=====================+================================+
The setup function takes a large number of arguments. These are laid out in the
following table.
+ .. tabularcolumns:: |l|L|L|
+
+--------------------+--------------------------------+-------------------------------------------------------------+
| argument name | value | type |
+====================+================================+=============================================================+
*stop_after* tells :func:`setup` when to stop processing; possible values:
+ .. tabularcolumns:: |l|L|
+
+---------------+---------------------------------------------+
| value | description |
+===============+=============================================+
The Extension class describes a single C or C++extension module in a setup
script. It accepts the following keyword arguments in its constructor:
+ .. tabularcolumns:: |l|L|l|
+
+------------------------+--------------------------------+---------------------------+
| argument name | value | type |
+========================+================================+===========================+
The options are all boolean, and affect the values returned by :meth:`readline`
+ .. tabularcolumns:: |l|L|l|
+
+------------------+--------------------------------+---------+
| option name | description | default |
+==================+================================+=========+
Extending/Embedding FAQ
=======================
-.. contents::
+.. only:: html
+
+ .. contents::
.. highlight:: c
General Python FAQ
==================
-.. contents::
+.. only:: html
+
+ .. contents::
+
General Information
===================
Graphic User Interface FAQ
==========================
-.. contents::
+.. only:: html
+
+ .. contents::
.. XXX need review for Python 3.
Library and Extension FAQ
=========================
-.. contents::
+.. only:: html
+
+ .. contents::
General Library Questions
=========================
Programming FAQ
===============
-.. contents::
+.. only:: html
+
+ .. contents::
General Questions
=================
Python on Windows FAQ
=====================
-.. contents::
+.. only:: html
+
+ .. contents::
.. XXX need review for Python 3.
XXX need review for Windows Vista/Seven?
they are used to track. The standard levels and their applicability are
described below (in increasing order of severity):
+.. tabularcolumns:: |l|L|
+
+--------------+---------------------------------------------+
| Level | When it's used |
+==============+=============================================+
Unix-based), it also depends on whether the module distribution being installed
is pure Python or contains extensions ("non-pure"):
+.. tabularcolumns:: |l|l|l|l|
+
+-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
| Platform | Standard installation location | Default value | Notes |
+=================+=====================================================+==================================================+=======+
providing the *errors* string argument. The following string values are defined
and implemented by all standard Python codecs:
+.. tabularcolumns:: |l|L|
+
+-------------------------+-----------------------------------------------+
| Value | Meaning |
+=========================+===============================================+
* an IBM PC code page, which is ASCII compatible
+.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
+
+-----------------+--------------------------------+--------------------------------+
| Codec | Aliases | Languages |
+=================+================================+================================+
.. XXX fix here, should be in above table
+.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
+
+--------------------+---------+---------------------------+
| Codec | Aliases | Purpose |
+====================+=========+===========================+
The following codecs provide bytes-to-bytes mappings.
+.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
+
+--------------------+---------------------------+---------------------------+
| Codec | Aliases | Purpose |
+====================+===========================+===========================+
The following codecs provide string-to-string mappings.
+.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
+
+--------------------+---------------------------+---------------------------+
| Codec | Aliases | Purpose |
+====================+===========================+===========================+
The collections module offers the following :term:`ABCs <abstract base class>`:
+.. tabularcolumns:: |l|L|L|L|
+
========================= ===================== ====================== ====================================================
ABC Inherits from Abstract Methods Mixin Methods
========================= ===================== ====================== ====================================================
the full :class:`Set` API, it only necessary to supply the three underlying
abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
The ABC supplies the remaining methods such as :meth:`__and__` and
-:meth:`isdisjoint` ::
+:meth:`isdisjoint`::
class ListBasedSet(collections.Set):
''' Alternate set implementation favoring space over speed
*return_when* indicates when this function should return. It must be one of
the following constants:
+ .. tabularcolumns:: |l|L|
+
+-----------------------------+----------------------------------------+
| Constant | Description |
+=============================+========================================+
Controls the type of Content Transfer Encodings that may be or are
required to be used. The possible values are:
+ .. tabularcolumns:: |l|L|
+
======== ===============================================================
``7bit`` all data must be "7 bit clean" (ASCII-only). This means that
where necessary data will be encoded using either
========= ===============================================================
Character Meaning
- --------- ---------------------------------------------------------------
+ ========= ===============================================================
``'r'`` open for reading (default)
``'w'`` open for writing, truncating the file first
``'x'`` open for exclusive creation, failing if the file already exists
Describes how argument values are bound to the parameter. Possible values
(accessible via :class:`Parameter`, like ``Parameter.KEYWORD_ONLY``):
+ .. tabularcolumns:: |l|L|
+
+------------------------+----------------------------------------------+
| Name | Meaning |
+========================+==============================================+
The following table summarizes the ABCs provided by the :mod:`io` module:
+.. tabularcolumns:: |l|l|L|L|
+
========================= ================== ======================== ==================================================
ABC Inherits Stub Methods Mixin Methods and Properties
========================= ================== ======================== ==================================================
Returns the database of the local conventions as a dictionary. This dictionary
has the following strings as keys:
+ .. tabularcolumns:: |l|l|L|
+
+----------------------+-------------------------------------+--------------------------------+
| Category | Key | Meaning |
+======================+=====================================+================================+
The following keyword arguments are supported.
+ .. tabularcolumns:: |l|L|
+
+--------------+---------------------------------------------+
| Format | Description |
+==============+=============================================+
.. versionadded:: 3.1
+ ..
+
.. warning::
Invoking the system shell with ``shell=True`` can be a security hazard
programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard
[C99]_, 'Characteristics of floating types', for details.
+ .. tabularcolumns:: |l|l|L|
+
+---------------------+----------------+--------------------------------------------------+
| attribute | float.h macro | explanation |
+=====================+================+==================================================+
A :term:`struct sequence` that holds information about Python's internal
representation of integers. The attributes are read only.
+ .. tabularcolumns:: |l|L|
+
+-------------------------+----------------------------------------------+
| Attribute | Explanation |
+=========================+==============================================+
A :term:`struct sequence` holding information about the thread
implementation.
+ .. tabularcolumns:: |l|p{0.7\linewidth}|
+
+------------------+---------------------------------------------------------+
| Attribute | Explanation |
+==================+=========================================================+
All the :mod:`ttk` Widgets accepts the following options:
+ .. tabularcolumns:: |l|L|
+
+-----------+--------------------------------------------------------------+
| Option | Description |
+===========+==============================================================+
The following options are supported by widgets that are controlled by a
scrollbar.
+ .. tabularcolumns:: |l|L|
+
+----------------+---------------------------------------------------------+
- | option | description |
+ | Option | Description |
+================+=========================================================+
| xscrollcommand | Used to communicate with horizontal scrollbars. |
| | |
The following options are supported by labels, buttons and other button-like
widgets.
-.. tabularcolumns:: |p{0.2\textwidth}|p{0.7\textwidth}|
-..
+ .. tabularcolumns:: |l|p{0.7\linewidth}|
+--------------+-----------------------------------------------------------+
- | option | description |
+ | Option | Description |
+==============+===========================================================+
| text | Specifies a text string to be displayed inside the widget.|
+--------------+-----------------------------------------------------------+
Compatibility Options
^^^^^^^^^^^^^^^^^^^^^
+ .. tabularcolumns:: |l|L|
+
+--------+----------------------------------------------------------------+
- | option | description |
+ | Option | Description |
+========+================================================================+
| state | May be set to "normal" or "disabled" to control the "disabled" |
| | state bit. This is a write-only option: setting it changes the |
The widget state is a bitmap of independent state flags.
+ .. tabularcolumns:: |l|L|
+
+------------+-------------------------------------------------------------+
- | flag | description |
+ | Flag | Description |
+============+=============================================================+
| active | The mouse cursor is over the widget and pressing a mouse |
| | button will cause some action to occur |
This widget accepts the following specific options:
+ .. tabularcolumns:: |l|L|
+
+-----------------+--------------------------------------------------------+
- | option | description |
+ | Option | Description |
+=================+========================================================+
| exportselection | Boolean value. If set, the widget selection is linked |
| | to the Window Manager selection (which can be returned |
This widget accepts the following specific options:
+ .. tabularcolumns:: |l|L|
+
+---------+----------------------------------------------------------------+
- | option | description |
+ | Option | Description |
+=========+================================================================+
| height | If present and greater than zero, specifies the desired height |
| | of the pane area (not including internal padding or tabs). |
There are also specific options for tabs:
+ .. tabularcolumns:: |l|L|
+
+-----------+--------------------------------------------------------------+
- | option | description |
+ | Option | Description |
+===========+==============================================================+
| state | Either "normal", "disabled" or "hidden". If "disabled", then |
| | the tab is not selectable. If "hidden", then the tab is not |
This widget accepts the following specific options:
+ .. tabularcolumns:: |l|L|
+
+----------+---------------------------------------------------------------+
- | option | description |
+ | Option | Description |
+==========+===============================================================+
| orient | One of "horizontal" or "vertical". Specifies the orientation |
| | of the progress bar. |
This widget accepts the following specific option:
+ .. tabularcolumns:: |l|L|
+
+--------+----------------------------------------------------------------+
- | option | description |
+ | Option | Description |
+========+================================================================+
| orient | One of "horizontal" or "vertical". Specifies the orientation of|
| | the separator. |
This widget accepts the following specific options:
-.. tabularcolumns:: |p{0.2\textwidth}|p{0.7\textwidth}|
-..
+ .. tabularcolumns:: |l|p{0.7\linewidth}|
+----------------+--------------------------------------------------------+
- | option | description |
+ | Option | Description |
+================+========================================================+
| columns | A list of column identifiers, specifying the number of |
| | columns and their names. |
The following item options may be specified for items in the insert and item
widget commands.
+ .. tabularcolumns:: |l|L|
+
+--------+---------------------------------------------------------------+
- | option | description |
+ | Option | Description |
+========+===============================================================+
| text | The textual label to display for the item. |
+--------+---------------------------------------------------------------+
The following options may be specified on tags:
+ .. tabularcolumns:: |l|L|
+
+------------+-----------------------------------------------------------+
- | option | description |
+ | Option | Description |
+============+===========================================================+
| foreground | Specifies the text foreground color. |
+------------+-----------------------------------------------------------+
The Treeview widget generates the following virtual events.
+ .. tabularcolumns:: |l|L|
+
+--------------------+--------------------------------------------------+
- | event | description |
+ | Event | Description |
+====================+==================================================+
| <<TreeviewSelect>> | Generated whenever the selection changes. |
+--------------------+--------------------------------------------------+
The demo scripts are:
+.. tabularcolumns:: |l|L|L|
+
+----------------+------------------------------+-----------------------+
| Name | Description | Features |
-+----------------+------------------------------+-----------------------+
++================+==============================+=======================+
| bytedesign | complex classical | :func:`tracer`, delay,|
| | turtle graphics pattern | :func:`update` |
+----------------+------------------------------+-----------------------+
This categorization is useful to be able to filter out groups of warnings. The
following warnings category classes are currently defined:
+.. tabularcolumns:: |l|p{0.6\linewidth}|
+
+----------------------------------+-----------------------------------------------+
| Class | Description |
+==================================+===============================================+
Supported XPath syntax
^^^^^^^^^^^^^^^^^^^^^^
+.. tabularcolumns:: |l|L|
+
+-----------------------+------------------------------------------------------+
| Syntax | Meaning |
+=======================+======================================================+
(e.g. that can be marshalled through XML), include the following (and except
where noted, they are unmarshalled as the same Python type):
+ .. tabularcolumns:: |l|L|
+
+---------------------------------+---------------------------------------------+
| Name | Meaning |
+=================================+=============================================+
Special attributes:
+ .. tabularcolumns:: |l|L|l|
+
+-------------------------+-------------------------------+-----------+
| Attribute | Meaning | |
+=========================+===============================+===========+
| :keyword:`not` ``x`` | Boolean NOT |
+-----------------------------------------------+-------------------------------------+
| :keyword:`in`, :keyword:`not in`, | Comparisons, including membership |
-| :keyword:`is`, :keyword:`is not`, ``<``, | tests and identity tests, |
+| :keyword:`is`, :keyword:`is not`, ``<``, | tests and identity tests |
| ``<=``, ``>``, ``>=``, ``!=``, ``==`` | |
+-----------------------------------------------+-------------------------------------+
| ``|`` | Bitwise OR |
:pep:`338` defines executing modules as scripts.
-Footnotes
-=========
+.. rubric:: Footnotes
.. [#fnmo] See :class:`types.ModuleType`.
The minimum set of controls implemented by all ``policy`` objects are:
+ .. tabularcolumns:: |l|L|
+
=============== =======================================================
max_line_length The maximum length, excluding the linesep character(s),
individual lines may have when a ``Message`` is
The new policies are instances of :class:`~email.policy.EmailPolicy`,
and add the following additional controls:
+ .. tabularcolumns:: |l|L|
+
=============== =======================================================
refold_source Controls whether or not headers parsed by a
:mod:`~email.parser` are refolded by the