diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/pickle.rst | 5 | ||||
| -rw-r--r-- | Doc/whatsnew/2.6.rst | 217 |
2 files changed, 183 insertions, 39 deletions
diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index 33bd9c9..520c24b 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -468,8 +468,9 @@ local name relative to its module; the pickle module searches the module namespace to determine the object's module. When a tuple is returned, it must be between two and five elements long. -Optional elements can either be omitted, or ``None`` can be provided as their -value. The semantics of each element are: +Optional elements can either be omitted, or ``None`` can be provided as their +value. The contents of this tuple are pickled as normal and used to +reconstruct the object at unpickling time. The semantics of each element are: * A callable object that will be called to create the initial version of the object. The next element of the tuple will provide arguments for this callable, diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index 26f5169..2098508 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -156,15 +156,18 @@ http://svn.python.org/view/tracker/importer/. .. seealso:: - http://bugs.python.org: The Python bug tracker. + http://bugs.python.org + The Python bug tracker. - http://bugs.jython.org: The Jython bug tracker. + http://bugs.jython.org: + The Jython bug tracker. - http://roundup.sourceforge.net/: Roundup downloads and documentation. + http://roundup.sourceforge.net/ + Roundup downloads and documentation. -New Documentation Format: ReStructured Text --------------------------------------------------- +New Documentation Format: ReStructured Text Using Sphinx +----------------------------------------------------------- Since the Python project's inception around 1989, the documentation had been written using LaTeX. At that time, most documentation was @@ -191,16 +194,20 @@ The input format is reStructured Text, a markup commonly used in the Python community that supports custom extensions and directives. Sphinx concentrates on HTML output, producing attractively styled -and modern HTML, but printed output is still supported through -conversion to LaTeX as an output format. +and modern HTML, though printed output is still supported through +conversion to LaTeX. Sphinx is a standalone package that +can be used in documenting other projects. .. seealso:: - `Docutils <http://docutils.sf.net>`__: The fundamental - reStructured Text parser and toolset. + :ref:`documenting-index` + Describes how to write for Python's documentation. + + `Sphinx <http://sphinx.pocoo.org/>`__ + Documentation and code for the Sphinx toolchain. - :ref:`documenting-index`: Describes how to write for - Python's documentation. + `Docutils <http://docutils.sf.net>`__ + The underlying reStructured Text parser and toolset. PEP 343: The 'with' statement @@ -487,8 +494,7 @@ can now be used in scripts running from inside a package. .. seealso:: :pep:`370` - XXX - - PEP written by XXX; implemented by Christian Heimes. + PEP written by XXX; implemented by Christian Heimes. .. ====================================================================== @@ -633,9 +639,8 @@ PEP 3105: ``print`` As a Function ===================================================== The ``print`` statement becomes the :func:`print` function in Python 3.0. -Making :func:`print` a function makes it easier to replace within a -module by doing 'def print(...)' or importing a new -function from somewhere else. +Making :func:`print` a function makes it easier to change +by doing 'def print(...)' or importing a new function from somewhere else. Python 2.6 has a ``__future__`` import that removes ``print`` as language syntax, letting you use the functional form instead. For example:: @@ -750,13 +755,50 @@ XXX write this. PEP 3118: Revised Buffer Protocol ===================================================== -The buffer protocol is a C-level API that lets Python extensions -XXX +The buffer protocol is a C-level API that lets Python types +exchange pointers into their internal representations. A +memory-mapped file can be viewed as a buffer of characters, for +example, and this lets another module such as :mod:`re` +treat memory-mapped files as a string of characters to be searched. + +The primary users of the buffer protocol are numeric-processing +packages such as NumPy, which can expose the internal representation +of arrays so that callers can write data directly into an array instead +of going through a slower API. This PEP updates the buffer protocol in light of experience +from NumPy development, adding a number of new features +such as indicating the shape of an array, +locking memory . + +The most important new C API function is +``PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)``, which +takes an object and a set of flags, and fills in the +``Py_buffer`` structure with information +about the object's memory representation. Objects +can use this operation to lock memory in place +while an external caller could be modifying the contents, +so there's a corresponding +``PyObject_ReleaseBuffer(PyObject *obj, Py_buffer *view)`` to +indicate that the external caller is done. + +The **flags** argument to :cfunc:`PyObject_GetBuffer` specifies +constraints upon the memory returned. Some examples are: + + * :const:`PyBUF_WRITABLE` indicates that the memory must be writable. + + * :const:`PyBUF_LOCK` requests a read-only or exclusive lock on the memory. + + * :const:`PyBUF_C_CONTIGUOUS` and :const:`PyBUF_F_CONTIGUOUS` + requests a C-contiguous (last dimension varies the fastest) or + Fortran-contiguous (first dimension varies the fastest) layout. + +.. XXX this feature is not in 2.6 docs yet .. seealso:: :pep:`3118` - Revising the buffer protocol - PEP written by Travis Oliphant and Carl Banks. + PEP written by Travis Oliphant and Carl Banks; implemented by + Travis Oliphant. + .. ====================================================================== @@ -765,41 +807,142 @@ XXX PEP 3119: Abstract Base Classes ===================================================== -XXX write this -- this section is currently just brief notes. +Some object-oriented languages such as Java support interfaces: declarations +that a class has a given set of methods or supports a given access protocol. +Abstract Base Classes (or ABCs) are an equivalent feature for Python. The ABC +support consists of an :mod:`abc` module containing a metaclass called +:class:`ABCMeta`, special handling +of this metaclass by the :func:`isinstance` and :func:`issubclass` built-ins, +and a collection of basic ABCs that the Python developers think will be widely +useful. + +Let's say you have a particular class and wish to know whether it supports +dictionary-style access. The phrase "dictionary-style" is vague, however. +It probably means that accessing items with ``obj[1]`` works. +Does it imply that setting items with ``obj[2] = value`` works? +Or that the object will have :meth:`keys`, :meth:`values`, and :meth:`items` +methods? What about the iterative variants such as :meth:`iterkeys`? :meth:`copy` +and :meth:`update`? Iterating over the object with :func:`iter`? + +Python 2.6 includes a number of different ABCs in the :mod:`collections` +module. :class:`Iterable` indicates that a class defines :meth:`__iter__`, +and :class:`Container` means the class supports ``x in y`` expressions +by defining a :meth:`__contains__` method. The basic dictionary interface of +getting items, setting items, and +:meth:`keys`, :meth:`values`, and :meth:`items`, is defined by the +:class:`MutableMapping` ABC. + +You can derive your own classes from a particular ABC +to indicate they support that ABC's interface:: + + import collections + + class Storage(collections.MutableMapping): + ... -How to identify a file object? -ABCs are a collection of classes describing various interfaces. -Classes can derive from an ABC to indicate they support that ABC's -interface. Concrete classes should obey the semantics specified by -an ABC, but Python can't check this; it's up to the implementor. +Alternatively, you could write the class without deriving from +the desired ABC and instead register the class by +calling the ABC's :meth:`register` method:: -A metaclass lets you declare that an existing class or type -derives from a particular ABC. You can even + import collections + + class Storage: + ... + + collections.MutableMapping.register(Storage) + +For classes that you write, deriving from the ABC is probably clearer. +The :meth:`register` method is useful when you've written a new +ABC that can describe an existing type or class, or if you want +to declare that some third-party class implements an ABC. +For example, if you defined a :class:`PrintableType` ABC, +it's legal to do: + + # Register Python's types + PrintableType.register(int) + PrintableType.register(float) + PrintableType.register(str) + +Classes should obey the semantics specified by an ABC, but +Python can't check this; it's up to the class author to +understand the ABC's requirements and to implement the code accordingly. + +To check whether an object supports a particular interface, you can +now write:: + + def func(d): + if not isinstance(d, collections.MutableMapping): + raise ValueError("Mapping object expected, not %r" % d) + +(Don't feel that you must now begin writing lots of checks as in the +above example. Python has a strong tradition of duck-typing, where +explicit type-checking isn't done and code simply calls methods on +an object, trusting that those methods will be there and raising an +exception if they aren't. Be judicious in checking for ABCs +and only do it where it helps.) + +You can write your own ABCs by using ``abc.ABCMeta`` as the +metaclass in a class definition:: + + from abc import ABCMeta + + class Drawable(): + __metaclass__ = ABCMeta + + def draw(self, x, y, scale=1.0): + pass -class AppendableSequence: - __metaclass__ = ABCMeta + def draw_doubled(self, x, y): + self.draw(x, y, scale=2.0) -AppendableSequence.register(list) -assert issubclass(list, AppendableSequence) -assert isinstance([], AppendableSequence) + + class Square(Drawable): + def draw(self, x, y, scale): + ... -@abstractmethod decorator -- you can't instantiate classes w/ -an abstract method. + +In the :class:`Drawable` ABC above, the :meth:`draw_doubled` method +renders the object at twice its size and can be implemented in terms +of other methods described in :class:`Drawable`. Classes implementing +this ABC therefore don't need to provide their own implementation +of :meth:`draw_doubled`, though they can do so. An implementation +of :meth:`draw` is necessary, though; the ABC can't provide +a useful generic implementation. You +can apply the ``@abstractmethod`` decorator to methods such as +:meth:`draw` that must be implemented; Python will +then raise an exception for classes that +don't define the method:: + + class Drawable(): + __metaclass__ = ABCMeta + + @abstractmethod + def draw(self, x, y, scale): + pass + +Note that the exception is only raised when you actually +try to create an instance of a subclass without the method:: + + >>> s=Square() + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + TypeError: Can't instantiate abstract class Square with abstract methods draw + >>> -:: +Abstract data attributes can be declared using the ``@abstractproperty`` decorator:: - @abstractproperty decorator @abstractproperty def readonly(self): return self._x +Subclasses must then define a :meth:`readonly` property .. seealso:: :pep:`3119` - Introducing Abstract Base Classes PEP written by Guido van Rossum and Talin. - Implemented by XXX. + Implemented by Guido van Rossum. Backported to 2.6 by Benjamin Aranguren, with Alex Martelli. .. ====================================================================== |