From c7fa81ccf53d9e9cca5a3fa786227ce37487b299 Mon Sep 17 00:00:00 2001 From: Brant Watson Date: Mon, 24 Oct 2016 07:06:12 -0500 Subject: [PATCH] Add more example documentation --- docs/ioutils.rst | 35 +++++++++++++++++++++++++++-------- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/docs/ioutils.rst b/docs/ioutils.rst index b304182..8737949 100644 --- a/docs/ioutils.rst +++ b/docs/ioutils.rst @@ -31,14 +31,33 @@ SpooledStringIO .. autoclass:: boltons.ioutils.SpooledStringIO -Example -------- -A good use case is downloading a file from some remote location. It's nice to -keep it in memory if it's small, but writing a large file into memory can make -servers quite grumpy. If the file being downloaded happens to be a zip file -then things are worse. You can't use a normal SpooledTemporaryFile because it -isn't compatible. A :ref:`spooledbytesio` instance is a good alternative. Here -is a simple example using the requests library to download a zip file:: +Examples +-------- +It's not uncommon to find excessive usage of StringIO in older Python code. A +SpooledTemporaryFile would be a nice replacement if one wanted to reduce memory +overhead, but unfortunately it's api differs too much. This is a good candidate +for :ref:`spooledbytesio` as it is api compatible and thus may be used as a +drop-in replacement. + +Old Code:: + + flo = StringIO() + flo.write(gigantic_string) + +Updated:: + + from boltions.ioutils import SpooledBytesIO + + flo = SpooledBytesIO() + flo.write(gigantic_string) + + +Another good use case is downloading a file from some remote location. It's +nice to keep it in memory if it's small, but writing a large file into memory +can make servers quite grumpy. If the file being downloaded happens to be a zip +file then things are worse. You can't use a normal SpooledTemporaryFile because +it isn't compatible. A :ref:`spooledbytesio` instance is a good alternative. +Here is a simple example using the requests library to download a zip file:: from zipfile import ZipFile