the conversion has failed. When the conversion fails, the *converter* function
should raise an exception and leave the content of *address* unmodified.
- If the *converter* returns Py_CLEANUP_SUPPORTED, it may get called a second time
- if the argument parsing eventually fails, giving the converter a chance to release
- any memory that it had already allocated. In this second call, the *object* parameter
- will be NULL; *address* will have the same value as in the original call.
+ If the *converter* returns ``Py_CLEANUP_SUPPORTED``, it may get called a
+ second time if the argument parsing eventually fails, giving the converter a
+ chance to release any memory that it had already allocated. In this second
+ call, the *object* parameter will be NULL; *address* will have the same value
+ as in the original call.
.. versionchanged:: 3.1
- Py_CLEANUP_SUPPORTED was added.
+ ``Py_CLEANUP_SUPPORTED`` was added.
``(items)`` (:class:`tuple`) [*matching-items*]
The object must be a Python sequence whose length is the number of format units
cannot be represented as a :ctype:`long long`, an
:exc:`OverflowError` is raised and ``-1`` is returned.
+
.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
.. index::
returned.
.. versionchanged:: 3.1
- A negative *pylong* now raises :exc:`OverflowError`, not
- :exc:`TypeError`.
+ A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`.
+
.. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
.. versionadded:: 3.2
+
.. _processcontrol:
Process Control
when :const:`HAVE_LONG_LONG` is defined.
.. versionchanged:: 3.2
- Support for `"%lld"` and `"%llu"` added.
-
+ Support for ``"%lld"`` and ``"%llu"`` added.
.. cfunction:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)
.. versionadded:: 3.1
+
To decode file names during argument parsing, the ``"O&"`` converter should be
used, passsing :func:`PyUnicode_FSDecoder` as the conversion function:
.. versionadded:: 3.2
+
.. cfunction:: PyObject* PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)
Decode a null-terminated string using :cdata:`Py_FileSystemDefaultEncoding`
:option:`-o` is a shortcut for :option:`--manifest-only`.
.. versionchanged:: 3.1
- An existing generated :file:`MANIFEST` will be regenerated without
- :command:`sdist` comparing its modification time to the one of
- :file:`MANIFEST.in` or :file:`setup.py`.
+ An existing generated :file:`MANIFEST` will be regenerated without
+ :command:`sdist` comparing its modification time to the one of
+ :file:`MANIFEST.in` or :file:`setup.py`.
*header* is present and true, underscores will be decoded as spaces.
.. versionchanged:: 3.2
- accept only bytestring or bytearray object as input.
+ Accept only bytestring or bytearray objects as input.
.. function:: b2a_qp(data, quotetabs=False, istext=True, header=False)
in which case the :exc:`Incomplete` exception is raised.
.. versionchanged:: 3.2
- accept only bytestring or bytearray object as input.
+ Accept only bytestring or bytearray objects as input.
.. function:: rlecode_hqx(data)
:exc:`TypeError` is raised.
.. versionchanged:: 3.2
- accept only bytestring or bytearray object as input.
+ Accept only bytestring or bytearray objects as input.
.. exception:: Error
.. versionadded:: 3.2
+
.. method:: extend(iterable)
Extend the right side of the deque by appending elements from the iterable
Removed the first occurrence of *value*. If not found, raises a
:exc:`ValueError`.
+
.. method:: reverse()
Reverse the elements of the deque in-place and then return ``None``.
.. versionadded:: 3.2
+
.. method:: rotate(n)
Rotate the deque *n* steps to the right. If *n* is negative, rotate to
lightweight and require no more memory than regular tuples.
.. versionchanged:: 3.1
- added support for *rename*.
+ Added support for *rename*.
Example:
.. versionadded:: 3.2
+
.. method:: RawConfigParser.read_dict(dictionary, source='<dict>')
Load configuration from a dictionary. Keys are section names, values are
.. versionadded:: 3.2
+
.. method:: RawConfigParser.get(section, option)
Get an *option* value for the named *section*.
Note that when reading configuration files, whitespace around the
option names are stripped before :meth:`optionxform` is called.
+
.. method:: RawConfigParser.readfp(fp, filename=None)
.. deprecated:: 3.2
Please use :meth:`read_file` instead.
+
.. _configparser-objects:
ConfigParser Objects
certain additions and subtractions with :class:`date` and :class:`datetime`
objects (see below).
-.. versionadded:: 3.2
- Floor division and true division of a :class:`timedelta` object by
- another :class:`timedelta` object are now supported, as are
- remainder operations and the :func:`divmod` function. True
- division and multiplication of a :class:`timedelta` object by
- a :class:`float` object are now supported.
+.. versionchanged:: 3.2
+ Floor division and true division of a :class:`timedelta` object by another
+ :class:`timedelta` object are now supported, as are remainder operations and
+ the :func:`divmod` function. True division and multiplication of a
+ :class:`timedelta` object by a :class:`float` object are now supported.
Comparisons of :class:`timedelta` objects are supported with the
For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``,
``%z`` is replaced with the string ``'-0330'``.
-.. versionadded:: 3.2
-
- When the ``%z`` directive is provided to the :meth:`strptime`
- method, an aware :class:`datetime` object will be produced. The
- ``tzinfo`` of the result will be set to a :class:`timezone`
- instance.
+.. versionchanged:: 3.2
+ When the ``%z`` directive is provided to the :meth:`strptime` method, an
+ aware :class:`datetime` object will be produced. The ``tzinfo`` of the
+ result will be set to a :class:`timezone` instance.
Once constructed, :class:`Decimal` objects are immutable.
.. versionchanged:: 3.2
- The argument to the constructor is now permitted to be a :class:`float` instance.
+ The argument to the constructor is now permitted to be a :class:`float`
+ instance.
Decimal floating point objects share many properties with the other built-in
numeric types such as :class:`float` and :class:`int`. All of the usual math
when doing equality comparisons between numbers of different types.
.. versionchanged:: 3.2
- Mixed-type comparisons between :class:`Decimal` instances and
- other numeric types are now fully supported.
+ Mixed-type comparisons between :class:`Decimal` instances and other
+ numeric types are now fully supported.
In addition to the standard numeric properties, decimal floating point
objects also have a number of specialized methods:
value for subnormal results. When underflow occurs, the exponent is set
to :const:`Etiny`.
-
.. method:: Etop()
Returns a value equal to ``Emax - prec + 1``.
.. function:: code_info(x=None)
- Return a formatted multi-line string with detailed code object
- information for the supplied function, method, source code string
- or code object.
+ Return a formatted multi-line string with detailed code object information
+ for the supplied function, method, source code string or code object.
- Note that the exact contents of code info strings are highly
- implementation dependent and they may change arbitrarily across
- Python VMs or Python releases.
+ Note that the exact contents of code info strings are highly implementation
+ dependent and they may change arbitrarily across Python VMs or Python
+ releases.
.. versionadded:: 3.2
+
.. function:: dis(x=None)
- Disassemble the *x* object. *x* can denote either a module, a
- class, a method, a function, a code object, a string of source code or a
- byte sequence of raw bytecode. For a module, it disassembles all
- functions. For a class, it disassembles all methods. For a code object
- or sequence of raw bytecode, it prints one line per bytecode instruction.
- Strings are first compiled to code objects with the :func:`compile`
- built-in function before being disassembled. If no object is provided,
- this function disassembles the last traceback.
+ Disassemble the *x* object. *x* can denote either a module, a class, a
+ method, a function, a code object, a string of source code or a byte sequence
+ of raw bytecode. For a module, it disassembles all functions. For a class,
+ it disassembles all methods. For a code object or sequence of raw bytecode,
+ it prints one line per bytecode instruction. Strings are first compiled to
+ code objects with the :func:`compile` built-in function before being
+ disassembled. If no object is provided, this function disassembles the last
+ traceback.
.. function:: distb(tb=None)
changed in Python 2.4 to say "does not" instead of "doesn't".
.. versionchanged:: 3.2
- :const:`IGNORE_EXCEPTION_DETAIL` now also ignores any information
- relating to the module containing the exception under test
+ :const:`IGNORE_EXCEPTION_DETAIL` now also ignores any information relating
+ to the module containing the exception under test.
.. data:: SKIP
character. This is to facilitate detection of incomplete and complete
statements in the :mod:`code` module.
-
.. versionchanged:: 3.2
Allowed use of Windows and Mac newlines. Also input in ``'exec'`` mode
does not have to end in a newline anymore.
[]
.. versionchanged:: 3.2
- Testing integers for membership takes constant time instead of
- iterating through all items.
+ Testing integers for membership takes constant time instead of iterating
+ through all items.
.. function:: repr(object)
.. versionadded:: 3.2
+
.. decorator:: lru_cache(maxsize)
Decorator to wrap a function with a memoizing callable that saves up to the
.. versionadded:: 3.2
+
.. decorator:: total_ordering
Given a class defining one or more rich comparison ordering methods, this
.. versionadded:: 3.2
+
.. function:: partial(func, *args, **keywords)
Return a new :class:`partial` object which when called will behave like *func*
.. versionchanged:: 3.2
If this list is non-empty at interpreter shutdown, a warning message
- gets printed:
+ gets printed.
::
- gc: 2 uncollectable objects at shutdown:
- Use gc.set_debug(gc.DEBUG_UNCOLLECTABLE) to list them.
+ gc: 2 uncollectable objects at shutdown:
+ Use gc.set_debug(gc.DEBUG_UNCOLLECTABLE) to list them.
The following constants are provided for use with :func:`set_debug`:
equivalent to ``m.update(a+b)``.
.. versionchanged:: 3.1
-
- The Python GIL is released to allow other threads to run while
- hash updates on data larger than 2048 bytes is taking place when
- using hash algorithms supplied by OpenSSL.
+ The Python GIL is released to allow other threads to run while hash
+ updates on data larger than 2048 bytes is taking place when using hash
+ algorithms supplied by OpenSSL.
.. method:: hash.digest()
.. versionadded:: 3.1
+
.. method:: HTTPConnection.set_tunnel(host, port=None, headers=None)
Set the host and the port for HTTP Connect Tunnelling. Normally used when it
.. versionadded:: 3.2
+
.. method:: HTTPConnection.connect()
Connect to the server specified when the object was created.
Return the new absolute position.
.. versionadded:: 3.1
- The ``SEEK_*`` constants
+ The ``SEEK_*`` constants.
.. method:: seekable()
.. versionadded:: 3.1
+
.. function:: compress(data, selectors)
Make an iterator that filters elements from *data* returning only those that
for i in count())``.
.. versionchanged:: 3.1
- added *step* argument and allowed non-integer arguments.
+ Added *step* argument and allowed non-integer arguments.
.. function:: cycle(iterable)
class defined in package `mypackage` and module `mymodule`, where `mypackage`
is available on the Python import path).
-.. versionchanged:: 3.2
-
In Python 3.2, a new means of configuring logging has been introduced, using
dictionaries to hold configuration information. This provides a superset of the
functionality of the config-file-based approach outlined above, and is the
just "foo".
.. versionadded:: 3.1
-
-The :class:`NullHandler` class was not present in previous versions, but is now
-included, so that it need not be defined in library code.
+ The :class:`NullHandler` class was not present in previous versions, but is
+ now included, so that it need not be defined in library code.
.. versionadded:: 3.2
+
.. method:: Logger.debug(msg, *args, **kwargs)
Logs a message with level :const:`DEBUG` on this logger. The *msg* is the
you can use the two types of instances interchangeably.
.. versionchanged:: 3.2
-
-The :meth:`isEnabledFor` method was added to :class:`LoggerAdapter`. This method
-delegates to the underlying logger.
+ The :meth:`isEnabledFor` method was added to :class:`LoggerAdapter`. This
+ method delegates to the underlying logger.
Thread Safety
File Names, Command Line Arguments, and Environment Variables
-------------------------------------------------------------
-In Python, file names, command line arguments, and environment
-variables are represented using the string type. On some systems,
-decoding these strings to and from bytes is necessary before passing
-them to the operating system. Python uses the file system encoding to
-perform this conversion (see :func:`sys.getfilesystemencoding`).
+In Python, file names, command line arguments, and environment variables are
+represented using the string type. On some systems, decoding these strings to
+and from bytes is necessary before passing them to the operating system. Python
+uses the file system encoding to perform this conversion (see
+:func:`sys.getfilesystemencoding`).
.. versionchanged:: 3.1
- On some systems, conversion using the file system encoding may
- fail. In this case, Python uses the ``surrogateescape`` encoding
- error handler, which means that undecodable bytes are replaced by a
- Unicode character U+DCxx on decoding, and these are again
- translated to the original byte on encoding.
+ On some systems, conversion using the file system encoding may fail. In this
+ case, Python uses the ``surrogateescape`` encoding error handler, which means
+ that undecodable bytes are replaced by a Unicode character U+DCxx on
+ decoding, and these are again translated to the original byte on encoding.
-The file system encoding must guarantee to successfully decode all
-bytes below 128. If the file system encoding fails to provide this
-guarantee, API functions may raise UnicodeErrors.
+The file system encoding must guarantee to successfully decode all bytes
+below 128. If the file system encoding fails to provide this guarantee, API
+functions may raise UnicodeErrors.
.. _os-procinfo:
will be set to *sig*. The Windows version of :func:`kill` additionally takes
process handles to be killed.
- .. versionadded:: 3.2 Windows support
+ .. versionadded:: 3.2
+ Windows support.
.. function:: killpg(pgid, sig)
a short description. The value of *annotate* is used as a hint for
the column where annotation should start.
- .. versionadded:: 3.2 the *annotate* argument.
+ .. versionadded:: 3.2
+ The *annotate* argument.
.. function:: genops(pickle)
.. versionchanged:: 3.1
- Added ability to execute packages by looking for a ``__main__``
- submodule
+ Added ability to execute packages by looking for a ``__main__`` submodule.
.. function:: run_path(file_path, init_globals=None, run_name=None)
.. attribute:: Connection.in_transaction
- .. versionadded:: 3.2
-
:const:`True` if a transaction is active (there are uncommitted changes),
:const:`False` otherwise. Read-only attribute.
+ .. versionadded:: 3.2
.. method:: Connection.cursor([cursorClass])
supplied, this must be a custom cursor class that extends
:class:`sqlite3.Cursor`.
-
.. method:: Connection.commit()
This method commits the current transaction. If you don't call this method,
.. method:: Connection.enable_load_extension(enabled)
- .. versionadded:: 3.2
-
This routine allows/disallows the SQLite engine to load SQLite extensions
from shared libraries. SQLite extensions can define new functions,
aggregates or whole new virtual table implementations. One well-known
extension is the fulltext-search extension distributed with SQLite.
+ .. versionadded:: 3.2
+
.. literalinclude:: ../includes/sqlite3/load_extension.py
.. method:: Connection.load_extension(path)
- .. versionadded:: 3.2
-
This routine loads a SQLite extension from a shared library. You have to
enable extension loading with ``enable_load_extension`` before you can use
this routine.
+ .. versionadded:: 3.2
+
.. attribute:: Connection.row_factory
You can change this attribute to a callable that accepts the cursor and the
.. versionadded:: 3.1
- .. method:: int.to_bytes(length, byteorder, \*, signed=False)
+.. method:: int.to_bytes(length, byteorder, \*, signed=False)
Return an array of bytes representing an integer.
.. versionadded:: 3.2
- .. classmethod:: int.from_bytes(bytes, byteorder, \*, signed=False)
+.. classmethod:: int.from_bytes(bytes, byteorder, \*, signed=False)
Return the integer represented by the given array of bytes.
list of possible encodings, see section :ref:`standard-encodings`.
.. versionchanged:: 3.1
- Added support for keyword arguments added.
+ Support for keyword arguments added.
+
.. method:: str.endswith(suffix[, start[, end]])
every virtual instruction, maximizing responsiveness as well as overhead.
.. deprecated:: 3.2
- This function doesn't have an effect anymore, as the internal logic
- for thread switching and asynchronous tasks has been rewritten.
- Use :func:`setswitchinterval` instead.
+ This function doesn't have an effect anymore, as the internal logic for
+ thread switching and asynchronous tasks has been rewritten. Use
+ :func:`setswitchinterval` instead.
.. function:: setdefaultencoding(name)
and so on.
.. versionchanged:: 3.1
- Added named component attributes
+ Added named component attributes.
.. data:: warnoptions
.. versionadded:: 3.2
+
Detailed interfaces for the objects are documented below.
The design of this module is loosely based on Java's threading model. However,
.. versionchanged:: 3.2
The *timeout* parameter is new.
+
.. method:: Lock.release()
Release a lock.
python -m unittest -h
-.. versionchanged:: 3.2
+.. versionchanged:: 3.2
In earlier versions it was only possible to run individual test methods and
not modules or classes.
Supplying both *delta* and *places* raises a ``TypeError``.
.. versionchanged:: 3.2
- Objects that compare equal automatically fail.
- Added the ``delta`` keyword argument.
+ Objects that compare equal automatically fail. Added the ``delta``
+ keyword argument.
.. deprecated:: 3.1
:meth:`failIfAlmostEqual`; use :meth:`assertNotAlmostEqual`.
If specified, *msg* will be used as the error message on failure.
.. versionadded:: 3.1
-
.. deprecated:: 3.2
+
.. method:: assertItemsEqual(actual, expected, msg=None)
Test that sequence *expected* contains the same elements as *actual*,
.. versionadded:: 3.2
+
.. method:: assertSetEqual(set1, set2, msg=None)
Tests that two sets are equal. If not, an error message is constructed
The default implementation appends the test to the instance's
:attr:`unexpectedSuccesses` attribute.
+
.. class:: TextTestResult(stream, descriptions, verbosity)
- A concrete implementation of :class:`TestResult` used by the
- :class:`TextTestRunner`.
+ A concrete implementation of :class:`TestResult` used by the
+ :class:`TextTestRunner`.
+
+ .. versionadded:: 3.2
+ This class was previously named ``_TextTestResult``. The old name still
+ exists as an alias but is deprecated.
- .. versionadded:: 3.2
- This class was previously named ``_TextTestResult``. The old name still
- exists as an alias but is deprecated.
.. data:: defaultTestLoader
parameters are sent the :func:`quote_plus` for encoding.
.. versionchanged:: 3.2
- query paramater supports bytes and string.
+ Query parameter supports bytes and string objects.
.. seealso::
.. method:: getchildren()
- .. deprecated:: 2.7
+ .. deprecated:: 3.2
Use ``list(elem)`` or iteration.
.. method:: getiterator(tag=None)
- .. deprecated:: 2.7
+ .. deprecated:: 3.2
Use method :meth:`Element.iter` instead.
.. method:: getiterator(tag=None)
- .. deprecated:: 2.7
+ .. deprecated:: 3.2
Use method :meth:`ElementTree.iter` instead.
.. method:: doctype(name, pubid, system)
- .. deprecated:: 2.7
+ .. deprecated:: 3.2
Define the :meth:`TreeBuilder.doctype` method on a custom TreeBuilder
target.
.. versionchanged:: 3.1
Support for file and file-like objects.
+
.. data:: ZIP_STORED
The numeric constant for an uncompressed archive member.
was imported. Raise :exc:`ZipImportError` if the module couldn't be
found.
- .. versionadded:: 3.1
+ .. versionadded:: 3.1
.. method:: get_source(fullname)
.. versionchanged:: 3.1
Supply the package name to run a ``__main__`` submodule.
+
.. describe:: -
Read commands from standard input (:data:`sys.stdin`). If standard input is
projects / python / commitdiff