document xmlfile(buffered=False)

1 files changed, 15 insertions, 3 deletions

diff --git a/doc/api.txt b/doc/api.txt
index e8a975cb..f2b1ec31 100644
--- a/doc/api.txt
+++ b/doc/api.txt
@@ -488,8 +488,8 @@ object, as in the example above.  In the first case, it takes care to
 open and close the file itself, whereas file(-like) objects are not
 closed by default.  This is left to the code that opened them.  Since
 lxml 3.4, however, you can pass the argument ``close=True`` to make
-lxml call the object's ``.close()`` method when exiting the context
-manager.
+lxml call the object's ``.close()`` method when exiting the xmlfile
+context manager.
 
 To insert pre-constructed Elements and subtrees, just pass them
 into ``write()``::
@@ -498,6 +498,7 @@ into ``write()``::
   >>> with etree.xmlfile(f) as xf:
   ...     with xf.element('abc'):
   ...         with xf.element('in'):
+  ...
   ...             for value in '123':
   ...                 # construct a really complex XML tree
   ...                 el = etree.Element('xyz', attr=value)
@@ -512,7 +513,7 @@ into ``write()``::
 
 It is a common pattern to have one or more nested ``element()``
 blocks, and then build in-memory XML subtrees in a loop (using the
-ElementTree API, the builder API, XSLT, or whatever) to write them
+ElementTree API, the builder API, XSLT, or whatever) and write them
 out into the XML file one after the other.  That way, they can be
 removed from memory right after their construction, which can largely
 reduce the memory footprint of an application, while keeping the
@@ -530,6 +531,7 @@ like the instant messaging protocol
                       while True:
                           el = (yield)
                           xf.write(el)
+                          xf.flush()
                   except GeneratorExit:
                       pass
 
@@ -546,6 +548,16 @@ And when done::
 
     w.close()
 
+Note the additional ``xf.flush()`` call in the example above.  Normally,
+the output stream is buffered to avoid excessive I/O calls.  Whenever
+the internal buffer fills up, its content is written out.  In the case
+above, however, we want to make sure that each message that we write
+(i.e. each element subtree) is written out immediately, so we flush the
+content explicitly at the right point.
+
+Alternatively, if buffering is not desired at all, it can be disabled
+by passing the flag ``buffered=False`` into ``xmlfile()``.
+
 
 CDATA
 -----