.. % 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.
- .. % Similar comments apply to the %ll width modifier and
- .. % PY_FORMAT_LONG_LONG.
+ .. tabularcolumns:: |l|l|L|
+
+-------------------+---------------------+--------------------------------+
| Format Characters | Type | Comment |
+===================+=====================+================================+
.. class:: Extension
The Extension class describes a single C or C++extension module in a setup
- script. It accepts the following keyword arguments in its constructor:
+ script. It accepts the following keyword arguments in its constructor
+ .. tabularcolumns:: |l|L|l|
+
+------------------------+--------------------------------+---------------------------+
| argument name | value | type |
+========================+================================+===========================+
Graphic User Interface FAQ
==========================
- .. contents::
+ .. only:: html
+
+ .. contents::
-.. XXX need review for Python 3.
-
-
-General GUI Questions
-=====================
-
What platform-independent GUI toolkits exist for Python?
========================================================
Python on Windows FAQ
=====================
- .. contents::
+ .. only:: html
+
+ .. contents::
-.. XXX need review for Python 3.
- XXX need review for Windows Vista/Seven?
-
-
How do I run a Python program under Windows?
--------------------------------------------
| utf_8_sig | | all languages |
+-----------------+--------------------------------+--------------------------------+
-.. XXX fix here, should be in above table
-
-.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
-
-+--------------------+---------+---------------------------+
-| Codec | Aliases | Purpose |
-+====================+=========+===========================+
-| idna | | Implements :rfc:`3490`, |
-| | | see also |
-| | | :mod:`encodings.idna` |
-+--------------------+---------+---------------------------+
-| mbcs | dbcs | Windows only: Encode |
-| | | operand according to the |
-| | | ANSI codepage (CP_ACP) |
-+--------------------+---------+---------------------------+
-| palmos | | Encoding of PalmOS 3.5 |
-+--------------------+---------+---------------------------+
-| punycode | | Implements :rfc:`3492` |
-+--------------------+---------+---------------------------+
-| raw_unicode_escape | | Produce a string that is |
-| | | suitable as raw Unicode |
-| | | literal in Python source |
-| | | code |
-+--------------------+---------+---------------------------+
-| undefined | | Raise an exception for |
-| | | all conversions. Can be |
-| | | used as the system |
-| | | encoding if no automatic |
-| | | coercion between byte and |
-| | | Unicode strings is |
-| | | desired. |
-+--------------------+---------+---------------------------+
-| unicode_escape | | Produce a string that is |
-| | | suitable as Unicode |
-| | | literal in Python source |
-| | | code |
-+--------------------+---------+---------------------------+
-| unicode_internal | | Return the internal |
-| | | representation of the |
-| | | operand |
-| | | |
-| | | .. deprecated:: 3.3 |
-+--------------------+---------+---------------------------+
-
-The following codecs provide bytes-to-bytes mappings.
-
-.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
-
-+--------------------+---------------------------+---------------------------+
-| Codec | Aliases | Purpose |
-+====================+===========================+===========================+
-| base64_codec | base64, base-64 | Convert operand to MIME |
-| | | base64 |
-+--------------------+---------------------------+---------------------------+
-| bz2_codec | bz2 | Compress the operand |
-| | | using bz2 |
-+--------------------+---------------------------+---------------------------+
-| hex_codec | hex | Convert operand to |
-| | | hexadecimal |
-| | | representation, with two |
-| | | digits per byte |
-+--------------------+---------------------------+---------------------------+
-| quopri_codec | quopri, quoted-printable, | Convert operand to MIME |
-| | quotedprintable | quoted printable |
-+--------------------+---------------------------+---------------------------+
-| uu_codec | uu | Convert the operand using |
-| | | uuencode |
-+--------------------+---------------------------+---------------------------+
-| zlib_codec | zip, zlib | Compress the operand |
-| | | using gzip |
-+--------------------+---------------------------+---------------------------+
-
-The following codecs provide string-to-string mappings.
-
-.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
-
-+--------------------+---------------------------+---------------------------+
-| Codec | Aliases | Purpose |
-+====================+===========================+===========================+
-| rot_13 | rot13 | Returns the Caesar-cypher |
-| | | encryption of the operand |
-+--------------------+---------------------------+---------------------------+
-
-.. versionadded:: 3.2
- bytes-to-bytes and string-to-string codecs.
+A number of codecs are specific to Python, so their codec names have no meaning
+outside Python. Some of them don't convert from Unicode strings to byte strings,
+but instead use the property of the Python codecs machinery that any bijective
+function with one argument can be considered as an encoding.
+
+For the codecs listed below, the result in the "encoding" direction is always a
+byte string. The result of the "decoding" direction is listed as operand type in
+the table.
+
++.. tabularcolumns:: |l|p{0.3\linewidth}|l|p{0.3\linewidth}|
++
++--------------------+---------------------------+----------------+---------------------------+
+| Codec | Aliases | Operand type | Purpose |
++====================+===========================+================+===========================+
+| base64_codec | base64, base-64 | byte string | Convert operand to MIME |
+| | | | base64 |
++--------------------+---------------------------+----------------+---------------------------+
+| bz2_codec | bz2 | byte string | Compress the operand |
+| | | | using bz2 |
++--------------------+---------------------------+----------------+---------------------------+
+| hex_codec | hex | byte string | Convert operand to |
+| | | | hexadecimal |
+| | | | representation, with two |
+| | | | digits per byte |
++--------------------+---------------------------+----------------+---------------------------+
+| idna | | Unicode string | Implements :rfc:`3490`, |
+| | | | see also |
+| | | | :mod:`encodings.idna` |
++--------------------+---------------------------+----------------+---------------------------+
+| mbcs | dbcs | Unicode string | Windows only: Encode |
+| | | | operand according to the |
+| | | | ANSI codepage (CP_ACP) |
++--------------------+---------------------------+----------------+---------------------------+
+| palmos | | Unicode string | Encoding of PalmOS 3.5 |
++--------------------+---------------------------+----------------+---------------------------+
+| punycode | | Unicode string | Implements :rfc:`3492` |
++--------------------+---------------------------+----------------+---------------------------+
+| quopri_codec | quopri, quoted-printable, | byte string | Convert operand to MIME |
+| | quotedprintable | | quoted printable |
++--------------------+---------------------------+----------------+---------------------------+
+| raw_unicode_escape | | Unicode string | Produce a string that is |
+| | | | suitable as raw Unicode |
+| | | | literal in Python source |
+| | | | code |
++--------------------+---------------------------+----------------+---------------------------+
+| rot_13 | rot13 | Unicode string | Returns the Caesar-cypher |
+| | | | encryption of the operand |
++--------------------+---------------------------+----------------+---------------------------+
+| string_escape | | byte string | Produce a string that is |
+| | | | suitable as string |
+| | | | literal in Python source |
+| | | | code |
++--------------------+---------------------------+----------------+---------------------------+
+| undefined | | any | Raise an exception for |
+| | | | all conversions. Can be |
+| | | | used as the system |
+| | | | encoding if no automatic |
+| | | | :term:`coercion` between |
+| | | | byte and Unicode strings |
+| | | | is desired. |
++--------------------+---------------------------+----------------+---------------------------+
+| unicode_escape | | Unicode string | Produce a string that is |
+| | | | suitable as Unicode |
+| | | | literal in Python source |
+| | | | code |
++--------------------+---------------------------+----------------+---------------------------+
+| unicode_internal | | Unicode string | Return the internal |
+| | | | representation of the |
+| | | | operand |
++--------------------+---------------------------+----------------+---------------------------+
+| uu_codec | uu | byte string | Convert the operand using |
+| | | | uuencode |
++--------------------+---------------------------+----------------+---------------------------+
+| zlib_codec | zip, zlib | byte string | Compress the operand |
+| | | | using gzip |
++--------------------+---------------------------+----------------+---------------------------+
+
+.. versionadded:: 2.3
+ The ``idna`` and ``punycode`` encodings.
:mod:`encodings.idna` --- Internationalized Domain Names in Applications
... shell=True)
'ls: non_existent_file: No such file or directory\n'
- .. versionadded:: 3.1
+ .. versionadded:: 2.7
+ ..
+
.. warning::
Invoking the system shell with ``shell=True`` can be a security hazard
:const:`no_user_site` :option:`-s`
:const:`no_site` :option:`-S`
:const:`ignore_environment` :option:`-E`
+ :const:`tabcheck` :option:`-t` or :option:`-tt <-t>`
:const:`verbose` :option:`-v`
+ :const:`unicode` :option:`-U`
:const:`bytes_warning` :option:`-b`
- :const:`quiet` :option:`-q`
:const:`hash_randomization` :option:`-R`
- ============================= =============================
+ ============================= ===================================
- .. versionchanged:: 3.2
- Added ``quiet`` attribute for the new :option:`-q` flag.
+ .. versionadded:: 2.6
- .. versionadded:: 3.2.3
+ .. versionadded:: 2.7.3
The ``hash_randomization`` attribute.
- .. versionchanged:: 3.3
- Removed obsolete ``division_warning`` attribute.
-
-
.. data:: float_info
- A :term:`struct sequence` holding information about the float type. It
- contains low level information about the precision and internal
- representation. The values correspond to the various floating-point
- constants defined in the standard header file :file:`float.h` for the 'C'
- programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard
- [C99]_, 'Characteristics of floating types', for details.
+ A structseq holding information about the float type. It contains low level
+ information about the precision and internal representation. The values
+ correspond to the various floating-point constants defined in the standard
+ header file :file:`float.h` for the 'C' 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 |
+=====================+================+==================================================+
This is called ``hexversion`` since it only really looks meaningful when viewed
as the result of passing it to the built-in :func:`hex` function. The
- :term:`struct sequence` :data:`sys.version_info` may be used for a more
- human-friendly encoding of the same information.
+ ``version_info`` value may be used for a more human-friendly encoding of the
+ same information.
- More details of ``hexversion`` can be found at :ref:`apiabiversion`
+ The ``hexversion`` is a 32-bit number with the following layout:
+ +-------------------------+------------------------------------------------+
+ | Bits (big endian order) | Meaning |
+ +=========================+================================================+
+ | :const:`1-8` | ``PY_MAJOR_VERSION`` (the ``2`` in |
+ | | ``2.1.0a3``) |
+ +-------------------------+------------------------------------------------+
+ | :const:`9-16` | ``PY_MINOR_VERSION`` (the ``1`` in |
+ | | ``2.1.0a3``) |
+ +-------------------------+------------------------------------------------+
+ | :const:`17-24` | ``PY_MICRO_VERSION`` (the ``0`` in |
+ | | ``2.1.0a3``) |
+ +-------------------------+------------------------------------------------+
+ | :const:`25-28` | ``PY_RELEASE_LEVEL`` (``0xA`` for alpha, |
+ | | ``0xB`` for beta, ``0xC`` for release |
+ | | candidate and ``0xF`` for final) |
+ +-------------------------+------------------------------------------------+
+ | :const:`29-32` | ``PY_RELEASE_SERIAL`` (the ``3`` in |
+ | | ``2.1.0a3``, zero for final releases) |
+ +-------------------------+------------------------------------------------+
-.. data:: implementation
+ Thus ``2.1.0a3`` is hexversion ``0x020100a3``.
- An object containing information about the implementation of the
- currently running Python interpreter. The following attributes are
- required to exist in all Python implementations.
+ .. versionadded:: 1.5.2
- *name* is the implementation's identifier, e.g. ``'cpython'``. The actual
- string is defined by the Python implementation, but it is guaranteed to be
- lower case.
- *version* is a named tuple, in the same format as
- :data:`sys.version_info`. It represents the version of the Python
- *implementation*. This has a distinct meaning from the specific
- version of the Python *language* to which the currently running
- interpreter conforms, which ``sys.version_info`` represents. For
- example, for PyPy 1.8 ``sys.implementation.version`` might be
- ``sys.version_info(1, 8, 0, 'final', 0)``, whereas ``sys.version_info``
- would be ``sys.version_info(2, 7, 2, 'final', 0)``. For CPython they
- are the same value, since it is the reference implementation.
+.. data:: long_info
- *hexversion* is the implementation version in hexadecimal format, like
- :data:`sys.hexversion`.
-
- *cache_tag* is the tag used by the import machinery in the filenames of
- cached modules. By convention, it would be a composite of the
- implementation's name and version, like ``'cpython-33'``. However, a
- Python implementation may use some other value if appropriate. If
- ``cache_tag`` is set to ``None``, it indicates that module caching should
- be disabled.
-
- :data:`sys.implementation` may contain additional attributes specific to
- the Python implementation. These non-standard attributes must start with
- an underscore, and are not described here. Regardless of its contents,
- :data:`sys.implementation` will not change during a run of the interpreter,
- nor between implementation versions. (It may change between Python
- language versions, however.) See `PEP 421` for more information.
-
- .. versionadded:: 3.3
-
-
-.. data:: int_info
-
- A :term:`struct sequence` that holds information about Python's internal
- representation of integers. The attributes are read only.
+ A struct sequence that holds information about Python's
+ internal representation of integers. The attributes are read only.
+ .. tabularcolumns:: |l|L|
+
+-------------------------+----------------------------------------------+
| Attribute | Explanation |
+=========================+==============================================+
Demo scripts
============
-There is a set of demo scripts in the :mod:`turtledemo` package. These
-scripts can be run and viewed using the supplied demo viewer as follows::
-
- python -m turtledemo
+There is a set of demo scripts in the turtledemo directory located in the
+:file:`Demo/turtle` directory in the source distribution.
-Alternatively, you can run the demo scripts individually. For example, ::
-
- python -m turtledemo.bytedesign
-
-The :mod:`turtledemo` package directory contains:
+It contains:
- a set of 15 demo scripts demonstrating different features of the new module
- :mod:`turtle`;
-- a demo viewer :file:`__main__.py` which can be used to view the sourcecode
+ :mod:`turtle`
+- a demo viewer :file:`turtleDemo.py` which can be used to view the sourcecode
of the scripts and run them at the same time. 14 of the examples can be
accessed via the Examples menu; all of them can also be run standalone.
-- The example :mod:`turtledemo.two_canvases` demonstrates the simultaneous
+- The example :file:`turtledemo_two_canvases.py` demonstrates the simultaneous
use of two canvases with the turtle module. Therefore it only can be run
standalone.
-- There is a :file:`turtle.cfg` file in this directory, which serves as an
+- There is a :file:`turtle.cfg` file in this directory, which also serves as an
example for how to write and use such files.
-The demo scripts are:
+The demoscripts are:
+ .. tabularcolumns:: |l|L|L|
+
+----------------+------------------------------+-----------------------+
| Name | Description | Features |
- +----------------+------------------------------+-----------------------+
+ +================+==============================+=======================+
| bytedesign | complex classical | :func:`tracer`, delay,|
-| | turtle graphics pattern | :func:`update` |
+| | turtlegraphics pattern | :func:`update` |
+----------------+------------------------------+-----------------------+
| chaos | graphs Verhulst dynamics, | world coordinates |
| | shows that computer's | |
Special attributes:
- +-------------------------+-------------------------------+-----------+
- | Attribute | Meaning | |
- +=========================+===============================+===========+
- | :attr:`__doc__` | The function's documentation | Writable |
- | | string, or ``None`` if | |
- | | unavailable | |
- +-------------------------+-------------------------------+-----------+
- | :attr:`__name__` | The function's name | Writable |
- +-------------------------+-------------------------------+-----------+
- | :attr:`__qualname__` | The function's | Writable |
- | | :term:`qualified name` | |
- | | | |
- | | .. versionadded:: 3.3 | |
- +-------------------------+-------------------------------+-----------+
- | :attr:`__module__` | The name of the module the | Writable |
- | | function was defined in, or | |
- | | ``None`` if unavailable. | |
- +-------------------------+-------------------------------+-----------+
- | :attr:`__defaults__` | A tuple containing default | Writable |
- | | argument values for those | |
- | | arguments that have defaults, | |
- | | or ``None`` if no arguments | |
- | | have a default value | |
- +-------------------------+-------------------------------+-----------+
- | :attr:`__code__` | The code object representing | Writable |
- | | the compiled function body. | |
- +-------------------------+-------------------------------+-----------+
- | :attr:`__globals__` | A reference to the dictionary | Read-only |
- | | that holds the function's | |
- | | global variables --- the | |
- | | global namespace of the | |
- | | module in which the function | |
- | | was defined. | |
- +-------------------------+-------------------------------+-----------+
- | :attr:`__dict__` | The namespace supporting | Writable |
- | | arbitrary function | |
- | | attributes. | |
- +-------------------------+-------------------------------+-----------+
- | :attr:`__closure__` | ``None`` or a tuple of cells | Read-only |
- | | that contain bindings for the | |
- | | function's free variables. | |
- +-------------------------+-------------------------------+-----------+
- | :attr:`__annotations__` | A dict containing annotations | Writable |
- | | of parameters. The keys of | |
- | | the dict are the parameter | |
- | | names, or ``'return'`` for | |
- | | the return annotation, if | |
- | | provided. | |
- +-------------------------+-------------------------------+-----------+
- | :attr:`__kwdefaults__` | A dict containing defaults | Writable |
- | | for keyword-only parameters. | |
- +-------------------------+-------------------------------+-----------+
+ .. tabularcolumns:: |l|L|l|
+
+ +-----------------------+-------------------------------+-----------+
+ | Attribute | Meaning | |
+ +=======================+===============================+===========+
+ | :attr:`func_doc` | The function's documentation | Writable |
+ | | string, or ``None`` if | |
+ | | unavailable | |
+ +-----------------------+-------------------------------+-----------+
+ | :attr:`__doc__` | Another way of spelling | Writable |
+ | | :attr:`func_doc` | |
+ +-----------------------+-------------------------------+-----------+
+ | :attr:`func_name` | The function's name | Writable |
+ +-----------------------+-------------------------------+-----------+
+ | :attr:`__name__` | Another way of spelling | Writable |
+ | | :attr:`func_name` | |
+ +-----------------------+-------------------------------+-----------+
+ | :attr:`__module__` | The name of the module the | Writable |
+ | | function was defined in, or | |
+ | | ``None`` if unavailable. | |
+ +-----------------------+-------------------------------+-----------+
+ | :attr:`func_defaults` | A tuple containing default | Writable |
+ | | argument values for those | |
+ | | arguments that have defaults, | |
+ | | or ``None`` if no arguments | |
+ | | have a default value | |
+ +-----------------------+-------------------------------+-----------+
+ | :attr:`func_code` | The code object representing | Writable |
+ | | the compiled function body. | |
+ +-----------------------+-------------------------------+-----------+
+ | :attr:`func_globals` | A reference to the dictionary | Read-only |
+ | | that holds the function's | |
+ | | global variables --- the | |
+ | | global namespace of the | |
+ | | module in which the function | |
+ | | was defined. | |
+ +-----------------------+-------------------------------+-----------+
+ | :attr:`func_dict` | The namespace supporting | Writable |
+ | | arbitrary function | |
+ | | attributes. | |
+ +-----------------------+-------------------------------+-----------+
+ | :attr:`func_closure` | ``None`` or a tuple of cells | Read-only |
+ | | that contain bindings for the | |
+ | | function's free variables. | |
+ +-----------------------+-------------------------------+-----------+
Most of the attributes labelled "Writable" check the type of the assigned value.
| :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 |
+-----------------------------------------------+-------------------------------------+
projects / python / commitdiff