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

[larry.hastings]

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