From a92d1f5041bac091435f1537be5cf216ae52f79b Mon Sep 17 00:00:00 2001 From: Antoine Pitrou Date: Sun, 12 Dec 2010 21:07:49 +0000 Subject: Merged revisions 87188-87190,87192-87194 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ 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 ........ --- Doc/c-api/buffer.rst | 40 +++++++++++++++++++++++++--------------- Doc/c-api/typeobj.rst | 2 +- Doc/library/os.path.rst | 2 +- Doc/library/stdtypes.rst | 17 +++++++---------- Doc/library/test.rst | 12 ++++++------ 5 files changed, 40 insertions(+), 33 deletions(-) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index ad6e3937..e6eff84 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -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 ==================== diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index eb8a83e..ab55292 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -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 ` 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` diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index fdc45b9..28a7aff 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -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) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 4b7ae39..f2563dd 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -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 ` 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. diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 0b16109..ecb2e5c 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -5,12 +5,12 @@ :synopsis: Regression tests package containing the testing suite for Python. .. sectionauthor:: Brett Cannon -.. 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 -- cgit v0.12