[Python-checkins] CVS: python/dist/src/Lib codecs.py,1.7,1.8

[Fred Drake]

Update of /projects/cvsroot/python/dist/src/Lib
In directory seahag.cnri.reston.va.us:/home/fdrake/projects/python/Lib

Modified Files:
	codecs.py 
Log Message:

M.-A. Lemburg <mal@lemburg.com>:

Added more documentation. Clarified some existing comments.


Index: codecs.py
===================================================================
RCS file: /projects/cvsroot/python/dist/src/Lib/codecs.py,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -r1.7 -r1.8
*** codecs.py	2000/04/11 15:41:38	1.7
--- codecs.py	2000/04/13 14:11:21	1.8
***************
*** 232,239 ****
              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.
  
              size, if given, is passed as size argument to the stream's
--- 232,242 ----
              decoded data.
  
!             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
***************
*** 289,292 ****
--- 292,303 ----
  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'
***************
*** 347,350 ****
--- 358,376 ----
  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'
***************
*** 453,456 ****
--- 479,487 ----
          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 \
***************
*** 488,491 ****
--- 519,527 ----
          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.
  
      """