summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
Diffstat (limited to 'Doc')
-rw-r--r--Doc/ACKS.txt1
-rw-r--r--Doc/c-api/import.rst13
-rw-r--r--Doc/library/__future__.rst5
-rw-r--r--Doc/library/future_builtins.rst53
-rw-r--r--Doc/library/python.rst1
-rw-r--r--Doc/library/select.rst304
-rw-r--r--Doc/license.rst55
-rw-r--r--Doc/reference/datamodel.rst4
-rw-r--r--Doc/tutorial/datastructures.rst9
-rw-r--r--Doc/whatsnew/2.6.rst4
10 files changed, 440 insertions, 9 deletions
diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt
index 5e97e33..9eae6a3 100644
--- a/Doc/ACKS.txt
+++ b/Doc/ACKS.txt
@@ -21,6 +21,7 @@ docs@python.org), and we'll be glad to correct the problem.
* Chris Barker
* Don Bashford
* Anthony Baxter
+ * Alexander Belopolsky
* Bennett Benson
* Jonathan Black
* Robin Boerdijk
diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst
index 907f531..89d5f84 100644
--- a/Doc/c-api/import.rst
+++ b/Doc/c-api/import.rst
@@ -134,6 +134,19 @@ Importing Modules
``sys.modules``). Note that this is a per-interpreter variable.
+.. cfunction:: PyObject* PyImport_GetImporter(PyObject *path)
+
+ Return an importer object for a :data:`sys.path`/:attr:`pkg.__path__` item
+ *path*, possibly by fetching it from the :data:`sys.path_importer_cache`
+ dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook
+ is found that can handle the path item. Return ``None`` if no hook could;
+ this tells our caller it should fall back to the builtin import mechanism.
+ Cache the result in :data:`sys.path_importer_cache`. Return a new reference
+ to the importer object.
+
+ .. versionadded:: 2.6
+
+
.. cfunction:: void _PyImport_Init()
Initialize the import mechanism. For internal use only.
diff --git a/Doc/library/__future__.rst b/Doc/library/__future__.rst
index 6bf2830..e2349cc 100644
--- a/Doc/library/__future__.rst
+++ b/Doc/library/__future__.rst
@@ -1,4 +1,3 @@
-
:mod:`__future__` --- Future statement definitions
==================================================
@@ -22,8 +21,8 @@
Each statement in :file:`__future__.py` is of the form::
- FeatureName = "_Feature(" OptionalRelease "," MandatoryRelease ","
- CompilerFlag ")"
+ FeatureName = _Feature(OptionalRelease, MandatoryRelease,
+ CompilerFlag)
where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are
diff --git a/Doc/library/future_builtins.rst b/Doc/library/future_builtins.rst
new file mode 100644
index 0000000..e845fe4
--- /dev/null
+++ b/Doc/library/future_builtins.rst
@@ -0,0 +1,53 @@
+:mod:`future_builtins` --- Python 3 builtins
+============================================
+
+.. module:: future_builtins
+.. sectionauthor:: Georg Brandl
+.. versionadded:: 2.6
+
+This module provides functions that exist in 2.x, but have different behavior in
+Python 3, so they cannot be put into the 2.x builtin namespace.
+
+Instead, if you want to write code compatible with Python 3 builtins, import
+them from this module, like this::
+
+ from future_builtins import map, filter
+
+ ... code using Python 3-style map and filter ...
+
+The :program:`2to3` tool that ports Python 2 code to Python 3 will recognize
+this usage and leave the new builtins alone.
+
+.. note::
+
+ The Python 3 :func:`print` function is already in the builtins, but cannot be
+ accessed from Python 2 code unless you use the appropriate future statement::
+
+ from __future__ import print_function
+
+
+Available builtins are:
+
+.. function:: filter(function, iterable)
+
+ Works like :func:`itertools.ifilter`.
+
+.. function:: hex(object)
+
+ Works like the builtin :func:`hex`, but instead of :meth:`__hex__` it will
+ use the :meth:`__index__` method on its argument to get an integer that is
+ then converted to hexadecimal.
+
+.. function:: map(function, iterable, ...)
+
+ Works like :func:`itertools.imap`.
+
+.. function:: oct(object)
+
+ Works like the builtin :func:`oct`, but instead of :meth:`__oct__` it will
+ use the :meth:`__index__` method on its argument to get an integer that is
+ then converted to hexadecimal.
+
+.. function:: zip(*iterables)
+
+ Works like :func:`itertools.izip`.
diff --git a/Doc/library/python.rst b/Doc/library/python.rst
index 0fdfa53..379d508 100644
--- a/Doc/library/python.rst
+++ b/Doc/library/python.rst
@@ -14,6 +14,7 @@ overview:
sys.rst
builtins.rst
+ future_builtins.rst
__main__.rst
warnings.rst
contextlib.rst
diff --git a/Doc/library/select.rst b/Doc/library/select.rst
index 4a97179..1368c78 100644
--- a/Doc/library/select.rst
+++ b/Doc/library/select.rst
@@ -7,10 +7,12 @@
This module provides access to the :cfunc:`select` and :cfunc:`poll` functions
-available in most operating systems. Note that on Windows, it only works for
-sockets; on other operating systems, it also works for other file types (in
-particular, on Unix, it works on pipes). It cannot be used on regular files to
-determine whether a file has grown since it was last read.
+available in most operating systems, :cfunc:`epoll` available on Linux 2.5+ and
+:cfunc:`kqueue` available on most BSD.
+Note that on Windows, it only works for sockets; on other operating systems,
+it also works for other file types (in particular, on Unix, it works on pipes).
+It cannot be used on regular files to determine whether a file has grown since
+it was last read.
The module defines the following:
@@ -22,6 +24,16 @@ The module defines the following:
string, as would be printed by the C function :cfunc:`perror`.
+.. type:: epoll([sizehint=-1])
+
+ (Only supported on Linux 2.5.44 and newer.) Returns an edge polling
+ object, which can be used as Edge or Level Triggered interface for I/O
+ events; see section :ref:`epoll-objects` below for the methods supported
+ by epolling objects.
+
+ .. versionadded:: 2.6
+
+
.. function:: poll()
(Not supported by all operating systems.) Returns a polling object, which
@@ -30,6 +42,24 @@ The module defines the following:
by polling objects.
+.. type:: kqueue()
+
+ (Only supported on BSD.) Returns a kernel queue object
+ object; see section :ref:`kqueue-objects` below for the methods supported
+ by kqueue objects.
+
+ .. versionadded:: 2.6
+
+
+.. type:: kqueue(ident, filter=KQ_FILTER_READ, flags=KQ_ADD, fflags=0, data=0, udata=0)
+
+ (Only supported on BSD.) Returns a kernel event object
+ object; see section :ref:`kevent-objects` below for the methods supported
+ by kqueue objects.
+
+ .. versionadded:: 2.6
+
+
.. function:: select(iwtd, owtd, ewtd[, timeout])
This is a straightforward interface to the Unix :cfunc:`select` system call.
@@ -67,6 +97,81 @@ The module defines the following:
not handle file descriptors that don't originate from WinSock.
+.. _epoll-objects:
+
+Edge and Level Trigger Polling (epoll) Objects
+----------------------------------------------
+
+ http://linux.die.net/man/4/epoll
+
+ *eventmask*
+
+ +-----------------------+-----------------------------------------------+
+ | Constant | Meaning |
+ +=======================+===============================================+
+ | :const:`EPOLLIN` | Available for read |
+ +-----------------------+-----------------------------------------------+
+ | :const:`EPOLLOUT` | Available for write |
+ +-----------------------+-----------------------------------------------+
+ | :const:`EPOLLPRI` | Urgent data for read |
+ +-----------------------+-----------------------------------------------+
+ | :const:`EPOLLERR` | Error condition happend on the assoc. fd |
+ +-----------------------+-----------------------------------------------+
+ | :const:`EPOLLHUP` | Hang up happend on the assoc. fd |
+ +-----------------------+-----------------------------------------------+
+ | :const:`EPOLLET` | Set Edge Trigger behavior, the default is |
+ | | Level Trigger behavior |
+ +-----------------------+-----------------------------------------------+
+ | :const:`EPOLLONESHOT` | Set one-shot behavior. After one event is |
+ | | pulled out, the fd is internally disabled |
+ +-----------------------+-----------------------------------------------+
+ | :const:`EPOLLRDNORM` | ??? |
+ +-----------------------+-----------------------------------------------+
+ | :const:`EPOLLRDBAND` | ??? |
+ +-----------------------+-----------------------------------------------+
+ | :const:`EPOLLWRNORM` | ??? |
+ +-----------------------+-----------------------------------------------+
+ | :const:`EPOLLWRBAND` | ??? |
+ +-----------------------+-----------------------------------------------+
+ | :const:`EPOLLMSG` | ??? |
+ +-----------------------+-----------------------------------------------+
+
+
+.. method:: epoll.close()
+
+ Close the control file descriptor of the epoll object.
+
+
+.. method:: epoll.fileno()
+
+ Return the file descriptor number of the control fd.
+
+
+.. method:: epoll.fromfd(fd)
+
+ Create an epoll object from a given file descriptor.
+
+
+.. method:: epoll.register(fd[, eventmask])
+
+ Register a fd descriptor with the epoll object.
+
+
+.. method:: epoll.modify(fd, eventmask)
+
+ Modify a register file descriptor.
+
+
+.. method:: epoll.unregister(fd)
+
+ Remove a registered file descriptor from the epoll object.
+
+
+.. method:: epoll.poll([timeout=-1[, maxevents=-1]])
+
+ Wait for events. timeout in seconds (float)
+
+
.. _poll-objects:
Polling Objects
@@ -114,6 +219,16 @@ linearly scanned again. :cfunc:`select` is O(highest file descriptor), while
the same effect as registering the descriptor exactly once.
+.. method:: poll.modify(fd, eventmask)
+
+ Modifies an already registered fd. This has the same effect as
+ :meth:`register(fd, eventmask)`. Attempting to modify a file descriptor
+ that was never registered causes an :exc:`IOError` exception with errno
+ :const:`ENOENT` to be raised.
+
+ .. versionadded:: 2.6
+
+
.. method:: poll.unregister(fd)
Remove a file descriptor being tracked by a polling object. Just like the
@@ -137,3 +252,184 @@ linearly scanned again. :cfunc:`select` is O(highest file descriptor), while
returning. If *timeout* is omitted, negative, or :const:`None`, the call will
block until there is an event for this poll object.
+
+.. _kqueue-objects:
+
+Kqueue Objects
+--------------
+
+.. method:: kqueue.close()
+
+ Close the control file descriptor of the kqueue object.
+
+
+.. method:: kqueue.fileno()
+
+ Return the file descriptor number of the control fd.
+
+
+.. method:: epoll.fromfd(fd)
+
+ Create a kqueue object from a given file descriptor.
+
+
+.. method:: control(changelist, max_events=0[, timeout=None]) -> eventlist
+
+ Low level interface to kevent
+
+ - changelist must be an iterable of kevent object or None
+ - max_events must be 0 or a positive integer
+ - timeout in seconds (floats possible)
+
+
+.. _kevent-objects:
+
+Kevent Objects
+--------------
+
+ http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
+
+ .. attribute:: ident
+
+ Value used to identify the event. The interpretation depends on the filter
+ but it's usually the file descriptor. In the constructor ident can either
+ be an int or an object with a fileno() function. kevent stores the integer
+ internally.
+
+ .. attribute:: filter
+
+ Name of the kernel filter
+
+ +---------------------------+---------------------------------------------+
+ | Constant | Meaning |
+ +===========================+=============================================+
+ | :const:`KQ_FILTER_READ` | Takes a descriptor and returns whenever |
+ | | there is data available to read |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_FILTER_WRITE` | Takes a descriptor and returns whenever |
+ | | there is data available to read |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_FILTER_AIO` | AIO requests |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_FILTER_VNODE` | Returns when one or more of the requested |
+ | | events watched in *fflag* occurs |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_FILTER_PROC` | Watch for events on a process id |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_FILTER_NETDEV` | Watch for events on a network device |
+ | | [not available on Mac OS X] |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_FILTER_SIGNAL` | Returns whenever the watched signal is |
+ | | delivered to the process |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_FILTER_TIMER` | Establishes an arbitrary timer |
+ +---------------------------+---------------------------------------------+
+
+ .. attribute:: flags
+
+ Filter action
+
+ +---------------------------+---------------------------------------------+
+ | Constant | Meaning |
+ +===========================+=============================================+
+ | :const:`KQ_EV_ADD` | Adds or modifies an event |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_EV_DELETE` | Removes an event from the queue |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_EV_ENABLE` | Permitscontrol() to returns the event |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_EV_DISABLE` | Disablesevent |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_EV_ONESHOT` | Removes event after first occurence |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_EV_CLEAR` | Reset the state after an event is retrieved |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_EV_SYSFLAGS` | internal event |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_EV_FLAG1` | internal event |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_EV_EOF` | Filter specific EOF condition |
+ +---------------------------+---------------------------------------------+
+ | :const:`KQ_EV_ERROR` | See return values |
+ +---------------------------+---------------------------------------------+
+
+
+ .. attribute:: fflags
+
+ Filter specific flags
+
+
+ *:const:`KQ_FILTER_READ` and :const:`KQ_FILTER_WRITE` filter flags
+
+ +----------------------------+--------------------------------------------+
+ | Constant | Meaning |
+ +============================+============================================+
+ | :const:`KQ_NOTE_LOWAT` | low water mark of a socket buffer |
+ +----------------------------+--------------------------------------------+
+
+
+ *:const:`KQ_FILTER_VNODE` filter flags*
+
+ +----------------------------+--------------------------------------------+
+ | Constant | Meaning |
+ +============================+============================================+
+ | :const:`KQ_NOTE_DELETE` | *unlink()* was called |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_WRITE` | a write occured |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_EXTEND` | the file was extended |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_ATTRIB` | an attribute was changed |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_LINK` | the link count has changed |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_RENAME` | the file was renamed |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_REVOKE` | access to the file was revoked |
+ +----------------------------+--------------------------------------------+
+
+
+ *:const:`KQ_FILTER_PROC` filter flags*
+
+ +----------------------------+--------------------------------------------+
+ | Constant | Meaning |
+ +============================+============================================+
+ | :const:`KQ_NOTE_EXIT` | the process has exited |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_FORK` | the process has called *fork()* |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_EXEC` | the process has executed a new process |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_PCTRLMASK` | internal filter flag |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_PDATAMASK` | internal filter flag |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_TRACK` | follow a process across *fork()* |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_CHILD` | returned on the child process for |
+ | | *NOTE_TRACK* |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_TRACKERR` | unable to attach to a child |
+ +----------------------------+--------------------------------------------+
+
+ *:const:`KQ_FILTER_NETDEV` filter flags* [not available on Mac OS X]
+
+ +----------------------------+--------------------------------------------+
+ | Constant | Meaning |
+ +============================+============================================+
+ | :const:`KQ_NOTE_LINKUP` | link is up |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_LINKDOWN` | link is down |
+ +----------------------------+--------------------------------------------+
+ | :const:`KQ_NOTE_LINKINV` | link state is invalid |
+ +----------------------------+--------------------------------------------+
+
+
+ .. attribute:: data
+
+ Filter specific data
+
+
+ .. attribute:: udata
+
+ User defined value
diff --git a/Doc/license.rst b/Doc/license.rst
index 0226ec5..e10f930 100644
--- a/Doc/license.rst
+++ b/Doc/license.rst
@@ -599,3 +599,58 @@ The :mod:`xmlrpclib` module contains the following notice::
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
OF THIS SOFTWARE.
+
+test_epoll
+----------
+
+The :mod:`test_epoll` contains the following notice::
+
+ Copyright (c) 2001-2006 Twisted Matrix Laboratories.
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Select kqueue
+-------------
+
+The :mod:`select` and contains the following notice for the kqueue interface::
+
+ Copyright (c) 2000 Doug White, 2006 James Knight, 2007 Christian Heimes
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+ 1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ SUCH DAMAGE.
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 0ab5f11..2ff9400 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -510,6 +510,10 @@ Callable types
An instance method object combines a class, a class instance and any
callable object (normally a user-defined function).
+ .. versionchanged:: 2.6
+ For 3.0 forward-compatibility, :attr:`im_func` is also available as
+ :attr:`__func__`, and :attr:`im_self` as :attr:`__self__`.
+
.. index::
single: __func__ (method attribute)
single: __self__ (method attribute)
diff --git a/Doc/tutorial/datastructures.rst b/Doc/tutorial/datastructures.rst
index e2f218c..201fa72 100644
--- a/Doc/tutorial/datastructures.rst
+++ b/Doc/tutorial/datastructures.rst
@@ -83,17 +83,20 @@ objects:
.. method:: list.append(x)
+ :noindex:
Add an item to the end of the list; equivalent to ``a[len(a):] = [x]``.
.. method:: list.extend(L)
+ :noindex:
Extend the list by appending all the items in the given list; equivalent to
``a[len(a):] = L``.
.. method:: list.insert(i, x)
+ :noindex:
Insert an item at a given position. The first argument is the index of the
element before which to insert, so ``a.insert(0, x)`` inserts at the front of
@@ -101,12 +104,14 @@ objects:
.. method:: list.remove(x)
+ :noindex:
Remove the first item from the list whose value is *x*. It is an error if there
is no such item.
.. method:: list.pop([i])
+ :noindex:
Remove the item at the given position in the list, and return it. If no index
is specified, ``a.pop()`` removes and returns the last item in the list. (The
@@ -116,22 +121,26 @@ objects:
.. method:: list.index(x)
+ :noindex:
Return the index in the list of the first item whose value is *x*. It is an
error if there is no such item.
.. method:: list.count(x)
+ :noindex:
Return the number of times *x* appears in the list.
.. method:: list.sort()
+ :noindex:
Sort the items of the list, in place.
.. method:: list.reverse()
+ :noindex:
Reverse the elements of the list, in place.
diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
index 3378fc8..0e8901b 100644
--- a/Doc/whatsnew/2.6.rst
+++ b/Doc/whatsnew/2.6.rst
@@ -540,7 +540,7 @@ complicated expressions inside a format string.
So far we've shown how to specify which field to substitute into the
resulting string. The precise formatting used is also controllable by
-adding a colon followed by a format specifier. For example:
+adding a colon followed by a format specifier. For example::
# Field 0: left justify, pad to 15 characters
# Field 1: right justify, pad to 6 characters
@@ -552,7 +552,7 @@ adding a colon followed by a format specifier. For example:
fmt.format('Banquet', 125) ->
'Banquet $ 125'
-Format specifiers can reference other fields through nesting:
+Format specifiers can reference other fields through nesting::
fmt = '{0:{1}}'
fmt.format('Invoice #1234', width) ->