mirror of
https://github.com/python/cpython.git
synced 2025-08-04 08:59:19 +00:00
reformat some documentation of classes so methods and attributes are under the class directive
This commit is contained in:
Benjamin Peterson
parent
1c596d5604
commit
c7b05920d6
42 changed files with 3690 additions and 3562 deletions
|
|
@ -435,16 +435,16 @@ define in order to be compatible with the Python codec registry.
|
|||
:func:`register_error`.
|
||||
|
||||
|
||||
.. method:: IncrementalEncoder.encode(object[, final])
|
||||
.. method:: encode(object[, final])
|
||||
|
||||
Encodes *object* (taking the current state of the encoder into account) and
|
||||
returns the resulting encoded object. If this is the last call to :meth:`encode`
|
||||
*final* must be true (the default is false).
|
||||
Encodes *object* (taking the current state of the encoder into account)
|
||||
and returns the resulting encoded object. If this is the last call to
|
||||
:meth:`encode` *final* must be true (the default is false).
|
||||
|
||||
|
||||
.. method:: IncrementalEncoder.reset()
|
||||
.. method:: reset()
|
||||
|
||||
Reset the encoder to the initial state.
|
||||
Reset the encoder to the initial state.
|
||||
|
||||
|
||||
.. _incremental-decoder-objects:
|
||||
|
|
@ -483,20 +483,21 @@ define in order to be compatible with the Python codec registry.
|
|||
:func:`register_error`.
|
||||
|
||||
|
||||
.. method:: IncrementalDecoder.decode(object[, final])
|
||||
.. method:: decode(object[, final])
|
||||
|
||||
Decodes *object* (taking the current state of the decoder into account) and
|
||||
returns the resulting decoded object. If this is the last call to :meth:`decode`
|
||||
*final* must be true (the default is false). If *final* is true the decoder must
|
||||
decode the input completely and must flush all buffers. If this isn't possible
|
||||
(e.g. because of incomplete byte sequences at the end of the input) it must
|
||||
initiate error handling just like in the stateless case (which might raise an
|
||||
exception).
|
||||
Decodes *object* (taking the current state of the decoder into account)
|
||||
and returns the resulting decoded object. If this is the last call to
|
||||
:meth:`decode` *final* must be true (the default is false). If *final* is
|
||||
true the decoder must decode the input completely and must flush all
|
||||
buffers. If this isn't possible (e.g. because of incomplete byte sequences
|
||||
at the end of the input) it must initiate error handling just like in the
|
||||
stateless case (which might raise an exception).
|
||||
|
||||
|
||||
.. method:: IncrementalDecoder.reset()
|
||||
.. method:: reset()
|
||||
|
||||
Reset the decoder to the initial state.
|
||||
|
||||
Reset the decoder to the initial state.
|
||||
|
||||
The :class:`StreamWriter` and :class:`StreamReader` classes provide generic
|
||||
working interfaces which can be used to implement new encoding submodules very
|
||||
|
|
@ -544,24 +545,25 @@ compatible with the Python codec registry.
|
|||
:func:`register_error`.
|
||||
|
||||
|
||||
.. method:: StreamWriter.write(object)
|
||||
.. method:: write(object)
|
||||
|
||||
Writes the object's contents encoded to the stream.
|
||||
Writes the object's contents encoded to the stream.
|
||||
|
||||
|
||||
.. method:: StreamWriter.writelines(list)
|
||||
.. method:: writelines(list)
|
||||
|
||||
Writes the concatenated list of strings to the stream (possibly by reusing the
|
||||
:meth:`write` method).
|
||||
Writes the concatenated list of strings to the stream (possibly by reusing
|
||||
the :meth:`write` method).
|
||||
|
||||
|
||||
.. method:: StreamWriter.reset()
|
||||
.. method:: reset()
|
||||
|
||||
Flushes and resets the codec buffers used for keeping state.
|
||||
Flushes and resets the codec buffers used for keeping state.
|
||||
|
||||
Calling this method should ensure that the data on the output is put into
|
||||
a clean state that allows appending of new fresh data without having to
|
||||
rescan the whole stream to recover state.
|
||||
|
||||
Calling this method should ensure that the data on the output is put into a
|
||||
clean state that allows appending of new fresh data without having to rescan the
|
||||
whole stream to recover state.
|
||||
|
||||
In addition to the above methods, the :class:`StreamWriter` must also inherit
|
||||
all other methods and attributes from the underlying stream.
|
||||
|
|
@ -604,64 +606,68 @@ compatible with the Python codec registry.
|
|||
:func:`register_error`.
|
||||
|
||||
|
||||
.. method:: StreamReader.read([size[, chars, [firstline]]])
|
||||
.. method:: read([size[, chars, [firstline]]])
|
||||
|
||||
Decodes data from the stream and returns the resulting object.
|
||||
Decodes data from the stream and returns the resulting object.
|
||||
|
||||
*chars* indicates the number of characters to read from the stream. :func:`read`
|
||||
will never return more than *chars* characters, but it might return less, if
|
||||
there are not enough characters available.
|
||||
*chars* indicates the number of characters to read from the
|
||||
stream. :func:`read` will never return more than *chars* characters, but
|
||||
it might return less, if there are not enough characters available.
|
||||
|
||||
*size* indicates the approximate maximum number of bytes to read from the stream
|
||||
for decoding purposes. The decoder can modify this setting as appropriate. The
|
||||
default value -1 indicates to read and decode as much as possible. *size* is
|
||||
intended to prevent having to decode huge files in one step.
|
||||
*size* indicates the approximate maximum number of bytes to read from the
|
||||
stream for decoding purposes. The decoder can modify this setting as
|
||||
appropriate. The default value -1 indicates to read and decode as much as
|
||||
possible. *size* is intended to prevent having to decode huge files in
|
||||
one step.
|
||||
|
||||
*firstline* indicates that it would be sufficient to only return the first line,
|
||||
if there are decoding errors on later lines.
|
||||
*firstline* indicates that it would be sufficient to only return the first
|
||||
line, if there are decoding errors on later lines.
|
||||
|
||||
The method should use a greedy read strategy meaning that it should read as much
|
||||
data as is allowed within the definition of the encoding and the given size,
|
||||
e.g. if optional encoding endings or state markers are available on the stream,
|
||||
these should be read too.
|
||||
The method should use a greedy read strategy meaning that it should read
|
||||
as much data as is allowed within the definition of the encoding and the
|
||||
given size, e.g. if optional encoding endings or state markers are
|
||||
available on the stream, these should be read too.
|
||||
|
||||
.. versionchanged:: 2.4
|
||||
*chars* argument added.
|
||||
.. versionchanged:: 2.4
|
||||
*chars* argument added.
|
||||
|
||||
.. versionchanged:: 2.4.2
|
||||
*firstline* argument added.
|
||||
.. versionchanged:: 2.4.2
|
||||
*firstline* argument added.
|
||||
|
||||
|
||||
.. method:: StreamReader.readline([size[, keepends]])
|
||||
.. method:: readline([size[, keepends]])
|
||||
|
||||
Read one line from the input stream and return the decoded data.
|
||||
Read one line from the input stream and return the decoded data.
|
||||
|
||||
*size*, if given, is passed as size argument to the stream's :meth:`readline`
|
||||
method.
|
||||
*size*, if given, is passed as size argument to the stream's
|
||||
:meth:`readline` method.
|
||||
|
||||
If *keepends* is false line-endings will be stripped from the lines returned.
|
||||
If *keepends* is false line-endings will be stripped from the lines
|
||||
returned.
|
||||
|
||||
.. versionchanged:: 2.4
|
||||
*keepends* argument added.
|
||||
.. versionchanged:: 2.4
|
||||
*keepends* argument added.
|
||||
|
||||
|
||||
.. method:: StreamReader.readlines([sizehint[, keepends]])
|
||||
.. method:: readlines([sizehint[, keepends]])
|
||||
|
||||
Read all lines available on the input stream and return them as a list of lines.
|
||||
Read all lines available on the input stream and return them as a list of
|
||||
lines.
|
||||
|
||||
Line-endings are implemented using the codec's decoder method and are included
|
||||
in the list entries if *keepends* is true.
|
||||
Line-endings are implemented using the codec's decoder method and are
|
||||
included in the list entries if *keepends* is true.
|
||||
|
||||
*sizehint*, if given, is passed as the *size* argument to the stream's
|
||||
:meth:`read` method.
|
||||
*sizehint*, if given, is passed as the *size* argument to the stream's
|
||||
:meth:`read` method.
|
||||
|
||||
|
||||
.. method:: StreamReader.reset()
|
||||
.. method:: reset()
|
||||
|
||||
Resets the codec buffers used for keeping state.
|
||||
Resets the codec buffers used for keeping state.
|
||||
|
||||
Note that no stream repositioning should take place. This method is
|
||||
primarily intended to be able to recover from decoding errors.
|
||||
|
||||
Note that no stream repositioning should take place. This method is primarily
|
||||
intended to be able to recover from decoding errors.
|
||||
|
||||
In addition to the above methods, the :class:`StreamReader` must also inherit
|
||||
all other methods and attributes from the underlying stream.
|
||||
|
|
@ -730,6 +736,7 @@ The design is such that one can use the factory functions returned by the
|
|||
Error handling is done in the same way as defined for the stream readers and
|
||||
writers.
|
||||
|
||||
|
||||
:class:`StreamRecoder` instances define the combined interfaces of
|
||||
:class:`StreamReader` and :class:`StreamWriter` classes. They inherit all other
|
||||
methods and attributes from the underlying stream.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue