diff options
Diffstat (limited to 'Doc')
-rw-r--r-- | Doc/ACKS.txt | 1 | ||||
-rw-r--r-- | Doc/c-api/import.rst | 13 | ||||
-rw-r--r-- | Doc/library/__future__.rst | 5 | ||||
-rw-r--r-- | Doc/library/future_builtins.rst | 53 | ||||
-rw-r--r-- | Doc/library/python.rst | 1 | ||||
-rw-r--r-- | Doc/library/select.rst | 304 | ||||
-rw-r--r-- | Doc/license.rst | 55 | ||||
-rw-r--r-- | Doc/reference/datamodel.rst | 4 | ||||
-rw-r--r-- | Doc/tutorial/datastructures.rst | 9 | ||||
-rw-r--r-- | Doc/whatsnew/2.6.rst | 4 |
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) -> |