M.-A. Lemburg <mal@lemburg.com>:
Added more documentation. Clarified some existing comments.
diff --git a/Lib/codecs.py b/Lib/codecs.py
index 917fc25..fff8ed7 100644
--- a/Lib/codecs.py
+++ b/Lib/codecs.py
@@ -231,10 +231,13 @@
""" Read one line from the input stream and return the
decoded data.
- Note: Unlike the .readlines() method, line breaking must
- be implemented by the underlying stream's .readline()
- method -- there is currently no support for line breaking
- using the codec decoder due to lack of line buffering.
+ Note: Unlike the .readlines() method, this method inherits
+ the line breaking knowledge from the underlying stream's
+ .readline() method -- there is currently no support for
+ line breaking using the codec decoder due to lack of line
+ buffering. Sublcasses should however, if possible, try to
+ implement this method using their own knowledge of line
+ breaking.
size, if given, is passed as size argument to the stream's
.readline() method.
@@ -288,6 +291,14 @@
class StreamReaderWriter:
+ """ StreamReaderWriter instances allow wrapping streams which
+ work in both read and write modes.
+
+ The design is such that one can use the factory functions
+ returned by the codec.lookup() function to contruct the
+ instance.
+
+ """
# Optional attributes set by the file wrappers below
encoding = 'unknown'
@@ -346,6 +357,21 @@
class StreamRecoder:
+ """ StreamRecoder instances provide a frontend - backend
+ view of encoding data.
+
+ They use the complete set of APIs returned by the
+ codecs.lookup() function to implement their task.
+
+ Data written to the stream is first decoded into an
+ intermediate format (which is dependent on the given codec
+ combination) and then written to the stream using an instance
+ of the provided Writer class.
+
+ In the other direction, data is read from the stream using a
+ Reader instance and then return encoded data to the caller.
+
+ """
# Optional attributes set by the file wrappers below
data_encoding = 'unknown'
file_encoding = 'unknown'
@@ -452,6 +478,11 @@
buffering has the same meaning as for the builtin open() API.
It defaults to line buffered.
+ The returned wrapped file object provides an extra attribute
+ .encoding which allows querying the used encoding. This
+ attribute is only available if an encoding was specified as
+ parameter.
+
"""
if encoding is not None and \
'b' not in mode:
@@ -488,6 +519,11 @@
data_encoding and file_encoding are added to the wrapped file
object as attributes .data_encoding and .file_encoding resp.
+ The returned wrapped file object provides two extra attributes
+ .data_encoding and .file_encoding which reflect the given
+ parameters of the same name. The attributes can be used for
+ introspection by Python programs.
+
"""
if file_encoding is None:
file_encoding = data_encoding