mirror of https://github.com/python/cpython
Merged revisions 87188-87190,87192-87194 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r87188 | antoine.pitrou | 2010-12-12 19:25:25 +0100 (dim., 12 déc. 2010) | 3 lines Make this a warning and fix indentation ........ r87189 | antoine.pitrou | 2010-12-12 20:59:47 +0100 (dim., 12 déc. 2010) | 3 lines Better explain the buffer interface (hopefully) ........ r87190 | antoine.pitrou | 2010-12-12 21:01:43 +0100 (dim., 12 déc. 2010) | 3 lines Add link to the buffer protocol description from the memory description. ........ r87192 | antoine.pitrou | 2010-12-12 21:09:18 +0100 (dim., 12 déc. 2010) | 3 lines Remove redundant sentence, and fix markup ........ r87193 | antoine.pitrou | 2010-12-12 21:13:31 +0100 (dim., 12 déc. 2010) | 3 lines Fix heading level ........ r87194 | antoine.pitrou | 2010-12-12 21:17:29 +0100 (dim., 12 déc. 2010) | 3 lines Consistent ordering of availability statements ........
This commit is contained in:
parent
0101a3a827
commit
a92d1f5041
|
@ -12,16 +12,32 @@ Buffer Protocol
|
|||
.. index::
|
||||
single: buffer interface
|
||||
|
||||
Python objects implemented in C can export a "buffer interface." These
|
||||
functions can be used by an object to expose its data in a raw, byte-oriented
|
||||
format. Clients of the object can use the buffer interface to access the
|
||||
object data directly, without needing to copy it first.
|
||||
Certain objects available in Python wrap access to an underlying memory
|
||||
array or *buffer*. Such objects include the built-in :class:`bytes` and
|
||||
:class:`bytearray`, and some extension types like :class:`array.array`.
|
||||
Third-party libraries may define their own types for special purposes, such
|
||||
as image processing or numeric analysis.
|
||||
|
||||
Examples of objects that support the buffer interface are :class:`bytes`,
|
||||
:class:`bytearray` and :class:`array.array`. The bytes and bytearray objects
|
||||
exposes their bytes contents in the buffer interface's byte-oriented form.
|
||||
An :class:`array.array` can also expose its contents, but it should be noted
|
||||
that array elements may be multi-byte values.
|
||||
While each of these types have their own semantics, they share the common
|
||||
characteristic of being backed by a possibly large memory buffer. It is
|
||||
then desireable, in some situations, to access that buffer directly and
|
||||
without intermediate copying.
|
||||
|
||||
Python provides such a facility at the C level in the form of the *buffer
|
||||
protocol*. This protocol has two sides:
|
||||
|
||||
.. index:: single: PyBufferProcs
|
||||
|
||||
- on the producer side, a type can export a "buffer interface" which allows
|
||||
objects of that type to expose information about their underlying buffer.
|
||||
This interface is described in the section :ref:`buffer-structs`;
|
||||
|
||||
- on the consumer side, several means are available to obtain a pointer to
|
||||
the raw underlying data of an object (for example a method parameter).
|
||||
|
||||
Simple objects such as :class:`bytes` and :class:`bytearray` expose their
|
||||
underlying buffer in byte-oriented form. Other forms are possible; for example,
|
||||
the elements exposed by a :class:`array.array` can be multi-byte values.
|
||||
|
||||
An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
|
||||
method of file objects: any object that can export a series of bytes through
|
||||
|
@ -44,12 +60,6 @@ isn't needed anymore. Failure to do so could lead to various issues such as
|
|||
resource leaks.
|
||||
|
||||
|
||||
.. index:: single: PyBufferProcs
|
||||
|
||||
How the buffer interface is exposed by a type object is described in the
|
||||
section :ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`.
|
||||
|
||||
|
||||
The buffer structure
|
||||
====================
|
||||
|
||||
|
|
|
@ -1193,7 +1193,7 @@ Buffer Object Structures
|
|||
.. sectionauthor:: Benjamin Peterson
|
||||
|
||||
|
||||
The buffer interface exports a model where an object can expose its internal
|
||||
The :ref:`buffer interface <bufferobjects>` exports a model where an object can expose its internal
|
||||
data.
|
||||
|
||||
If an object does not export the buffer interface, then its :attr:`tp_as_buffer`
|
||||
|
|
|
@ -227,7 +227,7 @@ applications should use string objects to access all files.
|
|||
|
||||
*start* defaults to :attr:`os.curdir`.
|
||||
|
||||
Availability: Windows, Unix.
|
||||
Availability: Unix, Windows.
|
||||
|
||||
|
||||
.. function:: samefile(path1, path2)
|
||||
|
|
|
@ -2081,9 +2081,9 @@ An example of dictionary view usage::
|
|||
memoryview Types
|
||||
================
|
||||
|
||||
:class:`memoryview`\s allow Python code to access the internal data of an object
|
||||
that supports the buffer protocol without copying. Memory can be interpreted as
|
||||
simple bytes or complex data structures.
|
||||
:class:`memoryview` objects allow Python code to access the internal data
|
||||
of an object that supports the :ref:`buffer protocol <bufferobjects>` without
|
||||
copying. Memory is generally interpreted as simple bytes.
|
||||
|
||||
.. class:: memoryview(obj)
|
||||
|
||||
|
@ -2203,12 +2203,9 @@ Context Manager Types
|
|||
single: protocol; context management
|
||||
|
||||
Python's :keyword:`with` statement supports the concept of a runtime context
|
||||
defined by a context manager. This is implemented using two separate methods
|
||||
defined by a context manager. This is implemented using a pair of methods
|
||||
that allow user-defined classes to define a runtime context that is entered
|
||||
before the statement body is executed and exited when the statement ends.
|
||||
|
||||
The :dfn:`context management protocol` consists of a pair of methods that need
|
||||
to be provided for a context manager object to define a runtime context:
|
||||
before the statement body is executed and exited when the statement ends:
|
||||
|
||||
|
||||
.. method:: contextmanager.__enter__()
|
||||
|
@ -2256,9 +2253,9 @@ decimal arithmetic context. The specific types are not treated specially beyond
|
|||
their implementation of the context management protocol. See the
|
||||
:mod:`contextlib` module for some examples.
|
||||
|
||||
Python's :term:`generator`\s and the ``contextlib.contextmanager`` :term:`decorator`
|
||||
Python's :term:`generator`\s and the :class:`contextlib.contextmanager` decorator
|
||||
provide a convenient way to implement these protocols. If a generator function is
|
||||
decorated with the ``contextlib.contextmanager`` decorator, it will return a
|
||||
decorated with the :class:`contextlib.contextmanager` decorator, it will return a
|
||||
context manager implementing the necessary :meth:`__enter__` and
|
||||
:meth:`__exit__` methods, rather than the iterator produced by an undecorated
|
||||
generator function.
|
||||
|
|
|
@ -5,12 +5,12 @@
|
|||
:synopsis: Regression tests package containing the testing suite for Python.
|
||||
.. sectionauthor:: Brett Cannon <brett@python.org>
|
||||
|
||||
.. note::
|
||||
The :mod:`test` package is meant for internal use by Python only. It is
|
||||
documented for the benefit of the core developers of Python. Any use of
|
||||
this package outside of Python's standard library is discouraged as code
|
||||
mentioned here can change or be removed without notice between releases of
|
||||
Python.
|
||||
.. warning::
|
||||
The :mod:`test` package is meant for internal use by Python only. It is
|
||||
documented for the benefit of the core developers of Python. Any use of
|
||||
this package outside of Python's standard library is discouraged as code
|
||||
mentioned here can change or be removed without notice between releases of
|
||||
Python.
|
||||
|
||||
|
||||
The :mod:`test` package contains all regression tests for Python as well as the
|
||||
|
|
Loading…
Reference in New Issue