[Python-checkins] cpython: Doc clarification / edification on the semantics of the 'w*' format unit.

Mon Apr 13 17:33:02 CEST 2015

https://hg.python.org/cpython/rev/c81dd9fe0d87
changeset: 95567:c81dd9fe0d87
user: Larry Hastings <larry at hastings.org>
date: Mon Apr 13 11:30:56 2015 -0400
summary:
 Doc clarification / edification on the semantics of the 'w*' format unit.
files:
 Doc/c-api/arg.rst | 2 +-
 Doc/glossary.rst | 15 +++++++++++----
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -152,7 +152,7 @@
 any conversion. Raises :exc:`TypeError` if the object is not a Unicode
 object. The C variable may also be declared as :c:type:`PyObject\*`.
 
-``w*`` (:class:`bytearray` or read-write byte-oriented buffer) [Py_buffer]
+``w*`` (read-write :term:`bytes-like object`) [Py_buffer]
 This format accepts any object which implements the read-write buffer
 interface. It fills a :c:type:`Py_buffer` structure provided by the caller.
 The buffer may contain embedded null bytes. The caller have to call
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -88,10 +88,17 @@
 bytes-like object
 An object that supports the :ref:`bufferobjects`, like :class:`bytes`,
 :class:`bytearray` or :class:`memoryview`. Bytes-like objects can
- be used for various operations that expect binary data, such as
- compression, saving to a binary file or sending over a socket.
- Some operations need the binary data to be mutable, in which case
- not all bytes-like objects can apply.
+ be used for various operations that work with binary data; these include
+ compression, saving to a binary file, and sending over a socket.
+
+ Some operations need the binary data to be mutable. The documentation
+ often refers to these as "read-write bytes-like objects". Example
+ mutable buffer objects include :class:`bytearray` and a
+ :class:`memoryview` of a :class:`bytearray`.
+ Other operations require the binary data to be stored in
+ immutable objects ("read-only bytes-like objects"); examples
+ of these include :class:`bytes` and a :class:`memoryview`
+ of a :class:`bytes` object.
 
 bytecode
 Python source code is compiled into bytecode, the internal representation
-- 
Repository URL: https://hg.python.org/cpython
