Allow to stream the downloads when appropriate

Some API calls will download possibly large data, resulting in a high
memory usage and out-of-memory errors. For these API calls use the
requests streaming capabilities and download chunked data. The caller is
responsible of providing a callable to actually store the data.

The default callable just prints the data on stdout.

2 files changed, 25 insertions, 2 deletions

diff --git a/docs/gl_objects/builds.py b/docs/gl_objects/builds.py
index 4b663c6..c535cb2 100644
--- a/docs/gl_objects/builds.py
+++ b/docs/gl_objects/builds.py
@@ -77,6 +77,19 @@ project.builds.get(build_id)
 build.artifacts()
 # end artifacts
 
+# stream artifacts
+class Foo(object):
+    def __init__(self):
+        self._fd = open('artifacts.zip', 'w')
+
+    def __call__(self, chunk):
+        self._fd.write(chunk)
+
+target = Foo()
+build.artifacts(streamed=True, streamed=True, action=target)
+del(target)  # flushes data on disk
+# end stream artifacts
+
 # keep artifacts
 build.keep_artifacts()
 # end keep artifacts
diff --git a/docs/gl_objects/builds.rst b/docs/gl_objects/builds.rst
index 23f47f0..ce4cc0e 100644
--- a/docs/gl_objects/builds.rst
+++ b/docs/gl_objects/builds.rst
@@ -116,7 +116,16 @@ Get a build artifacts:
 
 .. warning::
 
-   Artifacts are entirely stored in memory.
+   Artifacts are entirely stored in memory in this example.
+
+.. _streaming_example:
+
+You can download artifacts as a stream. Provide a callable to handle the
+stream:
+
+.. literalinclude:: builds.py
+   :start-after: # stream artifacts
+   :end-before: # end stream artifacts
 
 Mark a build artifact as kept when expiration is set:
 
@@ -132,7 +141,8 @@ Get a build trace:
 
 .. warning::
 
-   Traces are entirely stored in memory.
+   Traces are entirely stored in memory unless you use the streaming feature.
+   See :ref:`the artifacts example <streaming_example>`.
 
 Cancel/retry a build: