[Python-3000-checkins] r58878 - python/branches/py3k-pep3137/Doc/library/exceptions.rst python/branches/py3k-pep3137/Doc/library/functions.rst python/branches/py3k-pep3137/Doc/library/stdtypes.rst python/branches/py3k-pep3137/Doc/library/warnings.rst
georg.brandl
python-3000-checkins at python.org
Tue Nov 6 13:35:55 CET 2007
Author: georg.brandl
Date: Tue Nov 6 13:35:55 2007
New Revision: 58878
Modified:
python/branches/py3k-pep3137/Doc/library/exceptions.rst
python/branches/py3k-pep3137/Doc/library/functions.rst
python/branches/py3k-pep3137/Doc/library/stdtypes.rst
python/branches/py3k-pep3137/Doc/library/warnings.rst
Log:
More documentation for bytes vs. buffer types.
Modified: python/branches/py3k-pep3137/Doc/library/exceptions.rst
==============================================================================
--- python/branches/py3k-pep3137/Doc/library/exceptions.rst (original)
+++ python/branches/py3k-pep3137/Doc/library/exceptions.rst Tue Nov 6 13:35:55 2007
@@ -407,9 +407,9 @@
.. exception:: BytesWarning
- Base class for warnings related to bytes and buffer.
+ Base class for warnings related to :class:`bytes` and :class:`buffer`.
-The class hierarchy for built-in exceptions is:
+The class hierarchy for built-in exceptions is:
.. literalinclude:: ../../Lib/test/exception_hierarchy.txt
Modified: python/branches/py3k-pep3137/Doc/library/functions.rst
==============================================================================
--- python/branches/py3k-pep3137/Doc/library/functions.rst (original)
+++ python/branches/py3k-pep3137/Doc/library/functions.rst Tue Nov 6 13:35:55 2007
@@ -118,18 +118,19 @@
.. index:: pair: Boolean; type
-.. function:: bytes([arg[, encoding[, errors]]])
+.. function:: buffer([arg[, encoding[, errors]]])
- Return a new array of bytes. The :class:`bytes` type is a mutable sequence
+ Return a new array of bytes. The :class:`buffer` type is an immutable sequence
of integers in the range 0 <= x < 256. It has most of the usual methods of
- mutable sequences, described in :ref:`typesseq-mutable`, as well as a few
- methods borrowed from strings, described in :ref:`bytes-methods`.
+ mutable sequences, described in :ref:`typesseq-mutable`, as well as most methods
+ that the :class:`str` type has, see :ref:`bytes-methods`.
The optional *arg* parameter can be used to initialize the array in a few
different ways:
* If it is a *string*, you must also give the *encoding* (and optionally,
- *errors*) parameters; :func:`bytes` then acts like :meth:`str.encode`.
+ *errors*) parameters; :func:`buffer` then converts the Unicode string to
+ bytes using :meth:`str.encode`.
* If it is an *integer*, the array will have that size and will be
initialized with null bytes.
@@ -137,12 +138,24 @@
* If it is an object conforming to the *buffer* interface, a read-only buffer
of the object will be used to initialize the bytes array.
- * If it is an *iterable*, it must be an iterable of integers in the range 0
- <= x < 256, which are used as the initial contents of the array.
+ * If it is an *iterable*, it must be an iterable of integers in the range
+ ``0 <= x < 256``, which are used as the initial contents of the array.
Without an argument, an array of size 0 is created.
+.. function:: bytes([arg[, encoding[, errors]]])
+
+ Return a new "bytes" object, which is an immutable sequence of integers in
+ the range ``0 <= x < 256``. :class:`bytes` is an immutable version of
+ :class:`buffer` -- it has the same non-mutating methods and the same indexing
+ and slicing behavior.
+
+ Accordingly, constructor arguments are interpreted as for :func:`buffer`.
+
+ Bytes objects can also be created with literals, see :ref:`strings`.
+
+
.. function:: chr(i)
Return the string of one character whose Unicode codepoint is the integer
Modified: python/branches/py3k-pep3137/Doc/library/stdtypes.rst
==============================================================================
--- python/branches/py3k-pep3137/Doc/library/stdtypes.rst (original)
+++ python/branches/py3k-pep3137/Doc/library/stdtypes.rst Tue Nov 6 13:35:55 2007
@@ -1313,9 +1313,11 @@
Bytes and buffer objects, being "strings of bytes", have all methods found on
strings, with the exception of :func:`encode`, :func:`format` and
-:func:`isidentifier`, which do not make sense with these types. Wherever one of
-these methods needs to interpret the bytes as characters (e.g. the :func:`is...`
-methods), the ASCII character set is assumed.
+:func:`isidentifier`, which do not make sense with these types. For converting
+the objects to strings, they have a :func:`decode` method.
+
+Wherever one of these methods needs to interpret the bytes as characters
+(e.g. the :func:`is...` methods), the ASCII character set is assumed.
.. note::
Modified: python/branches/py3k-pep3137/Doc/library/warnings.rst
==============================================================================
--- python/branches/py3k-pep3137/Doc/library/warnings.rst (original)
+++ python/branches/py3k-pep3137/Doc/library/warnings.rst Tue Nov 6 13:35:55 2007
@@ -81,7 +81,7 @@
| | Unicode. |
+----------------------------------+-----------------------------------------------+
| :exc:`BytesWarning` | Base category for warnings related to |
-| | bytes and buffer. |
+| | :class:`bytes` and :class:`buffer`. |
+----------------------------------+-----------------------------------------------+
More information about the Python-3000-checkins
mailing list