package_data={'mypkg': ['data/*.dat']},
)
-.. versionadded:: 2.4
-
Installing Additional Files
===========================
Uploading Packages to the Package Index
***************************************
-.. versionadded:: 2.5
-
The Python Package Index (PyPI) not only stores the package info, but also the
package data if the author of the package wishes to. The distutils command
:command:`upload` pushes the distribution files to PyPI.
Generic Attribute Management
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. versionadded:: 2.2
-
Most extension types only use *simple* attributes. So, what makes the
attributes simple? There are only a couple of conditions that must be met:
| data | :file:`{home}/share` | :option:`--install-data` |
+------------------------------+---------------------------+-----------------------------+
-.. versionchanged:: 2.4
- The :option:`--home` option used to be supported only on Unix.
-
.. _inst-alt-install-home:
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
-.. versionadded:: 2.5
-
The ``_ast`` module helps Python applications to process trees of the Python
abstract syntax grammar. The Python compiler currently provides read-only access
to such trees, meaning that applications can only create a tree for a given
.. sectionauthor:: Mark Hammond <MarkH@ActiveState.com>
-.. versionadded:: 2.0
-
These functions expose the Windows registry API to Python. Instead of using an
integer as the registry handle, a handle object is used to ensure that the
handles are closed correctly, even if the programmer neglects to explicitly
from the optional *initializer* value, which must be a list, string, or iterable
over elements of the appropriate type.
- .. versionchanged:: 2.4
- Formerly, only lists or strings were accepted.
-
If given a list or string, the initializer is passed to the new array's
:meth:`fromlist`, :meth:`fromstring`, or :meth:`fromunicode` method (see below)
to add initial items to the array. Otherwise, the iterable initializer is
be raised. If *iterable* is not an array, it must be iterable and its elements
must be the right type to be appended to the array.
- .. versionchanged:: 2.4
- Formerly, the argument could only be another array.
-
.. method:: array.fromfile(f, n)
.. sectionauthor:: Skip Montanaro <skip@mojam.com>
-.. versionadded:: 2.0
-
The :mod:`atexit` module defines functions to register and unregister cleanup
functions. Functions thus registered are automatically executed upon normal
interpreter termination.
saved. After all exit handlers have had a chance to run the last exception to
be raised is re-raised.
- .. versionchanged:: 2.6
- This function now returns *func* which makes it possible to use it as a
- decorator without binding the original name to ``None``.
+ This function returns *func* which makes it possible to use it as a decorator
+ without binding the original name to ``None``.
.. function:: unregister(func)
shutdown. After calling :func:`unregister`, *func* is guaranteed not to be
called when the interpreter shuts down.
- .. versionadded:: 3.0
-
.. seealso::
a-LAW encoding always uses 8 bits samples, so *width* refers only to the sample
width of the output fragment here.
- .. versionadded:: 2.5
-
.. function:: avg(fragment, width)
range of about 13 bits using only 8 bit samples. It is used by the Sun audio
hardware, among others.
- .. versionadded:: 2.5
-
.. function:: lin2lin(fragment, width, newwidth)
The result looks like ``'Sun, 06 Nov 1994 08:49:37 GMT'``.
- .. versionadded:: 2.5
- The *timestamp* parameter.
-
.. method:: BaseHTTPRequestHandler.log_date_time_string()
existing entries. The return value is suitable for use as the first parameter
to ``list.insert()``. This assumes that *list* is already sorted.
- .. versionadded:: 2.1
-
.. function:: bisect_right(list, item[, lo[, hi]])
Similar to :func:`bisect_left`, but returns an insertion point which comes after
(to the right of) any existing entries of *item* in *list*.
- .. versionadded:: 2.1
-
.. function:: bisect(...)
``list.insert(bisect.bisect_left(list, item, lo, hi), item)``. This assumes
that *list* is already sorted.
- .. versionadded:: 2.1
-
.. function:: insort_right(list, item[, lo[, hi]])
Similar to :func:`insort_left`, but inserting *item* in *list* after any
existing entries of *item*.
- .. versionadded:: 2.1
-
.. function:: insort(...)
Wrapper class around a DB object that supports string keys (rather than bytes).
All keys are encoded as UTF-8, then passed to the underlying object.
-
- .. versionadded:: 3.0
.. class:: StringValues(db)
Wrapper class around a DB object that supports string values (rather than bytes).
All values are encoded as UTF-8, then passed to the underlying object.
- .. versionadded:: 3.0
-
.. seealso::
Once instantiated, hash, btree and record objects support the same methods as
dictionaries. In addition, they support the methods listed below.
-.. versionchanged:: 2.3.1
- Added dictionary methods.
-
.. method:: bsddbobject.close()
.. sectionauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
-.. versionadded:: 2.3
-
This module provides a comprehensive interface for the bz2 compression library.
It implements a complete file interface, one-shot (de)compression functions, and
types for sequential (de)compression.
preparing the calendar data for formatting. This class doesn't do any formatting
itself. This is the job of subclasses.
- .. versionadded:: 2.5
:class:`Calendar` instances have the following methods:
-
.. method:: Calendar.iterweekdays(weekday)
Return an iterator for the week day numbers that will be used for one week. The
This class can be used to generate plain text calendars.
- .. versionadded:: 2.5
:class:`TextCalendar` instances have the following methods:
-
.. method:: TextCalendar.formatmonth(theyear, themonth[, w[, l]])
Return a month's calendar in a multi-line string. If *w* is provided, it
This class can be used to generate HTML calendars.
- .. versionadded:: 2.5
:class:`HTMLCalendar` instances have the following methods:
-
.. method:: HTMLCalendar.formatmonth(theyear, themonth[, withyear])
Return a month's calendar as an HTML table. If *withyear* is true the year will
this locale includes an encoding all strings containing month and weekday names
will be returned as unicode.
- .. versionadded:: 2.5
-
.. class:: LocaleHTMLCalendar([firstweekday[, locale]])
this locale includes an encoding all strings containing month and weekday names
will be returned as unicode.
- .. versionadded:: 2.5
For simple text calendars this module provides the following functions.
-
.. function:: setfirstweekday(weekday)
Sets the weekday (``0`` is Monday, ``6`` is Sunday) to start each week. The
import calendar
calendar.setfirstweekday(calendar.SUNDAY)
- .. versionadded:: 2.0
-
.. function:: firstweekday()
Returns the current setting for the weekday to start each week.
- .. versionadded:: 2.0
-
.. function:: isleap(year)
Returns the number of leap years in the range from *y1* to *y2* (exclusive),
where *y1* and *y2* are years.
- .. versionchanged:: 2.0
- This function didn't work for ranges spanning a century change in Python
- 1.5.2.
+ This function works for ranges spanning a century change.
.. function:: weekday(year, month, day)
Returns a month's calendar in a multi-line string using the :meth:`formatmonth`
of the :class:`TextCalendar` class.
- .. versionadded:: 2.0
-
.. function:: prcal(year[, w[, l[c]]])
Returns a 3-column calendar for an entire year as a multi-line string using the
:meth:`formatyear` of the :class:`TextCalendar` class.
- .. versionadded:: 2.0
-
.. function:: timegm(tuple)
Unix timestamp value, assuming an epoch of 1970, and the POSIX encoding. In
fact, :func:`time.gmtime` and :func:`timegm` are each others' inverse.
- .. versionadded:: 2.0
The :mod:`calendar` module exports the following data attributes:
-
.. data:: day_name
An array that represents the days of the week in the current locale.
Higher Level Interface
----------------------
-.. versionadded:: 2.2
-
The previous section explains how to read CGI form data using the
:class:`FieldStorage` class. This section describes a higher level interface
which was added to this class to allow one to do it in a more readable and
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
-.. versionadded:: 2.2
-
.. index::
single: CGI; exceptions
single: CGI; tracebacks
specified, returns the natural logarithm of *x*. There is one branch cut, from 0
along the negative real axis to -∞, continuous from above.
- .. versionchanged:: 2.4
- *base* argument added.
-
.. function:: log10(x)
objects that the Cmd instance or subclass instance will use for input and
output. If not specified, they will default to *sys.stdin* and *sys.stdout*.
- .. versionchanged:: 2.3
- The *stdin* and *stdout* parameters were added.
-
.. _cmd-objects:
Raises a :exc:`LookupError` in case the encoding cannot be found or the codec
doesn't support an incremental encoder.
- .. versionadded:: 2.5
-
.. function:: getincrementaldecoder(encoding)
Raises a :exc:`LookupError` in case the encoding cannot be found or the codec
doesn't support an incremental decoder.
- .. versionadded:: 2.5
-
.. function:: getreader(encoding)
*iterable*. This function is a generator. *errors* (as well as any other keyword
argument) is passed through to the incremental encoder.
- .. versionadded:: 2.5
-
.. function:: iterdecode(iterable, encoding[, errors])
*iterable*. This function is a generator. *errors* (as well as any other keyword
argument) is passed through to the incremental decoder.
- .. versionadded:: 2.5
-
The module also provides the following constants which are useful for reading
and writing to platform dependent files:
IncrementalEncoder Objects
^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. versionadded:: 2.5
-
The :class:`IncrementalEncoder` class is used for encoding an input in multiple
steps. It defines the following methods which every incremental encoder must
define in order to be compatible with the Python codec registry.
marshaling/pickling the state and encoding the bytes of the resulting string
into an integer).
- .. versionadded:: 3.0
-
.. method:: IncrementalEncoder.setstate(state)
Set the state of the encoder to *state*. *state* must be an encoder state
returned by :meth:`getstate`.
- .. versionadded:: 3.0
-
.. _incremental-decoder-objects:
marshaling/pickling the info and encoding the bytes of the resulting string into
an integer.)
- .. versionadded:: 3.0
-
.. method:: IncrementalDecoder.setstate(state)
Set the state of the encoder to *state*. *state* must be a decoder state
returned by :meth:`getstate`.
- .. versionadded:: 3.0
-
The :class:`StreamWriter` and :class:`StreamReader` classes provide generic
working interfaces which can be used to implement new encoding submodules very
easily. See :mod:`encodings.utf_8` for an example of how this is done.
e.g. if optional encoding endings or state markers are available on the stream,
these should be read too.
- .. versionchanged:: 2.4
- *chars* argument added.
-
- .. versionchanged:: 2.4.2
- *firstline* argument added.
-
.. method:: StreamReader.readline([size[, keepends]])
If *keepends* is false line-endings will be stripped from the lines returned.
- .. versionchanged:: 2.4
- *keepends* argument added.
-
.. method:: StreamReader.readlines([sizehint[, keepends]])
| | | | operand |
+--------------------+---------+----------------+---------------------------+
-.. versionadded:: 2.3
- The ``idna`` and ``punycode`` encodings.
-
:mod:`encodings.idna` --- Internationalized Domain Names in Applications
------------------------------------------------------------------------
:synopsis: Internationalized Domain Names implementation
.. moduleauthor:: Martin v. Löwis
-.. versionadded:: 2.3
-
This module implements :rfc:`3490` (Internationalized Domain Names in
Applications) and :rfc:`3492` (Nameprep: A Stringprep Profile for
Internationalized Domain Names (IDN)). It builds upon the ``punycode`` encoding
:synopsis: UTF-8 codec with BOM signature
.. moduleauthor:: Walter Dörwald
-.. versionadded:: 2.5
-
This module implements a variant of the UTF-8 codec: On encoding a UTF-8 encoded
BOM will be prepended to the UTF-8 encoded bytes. For the stateful encoder this
is only done once (on the first write to the byte stream). For decoding an
.. sectionauthor:: Raymond Hettinger <python@rcn.com>
-.. versionadded:: 2.4
-
This module implements high-performance container datatypes. Currently,
there are two datatypes, :class:`deque` and :class:`defaultdict`, and
one datatype factory function, :func:`NamedTuple`. Python already
Future editions of the standard library may include balanced trees and
ordered dictionaries.
-.. versionchanged:: 2.5
- Added :class:`defaultdict`.
-
-.. versionchanged:: 2.6
- Added :class:`NamedTuple`.
-
.. _deque-objects:
``pop(0)`` and ``insert(0, v)`` operations which change both the size and
position of the underlying data representation.
- .. versionadded:: 2.4
Deque objects support the following methods:
-
.. method:: deque.append(x)
Add *x* to the right side of the deque.
Removed the first occurrence of *value*. If not found, raises a
:exc:`ValueError`.
- .. versionadded:: 2.5
-
.. method:: deque.rotate(n)
as if they were passed to the :class:`dict` constructor, including keyword
arguments.
- .. versionadded:: 2.5
:class:`defaultdict` objects support the following method in addition to the
standard :class:`dict` operations:
-
.. method:: defaultdict.__missing__(key)
If the :attr:`default_factory` attribute is ``None``, this raises an
helpful docstring (with typename and fieldnames) and a helpful :meth:`__repr__`
method which lists the tuple contents in a ``name=value`` format.
- .. versionadded:: 2.6
-
The *fieldnames* are specified in a single string and are separated by spaces.
Any valid Python identifier may be used for a field name.
options within a section, and for the default values. This class does not
support the magical interpolation behavior.
- .. versionadded:: 2.3
-
- .. versionchanged:: 2.6
- *dict_type* was added.
-
.. class:: ConfigParser([defaults])
.. % XXX Need to explain what's safer/more predictable about it.
- .. versionadded:: 2.3
-
.. exception:: NoSectionError
Exception raised when an option referenced from a value does not exist. Subclass
of :exc:`InterpolationError`.
- .. versionadded:: 2.3
-
.. exception:: InterpolationSyntaxError
Exception raised when the source text into which substitutions are made does not
conform to the required syntax. Subclass of :exc:`InterpolationError`.
- .. versionadded:: 2.3
-
.. exception:: MissingSectionHeaderError
If the given section exists, and contains the given option, return
:const:`True`; otherwise return :const:`False`.
- .. versionadded:: 1.6
-
.. method:: RawConfigParser.read(filenames)
config.readfp(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
- .. versionchanged:: 2.4
- Returns list of successfully parsed filenames.
-
.. method:: RawConfigParser.readfp(fp[, filename])
true) for *internal* storage of non-string values, full functionality (including
interpolation and output to files) can only be achieved using string values.
- .. versionadded:: 1.6
-
.. method:: RawConfigParser.write(fileobject)
Write a representation of the configuration to the specified file object. This
representation can be parsed by a future :meth:`read` call.
- .. versionadded:: 1.6
-
.. method:: RawConfigParser.remove_option(section, option)
not exist, raise :exc:`NoSectionError`. If the option existed to be removed,
return :const:`True`; otherwise return :const:`False`.
- .. versionadded:: 1.6
-
.. method:: RawConfigParser.remove_section(section)
Return a list of ``(name, value)`` pairs for each option in the given *section*.
Optional arguments have the same meaning as for the :meth:`get` method.
- .. versionadded:: 2.3
-
.. _safeconfigparser-objects:
otherwise raise :exc:`NoSectionError`. *value* must be a string (:class:`str`
or :class:`unicode`); if not, :exc:`TypeError` is raised.
- .. versionadded:: 2.4
-
A small number of constants live in the built-in namespace. They are:
+.. XXX False, True, None are keywords too
+
.. data:: False
The false value of the :class:`bool` type.
- .. versionadded:: 2.3
-
.. data:: True
The true value of the :class:`bool` type.
- .. versionadded:: 2.3
-
.. data:: None
:synopsis: Utilities for with-statement contexts.
-.. versionadded:: 2.5
-
This module provides utilities for common tasks involving the :keyword:`with`
statement. For more information see also :ref:`typecontextmanager` and
:ref:`context-managers`.
to join the headers together, and is by default the combination ``'\r\n'``
(CRLF).
- .. versionchanged:: 2.5
- The default separator has been changed from ``'\n'`` to match the cookie
- specification.
-
.. method:: BaseCookie.js_output([attrs])
.. sectionauthor:: John J. Lee <jjl@pobox.com>
-.. versionadded:: 2.4
-
-
-
The :mod:`cookielib` module defines classes for automatic handling of HTTP
cookies. It is useful for accessing web sites that require small pieces of data
-- :dfn:`cookies` -- to be set on the client machine by an HTTP response from a
case RFC 2109 cookies are downgraded if and only if RFC 2965 handling is turned
off. Therefore, RFC 2109 cookies are downgraded by default.
- .. versionadded:: 2.5
General strictness switches:
-
.. attribute:: DefaultCookiePolicy.strict_domain
Don't allow sites to set two-component domains with country-code top-level
domains like ``.co.uk``, ``.gov.uk``, ``.co.nz``.etc. This is far from perfect
and isn't guaranteed to work!
-RFC 2965 protocol strictness switches:
+RFC 2965 protocol strictness switches:
.. attribute:: DefaultCookiePolicy.strict_rfc2965_unverifiable
another site). If this is false, cookies are *never* blocked on the basis of
verifiability
-Netscape protocol strictness switches:
+Netscape protocol strictness switches:
.. attribute:: DefaultCookiePolicy.strict_ns_unverifiable
:mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in
which case :attr:`version` is 0.
- .. versionadded:: 2.5
-
.. attribute:: Cookie.port_specified
classes (shallow and deeply), by returning the original object unchanged; this
is compatible with the way these are treated by the :mod:`pickle` module.
-.. versionchanged:: 2.5
- Added copying functions.
-
.. index:: module: pickle
Classes can use the same interfaces to control copying that they use to control
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
-.. versionadded:: 2.3
-
.. index::
single: csv
pair: data; tabular
All data read are returned as strings. No automatic data type conversion is
performed.
- .. versionchanged:: 2.5
- The parser is now stricter with respect to multi-line quoted fields. Previously,
- if a line ended within a quoted field without a terminating newline character, a
- newline would be inserted into the returned field. This behavior caused problems
- when reading files which contained carriage return characters within fields.
- The behavior was changed to return the field without inserting newlines. As a
- consequence, if newlines embedded within fields are important, the input should
- be split into lines in a manner which preserves the newline characters.
+ The parser is quite strict with respect to multi-line quoted fields. Previously,
+ if a line ended within a quoted field without a terminating newline character, a
+ newline would be inserted into the returned field. This behavior caused problems
+ when reading files which contained carriage return characters within fields.
+ The behavior was changed to return the field without inserting newlines. As a
+ consequence, if newlines embedded within fields are important, the input should
+ be split into lines in a manner which preserves the newline characters.
.. function:: writer(csvfile[, dialect='excel'][, fmtparam])
Returns the current maximum field size allowed by the parser. If *new_limit* is
given, this becomes the new limit.
- .. versionadded:: 2.5
The :mod:`csv` module defines the following classes:
-
.. class:: DictReader(csvfile[, fieldnames=:const:None,[, restkey=:const:None[, restval=None[, dialect='excel'[, *args, **kwds]]]]])
Create an object which operates like a regular reader but maps the information
The number of lines read from the source iterator. This is not the same as the
number of records returned, as records can span multiple lines.
- .. versionadded:: 2.5
Writer Objects
.. moduleauthor:: Thomas Heller <theller@python.net>
-.. versionadded:: 2.5
-
``ctypes`` is a foreign function library for Python. It provides C compatible
data types, and allows calling functions in dlls/shared libraries. It can be
used to wrap these libraries in pure Python.
can be True or False, and the constructor accepts any object that has a truth
value.
- .. versionadded:: 2.6
-
.. class:: HRESULT
.. sectionauthor:: Eric S. Raymond <esr@thyrsus.com>
-.. versionadded:: 1.6
-
The :mod:`curses.ascii` module supplies name constants for ASCII characters and
functions to test membership in various ASCII character classes. The constants
supplied are names for control characters as follows:
.. sectionauthor:: Eric Raymond <esr@thyrsus.com>
-.. versionchanged:: 1.6
- Added support for the ``ncurses`` library and converted to a package.
-
The :mod:`curses` module provides an interface to the curses library, the
de-facto standard for portable advanced terminal handling.
.. sectionauthor:: Eric Raymond <esr@thyrsus.com>
-.. versionadded:: 1.6
-
The :mod:`curses.textpad` module provides a :class:`Textbox` class that handles
elementary text editing in a curses window, supporting a set of keybindings
resembling those of Emacs (thus, also of Netscape Navigator, BBedit 6.x,
.. sectionauthor:: Eric Raymond <esr@thyrsus.com>
-.. versionadded:: 1.6
-
This module supplies one function, :func:`wrapper`, which runs another function
which should be the rest of your curses-using application. If the application
raises an exception, :func:`wrapper` will restore the terminal to a sane state
.. sectionauthor:: A.M. Kuchling <amk@amk.ca>
-.. versionadded:: 2.3
-
The :mod:`datetime` module supplies classes for manipulating dates and times in
both simple and complex ways. While date and time arithmetic is supported, the
focus of the implementation is on efficient member extraction for output
can't be parsed by :func:`time.strptime` or if it returns a value which isn't a
time tuple.
- .. versionadded:: 2.5
Class attributes:
.. module:: decimal
:synopsis: Implementation of the General Decimal Arithmetic Specification.
-
.. moduleauthor:: Eric Price <eprice at tjhsst.edu>
.. moduleauthor:: Facundo Batista <facundo at taniquetil.com.ar>
.. moduleauthor:: Raymond Hettinger <python at rcn.com>
.. moduleauthor:: Aahz <aahz at pobox.com>
.. moduleauthor:: Tim Peters <tim.one at comcast.net>
-
-
.. sectionauthor:: Raymond D. Hettinger <python at rcn.com>
-.. versionadded:: 2.4
-
The :mod:`decimal` module provides support for decimal floating point
arithmetic. It offers several advantages over the :class:`float()` datatype:
when exiting the with-statement. If no context is specified, a copy of the
current context is used.
- .. versionadded:: 2.5
-
For example, the following code sets the current decimal precision to 42 places,
performs a calculation, and then automatically restores the previous context::
.. % LaTeXification by Fred L. Drake, Jr. <fdrake@acm.org>.
-.. versionadded:: 2.1
-
-
.. class:: SequenceMatcher
This is a flexible class for comparing pairs of sequences of any type, so long
:file:`Tools/scripts/diff.py` is a command-line front-end to this class and
contains a good example of its use.
- .. versionadded:: 2.4
-
.. function:: context_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm])
:file:`Tools/scripts/diff.py` is a command-line front-end for this function.
- .. versionadded:: 2.3
-
.. function:: get_close_matches(word, possibilities[, n][, cutoff])
:file:`Tools/scripts/diff.py` is a command-line front-end for this function.
- .. versionadded:: 2.3
-
.. function:: IS_LINE_JUNK(line)
then ``i+n != i'`` or ``j+n != j'``; in other words, adjacent triples always
describe non-adjacent equal blocks.
- .. % Explain why a dummy is used!
-
- .. versionchanged:: 2.5
- The guarantee that adjacent triples always describe non-adjacent blocks was
- implemented.
-
::
>>> s = SequenceMatcher(None, "abxcd", "abcd")
The groups are returned in the same format as :meth:`get_opcodes`.
- .. versionadded:: 2.3
-
.. method:: SequenceMatcher.ratio()
Any classes found are recursively searched similarly, to test docstrings in
their contained methods and nested classes.
-.. versionchanged:: 2.4
- A "private name" concept is deprecated and no longer documented.
-
.. _doctest-finding-examples:
don't believe tabs should mean that, too bad: don't use hard tabs, or write
your own :class:`DocTestParser` class.
-.. versionchanged:: 2.4
- Expanding tabs to spaces is new; previous versions tried to preserve hard tabs,
- with confusing results.
-
::
>>> # comments are ignored
blank line, put ``<BLANKLINE>`` in your doctest example each place a blank line
is expected.
- .. versionchanged:: 2.4
- ``<BLANKLINE>`` was added; there was no way to use expected output containing
- empty lines in previous versions.
-
* Output to stdout is captured, but not output to stderr (exception tracebacks
are captured via a different means).
^
SyntaxError: invalid syntax
-.. versionchanged:: 2.4
- The ability to handle a multi-line exception detail, and the
- :const:`IGNORE_EXCEPTION_DETAIL` doctest option, were added.
-
.. _doctest-options:
is on a single line. This test also passes, and also requires a directive to do
so::
- >>> print range(20) # doctest:+ELLIPSIS
+ >>> print range(20) # doctest: +ELLIPSIS
[0, 1, ..., 18, 19]
Multiple directives can be used on a single physical line, separated by commas::
functions that run doctests, establishing different defaults. In such cases,
disabling an option via ``-`` in a directive can be useful.
-.. versionchanged:: 2.4
- Constants :const:`DONT_ACCEPT_BLANKLINE`, :const:`NORMALIZE_WHITESPACE`,
- :const:`ELLIPSIS`, :const:`IGNORE_EXCEPTION_DETAIL`, :const:`REPORT_UDIFF`,
- :const:`REPORT_CDIFF`, :const:`REPORT_NDIFF`,
- :const:`REPORT_ONLY_FIRST_FAILURE`, :const:`COMPARISON_FLAGS` and
- :const:`REPORTING_FLAGS` were added; by default ``<BLANKLINE>`` in expected
- output matches an empty line in actual output; and doctest directives were
- added.
-
-.. versionchanged:: 2.5
- Constant :const:`SKIP` was added.
There's also a way to register new option flag names, although this isn't useful
unless you intend to extend :mod:`doctest` internals via subclassing:
MY_FLAG = register_optionflag('MY_FLAG')
- .. versionadded:: 2.4
-
.. _doctest-warnings:
Optional argument *encoding* specifies an encoding that should be used to
convert the file to unicode.
- .. versionadded:: 2.4
-
- .. versionchanged:: 2.5
- The parameter *encoding* was added.
-
.. function:: testmod([m][, name][, globs][, verbose][, report][, optionflags][, extraglobs][, raise_on_error][, exclude_empty])
*raise_on_error*, and *globs* are the same as for function :func:`testfile`
above, except that *globs* defaults to ``m.__dict__``.
- .. versionchanged:: 2.3
- The parameter *optionflags* was added.
-
- .. versionchanged:: 2.4
- The parameters *extraglobs*, *raise_on_error* and *exclude_empty* were added.
-
- .. versionchanged:: 2.5
- The optional argument *isprivate*, deprecated in 2.4, was removed.
There's also a function to run the doctests associated with a single object.
This function is provided for backward compatibility. There are no plans to
Optional argument *encoding* specifies an encoding that should be used to
convert the file to unicode.
- .. versionadded:: 2.4
-
- .. versionchanged:: 2.5
- The global ``__file__`` was added to the globals provided to doctests loaded
- from a text file using :func:`DocFileSuite`.
-
- .. versionchanged:: 2.5
- The parameter *encoding* was added.
+ The global ``__file__`` is added to the globals provided to doctests loaded
+ from a text file using :func:`DocFileSuite`.
.. function:: DocTestSuite([module][, globs][, extraglobs][, test_finder][, setUp][, tearDown][, checker])
Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as for
function :func:`DocFileSuite` above.
- .. versionadded:: 2.3
+ This function uses the same search technique as :func:`testmod`.
- .. versionchanged:: 2.4
- The parameters *globs*, *extraglobs*, *test_finder*, *setUp*, *tearDown*, and
- *optionflags* were added; this function now uses the same search technique as
- :func:`testmod`.
Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` out
of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a
The value of the :mod:`unittest` reporting flags in effect before the function
was called is returned by the function.
- .. versionadded:: 2.4
-
.. _doctest-advanced-api:
constructor arguments are used to initialize the member variables of the same
names.
- .. versionadded:: 2.4
:class:`DocTest` defines the following member variables. They are initialized
by the constructor, and should not be modified directly.
output. The constructor arguments are used to initialize the member variables
of the same names.
- .. versionadded:: 2.4
:class:`Example` defines the following member variables. They are initialized
by the constructor, and should not be modified directly.
If the optional argument *exclude_empty* is false, then
:meth:`DocTestFinder.find` will include tests for objects with empty docstrings.
- .. versionadded:: 2.4
:class:`DocTestFinder` defines the following method:
A processing class used to extract interactive examples from a string, and use
them to create a :class:`DocTest` object.
- .. versionadded:: 2.4
:class:`DocTestParser` defines the following methods:
runner compares expected output to actual output, and how it displays failures.
For more information, see section :ref:`doctest-options`.
- .. versionadded:: 2.4
:class:`DocTestParser` defines the following methods:
if they match; and :meth:`output_difference`, which returns a string describing
the differences between two outputs.
- .. versionadded:: 2.4
:class:`OutputChecker` defines the following methods:
-
.. method:: OutputChecker.check_output(want, got, optionflags)
Return ``True`` iff the actual output from an example (*got*) matches the
(0, 3)
>>>
- .. versionchanged:: 2.4
- The ability to use :func:`pdb.set_trace` usefully inside doctests was added.
Functions that convert doctests to Python code, and possibly run the synthesized
code under the debugger:
useful when you want to transform an interactive Python session into a Python
script.
- .. versionadded:: 2.4
-
.. function:: testsource(module, name)
prints a script version of function :func:`f`'s docstring, with doctests
converted to code, and the rest placed in comments.
- .. versionadded:: 2.3
-
.. function:: debug(module, name[, pm])
specified, or is false, the script is run under the debugger from the start, via
passing an appropriate :func:`exec` call to :func:`pdb.run`.
- .. versionadded:: 2.3
-
- .. versionchanged:: 2.4
- The *pm* argument was added.
-
.. function:: debug_src(src[, pm][, globs])
execution context. If not specified, or ``None``, an empty dictionary is used.
If specified, a shallow copy of the dictionary is used.
- .. versionadded:: 2.4
The :class:`DebugRunner` class, and the special exceptions it may raise, are of
most interest to testing framework authors, and will only be sketched here. See
.. sectionauthor:: Brian Quinlan <brianq@activestate.com>
-.. versionadded:: 2.3
-
The :mod:`DocXMLRPCServer` module extends the classes found in
:mod:`SimpleXMLRPCServer` to serve HTML documentation in response to HTTP GET
requests. Servers can either be free standing, using :class:`DocXMLRPCServer`,
database has to be created. It defaults to octal ``0666`` (and will be modified
by the prevailing umask).
- .. versionchanged:: 2.2
- The *mode* argument was ignored in earlier versions.
-
.. seealso::
chosen, the text of *cmdstr* will be appended to the command line as is, except
that a trailing ``':'`` or ``'='`` (if present) will be trimmed off.
- .. versionadded:: 2.0
-
.. function:: AskFileForOpen( [message] [, typeList] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, previewProc] [, filterProc] [, wanted] )
progress bars are supported. The bar will be determinate if its maximum value
is greater than zero; otherwise it will be indeterminate.
-.. versionchanged:: 2.2
- Support for indeterminate-style progress bars was added.
-
The dialog is displayed immediately after creation. If the dialog's "Cancel"
button is pressed, or if :kbd:`Cmd-.` or :kbd:`ESC` is typed, the dialog window
is hidden and :exc:`KeyboardInterrupt` is raised (but note that this response
Import this class from the :mod:`email.charset` module.
-.. versionadded:: 2.2.2
-
.. class:: Charset([input_charset])
All defect classes are subclassed from :class:`email.errors.MessageDefect`, but
this class is *not* an exception!
-.. versionadded:: 2.4
- All the defect classes were added.
-
* :class:`NoBoundaryInMultipartDefect` -- A message claimed to be a multipart,
but had no :mimetype:`boundary` parameter.
Note that for subparts, no envelope header is ever printed.
- .. versionadded:: 2.2.2
-
.. method:: Generator.clone(fp)
Return an independent clone of this :class:`Generator` instance with the exact
same options.
- .. versionadded:: 2.2.2
-
.. method:: Generator.write(s)
The default value for *fmt* is ``None``, meaning ::
[Non-text (%(type)s) part of message omitted, filename %(filename)s]
-
- .. versionadded:: 2.2.2
-
-.. versionchanged:: 2.5
- The previously deprecated method :meth:`__call__` was removed.
-
properly :rfc:`2047` encoded. MIME-aware mail readers would show this header
using the embedded ISO-8859-1 character.
-.. versionadded:: 2.2.2
-
Here is the :class:`Header` class description:
responsibility to ensure the payload invariants. Optional *charset* sets the
message's default character set; see :meth:`set_charset` for details.
- .. versionchanged:: 2.2.2
- *charset* argument added.
-
.. method:: Message.set_charset(charset)
:mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) will be
added as needed.
- .. versionadded:: 2.2.2
-
.. method:: Message.get_charset()
Return the :class:`Charset` instance associated with the message's payload.
- .. versionadded:: 2.2.2
-
The following methods implement a mapping-like interface for accessing the
message's :rfc:`2822` headers. Note that there are some semantic differences
between these methods and a normal mapping (i.e. dictionary) interface. For
*_name*, retaining header order and field name case. If no matching header was
found, a :exc:`KeyError` is raised.
- .. versionadded:: 2.2.2
-
.. method:: Message.get_content_type()
has an invalid type specification, :rfc:`2045` mandates that the default type be
:mimetype:`text/plain`.
- .. versionadded:: 2.2.2
-
.. method:: Message.get_content_maintype()
Return the message's main content type. This is the :mimetype:`maintype` part
of the string returned by :meth:`get_content_type`.
- .. versionadded:: 2.2.2
-
.. method:: Message.get_content_subtype()
Return the message's sub-content type. This is the :mimetype:`subtype` part of
the string returned by :meth:`get_content_type`.
- .. versionadded:: 2.2.2
-
.. method:: Message.get_default_type()
:mimetype:`multipart/digest` containers. Such subparts have a default content
type of :mimetype:`message/rfc822`.
- .. versionadded:: 2.2.2
-
.. method:: Message.set_default_type(ctype)
or :mimetype:`message/rfc822`, although this is not enforced. The default
content type is not stored in the :mailheader:`Content-Type` header.
- .. versionadded:: 2.2.2
-
.. method:: Message.get_params([failobj[, header[, unquote]]])
:mailheader:`Content-Type` header. Optional *header* is the header to search
instead of :mailheader:`Content-Type`.
- .. versionchanged:: 2.2.2
- *unquote* argument added.
-
.. method:: Message.get_param(param[, failobj[, header[, unquote]]])
In any case, the parameter value (either the returned string, or the ``VALUE``
item in the 3-tuple) is always unquoted, unless *unquote* is set to ``False``.
- .. versionchanged:: 2.2.2
- *unquote* argument added, and 3-tuple return value possible.
-
.. method:: Message.set_param(param, value[, header[, requote[, charset[, language]]]])
:rfc:`2231`. Optional *language* specifies the RFC 2231 language, defaulting to
the empty string. Both *charset* and *language* should be strings.
- .. versionadded:: 2.2.2
-
.. method:: Message.del_param(param[, header[, requote]])
(the default is ``True``). Optional *header* specifies an alternative to
:mailheader:`Content-Type`.
- .. versionadded:: 2.2.2
-
.. method:: Message.set_type(type[, header][, requote])
:mailheader:`Content-Type` header is set a :mailheader:`MIME-Version` header is
also added.
- .. versionadded:: 2.2.2
-
.. method:: Message.get_filename([failobj])
Note that this method differs from :meth:`get_charset` which returns the
:class:`Charset` instance for the default encoding of the message body.
- .. versionadded:: 2.2.2
-
.. method:: Message.get_charsets([failobj])
text/plain
message/rfc822
-.. versionchanged:: 2.5
- The previously deprecated methods :meth:`get_type`, :meth:`get_main_type`, and
- :meth:`get_subtype` were removed.
-
:class:`Message` objects can also optionally contain two instance attributes,
which can be used when generating the plain text of a MIME message.
that it contains text that appears between the last boundary and the end of the
message.
- .. versionchanged:: 2.5
- You do not need to set the epilogue to the empty string in order for the
- :class:`Generator` to print a newline at the end of the file.
+ You do not need to set the epilogue to the empty string in order for the
+ :class:`Generator` to print a newline at the end of the file.
.. data:: defects
The *defects* attribute contains a list of all the problems found when parsing
this message. See :mod:`email.errors` for a detailed description of the
possible parsing defects.
-
- .. versionadded:: 2.4
-
:mimetype:`multipart` messages. If :meth:`attach` is called, a
:exc:`MultipartConversionError` exception is raised.
- .. versionadded:: 2.2.2
-
.. class:: MIMEMultipart([subtype[, boundary[, _subparts[, _params]]]])
the keyword arguments, or passed into the *_params* argument, which is a keyword
dictionary.
- .. versionadded:: 2.2.2
-
.. class:: MIMEApplication(_data[, _subtype[, _encoder[, **_params]]])
*_params* are passed straight through to the base class constructor.
- .. versionadded:: 2.5
-
.. class:: MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]])
:class:`MIMENonMultipart` constructor; it defaults to ``us-ascii``. No guessing
or encoding is performed on the text data.
- .. versionchanged:: 2.4
- The previously deprecated *_encoding* argument has been removed. Encoding
- happens implicitly based on the *_charset* argument.
-
FeedParser API
^^^^^^^^^^^^^^
-.. versionadded:: 2.4
-
The :class:`FeedParser`, imported from the :mod:`email.feedparser` module,
provides an API that is conducive to incremental parsing of email messages, such
as would be necessary when reading the text of an email message from a source
effectively non-strict. You should simply stop passing a *strict* flag to
the :class:`Parser` constructor.
- .. versionchanged:: 2.2.2
- The *strict* flag was added.
-
- .. versionchanged:: 2.4
- The *strict* flag was deprecated.
-
The other public :class:`Parser` methods are:
Optional *headersonly* is as with the :meth:`parse` method.
- .. versionchanged:: 2.2.2
- The *headersonly* flag was added.
-
.. method:: Parser.parsestr(text[, headersonly])
reading the headers or not. The default is ``False``, meaning it parses the
entire contents of the file.
- .. versionchanged:: 2.2.2
- The *headersonly* flag was added.
Since creating a message object structure from a string or a file object is such
a common task, two functions are provided as a convenience. They are available
``Parser().parsestr(s)``. Optional *_class* and *strict* are interpreted as
with the :class:`Parser` class constructor.
- .. versionchanged:: 2.2.2
- The *strict* flag was added.
-
.. function:: message_from_file(fp[, _class[, strict]])
exactly equivalent to ``Parser().parse(fp)``. Optional *_class* and *strict*
are interpreted as with the :class:`Parser` class constructor.
- .. versionchanged:: 2.2.2
- The *strict* flag was added.
-
Here's an example of how you might use this at an interactive Python prompt::
>>> import email
.. sectionauthor:: Barry A. Warsaw <barry@python.org>
-.. versionadded:: 2.2
-
The :mod:`email` package is a library for managing email messages, including
MIME and other :rfc:`2822`\ -based message documents. It subsumes most of the
functionality in several older standard modules such as :mod:`rfc822`,
needed for some protocols (such as HTTP). This only applies when *localtime* is
``False``.
- .. versionadded:: 2.4
-
.. function:: make_msgid([idstring])
Decode parameters list according to :rfc:`2231`. *params* is a sequence of
2-tuples containing elements of the form ``(content-type, string-value)``.
-.. versionchanged:: 2.4
- The :func:`dump_address_pair` function has been removed; use :func:`formataddr`
- instead.
-
-.. versionchanged:: 2.4
- The :func:`decode` function has been removed; use the
- :meth:`Header.decode_header` method instead.
-
-.. versionchanged:: 2.4
- The :func:`encode` function has been removed; use the :meth:`Header.encode`
- method instead.
.. rubric:: Footnotes
string when there were no arguments. All arguments are stored in :attr:`args`
as a tuple.
- .. versionadded:: 2.5
-
.. exception:: Exception
All built-in, non-system-exiting exceptions are derived from this class. All
user-defined exceptions should also be derived from this class.
- .. versionchanged:: 2.5
- Changed to inherit from :exc:`BaseException`.
-
.. exception:: ArithmeticError
:attr:`strerror` attribute (it is usually the associated error message). The
tuple itself is also available on the :attr:`args` attribute.
- .. versionadded:: 1.5.2
-
When an :exc:`EnvironmentError` exception is instantiated with a 3-tuple, the
first two items are available as above, while the third item is available on the
:attr:`filename` attribute. However, for backwards compatibility, the
Raise when a generator's :meth:`close` method is called.
- .. versionadded:: 2.5
-
- .. versionchanged:: 3.0
- Changed to inherit from Exception instead of StandardError.
-
.. exception:: IOError
accidentally caught by code that catches :exc:`Exception` and thus prevent
the interpreter from exiting.
- .. versionchanged:: 2.5
- Changed to inherit from :exc:`BaseException`.
-
.. exception:: MemoryError
classes, abstract methods should raise this exception when they require derived
classes to override the method.
- .. versionadded:: 1.5.2
-
.. exception:: OSError
:mod:`os` module's ``os.error`` exception. See :exc:`EnvironmentError` above for
a description of the possible associated values.
- .. % xref for os module
-
- .. versionadded:: 1.5.2
-
.. exception:: OverflowError
after it has been garbage collected. For more information on weak references,
see the :mod:`weakref` module.
- .. versionadded:: 2.2
- Previously known as the :exc:`weakref.ReferenceError` exception.
-
.. exception:: RuntimeError
Raised by builtin :func:`next` and an iterator's :meth:`__next__` method to
signal that there are no further values.
- .. versionadded:: 2.2
-
- .. versionchanged:: 3.0
- Changed to inherit from Exception instead of StandardError.
-
.. exception:: SyntaxError
that it is not accidentally caught by code that catches :exc:`Exception`. This
allows the exception to properly propagate up and cause the interpreter to exit.
- .. versionchanged:: 2.5
- Changed to inherit from :exc:`BaseException`.
-
.. exception:: TypeError
no value has been bound to that variable. This is a subclass of
:exc:`NameError`.
- .. versionadded:: 2.0
-
.. exception:: UnicodeError
Raised when a Unicode-related encoding or decoding error occurs. It is a
subclass of :exc:`ValueError`.
- .. versionadded:: 2.0
-
.. exception:: UnicodeEncodeError
Raised when a Unicode-related error occurs during encoding. It is a subclass of
:exc:`UnicodeError`.
- .. versionadded:: 2.3
-
.. exception:: UnicodeDecodeError
Raised when a Unicode-related error occurs during decoding. It is a subclass of
:exc:`UnicodeError`.
- .. versionadded:: 2.3
-
.. exception:: UnicodeTranslateError
Raised when a Unicode-related error occurs during translating. It is a subclass
of :exc:`UnicodeError`.
- .. versionadded:: 2.3
-
.. exception:: ValueError
Platform API. The :attr:`errno` value maps the :attr:`winerror` value to
corresponding ``errno.h`` values. This is a subclass of :exc:`OSError`.
- .. versionadded:: 2.0
-
- .. versionchanged:: 2.5
- Previous versions put the :cfunc:`GetLastError` codes into :attr:`errno`.
-
.. exception:: ZeroDivisionError
Base class for warnings about probable mistakes in module imports.
- .. versionadded:: 2.5
-
.. exception:: UnicodeWarning
Base class for warnings related to Unicode.
- .. versionadded:: 2.5
-
The class hierarchy for built-in exceptions is:
during iteration. The parameters to this function will be passed along to the
constructor of the :class:`FileInput` class.
- .. versionchanged:: 2.5
- Added the *mode* and *openhook* parameters.
The following functions use the global state created by :func:`fileinput.input`;
if there is no active state, :exc:`RuntimeError` is raised.
Return the integer "file descriptor" for the current file. When no file is
opened (before the first line and between files), returns ``-1``.
- .. versionadded:: 2.5
-
.. function:: lineno()
*filename* and *mode*, and returns an accordingly opened file-like object. You
cannot use *inplace* and *openhook* together.
- .. versionchanged:: 2.5
- Added the *mode* and *openhook* parameters.
**Optional in-place filtering:** if the keyword argument ``inplace=1`` is passed
to :func:`fileinput.input` or to the :class:`FileInput` constructor, the file is
Usage example: ``fi = fileinput.FileInput(openhook=fileinput.hook_compressed)``
- .. versionadded:: 2.5
-
.. function:: hook_encoded(encoding)
With this hook, :class:`FileInput` might return Unicode strings depending on the
specified *encoding*.
- .. versionadded:: 2.5
-
Return the subset of the list of *names* that match *pattern*. It is the same as
``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.
- .. versionadded:: 2.2
-
.. function:: translate(pattern)
specifies a timeout in seconds for the connection attempt (if is not specified,
or passed as None, the global default timeout setting will be used).
- .. versionchanged:: 2.6
- *timeout* was added.
-
.. data:: all_errors
is used (the timeout that you passed when instantiating the class); if the
object timeout is also None, the global default timeout setting will be used.
- .. versionchanged:: 2.6
- *timeout* was added.
-
.. method:: FTP.getwelcome()
read until EOF using its :meth:`read` method in blocks of size *blocksize* to
provide the data to be stored. The *blocksize* argument defaults to 8192.
- .. versionchanged:: 2.1
- default for *blocksize* added.
-
.. method:: FTP.storlines(command, file)
.. index::
statement: import
- module: ihooks
- module: rexec
module: imp
.. note::
The function is invoked by the :keyword:`import` statement. It mainly exists
so that you can replace it with another function that has a compatible
- interface, in order to change the semantics of the :keyword:`import` statement.
- For examples of why and how you would do this, see the standard library modules
- :mod:`ihooks` and :mod:`rexec`. See also the built-in module :mod:`imp`, which
+ interface, in order to change the semantics of the :keyword:`import`
+ statement. For examples of why and how you would do this, see the standard
+ library module :mod:`ihooks`. See also the built-in module :mod:`imp`, which
defines some useful operations out of which you can build your own
:func:`__import__` function.
the number of parent directories to search relative to the directory of the
module calling :func:`__import__`.
- .. versionchanged:: 2.5
- The level parameter was added.
-
- .. versionchanged:: 2.5
- Keyword support for parameters was added.
-
.. function:: abs(x)
return False
return True
- .. versionadded:: 2.5
-
.. function:: any(iterable)
return True
return False
- .. versionadded:: 2.5
-
.. function:: basestring()
is an instance of :class:`str` (or a user-defined type inherited from
:class:`basestring`).
- .. versionadded:: 2.3
-
.. function:: bin(x)
expression. If *x* is not a Python :class:`int` object, it has to define an
:meth:`__index__` method that returns an integer.
- .. versionadded:: 3.0
-
.. function:: bool([x])
.. index:: pair: Boolean; type
- .. versionadded:: 2.2.1
-
- .. versionchanged:: 2.3
- If no argument is given, this function returns :const:`False`.
-
.. function:: bytes([arg[, encoding[, errors]]])
For more information on class methods, consult the documentation on the standard
type hierarchy in :ref:`types`.
- .. versionadded:: 2.2
-
- .. versionchanged:: 2.4
- Function decorator syntax added.
-
.. function:: cmp(x, y)
*a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0 <= abs(a % b)
< abs(b)``.
- .. versionchanged:: 2.3
- Using :func:`divmod` with complex numbers is deprecated.
-
.. function:: enumerate(iterable)
2 Fall
3 Winter
- .. versionadded:: 2.3
-
.. function:: eval(expression[, globals[, locals]])
*globals* must be a dictionary. If provided, *locals* can be any mapping
object.
- .. versionchanged:: 2.4
- formerly *locals* was required to be a dictionary.
-
The *expression* argument is parsed and evaluated as a Python expression
(technically speaking, a condition list) using the *globals* and *locals*
dictionaries as global and local name space. If the *globals* dictionary is
For other containers see the built in :class:`dict`, :class:`list`, and
:class:`tuple` classes, and the :mod:`collections` module.
- .. versionadded:: 2.4
-
.. function:: getattr(object, name[, default])
topic, and a help page is printed on the console. If the argument is any other
kind of object, a help page on the object is generated.
- .. versionadded:: 2.2
-
.. function:: hex(x)
expression. If *x* is not a Python :class:`int` object, it has to define an
:meth:`__index__` method that returns an integer.
- .. versionchanged:: 2.4
- Formerly only returned an unsigned literal.
-
.. function:: id(object)
accepted). If *classinfo* is not a type or tuple of types and such tuples,
a :exc:`TypeError` exception is raised.
- .. versionchanged:: 2.2
- Support for a tuple of type information was added.
-
.. function:: issubclass(class, classinfo)
objects, in which case every entry in *classinfo* will be checked. In any other
case, a :exc:`TypeError` exception is raised.
- .. versionchanged:: 2.3
- Support for a tuple of type information was added.
-
.. function:: iter(o[, sentinel])
its :meth:`__next__` method; if the value returned is equal to *sentinel*,
:exc:`StopIteration` will be raised, otherwise the value will be returned.
- .. versionadded:: 2.2
-
.. function:: len(s)
the result is always a list.
-.. function:: max(iterable[, args...][key])
+.. function:: max(iterable[, args...], *[, key])
With a single argument *iterable*, return the largest item of a non-empty
iterable (such as a string, tuple or list). With more than one argument, return
the largest of the arguments.
- The optional *key* argument specifies a one-argument ordering function like that
- used for :meth:`list.sort`. The *key* argument, if supplied, must be in keyword
- form (for example, ``max(a,b,c,key=func)``).
-
- .. versionchanged:: 2.5
- Added support for the optional *key* argument.
+ The optional keyword-only *key* argument specifies a one-argument ordering
+ function like that used for :meth:`list.sort`.
.. function:: memoryview(obj)
XXX: To be documented.
-.. function:: min(iterable[, args...][key])
+.. function:: min(iterable[, args...], *[, key])
With a single argument *iterable*, return the smallest item of a non-empty
iterable (such as a string, tuple or list). With more than one argument, return
the smallest of the arguments.
- The optional *key* argument specifies a one-argument ordering function like that
- used for :meth:`list.sort`. The *key* argument, if supplied, must be in keyword
- form (for example, ``min(a,b,c,key=func)``).
-
- .. versionchanged:: 2.5
- Added support for the optional *key* argument.
+ The optional keyword-only *key* argument specifies a one-argument ordering
+ function like that used for :meth:`list.sort`.
.. function:: next(iterator[, default])
.. function:: object()
Return a new featureless object. :class:`object` is a base for all classes.
- It has the methods that are common to all instances of Python classes.
+ It has the methods that are common to all instances of Python classes. This
+ function does not accept any arguments.
.. note::
:class:`object` does *not* have a :attr:`__dict__`, so you can't assign
arbitrary attributes to an instance of the :class:`object` class.
- .. versionadded:: 2.2
-
- .. versionchanged:: 2.3
- This function does not accept any arguments. Formerly, it accepted arguments but
- ignored them.
-
.. function:: oct(x)
expression. If *x* is not a Python :class:`int` object, it has to define an
:meth:`__index__` method that returns an integer.
- .. versionchanged:: 2.4
- Formerly only returned an unsigned literal.
-
.. function:: open(filename[, mode[, bufsize]])
See also the :mod:`fileinput` module.
- .. versionchanged:: 2.5
- Restriction on first letter of mode string introduced.
-
.. function:: ord(c)
turns the :meth:`voltage` method into a "getter" for a read-only attribute with
the same name.
- .. versionadded:: 2.2
-
- .. versionchanged:: 2.5
- Use *fget*'s docstring if no *doc* given.
-
.. function:: range([start,] stop[, step])
protocol (the :meth:`__len__` method and the :meth:`__getitem__` method with
integer arguments starting at ``0``).
- .. versionadded:: 2.4
-
.. function:: round(x[, n])
For other containers see the built in :class:`dict`, :class:`list`, and
:class:`tuple` classes, and the :mod:`collections` module.
- .. versionadded:: 2.4
-
.. function:: setattr(object, name, value)
multiple times for each list element while *key* and *reverse* touch each
element only once.
- .. versionadded:: 2.4
-
.. function:: staticmethod(function)
For more information on static methods, consult the documentation on the
standard type hierarchy in :ref:`types`.
- .. versionadded:: 2.2
-
- .. versionchanged:: 2.4
- Function decorator syntax added.
-
.. function:: str([object[, encoding[, errors]]])
and are not allowed to be strings. The fast, correct way to concatenate a
sequence of strings is by calling ``''.join(sequence)``.
- .. versionadded:: 2.3
-
.. function:: super(type[, object-or-type])
Accordingly, :func:`super` is undefined for implicit lookups using statements or
operators such as ``super(C, self)[name]``.
- .. versionadded:: 2.2
-
.. function:: tuple([iterable])
...
>>> X = type('X', (object,), dict(a=1))
- .. versionadded:: 2.2
-
.. function:: vars([object])
sequence argument, it returns a list of 1-tuples. With no arguments, it returns
an empty list.
- .. versionadded:: 2.0
-
- .. versionchanged:: 2.4
- Formerly, :func:`zip` required at least one argument and ``zip()`` raised a
- :exc:`TypeError` instead of returning an empty list.
.. % ---------------------------------------------------------------------------
.. sectionauthor:: Peter Harris <scav@blueyonder.co.uk>
-.. versionadded:: 2.5
-
The :mod:`functools` module is for higher-order functions: functions that act on
or return other functions. In general, any callable object can be treated as a
function for the purposes of this module.
This is the same function as :func:`reduce`. It is made available in this module
to allow writing code more forward-compatible with Python 3.
- .. versionadded:: 2.6
-
.. function:: partial(func[,*args][, **keywords])
:exc:`ValueError` is raised if the generation number is invalid. The number of
unreachable objects found is returned.
- .. versionchanged:: 2.5
- The optional *generation* argument was added.
-
.. function:: set_debug(flags)
Returns a list of all objects tracked by the collector, excluding the list
returned.
- .. versionadded:: 2.2
-
.. function:: set_threshold(threshold0[, threshold1[, threshold2]])
Return the current collection counts as a tuple of ``(count0, count1,
count2)``.
- .. versionadded:: 2.5
-
.. function:: get_threshold()
invalid state. Avoid using :func:`get_referrers` for any purpose other than
debugging.
- .. versionadded:: 2.2
-
.. function:: get_referents(*objs)
be involved in a cycle. So, for example, if an integer is directly reachable
from an argument, that integer object may or may not appear in the result list.
- .. versionadded:: 2.3
The following variable is provided for read-only access (you can mutate its
value but should not rebind it):
-
.. data:: garbage
A list of objects which the collector found to be unreachable but could not be
variable POSIXLY_CORRECT is set, then option processing stops as soon as a
non-option argument is encountered.
- .. versionadded:: 2.3
-
.. exception:: GetoptError
related option; if there is no specific option to which the exception relates,
:attr:`opt` is an empty string.
- .. versionchanged:: 1.6
- Introduced :exc:`GetoptError` as a synonym for :exc:`error`.
-
-
+.. XXX deprecated?
.. exception:: error
Alias for :exc:`GetoptError`; for backward compatibility.
Availability: Macintosh, Unix, Windows.
- .. versionchanged:: 2.5
- The *stream* parameter was added.
-
.. function:: getuser()
:func:`gettext` family of functions. If *codeset* is omitted, then the current
binding is returned.
- .. versionadded:: 2.4
-
.. function:: textdomain([domain])
system encoding, if no other encoding was explicitly set with
:func:`bind_textdomain_codeset`.
- .. versionadded:: 2.4
-
.. function:: dgettext(domain, message)
system encoding, if no other encoding was explicitly set with
:func:`bind_textdomain_codeset`.
- .. versionadded:: 2.4
-
.. function:: ngettext(singular, plural, n)
syntax to be used in :file:`.po` files and the formulas for a variety of
languages.
- .. versionadded:: 2.3
-
.. function:: lngettext(singular, plural, n)
system encoding, if no other encoding was explicitly set with
:func:`bind_textdomain_codeset`.
- .. versionadded:: 2.4
-
.. function:: dngettext(domain, singular, plural, n)
Like :func:`ngettext`, but look the message up in the specified *domain*.
- .. versionadded:: 2.3
-
.. function:: ldngettext(domain, singular, plural, n)
preferred system encoding, if no other encoding was explicitly set with
:func:`bind_textdomain_codeset`.
- .. versionadded:: 2.4
Note that GNU :program:`gettext` also defines a :func:`dcgettext` method, but
this was deemed not useful and so it is currently unimplemented.
*fallback* is false (which is the default), and returns a
:class:`NullTranslations` instance if *fallback* is true.
- .. versionchanged:: 2.4
- Added the *codeset* parameter.
-
.. function:: install(domain[, localedir[, unicode [, codeset[, names]]]])
builtin namespace, so it is easily accessible in all modules of your
application.
- .. versionchanged:: 2.4
- Added the *codeset* parameter.
-
- .. versionchanged:: 2.5
- Added the *names* parameter.
-
The :class:`NullTranslations` class
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If a fallback has been set, forward :meth:`lgettext` to the fallback. Otherwise,
return the translated message. Overridden in derived classes.
- .. versionadded:: 2.4
-
.. method:: NullTranslations.ugettext(message)
If a fallback has been set, forward :meth:`ngettext` to the fallback. Otherwise,
return the translated message. Overridden in derived classes.
- .. versionadded:: 2.3
-
.. method:: NullTranslations.lngettext(singular, plural, n)
If a fallback has been set, forward :meth:`ngettext` to the fallback. Otherwise,
return the translated message. Overridden in derived classes.
- .. versionadded:: 2.4
-
.. method:: NullTranslations.ungettext(singular, plural, n)
Otherwise, return the translated message as a Unicode string. Overridden in
derived classes.
- .. versionadded:: 2.3
-
.. method:: NullTranslations.info()
Return the "protected" :attr:`_output_charset` variable, which defines the
encoding used to return translated messages.
- .. versionadded:: 2.4
-
.. method:: NullTranslations.set_output_charset(charset)
Change the "protected" :attr:`_output_charset` variable, which defines the
encoding used to return translated messages.
- .. versionadded:: 2.4
-
.. method:: NullTranslations.install([unicode [, names]])
This puts :func:`_` only in the module's global namespace and so only affects
calls within this module.
- .. versionchanged:: 2.5
- Added the *names* parameter.
-
The :class:`GNUTranslations` class
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
system encoding, if no other encoding was explicitly set with
:meth:`set_output_charset`.
- .. versionadded:: 2.4
-
.. method:: GNUTranslations.ugettext(message)
request is forwarded to the fallback's :meth:`ngettext` method. Otherwise, when
*n* is 1 *singular* is returned, and *plural* is returned in all other cases.
- .. versionadded:: 2.3
-
.. method:: GNUTranslations.lngettext(singular, plural, n)
system encoding, if no other encoding was explicitly set with
:meth:`set_output_charset`.
- .. versionadded:: 2.4
-
.. method:: GNUTranslations.ungettext(singular, plural, n)
'There are %(num)d files in this directory',
n) % {'num': n}
- .. versionadded:: 2.3
-
Solaris message catalog support
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Return an iterator which yields the same values as :func:`glob` without actually
storing them all simultaneously.
- .. versionadded:: 2.5
For example, consider a directory containing only the following files:
:file:`1.gif`, :file:`2.txt`, and :file:`card.gif`. :func:`glob` will produce
.. sectionauthor:: Gregory P. Smith <greg@users.sourceforge.net>
-.. versionadded:: 2.5
-
.. index::
single: message digest, MD5
single: secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512
.. % Theoretical explanation:
-.. versionadded:: 2.3
-
This module provides an implementation of the heap queue algorithm, also known
as the priority queue algorithm.
not pull the data into memory all at once, and assumes that each of the input
streams is already sorted (smallest to largest).
- .. versionadded:: 2.6
-
.. function:: nlargest(n, iterable[, key])
``key=str.lower`` Equivalent to: ``sorted(iterable, key=key,
reverse=True)[:n]``
- .. versionadded:: 2.4
-
- .. versionchanged:: 2.5
- Added the optional *key* argument.
-
.. function:: nsmallest(n, iterable[, key])
used to extract a comparison key from each element in the iterable:
``key=str.lower`` Equivalent to: ``sorted(iterable, key=key)[:n]``
- .. versionadded:: 2.4
-
- .. versionchanged:: 2.5
- Added the optional *key* argument.
The latter two functions perform best for smaller values of *n*. For larger
values, it is more efficient to use the :func:`sorted` function. Also, when
.. sectionauthor:: Gerhard Häring <ghaering@users.sourceforge.net>
-.. versionadded:: 2.2
-
This module implements the HMAC algorithm as described by :rfc:`2104`.
.. sectionauthor:: Anthony Baxter <anthony@interlink.com.au>
-.. versionadded:: 2.2
-
This module provides a nicer interface to the :mod:`_hotshot` C module. Hotshot
is a replacement for the existing :mod:`profile` module. As it's written mostly
in C, it should result in a much smaller performance impact than the existing
recommended to use :mod:`cProfile` instead. :mod:`hotshot` is not maintained and
might be removed from the standard library in the future.
-.. versionchanged:: 2.5
- the results should be more meaningful than in the past: the timing core
- contained a critical bug.
-
.. warning::
The :mod:`hotshot` profiler does not yet work well with threads. It is useful to
:synopsis: Statistical analysis for Hotshot
-.. versionadded:: 2.2
-
This module loads hotshot profiling data into the standard :mod:`pstats` Stats
objects.
Exception raised by the :class:`HTMLParser` class when it encounters an error
while parsing.
- .. versionadded:: 2.4
-
.. seealso::
A dictionary that maps HTML entity names to the Unicode codepoints.
- .. versionadded:: 2.3
-
.. data:: codepoint2name
A dictionary that maps Unicode codepoints to HTML entity names.
- .. versionadded:: 2.3
-
:synopsis: A simple parser that can handle HTML and XHTML.
-.. versionadded:: 2.2
-
-.. index::
- single: HTML
- single: XHTML
+.. index:: HTML, XHTML
This module defines a class :class:`HTMLParser` which serves as the basis for
parsing text files formatted in HTML (HyperText Mark-up Language) and XHTML.
HREF="http://www.cwi.nl/">``, this method would be called as
``handle_starttag('a', [('href', 'http://www.cwi.nl/')])``.
- .. versionchanged:: 2.6
- All entity references from htmlentitydefs are now replaced in the attribute
- values.
+ All entity references from htmlentitydefs are replaced in the attribute
+ values.
.. method:: HTMLParser.handle_startendtag(tag, attrs)
>>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)
>>> h3 = httplib.HTTPConnection('www.cwi.nl', 80, timeout=10)
- .. versionadded:: 2.0
-
- .. versionchanged:: 2.6
- *timeout* was added.
-
.. class:: HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout]]]]])
This does not do any certificate verification!
- .. versionadded:: 2.0
-
- .. versionchanged:: 2.6
- *timeout* was added.
-
.. class:: HTTPResponse(sock[, debuglevel=0][, strict=0])
Class whose instances are returned upon successful connection. Not instantiated
directly by user.
- .. versionadded:: 2.0
The following exceptions are raised as appropriate:
The base class of the other exceptions in this module. It is a subclass of
:exc:`Exception`.
- .. versionadded:: 2.0
-
.. exception:: NotConnected
A subclass of :exc:`HTTPException`.
- .. versionadded:: 2.0
-
.. exception:: InvalidURL
A subclass of :exc:`HTTPException`, raised if a port is given and is either
non-numeric or empty.
- .. versionadded:: 2.3
-
.. exception:: UnknownProtocol
A subclass of :exc:`HTTPException`.
- .. versionadded:: 2.0
-
.. exception:: UnknownTransferEncoding
A subclass of :exc:`HTTPException`.
- .. versionadded:: 2.0
-
.. exception:: UnimplementedFileMode
A subclass of :exc:`HTTPException`.
- .. versionadded:: 2.0
-
.. exception:: IncompleteRead
A subclass of :exc:`HTTPException`.
- .. versionadded:: 2.0
-
.. exception:: ImproperConnectionState
A subclass of :exc:`HTTPException`.
- .. versionadded:: 2.0
-
.. exception:: CannotSendRequest
A subclass of :exc:`ImproperConnectionState`.
- .. versionadded:: 2.0
-
.. exception:: CannotSendHeader
A subclass of :exc:`ImproperConnectionState`.
- .. versionadded:: 2.0
-
.. exception:: ResponseNotReady
A subclass of :exc:`ImproperConnectionState`.
- .. versionadded:: 2.0
-
.. exception:: BadStatusLine
A subclass of :exc:`HTTPException`. Raised if a server responds with a HTTP
status code that we don't understand.
- .. versionadded:: 2.0
-
The constants defined in this module are:
Example: ``httplib.responses[httplib.NOT_FOUND]`` is ``'Not Found'``.
- .. versionadded:: 2.5
-
.. _httpconnection-objects:
Content-Length is automatically set to the correct value. The *headers*
argument should be a mapping of extra HTTP headers to send with the request.
- .. versionchanged:: 2.6
- *body* can be a file object.
-
.. method:: HTTPConnection.getresponse()
content encodings), specify *skip_host* or *skip_accept_encoding* with non-False
values.
- .. versionchanged:: 2.4
- *skip_accept_encoding* argument added.
-
.. method:: HTTPConnection.putheader(header, argument[, ...])
Return a list of (header, value) tuples.
- .. versionadded:: 2.4
-
.. attribute:: HTTPResponse.msg
``stdin/stdout`` file descriptors created by passing *command* to
``os.popen2()``.
- .. versionadded:: 2.3
The following utility functions are defined:
Delete the ACLs (remove any rights) set for who on mailbox.
- .. versionadded:: 2.4
-
.. method:: IMAP4.expunge()
Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is
non-standard, but is supported by the ``Cyrus`` server.
- .. versionadded:: 2.5
-
.. method:: IMAP4.getquota(root)
Get the ``quota`` *root*'s resource usage and limits. This method is part of the
IMAP4 QUOTA extension defined in rfc2087.
- .. versionadded:: 2.3
-
.. method:: IMAP4.getquotaroot(mailbox)
Get the list of ``quota`` ``roots`` for the named *mailbox*. This method is part
of the IMAP4 QUOTA extension defined in rfc2087.
- .. versionadded:: 2.3
-
.. method:: IMAP4.list([directory[, pattern]])
the password. Will only work if the server ``CAPABILITY`` response includes the
phrase ``AUTH=CRAM-MD5``.
- .. versionadded:: 2.3
-
.. method:: IMAP4.logout()
Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).
- .. versionadded:: 2.4
-
.. method:: IMAP4.namespace()
Returns IMAP namespaces as defined in RFC2342.
- .. versionadded:: 2.3
-
.. method:: IMAP4.noop()
Assume authentication as *user*. Allows an authorised administrator to proxy
into any user's mailbox.
- .. versionadded:: 2.3
-
.. method:: IMAP4.read(size)
Set ``ANNOTATION``\ s for *mailbox*. The method is non-standard, but is
supported by the ``Cyrus`` server.
- .. versionadded:: 2.5
-
.. method:: IMAP4.setquota(root, limits)
Set the ``quota`` *root*'s resource *limits*. This method is part of the IMAP4
QUOTA extension defined in rfc2087.
- .. versionadded:: 2.3
-
.. method:: IMAP4.shutdown()
This is an ``IMAP4rev1`` extension command.
- .. versionadded:: 2.4
-
.. method:: IMAP4.uid(command, arg[, ...])
| ``'png'`` | Portable Network Graphics |
+------------+-----------------------------------+
-.. versionadded:: 2.5
- Exif detection.
-
You can extend the list of file types :mod:`imghdr` can recognize by appending
to this variable:
be used by import hooks to ensure thread-safety when importing modules. On
platforms without threads, this function does nothing.
- .. versionadded:: 2.3
-
.. function:: release_lock()
Release the interpreter's import lock. On platforms without threads, this
function does nothing.
- .. versionadded:: 2.3
The following constants with integer values, defined in this module, are used to
indicate the search result of :func:`find_module`.
This method always returns ``None``, indicating that the requested module could
not be found.
- .. versionadded:: 2.5
-
.. _examples-imp:
:mod:`imputil` --- Import utilities
-=====================================================
+===================================
.. module:: imputil
:synopsis: Manage and augment the import process.
.. sectionauthor:: Ka-Ping Yee <ping@lfw.org>
-.. versionadded:: 2.1
-
The :mod:`inspect` module provides several useful functions to help get
information about live objects such as modules, classes, methods, functions,
tracebacks, frame objects, and code objects. For example, it can help you
They also help you determine when you can expect to find the following special
attributes:
-+-----------+-----------------+---------------------------+-------+
-| Type | Attribute | Description | Notes |
-+===========+=================+===========================+=======+
-| module | __doc__ | documentation string | |
-+-----------+-----------------+---------------------------+-------+
-| | __file__ | filename (missing for | |
-| | | built-in modules) | |
-+-----------+-----------------+---------------------------+-------+
-| class | __doc__ | documentation string | |
-+-----------+-----------------+---------------------------+-------+
-| | __module__ | name of module in which | |
-| | | this class was defined | |
-+-----------+-----------------+---------------------------+-------+
-| method | __doc__ | documentation string | |
-+-----------+-----------------+---------------------------+-------+
-| | __name__ | name with which this | |
-| | | method was defined | |
-+-----------+-----------------+---------------------------+-------+
-| | im_class | class object that asked | \(1) |
-| | | for this method | |
-+-----------+-----------------+---------------------------+-------+
-| | im_func | function object | |
-| | | containing implementation | |
-| | | of method | |
-+-----------+-----------------+---------------------------+-------+
-| | im_self | instance to which this | |
-| | | method is bound, or | |
-| | | ``None`` | |
-+-----------+-----------------+---------------------------+-------+
-| function | __doc__ | documentation string | |
-+-----------+-----------------+---------------------------+-------+
-| | __name__ | name with which this | |
-| | | function was defined | |
-+-----------+-----------------+---------------------------+-------+
-| | __code__ | code object containing | |
-| | | compiled function | |
-| | | bytecode | |
-+-----------+-----------------+---------------------------+-------+
-| | __defaults__ | tuple of any default | |
-| | | values for arguments | |
-+-----------+-----------------+---------------------------+-------+
-| | __globals__ | global namespace in which | |
-| | | this function was defined | |
-+-----------+-----------------+---------------------------+-------+
-| traceback | tb_frame | frame object at this | |
-| | | level | |
-+-----------+-----------------+---------------------------+-------+
-| | tb_lasti | index of last attempted | |
-| | | instruction in bytecode | |
-+-----------+-----------------+---------------------------+-------+
-| | tb_lineno | current line number in | |
-| | | Python source code | |
-+-----------+-----------------+---------------------------+-------+
-| | tb_next | next inner traceback | |
-| | | object (called by this | |
-| | | level) | |
-+-----------+-----------------+---------------------------+-------+
-| frame | f_back | next outer frame object | |
-| | | (this frame's caller) | |
-+-----------+-----------------+---------------------------+-------+
-| | f_builtins | built-in namespace seen | |
-| | | by this frame | |
-+-----------+-----------------+---------------------------+-------+
-| | f_code | code object being | |
-| | | executed in this frame | |
-+-----------+-----------------+---------------------------+-------+
-| | f_exc_traceback | traceback if raised in | |
-| | | this frame, or ``None`` | |
-+-----------+-----------------+---------------------------+-------+
-| | f_exc_type | exception type if raised | |
-| | | in this frame, or | |
-| | | ``None`` | |
-+-----------+-----------------+---------------------------+-------+
-| | f_exc_value | exception value if raised | |
-| | | in this frame, or | |
-| | | ``None`` | |
-+-----------+-----------------+---------------------------+-------+
-| | f_globals | global namespace seen by | |
-| | | this frame | |
-+-----------+-----------------+---------------------------+-------+
-| | f_lasti | index of last attempted | |
-| | | instruction in bytecode | |
-+-----------+-----------------+---------------------------+-------+
-| | f_lineno | current line number in | |
-| | | Python source code | |
-+-----------+-----------------+---------------------------+-------+
-| | f_locals | local namespace seen by | |
-| | | this frame | |
-+-----------+-----------------+---------------------------+-------+
-| | f_restricted | 0 or 1 if frame is in | |
-| | | restricted execution mode | |
-+-----------+-----------------+---------------------------+-------+
-| | f_trace | tracing function for this | |
-| | | frame, or ``None`` | |
-+-----------+-----------------+---------------------------+-------+
-| code | co_argcount | number of arguments (not | |
-| | | including \* or \*\* | |
-| | | args) | |
-+-----------+-----------------+---------------------------+-------+
-| | co_code | string of raw compiled | |
-| | | bytecode | |
-+-----------+-----------------+---------------------------+-------+
-| | co_consts | tuple of constants used | |
-| | | in the bytecode | |
-+-----------+-----------------+---------------------------+-------+
-| | co_filename | name of file in which | |
-| | | this code object was | |
-| | | created | |
-+-----------+-----------------+---------------------------+-------+
-| | co_firstlineno | number of first line in | |
-| | | Python source code | |
-+-----------+-----------------+---------------------------+-------+
-| | co_flags | bitmap: 1=optimized ``|`` | |
-| | | 2=newlocals ``|`` 4=\*arg | |
-| | | ``|`` 8=\*\*arg | |
-+-----------+-----------------+---------------------------+-------+
-| | co_lnotab | encoded mapping of line | |
-| | | numbers to bytecode | |
-| | | indices | |
-+-----------+-----------------+---------------------------+-------+
-| | co_name | name with which this code | |
-| | | object was defined | |
-+-----------+-----------------+---------------------------+-------+
-| | co_names | tuple of names of local | |
-| | | variables | |
-+-----------+-----------------+---------------------------+-------+
-| | co_nlocals | number of local variables | |
-+-----------+-----------------+---------------------------+-------+
-| | co_stacksize | virtual machine stack | |
-| | | space required | |
-+-----------+-----------------+---------------------------+-------+
-| | co_varnames | tuple of names of | |
-| | | arguments and local | |
-| | | variables | |
-+-----------+-----------------+---------------------------+-------+
-| builtin | __doc__ | documentation string | |
-+-----------+-----------------+---------------------------+-------+
-| | __name__ | original name of this | |
-| | | function or method | |
-+-----------+-----------------+---------------------------+-------+
-| | __self__ | instance to which a | |
-| | | method is bound, or | |
-| | | ``None`` | |
-+-----------+-----------------+---------------------------+-------+
-
-Note:
-
-(1)
- .. versionchanged:: 2.2
- :attr:`im_class` used to refer to the class that defined the method.
++-----------+-----------------+---------------------------+
+| Type | Attribute | Description |
++===========+=================+===========================+
+| module | __doc__ | documentation string |
++-----------+-----------------+---------------------------+
+| | __file__ | filename (missing for |
+| | | built-in modules) |
++-----------+-----------------+---------------------------+
+| class | __doc__ | documentation string |
++-----------+-----------------+---------------------------+
+| | __module__ | name of module in which |
+| | | this class was defined |
++-----------+-----------------+---------------------------+
+| method | __doc__ | documentation string |
++-----------+-----------------+---------------------------+
+| | __name__ | name with which this |
+| | | method was defined |
++-----------+-----------------+---------------------------+
+| | im_class | class object that asked |
+| | | for this method |
++-----------+-----------------+---------------------------+
+| | im_func | function object |
+| | | containing implementation |
+| | | of method |
++-----------+-----------------+---------------------------+
+| | im_self | instance to which this |
+| | | method is bound, or |
+| | | ``None`` |
++-----------+-----------------+---------------------------+
+| function | __doc__ | documentation string |
++-----------+-----------------+---------------------------+
+| | __name__ | name with which this |
+| | | function was defined |
++-----------+-----------------+---------------------------+
+| | __code__ | code object containing |
+| | | compiled function |
+| | | bytecode |
++-----------+-----------------+---------------------------+
+| | __defaults__ | tuple of any default |
+| | | values for arguments |
++-----------+-----------------+---------------------------+
+| | __globals__ | global namespace in which |
+| | | this function was defined |
++-----------+-----------------+---------------------------+
+| traceback | tb_frame | frame object at this |
+| | | level |
++-----------+-----------------+---------------------------+
+| | tb_lasti | index of last attempted |
+| | | instruction in bytecode |
++-----------+-----------------+---------------------------+
+| | tb_lineno | current line number in |
+| | | Python source code |
++-----------+-----------------+---------------------------+
+| | tb_next | next inner traceback |
+| | | object (called by this |
+| | | level) |
++-----------+-----------------+---------------------------+
+| frame | f_back | next outer frame object |
+| | | (this frame's caller) |
++-----------+-----------------+---------------------------+
+| | f_builtins | built-in namespace seen |
+| | | by this frame |
++-----------+-----------------+---------------------------+
+| | f_code | code object being |
+| | | executed in this frame |
++-----------+-----------------+---------------------------+
+| | f_exc_traceback | traceback if raised in |
+| | | this frame, or ``None`` |
++-----------+-----------------+---------------------------+
+| | f_exc_type | exception type if raised |
+| | | in this frame, or |
+| | | ``None`` |
++-----------+-----------------+---------------------------+
+| | f_exc_value | exception value if raised |
+| | | in this frame, or |
+| | | ``None`` |
++-----------+-----------------+---------------------------+
+| | f_globals | global namespace seen by |
+| | | this frame |
++-----------+-----------------+---------------------------+
+| | f_lasti | index of last attempted |
+| | | instruction in bytecode |
++-----------+-----------------+---------------------------+
+| | f_lineno | current line number in |
+| | | Python source code |
++-----------+-----------------+---------------------------+
+| | f_locals | local namespace seen by |
+| | | this frame |
++-----------+-----------------+---------------------------+
+| | f_restricted | 0 or 1 if frame is in |
+| | | restricted execution mode |
++-----------+-----------------+---------------------------+
+| | f_trace | tracing function for this |
+| | | frame, or ``None`` |
++-----------+-----------------+---------------------------+
+| code | co_argcount | number of arguments (not |
+| | | including \* or \*\* |
+| | | args) |
++-----------+-----------------+---------------------------+
+| | co_code | string of raw compiled |
+| | | bytecode |
++-----------+-----------------+---------------------------+
+| | co_consts | tuple of constants used |
+| | | in the bytecode |
++-----------+-----------------+---------------------------+
+| | co_filename | name of file in which |
+| | | this code object was |
+| | | created |
++-----------+-----------------+---------------------------+
+| | co_firstlineno | number of first line in |
+| | | Python source code |
++-----------+-----------------+---------------------------+
+| | co_flags | bitmap: 1=optimized ``|`` |
+| | | 2=newlocals ``|`` 4=\*arg |
+| | | ``|`` 8=\*\*arg |
++-----------+-----------------+---------------------------+
+| | co_lnotab | encoded mapping of line |
+| | | numbers to bytecode |
+| | | indices |
++-----------+-----------------+---------------------------+
+| | co_name | name with which this code |
+| | | object was defined |
++-----------+-----------------+---------------------------+
+| | co_names | tuple of names of local |
+| | | variables |
++-----------+-----------------+---------------------------+
+| | co_nlocals | number of local variables |
++-----------+-----------------+---------------------------+
+| | co_stacksize | virtual machine stack |
+| | | space required |
++-----------+-----------------+---------------------------+
+| | co_varnames | tuple of names of |
+| | | arguments and local |
+| | | variables |
++-----------+-----------------+---------------------------+
+| builtin | __doc__ | documentation string |
++-----------+-----------------+---------------------------+
+| | __name__ | original name of this |
+| | | function or method |
++-----------+-----------------+---------------------------+
+| | __self__ | instance to which a |
+| | | method is bound, or |
+| | | ``None`` |
++-----------+-----------------+---------------------------+
.. function:: getmembers(object[, predicate])
have __name__ and __doc__ attributes (properties, getsets, and members have both
of these attributes), but this is not guaranteed.
- .. versionadded:: 2.3
-
.. function:: isgetsetdescriptor(object)
structures. For Python implementations without such types, this method will
always return ``False``.
- .. versionadded:: 2.5
-
.. function:: ismemberdescriptor(object)
``PyMemberDef`` structures. For Python implementations without such types, this
method will always return ``False``.
- .. versionadded:: 2.5
-
.. _inspect-source:
.. sectionauthor:: Raymond Hettinger <python@rcn.com>
-.. versionadded:: 2.3
-
This module implements a number of iterator building blocks inspired by
constructs from the Haskell and SML programming languages. Each has been recast
in a form suitable for Python.
self.currvalue = next(self.it) # Exit on StopIteration
self.currkey = self.keyfunc(self.currvalue)
- .. versionadded:: 2.4
-
.. function:: ifilter(predicate, iterable)
If *start* is ``None``, then iteration starts at zero. If *step* is ``None``,
then the step defaults to one.
- .. versionchanged:: 2.5
- accept ``None`` values for default *start* and *step*.
-
.. function:: izip(*iterables)
result = [next(it) for it in iterables]
yield tuple(result)
- .. versionchanged:: 2.4
- When no iterables are specified, returns a zero length iterator instead of
- raising a :exc:`TypeError` exception.
+ When no iterables are specified, return a zero length iterator.
Note, the left-to-right evaluation order of the iterables is guaranteed. This
makes possible an idiom for clustering a data series into n-length groups using
function should be wrapped with something that limits the number of calls (for
example :func:`islice` or :func:`takewhile`).
- .. versionadded:: 2.6
-
.. function:: repeat(object[, times])
iterator is going to use most or all of the data before the other iterator, it
is faster to use :func:`list` instead of :func:`tee`.
- .. versionadded:: 2.4
-
.. _itertools-example:
``__loader__`` in *module_globals*, in case the module was imported from a
zipfile or other non-filesystem import source.
- .. versionadded:: 2.5
- The *module_globals* parameter was added.
-
.. function:: clearcache()
specified in the :envvar:`LANG` environment variable). If the locale is not
changed thereafter, using multithreading should not cause problems.
- .. versionchanged:: 2.0
- Added support for tuple values of the *locale* parameter.
-
.. function:: localeconv()
*language code* and *encoding* may be ``None`` if their values cannot be
determined.
- .. versionadded:: 2.0
-
.. function:: getlocale([category])
*language code* and *encoding* may be ``None`` if their values cannot be
determined.
- .. versionadded:: 2.0
-
.. function:: getpreferredencoding([do_setlocale])
preferences, so this function is not thread-safe. If invoking setlocale is not
necessary or desired, *do_setlocale* should be set to ``False``.
- .. versionadded:: 2.3
-
.. function:: normalize(localename)
If the given encoding is not known, the function defaults to the default
encoding for the locale code just like :func:`setlocale`.
- .. versionadded:: 2.0
-
.. function:: resetlocale([category])
The default setting is determined by calling :func:`getdefaultlocale`.
*category* defaults to :const:`LC_ALL`.
- .. versionadded:: 2.0
-
.. function:: strcoll(string1, string2)
Please note that this function will only work for exactly one %char specifier.
For whole format strings, use :func:`format_string`.
- .. versionchanged:: 2.5
- Added the *monetary* parameter.
-
.. function:: format_string(format, val[, grouping])
Processes formatting specifiers as in ``format % val``, but takes the current
locale settings into account.
- .. versionadded:: 2.5
-
.. function:: currency(val[, symbol[, grouping[, international]]])
Note that this function will not work with the 'C' locale, so you have to set a
locale via :func:`setlocale` first.
- .. versionadded:: 2.5
-
.. function:: str(float)
.. index:: pair: Errors; logging
-.. versionadded:: 2.3
-
This module defines functions and classes which implement a flexible error
logging system for applications.
above example). In such circumstances, it is likely that specialized
:class:`Formatter`\ s would be used with particular :class:`Handler`\ s.
- .. versionchanged:: 2.5
- *extra* was added.
-
.. function:: info(msg[, *args[, **kwargs]])
:func:`error` and :func:`critical` will call :func:`basicConfig` automatically
if no handlers are defined for the root logger.
- .. versionchanged:: 2.4
- Formerly, :func:`basicConfig` did not take any keyword arguments.
-
The following keyword arguments are supported.
+--------------+---------------------------------------------+
above example). In such circumstances, it is likely that specialized
:class:`Formatter`\ s would be used with particular :class:`Handler`\ s.
- .. versionchanged:: 2.5
- *extra* was added.
-
.. method:: Logger.info(msg[, *args[, **kwargs]])
Finds the caller's source filename and line number. Returns the filename, line
number and function name as a 3-element tuple.
- .. versionchanged:: 2.4
- The function name was added. In earlier versions, the filename and line number
- were returned as a 2-element tuple..
-
.. method:: Logger.handle(record)
This is a factory method which can be overridden in subclasses to create
specialized :class:`LogRecord` instances.
- .. versionchanged:: 2.5
- *func* and *extra* were added.
-
.. _minimal-example:
Basic example
-------------
-.. versionchanged:: 2.4
- formerly :func:`basicConfig` did not take any keyword arguments.
-
The :mod:`logging` package provides a lot of flexibility, and its configuration
can appear daunting. This section demonstrates that simple use of the logging
package is possible.
WatchedFileHandler
^^^^^^^^^^^^^^^^^^
-.. versionadded:: 2.6
-
The :class:`WatchedFileHandler` class, located in the :mod:`logging.handlers`
module, is a :class:`FileHandler` which watches the file it is logging to. If
the file changes, it is closed and reopened using the file name.
the standard SMTP port is used. If your SMTP server requires authentication, you
can specify a (username, password) tuple for the *credentials* argument.
- .. versionchanged:: 2.6
- *credentials* was added.
-
.. method:: SMTPHandler.emit(record)
| | args``. |
+-------------------------+-----------------------------------------------+
-.. versionchanged:: 2.5
- *funcName* was added.
-
.. class:: Formatter([fmt[, datefmt]])
the name of the function from which the logging call was made. If not
specified, it defaults to ``None``.
- .. versionchanged:: 2.5
- *func* was added.
-
.. method:: LogRecord.getMessage()
:exc:`ValueError` exception is raised --- but garbage data will also be written
to the file. The object will not be properly read back by :func:`load`.
- .. versionadded:: 2.4
- The *version* argument indicates the data format that ``dump`` should use
- (see below).
+ The *version* argument indicates the data format that ``dump`` should use
+ (see below).
.. function:: load(file)
value must be a supported type. Raise a :exc:`ValueError` exception if value
has (or contains an object that has) an unsupported type.
- .. versionadded:: 2.4
- The *version* argument indicates the data format that ``dumps`` should use
- (see below).
+ The *version* argument indicates the data format that ``dumps`` should use
+ (see below).
.. function:: loads(string)
Python 2.5) uses a binary format for floating point numbers. The current version
is 2.
- .. versionadded:: 2.4
-
.. rubric:: Footnotes
Return the logarithm of *x* to the given *base*. If the *base* is not specified,
return the natural logarithm of *x* (that is, the logarithm to base *e*).
- .. versionchanged:: 2.3
- *base* argument added.
-
.. function:: log10(x)
The optional *filenames* parameter can be used to cause additional files to be
loaded "on top" of the default database.
- .. versionadded:: 2.2
An example usage of the module::
file. Assignment to an :const:`ACCESS_COPY` memory map affects memory but does
not update the underlying file.
-.. versionchanged:: 2.5
- To map anonymous memory, -1 should be passed as the fileno along with the
- length.
+To map anonymous memory, -1 should be passed as the fileno along with the length.
.. function:: mmap(fileno, length[, tagname[, access]])
:synopsis: Find modules used by a script.
-.. versionadded:: 2.3
-
This module provides a :class:`ModuleFinder` class that can be used to determine
the set of modules imported by a script. ``modulefinder.py`` can also be run as
a script, giving the filename of a Python script as its argument, after which a
.. index:: single: msi
-.. versionadded:: 2.5
-
The :mod:`msilib` supports the creation of Microsoft Installer (``.msi``) files.
Because these files often contain an embedded "cabinet" file (``.cab``), it also
exposes an API to create CAB files. Support for reading ``.cab`` files is
.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
-.. % Note the \protect needed for \file... ;-(
-
-.. versionadded:: 1.5.2
-
The :class:`netrc` class parses and encapsulates the netrc file format used by
the Unix :program:`ftp` program and other FTP clients.
Note that *mapname* is first checked if it is an alias to another name.
- .. versionchanged:: 2.5
- The *domain* argument allows to override the NIS domain used for the lookup. If
- unspecified, lookup is in the default NIS domain.
+ The *domain* argument allows to override the NIS domain used for the lookup. If
+ unspecified, lookup is in the default NIS domain.
.. function:: cat(mapname[, domain=default_domain])
Note that *mapname* is first checked if it is an alias to another name.
- .. versionchanged:: 2.5
- The *domain* argument allows to override the NIS domain used for the lookup. If
- unspecified, lookup is in the default NIS domain.
+ The *domain* argument allows to override the NIS domain used for the lookup. If
+ unspecified, lookup is in the default NIS domain.
.. function:: maps([domain=default_domain])
Return a list of all valid maps.
- .. versionchanged:: 2.5
- The *domain* argument allows to override the NIS domain used for the lookup. If
- unspecified, lookup is in the default NIS domain.
+ The *domain* argument allows to override the NIS domain used for the lookup. If
+ unspecified, lookup is in the default NIS domain.
.. function:: get_default_domain()
Return the system default NIS domain.
- .. versionadded:: 2.5
The :mod:`nis` module defines the following exception:
-
.. exception:: error
An error raised when a NIS function returns an error code.
The module itself defines the following items:
-.. class:: NNTP(host[, port [, user[, password [, readermode] [, usenetrc]]]])
+.. class:: NNTP(host[, port [, user[, password [, readermode][, usenetrc]]]])
Return a new instance of the :class:`NNTP` class, representing a connection
to the NNTP server running on host *host*, listening at port *port*. The
:exc:`NNTPPermanentError`\ s, you might need to set *readermode*.
*readermode* defaults to ``None``. *usenetrc* defaults to ``True``.
- .. versionchanged:: 2.4
- *usenetrc* argument added.
-
.. exception:: NNTPError
strings). Return a pair ``(response, list)``, where *list* is a list of tuples
containing ``(name, title)``.
- .. versionadded:: 2.4
-
.. method:: NNTP.description(group)
This elides the response code from the server. If the response code is needed,
use :meth:`descriptions`.
- .. versionadded:: 2.4
-
.. method:: NNTP.group(name)
return any value, which may or may not be interpretable as a Boolean value.
See :ref:`comparisons` for more information about rich comparisons.
- .. versionadded:: 2.2
The logical operations are also generally applicable to all objects, and support
truth tests, identity tests, and boolean operations:
Return ``a is b``. Tests object identity.
- .. versionadded:: 2.3
-
.. function:: is_not(a, b)
Return ``a is not b``. Tests object identity.
- .. versionadded:: 2.3
The mathematical and bitwise operations are the most numerous:
Return ``a // b``.
- .. versionadded:: 2.2
-
.. function:: inv(o)
invert(o)
Return the bitwise inverse of the number *o*. This is equivalent to ``~o``.
- .. versionadded:: 2.0
- The names :func:`invert` and :func:`__invert__`.
-
.. function:: lshift(a, b)
__lshift__(a, b)
Return ``a ** b``, for *a* and *b* numbers.
- .. versionadded:: 2.3
-
.. function:: rshift(a, b)
__rshift__(a, b)
Return ``a / b`` when ``__future__.division`` is in effect. This is also
known as "true" division.
- .. versionadded:: 2.2
-
.. function:: xor(a, b)
__xor__(a, b)
Return *a* converted to an integer. Equivalent to ``a.__index__()``.
- .. versionadded:: 2.5
-
Operations which work with sequences include:
Return the outcome of the test ``b in a``. Note the reversed operands.
- .. versionadded:: 2.0
- The name :func:`__contains__`.
-
.. function:: countOf(a, b)
``a = iadd(a, b)`` is equivalent to ``a += b``.
- .. versionadded:: 2.5
-
.. function:: iand(a, b)
__iand__(a, b)
``a = iand(a, b)`` is equivalent to ``a &= b``.
- .. versionadded:: 2.5
-
.. function:: iconcat(a, b)
__iconcat__(a, b)
``a = iconcat(a, b)`` is equivalent to ``a += b`` for *a* and *b* sequences.
- .. versionadded:: 2.5
-
.. function:: idiv(a, b)
__idiv__(a, b)
``a = idiv(a, b)`` is equivalent to ``a /= b`` when ``__future__.division`` is
not in effect.
- .. versionadded:: 2.5
-
.. function:: ifloordiv(a, b)
__ifloordiv__(a, b)
``a = ifloordiv(a, b)`` is equivalent to ``a //= b``.
- .. versionadded:: 2.5
-
.. function:: ilshift(a, b)
__ilshift__(a, b)
- ``a = ilshift(a, b)`` is equivalent to ``a <``\ ``<= b``.
-
- .. versionadded:: 2.5
+ ``a = ilshift(a, b)`` is equivalent to ``a <<= b``.
.. function:: imod(a, b)
``a = imod(a, b)`` is equivalent to ``a %= b``.
- .. versionadded:: 2.5
-
.. function:: imul(a, b)
__imul__(a, b)
``a = imul(a, b)`` is equivalent to ``a *= b``.
- .. versionadded:: 2.5
-
.. function:: ior(a, b)
__ior__(a, b)
``a = ior(a, b)`` is equivalent to ``a |= b``.
- .. versionadded:: 2.5
-
.. function:: ipow(a, b)
__ipow__(a, b)
``a = ipow(a, b)`` is equivalent to ``a **= b``.
- .. versionadded:: 2.5
-
.. function:: irepeat(a, b)
__irepeat__(a, b)
``a = irepeat(a, b)`` is equivalent to ``a *= b`` where *a* is a sequence and
*b* is an integer.
- .. versionadded:: 2.5
-
.. function:: irshift(a, b)
__irshift__(a, b)
``a = irshift(a, b)`` is equivalent to ``a >>= b``.
- .. versionadded:: 2.5
-
.. function:: isub(a, b)
__isub__(a, b)
``a = isub(a, b)`` is equivalent to ``a -= b``.
- .. versionadded:: 2.5
-
.. function:: itruediv(a, b)
__itruediv__(a, b)
``a = itruediv(a, b)`` is equivalent to ``a /= b`` when ``__future__.division``
is in effect.
- .. versionadded:: 2.5
-
.. function:: ixor(a, b)
__ixor__(a, b)
``a = ixor(a, b)`` is equivalent to ``a ^= b``.
- .. versionadded:: 2.5
-
The :mod:`operator` module also defines a few predicates to test the type of
objects.
``f=attrgetter('name', 'date')``, the call ``f(b)`` returns ``(b.name,
b.date)``.
- .. versionadded:: 2.4
-
- .. versionchanged:: 2.5
- Added support for multiple attributes.
-
.. function:: itemgetter(item[, args...])
call ``f(b)`` returns ``b[2]``. After, ``f=itemgetter(2,5,3)``, the call
``f(b)`` returns ``(b[2], b[5], b[3])``.
- .. versionadded:: 2.4
-
- .. versionchanged:: 2.5
- Added support for multiple item extraction.
Examples::
.. module:: optparse
:synopsis: More convenient, flexible, and powerful command-line parsing library.
.. moduleauthor:: Greg Ward <gward@python.net>
-
-
-.. versionadded:: 2.3
-
.. sectionauthor:: Greg Ward <gward@python.net>
Return a normalized absolutized version of the pathname *path*. On most
platforms, this is equivalent to ``normpath(join(os.getcwd(), path))``.
- .. versionadded:: 1.5.2
-
.. function:: basename(path)
broken symbolic links. Equivalent to :func:`exists` on platforms lacking
:func:`os.lstat`.
- .. versionadded:: 2.4
-
.. function:: expanduser(path)
the number of seconds since the epoch (see the :mod:`time` module). Raise
:exc:`os.error` if the file does not exist or is inaccessible.
- .. versionadded:: 1.5.2
-
- .. versionchanged:: 2.3
- If :func:`os.stat_float_times` returns True, the result is a floating point
- number.
+ If :func:`os.stat_float_times` returns True, the result is a floating point
+ number.
.. function:: getmtime(path)
giving the number of seconds since the epoch (see the :mod:`time` module).
Raise :exc:`os.error` if the file does not exist or is inaccessible.
- .. versionadded:: 1.5.2
-
- .. versionchanged:: 2.3
- If :func:`os.stat_float_times` returns True, the result is a floating point
- number.
+ If :func:`os.stat_float_times` returns True, the result is a floating point
+ number.
.. function:: getctime(path)
the :mod:`time` module). Raise :exc:`os.error` if the file does not exist or
is inaccessible.
- .. versionadded:: 2.3
-
.. function:: getsize(path)
Return the size, in bytes, of *path*. Raise :exc:`os.error` if the file does
not exist or is inaccessible.
- .. versionadded:: 1.5.2
-
.. function:: isabs(path)
Return the canonical path of the specified filename, eliminating any symbolic
links encountered in the path (if they are supported by the operating system).
- .. versionadded:: 2.2
-
.. function:: relpath(path[, start])
*start* defaults to :attr:`os.curdir`. Availability: Windows, Unix.
- .. versionadded:: 2.6
-
.. function:: samefile(path1, path2)
specifications, *drive* will always be the empty string. In all cases, ``drive
+ tail`` will be the same as *path*.
- .. versionadded:: 1.3
-
.. function:: splitext(path)
period. Leading periods on the basename are ignored; ``splitext('.cshrc')``
returns ``('.cshrc', '')``.
- .. versionchanged:: 2.6
- Earlier versions could produce an empty root when the only period was the
- first character.
-
.. function:: splitunc(path)
True if arbitrary Unicode strings can be used as file names (within limitations
imposed by the file system), and if :func:`os.listdir` returns Unicode strings
for a Unicode argument.
-
- .. versionadded:: 2.3
-
Return the process group id of the process with process id *pid*. If *pid* is 0,
the process group id of the current process is returned. Availability: Unix.
- .. versionadded:: 2.3
-
.. function:: getpgrp()
identifying a group. This operation is typical available only to the superuser.
Availability: Unix.
- .. versionadded:: 2.2
-
.. function:: setpgrp()
Calls the system call :cfunc:`getsid`. See the Unix manual for the semantics.
Availability: Unix.
- .. versionadded:: 2.4
-
.. function:: setsid()
and *bufsize* arguments have the same meaning as the corresponding arguments to
the built-in :func:`open` function. Availability: Macintosh, Unix, Windows.
- .. versionchanged:: 2.3
- When specified, the *mode* argument must now start with one of the letters
- ``'r'``, ``'w'``, or ``'a'``, otherwise a :exc:`ValueError` is raised.
+ When specified, the *mode* argument must start with one of the letters
+ ``'r'``, ``'w'``, or ``'a'``, otherwise a :exc:`ValueError` is raised.
- .. versionchanged:: 2.5
- On Unix, when the *mode* argument starts with ``'a'``, the *O_APPEND* flag is
- set on the file descriptor (which the :cfunc:`fdopen` implementation already
- does on most platforms).
+ On Unix, when the *mode* argument starts with ``'a'``, the *O_APPEND* flag is
+ set on the file descriptor (which the :cfunc:`fdopen` implementation already
+ does on most platforms).
.. function:: popen(command[, mode[, bufsize]])
.. deprecated:: 2.6
This function is obsolete. Use the :mod:`subprocess` module.
- .. versionchanged:: 2.0
- This function worked unreliably under Windows in earlier versions of Python.
- This was due to the use of the :cfunc:`_popen` function from the libraries
- provided with Windows. Newer versions of Python do not use the broken
- implementation from the Windows libraries.
-
.. function:: tmpfile()
Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
respectively. Availability: Windows, Macintosh, Unix.
- .. versionadded:: 2.5
-
.. _os-file-dir:
descriptor *fd*. The descriptor must refer to an opened directory, not an open
file. Availability: Unix.
- .. versionadded:: 2.3
-
.. function:: getcwd()
Return a Unicode object representing the current working directory.
Availability: Macintosh, Unix, Windows.
- .. versionadded:: 2.3
-
.. function:: chflags(path, flags)
Availability: Macintosh, Unix.
- .. versionadded:: 2.6
-
.. function:: chroot(path)
Change the root directory of the current process to *path*. Availability:
Macintosh, Unix.
- .. versionadded:: 2.2
-
.. function:: chmod(path, mode)
Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do not
follow symbolic links. Availability: Unix.
- .. versionadded:: 2.6
-
.. function:: lchown(path, uid, gid)
Change the owner and group id of *path* to the numeric *uid* and gid. This
function will not follow symbolic links. Availability: Macintosh, Unix.
- .. versionadded:: 2.3
-
.. function:: link(src, dst)
``'..'`` even if they are present in the directory. Availability: Macintosh,
Unix, Windows.
- .. versionchanged:: 2.3
- On Windows NT/2k/XP and Unix, if *path* is a Unicode object, the result will be
- a list of Unicode objects.
+ On Windows NT/2k/XP and Unix, if *path* is a Unicode object, the result will be
+ a list of Unicode objects.
.. function:: lstat(path)
``stat.S_IFBLK``, *device* defines the newly created device special file (probably using
:func:`os.makedev`), otherwise it is ignored.
- .. versionadded:: 2.3
-
.. function:: major(device)
Extracts the device major number from a raw device number (usually the
:attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`).
- .. versionadded:: 2.3
-
.. function:: minor(device)
Extracts the device minor number from a raw device number (usually the
:attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`).
- .. versionadded:: 2.3
-
.. function:: makedev(major, minor)
Composes a raw device number from the major and minor device numbers.
- .. versionadded:: 2.3
-
.. function:: mkdir(path[, mode])
:func:`makedirs` will become confused if the path elements to create include
*os.pardir*.
- .. versionadded:: 1.5.2
-
- .. versionchanged:: 2.3
- This function now handles UNC paths correctly.
+ This function handles UNC paths correctly.
.. function:: pathconf(path, name)
be converted to an absolute pathname using ``os.path.join(os.path.dirname(path),
result)``.
- .. versionchanged:: 2.6
- If the *path* is a Unicode object the result will also be a Unicode object.
+ If the *path* is a Unicode object, the result will also be a Unicode object.
Availability: Macintosh, Unix.
they are empty. Raises :exc:`OSError` if the leaf directory could not be
successfully removed.
- .. versionadded:: 1.5.2
-
.. function:: rename(src, dst)
attempted first. After the rename, directories corresponding to rightmost path
segments of the old name will be pruned away using :func:`removedirs`.
- .. versionadded:: 1.5.2
-
.. note::
This function can fail with the new directory structure made if you lack
926L
>>>
- .. versionchanged:: 2.3
- If :func:`stat_float_times` returns true, the time values are floats, measuring
- seconds. Fractions of a second may be reported if the system supports that. On
- Mac OS, the times are always floats. See :func:`stat_float_times` for further
- discussion.
+ If :func:`stat_float_times` returns true, the time values are floats, measuring
+ seconds. Fractions of a second may be reported if the system supports that. On
+ Mac OS, the times are always floats. See :func:`stat_float_times` for further
+ discussion.
On some Unix systems (such as Linux), the following attributes may also be
available: :attr:`st_blocks` (number of blocks allocated for file),
Availability: Macintosh, Unix, Windows.
- .. versionchanged:: 2.2
- Added access to values as attributes of the returned object.
-
- .. versionchanged:: 2.5
- Added st_gen, st_birthtime.
-
.. function:: stat_float_times([newvalue])
For compatibility with older Python versions, accessing :class:`stat_result` as
a tuple always returns integers.
- .. versionchanged:: 2.5
- Python now returns float values by default. Applications which do not work
- correctly with floating point time stamps can use this function to restore the
- old behaviour.
+ Python now returns float values by default. Applications which do not work
+ correctly with floating point time stamps can use this function to restore the
+ old behaviour.
The resolution of the timestamps (that is the smallest possible fraction)
depends on the system. Some systems only support second resolution; on these
this remains useful when writing code that needs to work with versions of Python
that don't support accessing the fields as attributes.
- .. versionchanged:: 2.2
- Added access to values as attributes of the returned object.
-
.. function:: symlink(src, dst)
depending on the resolution with which your operating system records access and
modification times; see :func:`stat`.
- .. versionchanged:: 2.0
- Added support for ``None`` for *times*.
-
Availability: Macintosh, Unix, Windows.
directories. Set *followlinks* to True to visit directories pointed to by
symlinks, on systems that support them.
- .. versionadded:: 2.6
- The *followlinks* parameter.
-
.. note::
Be aware that setting *followlinks* to true can lead to infinite recursion if a
for name in dirs:
os.rmdir(os.path.join(root, name))
- .. versionadded:: 2.3
-
.. _os-process:
Exit code that means no error occurred. Availability: Macintosh, Unix.
- .. versionadded:: 2.3
-
.. data:: EX_USAGE
Exit code that means the command was used incorrectly, such as when the wrong
number of arguments are given. Availability: Macintosh, Unix.
- .. versionadded:: 2.3
-
.. data:: EX_DATAERR
Exit code that means the input data was incorrect. Availability: Macintosh,
Unix.
- .. versionadded:: 2.3
-
.. data:: EX_NOINPUT
Exit code that means an input file did not exist or was not readable.
Availability: Macintosh, Unix.
- .. versionadded:: 2.3
-
.. data:: EX_NOUSER
Exit code that means a specified user did not exist. Availability: Macintosh,
Unix.
- .. versionadded:: 2.3
-
.. data:: EX_NOHOST
Exit code that means a specified host did not exist. Availability: Macintosh,
Unix.
- .. versionadded:: 2.3
-
.. data:: EX_UNAVAILABLE
Exit code that means that a required service is unavailable. Availability:
Macintosh, Unix.
- .. versionadded:: 2.3
-
.. data:: EX_SOFTWARE
Exit code that means an internal software error was detected. Availability:
Macintosh, Unix.
- .. versionadded:: 2.3
-
.. data:: EX_OSERR
Exit code that means an operating system error was detected, such as the
inability to fork or create a pipe. Availability: Macintosh, Unix.
- .. versionadded:: 2.3
-
.. data:: EX_OSFILE
Exit code that means some system file did not exist, could not be opened, or had
some other kind of error. Availability: Macintosh, Unix.
- .. versionadded:: 2.3
-
.. data:: EX_CANTCREAT
Exit code that means a user specified output file could not be created.
Availability: Macintosh, Unix.
- .. versionadded:: 2.3
-
.. data:: EX_IOERR
Exit code that means that an error occurred while doing I/O on some file.
Availability: Macintosh, Unix.
- .. versionadded:: 2.3
-
.. data:: EX_TEMPFAIL
that may not really be an error, such as a network connection that couldn't be
made during a retryable operation. Availability: Macintosh, Unix.
- .. versionadded:: 2.3
-
.. data:: EX_PROTOCOL
Exit code that means that a protocol exchange was illegal, invalid, or not
understood. Availability: Macintosh, Unix.
- .. versionadded:: 2.3
-
.. data:: EX_NOPERM
operation (but not intended for file system problems). Availability: Macintosh,
Unix.
- .. versionadded:: 2.3
-
.. data:: EX_CONFIG
Exit code that means that some kind of configuration error occurred.
Availability: Macintosh, Unix.
- .. versionadded:: 2.3
-
.. data:: EX_NOTFOUND
Exit code that means something like "an entry was not found". Availability:
Macintosh, Unix.
- .. versionadded:: 2.3
-
.. function:: fork()
Send the signal *sig* to the process group *pgid*. Availability: Macintosh,
Unix.
- .. versionadded:: 2.3
-
.. function:: nice(increment)
Availability: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
and :func:`spawnvpe` are not available on Windows.
- .. versionadded:: 1.6
-
.. data:: P_NOWAIT
P_NOWAITO
will return as soon as the new process has been created, with the process ID as
the return value. Availability: Macintosh, Unix, Windows.
- .. versionadded:: 1.6
-
.. data:: P_WAIT
of the process the run is successful, or ``-signal`` if a signal kills the
process. Availability: Macintosh, Unix, Windows.
- .. versionadded:: 1.6
-
.. data:: P_DETACH
P_OVERLAY
process will be replaced; the :func:`spawn\*` function will not return.
Availability: Windows.
- .. versionadded:: 1.6
-
.. function:: startfile(path[, operation])
doesn't work if it is. Use the :func:`os.path.normpath` function to ensure that
the path is properly encoded for Win32. Availability: Windows.
- .. versionadded:: 2.0
-
- .. versionadded:: 2.5
- The *operation* parameter.
-
.. function:: system(command)
argument is the same as that provided to :func:`waitpid` and :func:`wait4`.
Availability: Unix.
- .. versionadded:: 2.5
-
.. function:: wait4(pid, options)
information. The arguments to :func:`wait4` are the same as those provided to
:func:`waitpid`. Availability: Unix.
- .. versionadded:: 2.5
-
.. data:: WNOHANG
from a job control stop since their status was last reported. Availability: Some
Unix systems.
- .. versionadded:: 2.3
-
.. data:: WUNTRACED
their current state has not been reported since they were stopped. Availability:
Macintosh, Unix.
- .. versionadded:: 2.3
The following functions take a process status code as returned by
:func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be
used to determine the disposition of a process.
-
.. function:: WCOREDUMP(status)
Returns ``True`` if a core dump was generated for the process, otherwise it
returns ``False``. Availability: Macintosh, Unix.
- .. versionadded:: 2.3
-
.. function:: WIFCONTINUED(status)
Returns ``True`` if the process has been continued from a job control stop,
otherwise it returns ``False``. Availability: Unix.
- .. versionadded:: 2.3
-
.. function:: WIFSTOPPED(status)
5, and 15 minutes or raises :exc:`OSError` if the load average was
unobtainable.
- .. versionadded:: 2.3
-
.. function:: sysconf(name)
The character which separates the base filename from the extension; for example,
the ``'.'`` in :file:`os.py`. Also available via :mod:`os.path`.
- .. versionadded:: 2.2
-
.. data:: pathsep
The file path of the null device. For example: ``'/dev/null'`` for POSIX or
``'Dev:Nul'`` for Mac OS 9. Also available via :mod:`os.path`.
- .. versionadded:: 2.4
-
.. _os-miscfunc:
though its exact quality depends on the OS implementation. On a UNIX-like
system this will query /dev/urandom, and on Windows it will use CryptGenRandom.
If a randomness source is not found, :exc:`NotImplementedError` will be raised.
-
- .. versionadded:: 2.4
-
:synopsis: Access to OSS-compatible audio devices.
-.. versionadded:: 2.3
-
This module allows you to access the OSS (Open Sound System) audio interface.
OSS is available for a wide range of open-source and commercial Unices, and is
the standard audio interface for Linux and recent versions of FreeBSD.
restarting preserves pdb's state (such as breakpoints) and in most cases is more
useful than quitting the debugger upon program's exit.
-.. versionadded:: 2.4
- Restarting post-mortem behavior added.
-
Typical usage to inspect a crashed program is::
>>> import pdb
that are to print a specific message and then continue. If none of the other
commands print anything, you see no sign that the breakpoint was reached.
- .. versionadded:: 2.5
-
s(tep)
Execute the current line, stop at the first possible occasion (either in a
function that is called or on the next line in the current function).
with "shlex" and the result is used as the new sys.argv. History, breakpoints,
actions and debugger options are preserved. "restart" is an alias for "run".
- .. versionadded:: 2.6
-
q(uit)
Quit from the debugger. The program being executed is aborted.
as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol version
available will be used.
-.. versionchanged:: 2.3
- Introduced the *protocol* parameter.
-
A binary format, which is slightly more efficient, can be chosen by specifying a
*protocol* version >= 1.
The highest protocol version available. This value can be passed as a
*protocol* value.
- .. versionadded:: 2.3
-
.. note::
Be sure to always open pickle files created with protocols >= 1 in binary mode.
specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol
version will be used.
- .. versionchanged:: 2.3
- Introduced the *protocol* parameter.
-
*file* must have a :meth:`write` method that accepts a single string argument.
It can thus be a file object opened for writing, a :mod:`StringIO` object, or
any other custom object that meets this interface.
specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol
version will be used.
- .. versionchanged:: 2.3
- The *protocol* parameter was added.
-
.. function:: loads(string)
specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest
protocol version will be used.
- .. versionchanged:: 2.3
- Introduced the *protocol* parameter.
-
*file* must have a :meth:`write` method that accepts a single string argument.
It can thus be an open file object, a :mod:`StringIO` object, or any other
custom object that meets this interface.
:exc:`UnpicklingError` will be raised in the unpickling environment. Note that
as usual, the callable itself is pickled by name.
-* A tuple of arguments for the callable object.
-
- .. versionchanged:: 2.5
- Formerly, this argument could also be ``None``.
+* A tuple of arguments for the callable object, not ``None``.
* Optionally, the object's state, which will be passed to the object's
:meth:`__setstate__` method as described in section :ref:`pickle-inst`. If the
opcodes, as well as some useful functions.
-.. versionadded:: 2.3
-
This module contains various constants relating to the intimate details of the
:mod:`pickle` module, some lengthy comments about the implementation, and a few
useful functions for analyzing pickled data. The contents of this module are
:synopsis: Utilities to support extension of packages.
-.. versionadded:: 2.3
-
This module provides a single function:
.. sectionauthor:: Bjorn Pettersen <bpettersen@corp.fairisaac.com>
-.. versionadded:: 2.3
-
.. note::
Specific platforms listed alphabetically, with Linux included in the Unix
Returns a string identifying the Python implementation SCM branch.
- .. versionadded:: 2.6
-
.. function:: python_implementation()
Returns a string identifying the Python implementation. Possible return values
are: 'CPython', 'IronPython', 'Jython'
- .. versionadded:: 2.6
-
.. function:: python_revision()
Returns a string identifying the Python implementation SCM revision.
- .. versionadded:: 2.6
-
.. function:: python_version()
connection attempt (if not specified, or passed as None, the global default
timeout setting will be used).
- .. versionchanged:: 2.6
- *timeout* was added.
-
.. class:: POP3_SSL(host[, port[, keyfile[, certfile]]])
port is used. *keyfile* and *certfile* are also optional - they can contain a
PEM formatted private key and certificate chain file for the SSL connection.
- .. versionadded:: 2.4
One exception is defined as an attribute of the :mod:`poplib` module:
Construct :class:`PrettyPrinter` objects explicitly if you need to adjust the
width constraint.
-.. versionchanged:: 2.5
- Dictionaries are sorted by key before the display is computed; before 2.5, a
- dictionary was sorted only if its display required more than one line, although
- that wasn't documented.
+Dictionaries are sorted by key before the display is computed.
The :mod:`pprint` module defines one class:
and *depth* will be passed to the :class:`PrettyPrinter` constructor as
formatting parameters.
- .. versionchanged:: 2.4
- The parameters *indent*, *width* and *depth* were added.
-
.. function:: pprint(object[, stream[, indent[, width[, depth]]]])
'/usr/local/lib/python1.5/sharedmodules',
'/usr/local/lib/python1.5/tkinter']
- .. versionchanged:: 2.4
- The parameters *indent*, *width* and *depth* were added.
-
.. function:: isreadable(object)
is no requested limit. This argument should be passed unmodified to recursive
calls. The fourth argument, *level*, gives the current level; recursive calls
should be passed a value less than that of the current call.
-
- .. versionadded:: 2.3
-
#. :mod:`profile`, a pure Python module, described in the sequel. Copyright ©
1994, by InfoSeek Corporation.
- .. versionchanged:: 2.4
- also reports the time spent in calls to built-in functions and methods.
-
#. :mod:`cProfile`, a module written in C, with a reasonable overhead that makes
it suitable for profiling long-running programs. Based on :mod:`lsprof`,
contributed by Brett Rosen and Ted Czotter.
- .. versionadded:: 2.5
-
#. :mod:`hotshot`, a C module focusing on minimizing the overhead while
profiling, at the expense of long data post-processing times.
- .. versionchanged:: 2.5
- the results should be more meaningful than in the past: the timing core
- contained a critical bug.
-
The :mod:`profile` and :mod:`cProfile` modules export the same interface, so
they are mostly interchangeables; :mod:`cProfile` has a much lower overhead but
is not so far as well-tested and might not be available on all systems.
a single report. If additional files need to be combined with data in an
existing :class:`Stats` object, the :meth:`add` method can be used.
- .. % (such as the old system profiler).
-
- .. versionchanged:: 2.5
- The *stream* parameter was added.
-
.. _profile-stats:
exists. This is equivalent to the method of the same name on the
:class:`profile.Profile` and :class:`cProfile.Profile` classes.
- .. versionadded:: 2.3
-
.. method:: Stats.sort_stats(key[, ...])
.. sectionauthor:: Ka-Ping Yee <ping@lfw.org>
-.. versionadded:: 2.1
-
.. index::
single: documentation; generation
single: documentation; online
.. % should be marked using the \member macro and should not include the
.. % parentheses used when marking functions and methods.
-.. versionadded:: 2.0
-
.. index:: single: Expat
The :mod:`xml.parsers.expat` module is a Python interface to the Expat
in the encoding of the entity which contains the text. When called while an
event handler is not active, the return value is ``None``.
- .. versionadded:: 2.1
-
.. method:: xmlparser.ExternalEntityParserCreate(context[, encoding])
:exc:`ExpatError` to be raised with the :attr:`code` attribute set to
:const:`errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING`.
- .. versionadded:: 2.3
-
:class:`xmlparser` objects have the following attributes:
The size of the buffer used when :attr:`buffer_text` is true. This value cannot
be changed at this time.
- .. versionadded:: 2.3
-
.. attribute:: xmlparser.buffer_text
at every line ending. This attribute is false by default, and may be changed at
any time.
- .. versionadded:: 2.3
-
.. attribute:: xmlparser.buffer_used
These bytes represent UTF-8 encoded text. This attribute has no meaningful
interpretation when :attr:`buffer_text` is false.
- .. versionadded:: 2.3
-
.. attribute:: xmlparser.ordered_attributes
module also used this format.) By default, this attribute is false; it may be
changed at any time.
- .. versionadded:: 2.1
-
.. attribute:: xmlparser.specified_attributes
needed to comply with the standards for the behavior of XML processors. By
default, this attribute is false; it may be changed at any time.
- .. versionadded:: 2.1
The following attributes contain values relating to the most recent error
encountered by an :class:`xmlparser` object, and will only have correct values
just past the last parse event (regardless of whether there was an associated
callback).
-.. versionadded:: 2.4
-
.. attribute:: xmlparser.CurrentByteIndex
or ``-1`` if the standalone clause was omitted. This is only available with
Expat version 1.95.0 or newer.
- .. versionadded:: 2.1
-
.. method:: xmlparser.StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset)
general entities). This is only available starting with version 1.95.0 of the
Expat library.
- .. versionadded:: 2.1
-
.. method:: xmlparser.NotationDeclHandler(notationName, base, systemId, publicId)
Expat's internal error number for the specific error. This will match one of
the constants defined in the ``errors`` object from this module.
- .. versionadded:: 2.1
-
.. attribute:: ExpatError.lineno
Line number on which the error was detected. The first line is numbered ``1``.
- .. versionadded:: 2.1
-
.. attribute:: ExpatError.offset
Character offset into the line where the error occurred. The first column is
numbered ``0``.
- .. versionadded:: 2.1
-
.. _expat-example:
immediately available, else raise the :exc:`Full` exception (*timeout* is
ignored in that case).
- .. versionadded:: 2.3
- The *timeout* parameter.
-
.. method:: Queue.put_nowait(item)
Otherwise (*block* is false), return an item if one is immediately available,
else raise the :exc:`Empty` exception (*timeout* is ignored in that case).
- .. versionadded:: 2.3
- The *timeout* parameter.
-
.. method:: Queue.get_nowait()
Raises a :exc:`ValueError` if called more times than there were items placed in
the queue.
- .. versionadded:: 2.5
-
.. method:: Queue.join()
indicate that the item was retrieved and all work on it is complete. When the
count of unfinished tasks drops to zero, join() unblocks.
- .. versionadded:: 2.5
Example of how to wait for enqueued tasks to be completed::
Optionally, a new generator can supply a :meth:`getrandombits` method --- this
allows :meth:`randrange` to produce selections over an arbitrarily large range.
-.. versionadded:: 2.4
- the :meth:`getrandombits` method.
-
As an example of subclassing, the :mod:`random` module provides the
:class:`WichmannHill` class that implements an alternative generator in pure
Python. The class provides a backward compatible way to reproduce results from
known to fail some stringent randomness tests. See the references below for a
recent variant that repairs these flaws.
-.. versionchanged:: 2.3
- Substituted MersenneTwister for Wichmann-Hill.
-
Bookkeeping functions:
they are used instead of the system time (see the :func:`os.urandom` function
for details on availability).
- .. versionchanged:: 2.4
- formerly, operating system resources were not used.
-
If *x* is not ``None`` or an int or long, ``hash(x)`` is used instead. If *x* is
an int or long, *x* is used directly.
Return an object capturing the current internal state of the generator. This
object can be passed to :func:`setstate` to restore the state.
- .. versionadded:: 2.1
-
.. function:: setstate(state)
:func:`setstate` restores the internal state of the generator to what it was at
the time :func:`setstate` was called.
- .. versionadded:: 2.1
-
.. function:: jumpahead(n)
same internal state, and then :meth:`jumpahead` can be used to force the
instances' states far apart.
- .. versionadded:: 2.1
-
- .. versionchanged:: 2.3
- Instead of jumping to a specific state, *n* steps ahead, ``jumpahead(n)``
- jumps to another state likely to be separated by many steps.
-
.. function:: getrandbits(k)
as an optional part of the API. When available, :meth:`getrandbits` enables
:meth:`randrange` to handle arbitrarily large ranges.
- .. versionadded:: 2.4
Functions for integers:
-
.. function:: randrange([start,] stop[, step])
Return a randomly selected element from ``range(start, stop, step)``. This is
equivalent to ``choice(range(start, stop, step))``, but doesn't actually build a
range object.
- .. versionadded:: 1.5.2
-
.. function:: randint(a, b)
Return a random integer *N* such that ``a <= N <= b``.
-Functions for sequences:
+Functions for sequences:
.. function:: choice(seq)
Return a *k* length list of unique elements chosen from the population sequence.
Used for random sampling without replacement.
- .. versionadded:: 2.3
-
Returns a new list containing elements from the population while leaving the
original population unchanged. The resulting list is in selection order so that
all sub-slices will also be valid random samples. This allows raffle winners
The :meth:`getstate` and :meth:`setstate` methods raise
:exc:`NotImplementedError` if called.
- .. versionadded:: 2.4
Examples of basic usage::
matching pattern, which will match with ``'<user@host.com>'`` as well as
``'user@host.com'``, but not with ``'<user@host.com'``.
- .. versionadded:: 2.4
The special sequences consist of ``'\'`` and a character from the list below.
If the ordinary character is not on the list, then the resulting RE will match
Make ``\w``, ``\W``, ``\b``, ``\B``, ``\d``, ``\D``, ``\s`` and ``\S`` dependent
on the Unicode character properties database.
- .. versionadded:: 2.0
-
.. data:: X
VERBOSE
a list of tuples if the pattern has more than one group. Empty matches are
included in the result unless they touch the beginning of another match.
- .. versionadded:: 1.5.2
-
- .. versionchanged:: 2.4
- Added the optional flags argument.
-
.. function:: finditer(pattern, string[, flags])
*string*. For each match, the iterator returns a match object. Empty matches
are included in the result unless they touch the beginning of another match.
- .. versionadded:: 2.2
-
- .. versionchanged:: 2.4
- Added the optional flags argument.
-
.. function:: sub(pattern, repl, string[, count])
Clear the current history. (Note: this function is not available if the
installed version of GNU readline doesn't support it.)
- .. versionadded:: 2.4
-
.. function:: get_history_length()
:func:`get_history_length`, which returns the maximum number of lines that will
be written to a history file.)
- .. versionadded:: 2.3
-
.. function:: get_history_item(index)
Return the current contents of history item at *index*.
- .. versionadded:: 2.3
-
.. function:: remove_history_item(pos)
Remove history item specified by its position from the history.
- .. versionadded:: 2.4
-
.. function:: replace_history_item(pos, line)
Replace history item specified by its position with the given line.
- .. versionadded:: 2.4
-
.. function:: redisplay()
Change what's displayed on the screen to reflect the current contents of the
line buffer.
- .. versionadded:: 2.3
-
.. function:: set_startup_hook([function])
Get the completer function, or ``None`` if no completer function has been set.
- .. versionadded:: 2.3
-
.. function:: get_begidx()
default is ``4`` for :attr:`maxdict`, ``5`` for :attr:`maxarray`, and ``6`` for
the others.
- .. versionadded:: 2.4
- :attr:`maxset`, :attr:`maxfrozenset`, and :attr:`set`.
-
.. attribute:: Repr.maxlong
This function will raise a :exc:`ValueError` if an invalid *who* parameter is
specified. It may also raise :exc:`error` exception in unusual circumstances.
- .. versionchanged:: 2.3
- Added access to values as attributes of the returned object.
-
.. function:: getpagesize()
.. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
-.. versionadded:: 2.5
-
The :mod:`runpy` module is used to locate and run Python modules without
importing them first. Its main use is to implement the :option:`-m` command line
switch that allows scripts to be located using the Python module namespace
Exception raised by the :class:`SGMLParser` class when it encounters an error
while parsing.
- .. versionadded:: 2.1
-
:class:`SGMLParser` instances have the following methods:
base implementation simply calls *method* with *attributes* as the only
argument.
- .. versionadded:: 2.5
- Handling of entity and character references within attribute values.
-
.. method:: SGMLParser.handle_endtag(tag, method)
a string. If that method returns a string, it is passed to :meth:`handle_data`,
otherwise ``unknown_charref(ref)`` is called to handle the error.
- .. versionchanged:: 2.5
- Use :meth:`convert_charref` instead of hard-coding the conversion.
-
.. method:: SGMLParser.convert_charref(ref)
method returns ``None``. This method is called by the default
:meth:`handle_charref` implementation and by the attribute value parser.
- .. versionadded:: 2.5
-
.. method:: SGMLParser.convert_codepoint(codepoint)
Convert a codepoint to a :class:`str` value. Encodings can be handled here if
appropriate, though the rest of :mod:`sgmllib` is oblivious on this matter.
- .. versionadded:: 2.5
-
.. method:: SGMLParser.handle_entityref(ref)
method ``unknown_entityref(ref)``. The default :attr:`entitydefs` defines
translations for ``&``, ``&apos``, ``>``, ``<``, and ``"``.
- .. versionchanged:: 2.5
- Use :meth:`convert_entityref` instead of hard-coding the conversion.
-
.. method:: SGMLParser.convert_entityref(ref)
``None``. This method is called by the default :meth:`handle_entityref`
implementation and by the attribute value parser.
- .. versionadded:: 2.5
-
.. method:: SGMLParser.handle_comment(comment)
By default, version 0 pickles are used to serialize values. The version of the
pickle protocol can be specified with the *protocol* parameter.
- .. versionchanged:: 2.3
- The *protocol* parameter was added.
-
By default, mutations to persistent-dictionary mutable entries are not
automatically written back. If the optional *writeback* parameter is set to
*True*, all entries accessed are cached in memory, and written back at close
pickle protocol can be specified with the *protocol* parameter. See the
:mod:`pickle` documentation for a discussion of the pickle protocols.
- .. versionchanged:: 2.3
- The *protocol* parameter was added.
-
If the *writeback* parameter is ``True``, the object will hold a cache of all
entries accessed and write them back to the *dict* at sync and close times.
This allows natural operations on mutable entries, but can consume much more
.. sectionauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
-.. versionadded:: 1.5.2
-
The :class:`shlex` class makes it easy to write lexical analyzers for simple
syntaxes resembling that of the Unix shell. This will often be useful for
writing minilanguages, (for example, in run control files for Python
empty string). This function operates in POSIX mode by default, but uses
non-POSIX mode if the *posix* argument is false.
- .. versionadded:: 2.3
-
- .. versionchanged:: 2.6
- Added the *posix* parameter.
-
.. note::
Since the :func:`split` function instantiates a :class:`shlex` instance, passing
specified it will later be available for use in error messages. This is the
same method used internally by the :meth:`sourcehook` method.
- .. versionadded:: 2.1
-
.. method:: shlex.pop_source()
Pop the last-pushed input source from the input stack. This is the same method
used internally when the lexer reaches EOF on a stacked input stream.
- .. versionadded:: 2.1
-
.. method:: shlex.error_leader([file[, line]])
Characters that will be considered as escape. This will be only used in POSIX
mode, and includes just ``'\'`` by default.
- .. versionadded:: 2.3
-
.. attribute:: shlex.quotes
:attr:`escape`. This is only used in POSIX mode, and includes just ``'"'`` by
default.
- .. versionadded:: 2.3
-
.. attribute:: shlex.whitespace_split
example, for parsing command lines with :class:`shlex`, getting tokens in a
similar way to shell arguments.
- .. versionadded:: 2.3
-
.. attribute:: shlex.infile
Token used to determine end of file. This will be set to the empty string
(``''``), in non-POSIX mode, and to ``None`` in POSIX mode.
- .. versionadded:: 2.3
-
.. _shlex-parsing-rules:
files are copied to the new tree. If exception(s) occur, an :exc:`Error` is
raised with a list of reasons.
- The source code for this should be considered an example rather than a tool.
-
- .. versionchanged:: 2.3
- :exc:`Error` is raised if any exceptions occur during copying, rather than
- printing a message.
-
- .. versionchanged:: 2.5
- Create intermediate directories needed to create *dst*, rather than raising an
- error. Copy permissions and times of directories using :func:`copystat`.
+ The source code for this should be considered an example rather than a tool.
.. function:: rmtree(path[, ignore_errors[, onerror]])
If the destination is on our current filesystem, then simply use rename.
Otherwise, copy src to the dst and then remove src.
- .. versionadded:: 2.3
-
.. exception:: Error
:func:`copytree`, the exception argument is a list of 3-tuples (*srcname*,
*dstname*, *exception*).
- .. versionadded:: 2.3
-
.. _shutil-example:
For example usage, see the implementation of the :func:`test` function.
- .. versionadded:: 2.5
- The ``'Last-Modified'`` header.
-
.. seealso::
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
-.. versionadded:: 2.2
-
The :mod:`SimpleXMLRPCServer` module provides a basic server framework for
XML-RPC servers written in Python. Servers can either be free standing, using
:class:`SimpleXMLRPCServer`, or embedded in a CGI environment, using
:class:`CGIXMLRPCRequestHandler`.
-.. class:: SimpleXMLRPCServer(addr[, requestHandler[, logRequests[, allow_none[, encoding]]]])
+.. class:: SimpleXMLRPCServer(addr[, requestHandler[, logRequests[, allow_none[, encoding[, bind_and_activate]]]]])
Create a new server instance. This class provides methods for registration of
functions that can be called by the XML-RPC protocol. The *requestHandler*
constructor; it defaults to true. Setting it to false allows code to manipulate
the *allow_reuse_address* class variable before the address is bound.
- .. versionchanged:: 2.5
- The *allow_none* and *encoding* parameters were added.
-
- .. versionchanged:: 2.6
- The *bind_and_activate* parameter was added.
-
.. class:: CGIXMLRPCRequestHandler([allow_none[, encoding]])
*allow_none* and *encoding* parameters are passed on to :mod:`xmlrpclib` and
control the XML-RPC responses that will be returned from the server.
- .. versionadded:: 2.3
-
- .. versionchanged:: 2.5
- The *allow_none* and *encoding* parameters were added.
-
.. class:: SimpleXMLRPCRequestHandler()
module's global variables and may allow intruders to execute arbitrary code on
your machine. Only use this option on a secure, closed network.
- .. versionchanged:: 2.3.5, 2.4.1
- *allow_dotted_names* was added to plug a security hole; prior versions are
- insecure.
-
.. method:: SimpleXMLRPCServer.register_introspection_functions()
Registers the XML-RPC introspection functions ``system.listMethods``,
``system.methodHelp`` and ``system.methodSignature``.
- .. versionadded:: 2.3
-
.. method:: SimpleXMLRPCServer.register_multicall_functions()
404 "no such page" HTTP error. If this tuple is empty, all paths will be
considered valid. The default value is ``('/', '/RPC2')``.
- .. versionadded:: 2.5
Example::
once. Blank lines and lines beginning with ``#`` are skipped. Lines starting
with ``import`` (followed by space or tab) are executed.
-.. versionchanged:: 2.6
- A space or tab is now required after the import keyword.
-
.. index::
single: package
triple: path; configuration; file
For normal use, you should only require the initialization/connect,
:meth:`sendmail`, and :meth:`quit` methods. An example is included below.
- .. versionchanged:: 2.6
- *timeout* was added.
-
.. class:: SMTP_SSL([host[, port[, local_hostname[, keyfile[, certfile[, timeout]]]]]])
timeout in seconds for the connection attempt (if not specified, or passed as
None, the global default timeout setting will be used).
- .. versionchanged:: 2.6
- *timeout* was added.
-
.. class:: LMTP([host[, port[, local_hostname]]])
socket, LMTP generally don't support or require any authentication, but your
mileage might vary.
- .. versionadded:: 2.6
A nice selection of exceptions is defined as well:
resolution and/or the host configuration. For deterministic behavior use a
numeric address in *host* portion.
-.. versionadded:: 2.5
- AF_NETLINK sockets are represented as pairs ``pid, groups``.
+AF_NETLINK sockets are represented as pairs ``pid, groups``.
All errors raise exceptions. The normal exceptions for invalid argument types
and out-of-memory conditions can be raised; errors related to socket or address
timeouts enabled via a prior call to :meth:`settimeout`. The accompanying value
is a string whose value is currently always "timed out".
- .. versionadded:: 2.3
-
.. data:: AF_UNIX
AF_INET
This constant contains a boolean value which indicates if IPv6 is supported on
this platform.
- .. versionadded:: 2.3
-
.. function:: create_connection(address[, timeout])
instance (if it is not given or ``None``, the global default timeout setting is
used).
- .. versionadded:: 2.6
-
.. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])
address, as described above. See the source for :mod:`socket` and other
library modules for a typical usage of the function.
- .. versionadded:: 2.2
-
.. function:: getfqdn([name])
case no fully qualified domain name is available, the hostname as returned by
:func:`gethostname` is returned.
- .. versionadded:: 2.0
-
.. function:: gethostbyname(hostname)
or numeric address representation in *host*. Similarly, *port* can contain a
string port name or a numeric port number.
- .. versionadded:: 2.2
-
.. function:: getprotobyname(protocolname)
if defined on the platform; otherwise, the default is :const:`AF_INET`.
Availability: Unix.
- .. versionadded:: 2.4
-
.. function:: fromfd(fd, family, type[, proto])
Availability: Unix (maybe not all platforms).
- .. versionadded:: 2.3
-
.. function:: inet_ntop(address_family, packed_ip)
Availability: Unix (maybe not all platforms).
- .. versionadded:: 2.3
-
.. function:: getdefaulttimeout()
of ``None`` indicates that new socket objects have no timeout. When the socket
module is first imported, the default is ``None``.
- .. versionadded:: 2.3
-
.. function:: setdefaulttimeout(timeout)
``None`` indicates that new socket objects have no timeout. When the socket
module is first imported, the default is ``None``.
- .. versionadded:: 2.3
-
.. data:: SocketType
optional argument *flags*; it defaults to zero. (The format of *address*
depends on the address family --- see above.)
- .. versionadded:: 2.5
-
.. method:: socket.recv_into(buffer[, nbytes[, flags]])
:manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults
to zero.
- .. versionadded:: 2.5
-
.. method:: socket.send(string[, flags])
``s.settimeout(0.0)`` is equivalent to ``s.setblocking(0)``;
``s.settimeout(None)`` is equivalent to ``s.setblocking(1)``.
- .. versionadded:: 2.3
-
.. method:: socket.gettimeout()
``None`` if no timeout is set. This reflects the last call to
:meth:`setblocking` or :meth:`settimeout`.
- .. versionadded:: 2.3
Some notes on socket blocking and timeouts: A socket object can be in one of
three modes: blocking, non-blocking, or timeout. Sockets are always created in
The socket family.
- .. versionadded:: 2.5
-
.. attribute:: socket.type
The socket type.
- .. versionadded:: 2.5
-
.. attribute:: socket.proto
The socket protocol.
- .. versionadded:: 2.5
-
.. _socket-example:
:synopsis: The shadow password database (getspnam() and friends).
-.. versionadded:: 2.5
-
This module provides access to the Unix shadow password database. It is
available on various Unix versions.
.. sectionauthor:: Gerhard Häring <gh@ghaering.de>
-.. versionadded:: 2.5
-
SQLite is a C library that provides a lightweight disk-based database that
doesn't require a separate server process and allows accessing the database
using a nonstandard variant of the SQL query language. Some applications can use
:synopsis: SSL wrapper for socket objects
.. moduleauthor:: Bill Janssen <bill.janssen@gmail.com>
-
-.. versionadded:: 2.6
-
.. sectionauthor:: Bill Janssen <bill.janssen@gmail.com>
Iterator Types
==============
-.. versionadded:: 2.2
-
.. index::
single: iterator protocol
single: protocol; iterator
method which assures consistent linear concatenation performance across versions
and implementations.
- .. versionchanged:: 2.4
- Formerly, string concatenation never occurred in-place.
-
.. _string-methods:
Return centered in a string of length *width*. Padding is done using the
specified *fillchar* (default is a space).
- .. versionchanged:: 2.4
- Support for the *fillchar* argument.
-
.. method:: str.count(sub[, start[, end]])
:ref:`codec-base-classes`. For a list of possible encodings, see section
:ref:`standard-encodings`.
- .. versionadded:: 2.0
-
- .. versionchanged:: 2.3
- Support for ``'xmlcharrefreplace'`` and ``'backslashreplace'`` and other error
- handling schemes added.
-
.. method:: str.endswith(suffix[, start[, end]])
*start*, test beginning at that position. With optional *end*, stop comparing
at that position.
- .. versionchanged:: 2.5
- Accept tuples as *suffix*.
-
.. method:: str.expandtabs([tabsize])
See :ref:`formatstrings` for a description of the various formatting options
that can be specified in format strings.
- .. versionadded:: 3.0
-
.. method:: str.index(sub[, start[, end]])
using the specified *fillchar* (default is a space). The original string is
returned if *width* is less than ``len(s)``.
- .. versionchanged:: 2.4
- Support for the *fillchar* argument.
-
.. method:: str.lower()
>>> 'www.example.com'.lstrip('cmowz.')
'example.com'
- .. versionchanged:: 2.2.2
- Support for the *chars* argument.
-
.. method:: str.partition(sep)
after the separator. If the separator is not found, return a 3-tuple containing
the string itself, followed by two empty strings.
- .. versionadded:: 2.5
-
.. method:: str.replace(old, new[, count])
using the specified *fillchar* (default is a space). The original string is
returned if *width* is less than ``len(s)``.
- .. versionchanged:: 2.4
- Support for the *fillchar* argument.
-
.. method:: str.rpartition(sep)
after the separator. If the separator is not found, return a 3-tuple containing
two empty strings, followed by the string itself.
- .. versionadded:: 2.5
-
.. method:: str.rsplit([sep[, maxsplit]])
separator. Except for splitting from the right, :meth:`rsplit` behaves like
:meth:`split` which is described in detail below.
- .. versionadded:: 2.4
-
.. method:: str.rstrip([chars])
>>> 'mississippi'.rstrip('ipz')
'mississ'
- .. versionchanged:: 2.2.2
- Support for the *chars* argument.
-
.. method:: str.split([sep[, maxsplit]])
test string beginning at that position. With optional *end*, stop comparing
string at that position.
- .. versionchanged:: 2.5
- Accept tuples as *prefix*.
-
.. method:: str.strip([chars])
>>> 'www.example.com'.strip('cmowz.')
'example'
- .. versionchanged:: 2.2.2
- Support for the *chars* argument.
-
.. method:: str.swapcase()
Return the numeric string left filled with zeros in a string of length *width*.
The original string is returned if *width* is less than ``len(s)``.
- .. versionadded:: 2.2.2
-
.. _old-string-formatting:
length is added, as for slice indices. If it is still negative, it is truncated
to zero, as for slice indices.
- .. versionchanged:: 2.3
- Previously, :meth:`index` didn't have arguments for specifying start and stop
- positions.
-
(4)
When a negative index is passed as the first parameter to the :meth:`insert`
method, the sequence length is added, as for slice indices. If it is still
negative, it is truncated to zero, as for slice indices.
- .. versionchanged:: 2.3
- Previously, all negative indices were truncated to zero.
-
(5)
The optional argument *i* defaults to ``-1``, so that by default the last
item is removed and returned.
multiple times for each list element while *key* and *reverse* touch each
element only once.
- .. versionchanged:: 2.3
- Support for ``None`` as an equivalent to omitting *cmp* was added.
-
- .. versionchanged:: 2.4
- Support for *key* and *reverse* was added.
-
Starting with Python 2.3, the :meth:`sort` method is guaranteed to be stable. A
sort is stable if it guarantees not to change the relative order of elements
that compare equal --- this is helpful for sorting in multiple passes (for
(For other containers see the built in :class:`dict`, :class:`list`,
and :class:`tuple` classes, and the :mod:`collections` module.)
-
-.. versionadded:: 2.4
-
Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in
set``. Being an unordered collection, sets do not record element position or
order of insertion. Accordingly, sets do not support indexing, slicing, or
The first example only works for keys that are valid Python
identifiers; the others work with any valid keys.
- .. versionadded:: 2.2
-
- .. versionchanged:: 2.3
- Support for building a dictionary from keyword arguments added.
-
These are the operations that dictionaries support (and therefore, custom mapping
types should support too):
Return the item of *d* with key *key*. Raises a :exc:`KeyError` if *key* is
not in the map.
- .. versionadded:: 2.5
- If a subclass of dict defines a method :meth:`__missing__`, if the key
- *key* is not present, the ``d[key]`` operation calls that method with the
- key *key* as argument. The ``d[key]`` operation then returns or raises
- whatever is returned or raised by the ``__missing__(key)`` call if the key
- is not present. No other operations or methods invoke
- :meth:`__missing__`. If :meth:`__missing__` is not defined,
- :exc:`KeyError` is raised. :meth:`__missing__` must be a method; it
- cannot be an instance variable. For an example, see
- :class:`collections.defaultdict`.
+ If a subclass of dict defines a method :meth:`__missing__`, if the key *key*
+ is not present, the ``d[key]`` operation calls that method with the key *key*
+ as argument. The ``d[key]`` operation then returns or raises whatever is
+ returned or raised by the ``__missing__(key)`` call if the key is not
+ present. No other operations or methods invoke :meth:`__missing__`. If
+ :meth:`__missing__` is not defined, :exc:`KeyError` is raised.
+ :meth:`__missing__` must be a method; it cannot be an instance variable. For
+ an example, see :class:`collections.defaultdict`.
.. describe:: d[key] = value
Return ``True`` if *d* has a key *key*, else ``False``.
- .. versionadded:: 2.2
-
.. describe:: key not in d
Equivalent to ``not key in d``.
- .. versionadded:: 2.2
-
.. method:: dict.clear()
Remove all items from the dictionary.
:func:`fromkeys` is a class method that returns a new dictionary. *value*
defaults to ``None``.
- .. versionadded:: 2.3
-
.. method:: dict.get(key[, default])
Return the value for *key* if *key* is in the dictionary, else *default*. If
Return an iterator over the dictionary's ``(key, value)`` pairs.
See the note for :meth:`dict.items`.
- .. versionadded:: 2.2
-
.. method:: dict.iterkeys()
Return an iterator over the dictionary's keys. See the note for
:meth:`dict.items`.
- .. versionadded:: 2.2
-
.. method:: dict.itervalues()
Return an iterator over the dictionary's values. See the note for
:meth:`dict.items`.
- .. versionadded:: 2.2
-
.. method:: dict.keys()
Return a copy of the dictionary's list of keys. See the note for
*default*. If *default* is not given and *key* is not in the dictionary, a
:exc:`KeyError` is raised.
- .. versionadded:: 2.3
-
.. method:: dict.popitem()
Remove and return an arbitrary ``(key, value)`` pair from the dictionary.
arguments are specified, the dictionary is then is updated with those
key/value pairs: ``d.update(red=1, blue=2)``.
- .. versionchanged:: 2.4
- Allowed the argument to be an iterable of key/value pairs and allowed
- keyword arguments.
-
.. method:: dict.values()
Return a copy of the dictionary's list of values. See the note for
right. However, using :meth:`seek` to reposition the file to an absolute
position will flush the read-ahead buffer.
- .. versionadded:: 2.3
-
.. method:: file.read([size])
Note that not all file objects are seekable.
- .. versionchanged:: 2.6
- Passing float values as offset has been deprecated
-
.. method:: file.tell()
on all file-like objects. It may also be ``None``, in which case the file uses
the system default encoding for converting Unicode strings.
- .. versionadded:: 2.3
-
.. attribute:: file.mode
Context Manager Types
=====================
-.. versionadded:: 2.5
-
.. index::
single: context manager
single: context management protocol
(as in the tuple returned by the :meth:`parse` method.) The default
version understands 'r' (repr) and 's' (str) conversion types.
- .. versionadded:: 3.0
.. _formatstrings:
(The extra space is because we specified a field width of 10, and because left
alignment is the default for strings.)
-.. versionadded:: 3.0
.. _formatspec:
Any other appearance of ``$`` in the string will result in a :exc:`ValueError`
being raised.
-.. versionadded:: 2.4
-
The :mod:`string` module provides a :class:`Template` class that implements
these rules. The methods of :class:`Template` are:
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
-.. versionadded:: 2.3
-
When identifying things (such as host names) in the internet, it is often
necessary to compare such identifications for "equality". Exactly how this
comparison is executed may depend on the application domain, e.g. whether it
bytes into the writable *buffer* starting at *offset*. Note that the offset is
a required argument.
- .. versionadded:: 2.5
-
.. function:: unpack(fmt, string)
of data required by the format (``len(buffer[offset:])`` must be at least
``calcsize(fmt)``).
- .. versionadded:: 2.5
-
.. function:: calcsize(fmt)
C99. If this type is not available, it is simulated using a :ctype:`char`. In
standard mode, it is always represented by one byte.
- .. versionadded:: 2.6
-
(2)
The ``'q'`` and ``'Q'`` conversion codes are available in native mode only if
the platform C compiler supports C :ctype:`long long`, or, on Windows,
:ctype:`__int64`. They are always available in standard modes.
- .. versionadded:: 2.2
-
A format character may be preceded by an integral repeat count. For example,
the format string ``'4h'`` means exactly the same as ``'hhhh'``.
is more efficient than calling the :mod:`struct` functions with the same format
since the format string only needs to be compiled once.
- .. versionadded:: 2.5
Compiled Struct objects support the following methods and attributes:
-
.. method:: Struct.pack(v1, v2, ...)
Identical to the :func:`pack` function, using the compiled format.
.. sectionauthor:: Peter Åstrand <astrand@lysator.liu.se>
-.. versionadded:: 2.4
-
The :mod:`subprocess` module allows you to spawn new processes, connect to their
input/output/error pipes, and obtain their return codes. This module intends to
replace several other, older modules and functions, such as::
check_call(["ls", "-l"])
- .. versionadded:: 2.5
-
Exceptions
^^^^^^^^^^
big-endian (most-significant byte first) platforms, and ``'little'`` on
little-endian (least-significant byte first) platforms.
- .. versionadded:: 2.0
-
.. data:: subversion
exported (or svnversion was not available), it is the revision of
``Include/patchlevel.h`` if the branch is a tag. Otherwise, it is ``None``.
- .. versionadded:: 2.5
-
.. data:: builtin_module_names
This function should be used for internal and specialized purposes only.
- .. versionadded:: 2.5
-
.. data:: dllhandle
Return the interpreter's "check interval"; see :func:`setcheckinterval`.
- .. versionadded:: 2.3
-
.. function:: getdefaultencoding()
Return the name of the current default string encoding used by the Unicode
implementation.
- .. versionadded:: 2.0
-
.. function:: getdlopenflags()
The flag constants are defined in the :mod:`dl` and :mod:`DLFCN` modules.
Availability: Unix.
- .. versionadded:: 2.2
-
.. function:: getfilesystemencoding()
the encoding that applications should use when they explicitly want to convert
Unicode strings to byte strings that are equivalent when used as file names.
- .. versionadded:: 2.3
-
.. function:: getrefcount(object)
Availability: Windows.
- .. versionadded:: 2.3
-
.. data:: hexversion
``version_info`` value may be used for a more human-friendly encoding of the
same information.
- .. versionadded:: 1.5.2
-
.. function:: intern(string)
names used in Python programs are automatically interned, and the dictionaries
used to hold module, class or instance attributes have interned keys.
- .. versionchanged:: 2.3
- Interned strings are not immortal (like they used to be in Python 2.2 and
- before); you must keep a reference to the return value of :func:`intern` around
- to benefit from it.
+ Interned strings are not immortal; you must keep a reference to the return
+ value of :func:`intern` around to benefit from it.
.. data:: last_type
A program is free to modify this list for its own purposes.
- .. versionchanged:: 2.3
- Unicode strings are no longer ignored.
-
.. data:: platform
.. % the \programopt{-S} option is passed to the interpreter, in which
.. % case this function will remain available.
- .. versionadded:: 2.0
-
.. function:: setdlopenflags(n)
:file:`/usr/include/dlfcn.h` using the :program:`h2py` script. Availability:
Unix.
- .. versionadded:: 2.2
-
.. function:: setprofile(profilefunc)
available only if Python was compiled with :option:`--with-tsc`. To understand
the output of this dump, read :file:`Python/ceval.c` in the Python sources.
- .. versionadded:: 2.4
-
.. data:: stdin
stdout
The C API version for this interpreter. Programmers may find this useful when
debugging version conflicts between Python and extension modules.
- .. versionadded:: 2.3
-
.. data:: version_info
``'final'``. The ``version_info`` value corresponding to the Python version 2.0
is ``(2, 0, 0, 'final', 0)``.
- .. versionadded:: 2.0
-
.. data:: warnoptions
:synopsis: Read and write tar-format archive files.
-.. versionadded:: 2.3
-
.. moduleauthor:: Lars Gustäbel <lars@gustaebel.de>
.. sectionauthor:: Lars Gustäbel <lars@gustaebel.de>
* read/write support for the POSIX.1-2001 (pax) format.
- .. versionadded:: 2.6
-
* handles directories, regular files, hardlinks, symbolic links, fifos,
character devices and block devices and is able to acquire and restore file
information like timestamp, access permissions and owner.
Is raised by :meth:`frombuf` if the buffer it gets is invalid.
- .. versionadded:: 2.6
Each of the following constants defines a tar archive format that the
:mod:`tarfile` module is able to create. See section :ref:`tar-formats` for
:const:`USTAR_FORMAT`, :const:`GNU_FORMAT` or :const:`PAX_FORMAT` that are
defined at module level.
- .. versionadded:: 2.6
-
The *tarinfo* argument can be used to replace the default :class:`TarInfo` class
with a different one.
- .. versionadded:: 2.6
-
If *dereference* is ``False``, add symbolic and hard links to the archive. If it
is ``True``, add the content of the target files to the archive. This has no
effect on systems that do not support symbolic links.
to be handled. The default settings will work for most users.
See section :ref:`tar-unicode` for in-depth information.
- .. versionadded:: 2.6
-
The *pax_headers* argument is an optional dictionary of strings which
will be added as a pax global header if *format* is :const:`PAX_FORMAT`.
- .. versionadded:: 2.6
-
.. method:: TarFile.open(...)
that have absolute filenames starting with ``"/"`` or filenames with two
dots ``".."``.
- .. versionadded:: 2.5
-
.. method:: TarFile.extract(member[, path])
Add the file *name* to the archive. *name* may be any type of file (directory,
fifo, symbolic link, etc.). If given, *arcname* specifies an alternative name
for the file in the archive. Directories are added recursively by default. This
- can be avoided by setting *recursive* to :const:`False`. If *exclude* is given
+ can be avoided by setting *recursive* to :const:`False`. If *exclude* is given,
it must be a function that takes one filename argument and returns a boolean
value. Depending on this value the respective file is either excluded
(:const:`True`) or added (:const:`False`).
- .. versionchanged:: 2.6
- Added the *exclude* parameter.
-
.. method:: TarFile.addfile(tarinfo[, fileobj])
attribute to :const:`USTAR_FORMAT`, :const:`False` is equivalent to
:const:`GNU_FORMAT`.
- .. versionchanged:: 2.4
- *posix* defaults to :const:`False`.
+ *posix* defaults to :const:`False`.
.. deprecated:: 2.6
Use the :attr:`format` attribute instead.
A dictionary containing key-value pairs of pax global headers.
- .. versionadded:: 2.6
.. % -----------------
.. % TarInfo Objects
Create and return a :class:`TarInfo` object from string buffer *buf*.
- .. versionadded:: 2.6
- Raises :exc:`HeaderError` if the buffer is invalid..
+ Raises :exc:`HeaderError` if the buffer is invalid..
.. method:: TarInfo.fromtarfile(tarfile)
Read the next member from the :class:`TarFile` object *tarfile* and return it as
a :class:`TarInfo` object.
- .. versionadded:: 2.6
-
.. method:: TarInfo.tobuf([format[, encoding [, errors]]])
Create a string buffer from a :class:`TarInfo` object. For information on the
arguments see the constructor of the :class:`TarFile` class.
- .. versionchanged:: 2.6
- The arguments were added.
A ``TarInfo`` object has the following public data attributes:
A dictionary containing key-value pairs of an associated pax extended header.
- .. versionadded:: 2.6
A :class:`TarInfo` object also provides some convenient query methods:
:exc:`EOFError` when the end of the connection is read, because they can return
an empty string for other reasons. See the individual descriptions below.
- .. versionchanged:: 2.6
- *timeout* was added.
-
.. seealso::
callback should access these data when it was invoked with a ``SE`` command.
This method never blocks.
- .. versionadded:: 2.3
-
.. method:: Telnet.open(host[, port[, timeout]])
Do not try to reopen an already connected instance.
- .. versionchanged:: 2.6
- *timeout* was added.
-
.. method:: Telnet.msg(msg[, *args])
across platforms (it can be so used on Unix; it cannot on Windows NT or later).
If *delete* is true (the default), the file is deleted as soon as it is closed.
- .. versionadded:: 2.3
-
- .. versionadded:: 2.6
- The *delete* parameter.
-
.. function:: SpooledTemporaryFile([max_size=0, [mode='w+b'[, bufsize=-1[, suffix[, prefix[, dir]]]]]])
The resulting file has one additional method, :func:`rollover`, which causes the
file to roll over to an on-disk file regardless of its size.
- .. versionadded:: 2.6
-
.. function:: mkstemp([suffix[, prefix[, dir[, text]]]])
(as would be returned by :func:`os.open`) and the absolute pathname of that
file, in that order.
- .. versionadded:: 2.3
-
.. function:: mkdtemp([suffix[, prefix[, dir]]])
:func:`mkdtemp` returns the absolute pathname of the new directory.
- .. versionadded:: 2.3
-
.. function:: mktemp([suffix[, prefix[, dir]]])
contain the directory component. Using this function is preferred over reading
the *template* variable directly.
- .. versionadded:: 1.5.2
-
warnings.warn("foo")
assert str(w.message) == "foo"
- .. versionadded:: 2.6
-
.. function:: captured_stdout()
print "hello"
assert s.getvalue() == "hello"
- .. versionadded:: 2.6
-
The :mod:`test.test_support` module defines the following classes:
:keyword:`with` statement. Only if all pairs match properly against
attributes on the exception is :exc:`ResourceDenied` raised.
- .. versionadded:: 2.6
-
.. class:: EnvironmentVarGuard()
Class used to temporarily set or unset environment variables. Instances can be
used as a context manager.
- .. versionadded:: 2.6
-
.. method:: EnvironmentVarGuard.set(envvar, value)
.. sectionauthor:: Greg Ward <gward@python.net>
-.. versionadded:: 2.3
-
The :mod:`textwrap` module provides two convenience functions, :func:`wrap` and
:func:`fill`, as well as :class:`TextWrapper`, the class that does all the work,
and a utility function :func:`dedent`. If you're just wrapping or filling one
at the beginning or end of a line is dropped (leading whitespace in the first
line is always preserved, though).
- .. versionadded:: 2.6
- Whitespace was always dropped in earlier versions.
-
.. attribute:: TextWrapper.initial_indent
Raise a :exc:`KeyboardInterrupt` exception in the main thread. A subthread can
use this function to interrupt the main thread.
- .. versionadded:: 2.3
-
.. function:: exit()
the suggested approach in the absence of more specific information).
Availability: Windows, systems with POSIX threads.
- .. versionadded:: 2.5
Lock objects have the following methods:
For more details and extensive examples, see the documentation string of the
:mod:`_threading_local` module.
- .. versionadded:: 2.4
-
.. function:: Lock()
The *func* will be passed to :func:`sys.settrace` for each thread, before its
:meth:`run` method is called.
- .. versionadded:: 2.3
-
.. function:: setprofile(func)
The *func* will be passed to :func:`sys.setprofile` for each thread, before its
:meth:`run` method is called.
- .. versionadded:: 2.3
-
.. function:: stack_size([size])
the suggested approach in the absence of more specific information).
Availability: Windows, systems with POSIX threads.
- .. versionadded:: 2.5
Detailed interfaces for the objects are documented below.
:class:`struct_time`, or having elements of the wrong type, a :exc:`TypeError`
is raised.
- .. versionchanged:: 2.2
- The time value sequence was changed from a tuple to a :class:`struct_time`, with
- the addition of attribute names for the fields.
-
The module defines the following functions and data items:
Unlike the C function of the same name, there is no trailing newline.
- .. versionchanged:: 2.1
- Allowed *t* to be omitted.
-
.. function:: clock()
returned by :func:`time` is used. ``ctime(secs)`` is equivalent to
``asctime(localtime(secs))``. Locale information is not used by :func:`ctime`.
- .. versionchanged:: 2.1
- Allowed *secs* to be omitted.
-
- .. versionchanged:: 2.4
- If *secs* is :const:`None`, the current time is used.
-
.. data:: daylight
:class:`struct_time` object. See :func:`calendar.timegm` for the inverse of this
function.
- .. versionchanged:: 2.1
- Allowed *secs* to be omitted.
-
- .. versionchanged:: 2.4
- If *secs* is :const:`None`, the current time is used.
-
.. function:: localtime([secs])
:const:`None`, the current time as returned by :func:`time` is used. The dst
flag is set to ``1`` when DST applies to the given time.
- .. versionchanged:: 2.1
- Allowed *secs* to be omitted.
-
- .. versionchanged:: 2.4
- If *secs* is :const:`None`, the current time is used.
-
.. function:: mktime(t)
:func:`localtime` is used. *format* must be a string. :exc:`ValueError` is
raised if any field in *t* is outside of the allowed range.
- .. versionchanged:: 2.1
- Allowed *t* to be omitted.
-
- .. versionchanged:: 2.4
- :exc:`ValueError` raised if a field in *t* is out of range.
-
- .. versionchanged:: 2.5
- 0 is now a legal argument for any position in the time tuple; if it is normally
- illegal the value is forced to a correct one..
+ 0 is a legal argument for any position in the time tuple; if it is normally
+ illegal the value is forced to a correct one.
The following directives can be embedded in the *format* string. They are shown
without the optional field width and precision specification, and are replaced
by the indicated characters in the :func:`strftime` result:
- +-----------+--------------------------------+-------+
- | Directive | Meaning | Notes |
- +===========+================================+=======+
- | ``%a`` | Locale's abbreviated weekday | |
- | | name. | |
- +-----------+--------------------------------+-------+
- | ``%A`` | Locale's full weekday name. | |
- +-----------+--------------------------------+-------+
- | ``%b`` | Locale's abbreviated month | |
- | | name. | |
- +-----------+--------------------------------+-------+
- | ``%B`` | Locale's full month name. | |
- +-----------+--------------------------------+-------+
- | ``%c`` | Locale's appropriate date and | |
- | | time representation. | |
- +-----------+--------------------------------+-------+
- | ``%d`` | Day of the month as a decimal | |
- | | number [01,31]. | |
- +-----------+--------------------------------+-------+
- | ``%H`` | Hour (24-hour clock) as a | |
- | | decimal number [00,23]. | |
- +-----------+--------------------------------+-------+
- | ``%I`` | Hour (12-hour clock) as a | |
- | | decimal number [01,12]. | |
- +-----------+--------------------------------+-------+
- | ``%j`` | Day of the year as a decimal | |
- | | number [001,366]. | |
- +-----------+--------------------------------+-------+
- | ``%m`` | Month as a decimal number | |
- | | [01,12]. | |
- +-----------+--------------------------------+-------+
- | ``%M`` | Minute as a decimal number | |
- | | [00,59]. | |
- +-----------+--------------------------------+-------+
- | ``%p`` | Locale's equivalent of either | \(1) |
- | | AM or PM. | |
- +-----------+--------------------------------+-------+
- | ``%S`` | Second as a decimal number | \(2) |
- | | [00,61]. | |
- +-----------+--------------------------------+-------+
- | ``%U`` | Week number of the year | \(3) |
- | | (Sunday as the first day of | |
- | | the week) as a decimal number | |
- | | [00,53]. All days in a new | |
- | | year preceding the first | |
- | | Sunday are considered to be in | |
- | | week 0. | |
- +-----------+--------------------------------+-------+
- | ``%w`` | Weekday as a decimal number | |
- | | [0(Sunday),6]. | |
- +-----------+--------------------------------+-------+
- | ``%W`` | Week number of the year | \(3) |
- | | (Monday as the first day of | |
- | | the week) as a decimal number | |
- | | [00,53]. All days in a new | |
- | | year preceding the first | |
- | | Monday are considered to be in | |
- | | week 0. | |
- +-----------+--------------------------------+-------+
- | ``%x`` | Locale's appropriate date | |
- | | representation. | |
- +-----------+--------------------------------+-------+
- | ``%X`` | Locale's appropriate time | |
- | | representation. | |
- +-----------+--------------------------------+-------+
- | ``%y`` | Year without century as a | |
- | | decimal number [00,99]. | |
- +-----------+--------------------------------+-------+
- | ``%Y`` | Year with century as a decimal | |
- | | number. | |
- +-----------+--------------------------------+-------+
- | ``%Z`` | Time zone name (no characters | |
- | | if no time zone exists). | |
- +-----------+--------------------------------+-------+
- | ``%%`` | A literal ``'%'`` character. | |
- +-----------+--------------------------------+-------+
+ +-----------+------------------------------------------------+-------+
+ | Directive | Meaning | Notes |
+ +===========+================================================+=======+
+ | ``%a`` | Locale's abbreviated weekday name. | |
+ | | | |
+ +-----------+------------------------------------------------+-------+
+ | ``%A`` | Locale's full weekday name. | |
+ +-----------+------------------------------------------------+-------+
+ | ``%b`` | Locale's abbreviated month name. | |
+ | | | |
+ +-----------+------------------------------------------------+-------+
+ | ``%B`` | Locale's full month name. | |
+ +-----------+------------------------------------------------+-------+
+ | ``%c`` | Locale's appropriate date and time | |
+ | | representation. | |
+ +-----------+------------------------------------------------+-------+
+ | ``%d`` | Day of the month as a decimal number [01,31]. | |
+ | | | |
+ +-----------+------------------------------------------------+-------+
+ | ``%H`` | Hour (24-hour clock) as a decimal number | |
+ | | [00,23]. | |
+ +-----------+------------------------------------------------+-------+
+ | ``%I`` | Hour (12-hour clock) as a decimal number | |
+ | | [01,12]. | |
+ +-----------+------------------------------------------------+-------+
+ | ``%j`` | Day of the year as a decimal number [001,366]. | |
+ | | | |
+ +-----------+------------------------------------------------+-------+
+ | ``%m`` | Month as a decimal number [01,12]. | |
+ | | | |
+ +-----------+------------------------------------------------+-------+
+ | ``%M`` | Minute as a decimal number [00,59]. | |
+ | | | |
+ +-----------+------------------------------------------------+-------+
+ | ``%p`` | Locale's equivalent of either AM or PM. | \(1) |
+ | | | |
+ +-----------+------------------------------------------------+-------+
+ | ``%S`` | Second as a decimal number [00,61]. | \(2) |
+ | | | |
+ +-----------+------------------------------------------------+-------+
+ | ``%U`` | Week number of the year (Sunday as the first | \(3) |
+ | | day of the week) as a decimal number [00,53]. | |
+ | | All days in a new year preceding the first | |
+ | | Sunday are considered to be in week 0. | |
+ | | | |
+ | | | |
+ | | | |
+ +-----------+------------------------------------------------+-------+
+ | ``%w`` | Weekday as a decimal number [0(Sunday),6]. | |
+ | | | |
+ +-----------+------------------------------------------------+-------+
+ | ``%W`` | Week number of the year (Monday as the first | \(3) |
+ | | day of the week) as a decimal number [00,53]. | |
+ | | All days in a new year preceding the first | |
+ | | Monday are considered to be in week 0. | |
+ | | | |
+ | | | |
+ | | | |
+ +-----------+------------------------------------------------+-------+
+ | ``%x`` | Locale's appropriate date representation. | |
+ | | | |
+ +-----------+------------------------------------------------+-------+
+ | ``%X`` | Locale's appropriate time representation. | |
+ | | | |
+ +-----------+------------------------------------------------+-------+
+ | ``%y`` | Year without century as a decimal number | |
+ | | [00,99]. | |
+ +-----------+------------------------------------------------+-------+
+ | ``%Y`` | Year with century as a decimal number. | |
+ | | | |
+ +-----------+------------------------------------------------+-------+
+ | ``%Z`` | Time zone name (no characters if no time zone | |
+ | | exists). | |
+ +-----------+------------------------------------------------+-------+
+ | ``%%`` | A literal ``'%'`` character. | |
+ +-----------+------------------------------------------------+-------+
Notes:
The type of the time value sequence returned by :func:`gmtime`,
:func:`localtime`, and :func:`strptime`.
- .. versionadded:: 2.2
-
.. function:: time()
Resets the time conversion rules used by the library routines. The environment
variable :envvar:`TZ` specifies how this is done.
- .. versionadded:: 2.3
-
Availability: Unix.
.. note::
:synopsis: Measure the execution time of small code snippets.
-.. versionadded:: 2.3
-
.. index::
single: Benchmarking
single: Performance
method. The :meth:`repeat` method is a convenience to call :meth:`timeit`
multiple times and return a list of results.
- .. versionchanged:: 2.6
- The *stmt* and *setup* parameters can now also take objects that are callable
- without arguments. This will embed calls to them in a timer function that will
- then be executed by :meth:`timeit`. Note that the timing overhead is a little
- larger in this case because of the extra function calls.
+ The *stmt* and *setup* parameters can also take objects that are callable
+ without arguments. This will embed calls to them in a timer function that
+ will then be executed by :meth:`timeit`. Note that the timing overhead is a
+ little larger in this case because of the extra function calls.
.. method:: Timer.print_exc([file=None])
function and run its :meth:`repeat` method with the given repeat count and
*number* executions.
- .. versionadded:: 2.6
-
.. function:: timeit(stmt[, setup[, timer[, number=1000000]]])
Create a :class:`Timer` instance with the given statement, setup code and timer
function and run its :meth:`timeit` method with *number* executions.
- .. versionadded:: 2.6
-
Command Line Interface
----------------------
.. % FIXME: The following keyword arguments are currently recognized:
- .. versionchanged:: 2.4
- The *useTk* parameter was added.
-
.. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=0)
created by the :func:`Tcl` object can have a Toplevel window created (and the Tk
subsystem initialized) by calling its :meth:`loadtk` method.
- .. versionadded:: 2.4
Other modules that provide Tk support include:
token was found. The line passed is the *logical* line; continuation lines are
included.
- .. versionadded:: 2.2
An older entry point is retained for backward compatibility:
-
.. function:: tokenize(readline[, tokeneater])
The :func:`tokenize` function accepts two parameters: one representing the input
line of input as a string. Alternately, *readline* may be a callable object that
signals completion by raising :exc:`StopIteration`.
- .. versionchanged:: 2.5
- Added :exc:`StopIteration` support.
-
The second parameter, *tokeneater*, must also be a callable object. It is
called once for each token, with five arguments, corresponding to the tuples
generated by :func:`generate_tokens`.
+
All constants from the :mod:`token` module are also exported from
:mod:`tokenize`, as are two additional token type values that might be passed to
the *tokeneater* function by :func:`tokenize`:
-
.. data:: COMMENT
Token value used to indicate a comment.
type and token string as the spacing between tokens (column positions) may
change.
- .. versionadded:: 2.5
Example of a script re-writer that transforms float literals into Decimal
objects::
This is like ``print_exc(limit)`` but returns a string instead of printing to a
file.
- .. versionadded:: 2.4
-
.. function:: print_last([limit[, file]])
``'fastest'`` (no delay), ``'fast'``, (delay 5ms), ``'normal'`` (delay 10ms),
``'slow'`` (delay 15ms), and ``'slowest'`` (delay 20ms).
- .. versionadded:: 2.5
-
.. function:: delay(delay)
Set the speed of the turtle to *delay*, which is given in ms.
- .. versionadded:: 2.5
-
.. function:: forward(distance)
Switch turtle into filling mode; Must eventually be followed by a corresponding
end_fill() call. Otherwise it will be ignored.
- .. versionadded:: 2.5
-
.. function:: end_fill()
End filling mode, and fill the shape; equivalent to ``fill(0)``.
- .. versionadded:: 2.5
-
.. function:: circle(radius[, extent])
The co-ordinates may be specified either as two separate arguments, as a
2-tuple, or as another pen object.
- .. versionadded:: 2.5
-
.. function:: heading()
Return the current orientation of the turtle.
- .. versionadded:: 2.3
-
.. function:: setheading(angle)
Set the orientation of the turtle to *angle*.
- .. versionadded:: 2.3
-
.. function:: position()
Return the current location of the turtle as an ``(x,y)`` pair.
- .. versionadded:: 2.3
-
.. function:: setx(x)
Set the x coordinate of the turtle to *x*.
- .. versionadded:: 2.3
-
.. function:: sety(y)
Set the y coordinate of the turtle to *y*.
- .. versionadded:: 2.3
-
.. function:: window_width()
Return the width of the canvas window.
- .. versionadded:: 2.3
-
.. function:: window_height()
Return the height of the canvas window.
- .. versionadded:: 2.3
This module also does ``from math import *``, so see the documentation for the
:mod:`math` module for additional constants and functions useful for turtle
The type of the :class:`bool` values ``True`` and ``False``; alias of the
built-in :class:`bool`.
- .. versionadded:: 2.3
-
.. data:: IntType
The type of generator-iterator objects, produced by calling a generator
function.
- .. versionadded:: 2.2
-
.. data:: CodeType
defined in implementations of Python that do not have such extension types, so
for portable code use ``hasattr(types, 'GetSetDescriptorType')``.
- .. versionadded:: 2.5
-
.. data:: MemberDescriptorType
Python that do not have such extension types, so for portable code use
``hasattr(types, 'MemberDescriptorType')``.
- .. versionadded:: 2.5
-
.. data:: StringTypes
sequence of the two string types constructed elsewhere since it only contains
``UnicodeType`` if it has been built in the running version of Python. For
example: ``isinstance(s, types.StringTypes)``.
-
- .. versionadded:: 2.2
Returns the east asian width assigned to the Unicode character *unichr* as
string.
- .. versionadded:: 2.4
-
.. function:: mirrored(unichr)
a human reader, if one has combining characters and the other
doesn't, they may not compare equal.
- .. versionadded:: 2.3
In addition, the module exposes the following constant:
-
.. data:: unidata_version
The version of the Unicode database used in this module.
- .. versionadded:: 2.3
-
.. data:: ucd_3_2_0
Unicode database version 3.2 instead, for applications that require this
specific version of the Unicode database (such as IDNA).
- .. versionadded:: 2.5
-
Examples::
>>> unicodedata.lookup('LEFT CURLY BRACKET')
.. sectionauthor:: Raymond Hettinger <python@rcn.com>
-.. versionadded:: 2.1
-
The Python unit testing framework, sometimes referred to as "PyUnit," is a
Python language version of JUnit, by Kent Beck and Erich Gamma. JUnit is, in
turn, a Java version of Kent's Smalltalk testing framework. Each is the de
automatically build :class:`unittest.TestSuite` instances from the existing
:mod:`doctest`\ -based tests.
-.. versionadded:: 2.3
-
.. _testcase-objects:
formatted tracebacks. Each tuple represents a test which raised an unexpected
exception.
- .. versionchanged:: 2.2
- Contains formatted tracebacks instead of :func:`sys.exc_info` results.
-
.. attribute:: TestResult.failures
explicitly signalled using the :meth:`TestCase.fail\*` or
:meth:`TestCase.assert\*` methods.
- .. versionchanged:: 2.2
- Contains formatted tracebacks instead of :func:`sys.exc_info` results.
-
.. attribute:: TestResult.testsRun
Proxies which require authentication for use are not currently supported; this
is considered an implementation limitation.
- .. versionchanged:: 2.3
- Added the *proxies* support.
-
.. function:: urlretrieve(url[, filename[, reporthook[, data]]])
:mimetype:`application/x-www-form-urlencoded` format; see the :func:`urlencode`
function below.
- .. versionchanged:: 2.5
- :func:`urlretrieve` will raise :exc:`ContentTooShortError` when it detects that
- the amount of data available was less than the expected amount (which is the
- size reported by a *Content-Length* header). This can occur, for example, when
- the download is interrupted.
+ :func:`urlretrieve` will raise :exc:`ContentTooShortError` when it detects that
+ the amount of data available was less than the expected amount (which is the
+ size reported by a *Content-Length* header). This can occur, for example, when
+ the download is interrupted.
- The *Content-Length* is treated as a lower bound: if there's more data to read,
- urlretrieve reads more data, but if less data is available, it raises the
- exception.
+ The *Content-Length* is treated as a lower bound: if there's more data to read,
+ urlretrieve reads more data, but if less data is available, it raises the
+ exception.
- You can still retrieve the downloaded data in this case, it is stored in the
- :attr:`content` attribute of the exception instance.
+ You can still retrieve the downloaded data in this case, it is stored in the
+ :attr:`content` attribute of the exception instance.
- If no *Content-Length* header was supplied, urlretrieve can not check the size
- of the data it has downloaded, and just returns it. In this case you just have
- to assume that the download was successful.
+ If no *Content-Length* header was supplied, urlretrieve can not check the size
+ of the data it has downloaded, and just returns it. In this case you just have
+ to assume that the download was successful.
.. data:: _urlopener
*Content-Length* header). The :attr:`content` attribute stores the downloaded
(and supposedly truncated) data.
- .. versionadded:: 2.5
-
Restrictions:
.. index::
default installed global :class:`OpenerDirector` uses :class:`UnknownHandler` to
ensure this never happens).
- .. versionchanged:: 2.6
- *timeout* was added.
-
.. function:: install_opener(opener)
Add a header that will not be added to a redirected request.
- .. versionadded:: 2.4
-
.. method:: Request.has_header(header)
Return whether the instance has the named header (checks both regular and
unredirected).
- .. versionadded:: 2.4
-
.. method:: Request.get_full_url()
specified, or passed as None, the global default timeout setting will be used;
this actually only work for HTTP, HTTPS, FTP and FTPS connections).
- .. versionchanged:: 2.6
- *timeout* was added.
-
.. method:: OpenerDirector.error(proto[, arg[, ...]])
HTTPCookieProcessor Objects
---------------------------
-.. versionadded:: 2.4
-
:class:`HTTPCookieProcessor` instances have one attribute:
-
.. attribute:: HTTPCookieProcessor.cookiejar
The :class:`cookielib.CookieJar` in which cookies are stored.
HTTPErrorProcessor Objects
--------------------------
-.. versionadded:: 2.4
-
-
.. method:: HTTPErrorProcessor.unknown_open()
Process HTTP error responses.
``rsync``, ``rtsp``, ``rtspu``, ``sftp``, ``shttp``, ``sip``, ``sips``,
``snews``, ``svn``, ``svn+ssh``, ``telnet``, ``wais``.
-.. versionadded:: 2.5
- Support for the ``sftp`` and ``sips`` schemes.
-
The :mod:`urlparse` module defines the following functions:
See section :ref:`urlparse-result-object` for more information on the result
object.
- .. versionchanged:: 2.5
- Added attributes to return value.
-
.. function:: urlunparse(parts)
See section :ref:`urlparse-result-object` for more information on the result
object.
- .. versionadded:: 2.2
-
- .. versionchanged:: 2.5
- Added attributes to return value.
-
.. function:: urlunsplit(parts)
originally had unnecessary delimiters (for example, a ? with an empty query; the
RFC states that these are equivalent).
- .. versionadded:: 2.2
-
.. function:: urljoin(base, url[, allow_fragments])
>>> r2.geturl()
'http://www.Python.org/doc/'
- .. versionadded:: 2.5
The following classes provide the implementations of the parse results::
consult the sources for information about the methods which need to be provided
in that case.
-.. versionchanged:: 2.0
- Python versions 1.5.2 and 1.6 also required that the constructor be callable
- with no parameters, and offer a mutable :attr:`data` attribute. Earlier
- versions of Python did not attempt to create instances of the derived class.
-
:mod:`UserString` --- Class wrapper for string objects
======================================================
.. sectionauthor:: George Yoshida <quiver@users.sourceforge.net>
-.. versionadded:: 2.5
-
This module provides immutable :class:`UUID` objects (the :class:`UUID` class)
and the functions :func:`uuid1`, :func:`uuid3`, :func:`uuid4`, :func:`uuid5` for
generating version 1, 3, 4, and 5 UUIDs as specified in :rfc:`4122`.
:synopsis: Issue warning messages and control their disposition.
-.. versionadded:: 2.1
-
Warning messages are typically issued in situations where it is useful to alert
the user of some condition in a program, where that condition (normally) doesn't
warrant raising an exception and terminating the program. For example, one
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
-.. versionadded:: 2.1
-
The :mod:`weakref` module allows the Python programmer to create :dfn:`weak
references` to objects.
objects from the :mod:`bsddb` module, sockets, arrays, deques, and regular
expression pattern objects.
-.. versionchanged:: 2.4
- Added support for files, sockets, arrays, and patterns.
-
Several builtin types such as :class:`list` and :class:`dict` do not directly
support weak references but can add support through subclassing::
referents (regardless of the *callback*). If either referent has been deleted,
the references are equal only if the reference objects are the same object.
- .. versionchanged:: 2.4
- This is now a subclassable type rather than a factory function; it derives from
- :class:`object`.
+ This is a subclassable type rather than a factory function.
.. function:: proxy(object[, callback])
Return an iterator that yields the weak references to the keys.
- .. versionadded:: 2.5
-
.. method:: WeakKeyDictionary.keyrefs()
Return a list of weak references to the keys.
- .. versionadded:: 2.5
-
.. class:: WeakValueDictionary([dict])
Return an iterator that yields the weak references to the values.
- .. versionadded:: 2.5
-
.. method:: WeakValueDictionary.valuerefs()
Return a list of weak references to the values.
- .. versionadded:: 2.5
-
.. data:: ReferenceType
under many window managers this will occur regardless of the setting of this
variable).
- .. versionchanged:: 2.5
- *new* can now be 2.
-
.. function:: open_new(url)
Open *url* in a new page ("tab") of the default browser, if possible, otherwise
equivalent to :func:`open_new`.
- .. versionadded:: 2.5
-
.. function:: get([name])
Open *url* in a new page ("tab") of the browser handled by this controller, if
possible, otherwise equivalent to :func:`open_new`.
-
- .. versionadded:: 2.5
-
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
-.. versionadded:: 1.5.2
-
The :mod:`winsound` module provides access to the basic sound-playing machinery
provided by Windows platforms. It includes functions and several constants.
port manipulation (added in version 2.1). It's unknown whether that will work
on all systems.
- .. versionadded:: 1.6
-
.. function:: PlaySound(sound, flags)
described below. The value ``-1`` produces a "simple beep"; this is the final
fallback if a sound cannot be played otherwise.
- .. versionadded:: 2.3
-
.. data:: SND_FILENAME
.. sectionauthor:: Phillip J. Eby <pje@telecommunity.com>
-.. versionadded:: 2.5
-
The Web Server Gateway Interface (WSGI) is a standard interface between web
server software and web applications written in Python. Having a standard
interface makes it easy to use an application that supports WSGI with a number
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
-.. versionadded:: 2.0
-
:mod:`xml.dom.minidom` is a light-weight implementation of the Document Object
Model interface. It is intended to be simpler than the full DOM and also
significantly smaller.
indentation to use for subnodes of the current one. The *newl* parameter
specifies the string to use to terminate newlines.
- .. versionchanged:: 2.1
- The optional keyword parameters *indent*, *addindent*, and *newl* were added to
- support pretty output.
-
- .. versionchanged:: 2.3
- For the :class:`Document` node, an additional keyword argument *encoding* can be
- used to specify the encoding field of the XML header.
+ For the :class:`Document` node, an additional keyword argument *encoding* can be
+ used to specify the encoding field of the XML header.
.. method:: Node.toxml([encoding])
avoid :exc:`UnicodeError` exceptions in case of unrepresentable text data, the
encoding argument should be specified as "utf-8".
- .. versionchanged:: 2.3
- the *encoding* argument was introduced.
-
-.. method:: Node.toprettyxml([indent[, newl]])
+.. method:: Node.toprettyxml([indent[, newl[, encoding]]])
Return a pretty-printed version of the document. *indent* specifies the
indentation string and defaults to a tabulator; *newl* specifies the string
emitted at the end of each line and defaults to ``\n``.
- .. versionadded:: 2.1
+ There's also an *encoding* argument; see :meth:`toxml`.
- .. versionchanged:: 2.3
- the 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`
.. moduleauthor:: Paul Prescod <paul@prescod.net>
-.. versionadded:: 2.0
-
:mod:`xml.dom.pulldom` allows building only selected portions of a Document
Object Model representation of a document from SAX events.
Default value for the *bufsize* parameter to :func:`parse`.
- .. versionchanged:: 2.1
- The value of this variable can be changed before calling :func:`parse` and the
- new value will take effect.
+ The value of this variable can be changed before calling :func:`parse` and
+ the new value will take effect.
.. _domeventstream-objects:
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
-.. versionadded:: 2.0
-
The Document Object Model, or "DOM," is a cross-language API from the World Wide
Web Consortium (W3C) for accessing and modifying XML documents. A DOM
implementation presents an XML document as a tree structure, or allows client
DOM. This is typically found as the :attr:`namespaceURI` of a node, or used as
the *namespaceURI* parameter to a namespaces-specific method.
- .. versionadded:: 2.2
-
.. data:: XML_NAMESPACE
The namespace URI associated with the reserved prefix ``xml``, as defined by
`Namespaces in XML <http://www.w3.org/TR/REC-xml-names/>`_ (section 4).
- .. versionadded:: 2.2
-
.. data:: XMLNS_NAMESPACE
Model (DOM) Level 2 Core Specification
<http://www.w3.org/TR/DOM-Level-2-Core/core.html>`_ (section 1.1.8).
- .. versionadded:: 2.2
-
.. data:: XHTML_NAMESPACE
The URI of the XHTML namespace as defined by `XHTML 1.0: The Extensible
HyperText Markup Language <http://www.w3.org/TR/xhtml1/>`_ (section 3.1.1).
- .. versionadded:: 2.2
In addition, :mod:`xml.dom` contains a base :class:`Node` class and the DOM
exception classes. The :class:`Node` class provided by this module does not
:class:`Text` instances. This simplifies processing text from a DOM tree for
many applications.
- .. versionadded:: 2.1
-
.. method:: Node.cloneNode(deep)
Exceptions
^^^^^^^^^^
-.. versionadded:: 2.1
-
The DOM Level 2 recommendation defines a single exception, :exc:`DOMException`,
and a number of constants that allow applications to determine what sort of
error occurred. :exc:`DOMException` instances carry a :attr:`code` attribute
.. moduleauthor:: Fredrik Lundh <fredrik@pythonware.com>
-.. versionadded:: 2.5
-
The Element type is a flexible container object, designed to store hierarchical
data structures in memory. The type can be described as a cross between a list
and a dictionary.
.. moduleauthor:: Fredrik Lundh <fredrik@pythonware.com>
-.. versionadded:: 2.5
-
The ElementTree package is a simple, efficient, and quite popular library for
XML manipulation in Python. The :mod:`xml.etree` package contains the most
common components from the ElementTree API library. In the current release,
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
-.. versionadded:: 2.0
-
The SAX API defines four kinds of handlers: content handlers, DTD handlers,
error handlers, and entity resolvers. Applications normally only need to
implement those interfaces whose events they are interested in; they can
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
-.. versionadded:: 2.0
-
SAX parsers implement the :class:`XMLReader` interface. They are implemented in
a Python module, which must provide a function :func:`create_parser`. This
function is invoked by :func:`xml.sax.make_parser` with no arguments to create
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
-.. versionadded:: 2.0
-
The :mod:`xml.sax` package provides a number of modules which implement the
Simple API for XML (SAX) interface for Python. The package itself provides the
SAX exceptions and the convenience functions which will be most used by users of
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
-.. versionadded:: 2.0
-
The module :mod:`xml.sax.saxutils` contains a number of classes and functions
that are commonly useful when creating SAX applications, either in direct use,
or as base classes.
*entities* parameter. The keys and values must all be strings; each key will be
replaced with its corresponding value.
- .. versionadded:: 2.3
-
.. function:: quoteattr(data[, entities])
This function is useful when generating attribute values for HTML or any SGML
using the reference concrete syntax.
- .. versionadded:: 2.2
-
.. class:: XMLGenerator([out[, encoding]])
.. % Not everything is documented yet. It might be good to describe
.. % Marshaller, Unmarshaller, getparser, dumps, loads, and Transport.
-.. versionadded:: 2.2
-
XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP as a
transport. With it, a client can call methods with parameters on a remote
server (the server is named by a URI) and get back structured data. This module
:class:`Server` is retained as an alias for :class:`ServerProxy` for backwards
compatibility. New code should use :class:`ServerProxy`.
- .. versionchanged:: 2.5
- The *use_datetime* flag was added.
-
- .. versionchanged:: 2.6
- Instances of new-style classes can be passed in if they have an *__dict__*
- attribute and don't have a base class that is marshalled in a special way.
-
.. seealso::
MultiCall Objects
-----------------
-.. versionadded:: 2.4
-
In http://www.xmlrpc.com/discuss/msgReader%241208, an approach is presented to
encapsulate multiple calls to a remote server into a single request.
objects, they are converted to :class:`DateTime` objects internally, so only
:class:`datetime.datetime` objects will be returned.
- .. versionchanged:: 2.5
- The *use_datetime* flag was added.
-
.. _xmlrpc-client-example:
.. % LaTeX markup by Fred L. Drake, Jr. <fdrake@acm.org>
-.. versionadded:: 1.6
-
The ZIP file format is a common archive and compression standard. This module
provides tools to create, read, write, append, and list a ZIP file. Any
advanced use of this module will require an understanding of the format, as
because the default :program:`zip` and :program:`unzip` commands on Unix (the
InfoZIP utilities) don't support these extensions.
- .. versionchanged:: 2.6
- If the file does not exist, it is created if the mode is 'a'.
-
.. method:: ZipFile.close()
create a new file object that will be held by the ZipExtFile, allowing it to
operate independently of the ZipFile.
- .. versionadded:: 2.6
-
.. method:: ZipFile.printdir()
Set *pwd* as default password to extract encrypted files.
- .. versionadded:: 2.6
-
.. method:: ZipFile.read(name[, pwd])
will override the default password set with :meth:`setpassword`. Calling
:meth:`read` on a closed ZipFile will raise a :exc:`RuntimeError`.
- .. versionchanged:: 2.6
- *pwd* was added.
-
.. method:: ZipFile.testzip()
.. moduleauthor:: Just van Rossum <just@letterror.com>
-.. versionadded:: 2.3
-
This module adds the ability to import Python modules (:file:`\*.py`,
:file:`\*.py[co]`) and packages from ZIP-format archives. It is usually not
needed to use the :mod:`zipimport` module explicitly; it is automatically used
Returns a copy of the compression object. This can be used to efficiently
compress a set of data that share a common initial prefix.
- .. versionadded:: 2.5
Decompression objects support the following methods, and two attributes:
of the decompressor midway through the data stream in order to speed up random
seeks into the stream at a future point.
- .. versionadded:: 2.5
-
.. seealso::
projects / thirdparty / Python / cpython.git / commitdiff
