# HG changeset patch
# Parent  30b6cd2b34401ffabbf7722410fd3f9a1e92777e
Issue #26292: Document the problem with RawIOBase.writelines()

diff -r 30b6cd2b3440 Doc/library/io.rst
--- a/Doc/library/io.rst	Mon Jun 20 14:13:12 2016 +0200
+++ b/Doc/library/io.rst	Mon Jun 20 13:17:49 2016 +0000
@@ -363,6 +363,13 @@
       is usual for each of the lines provided to have a line separator at the
       end.
 
+      For :class:`RawIOBase` subclasses, it is undefined what
+      :meth:`writelines` does if a :meth:`~RawIOBase.write` call does
+      a partial write, or encounters a blocking error and returns ``None``.
+      However, this is not a problem for :class:`BufferedIOBase` and
+      :class:`TextIOBase` subclasses, which never do partial writes,
+      and raise blocking errors as exceptions.
+
    .. method:: __del__()
 
       Prepare for object destruction. :class:`IOBase` provides a default
@@ -524,6 +531,12 @@
       The caller may release or mutate *b* after this method returns,
       so the implementation should only access *b* during the method call.
 
+   .. method:: writelines(lines)
+
+      Write a list of lines to the stream.  :exc:`BlockingIOError` is raised
+      when appropriate, however the value of its
+      :attr:`~BlockingIOError.characters_written` attribute is undefined.
+
 
 Raw File I/O
 ^^^^^^^^^^^^