add invalidation section to CF docs

1 files changed, 84 insertions, 0 deletions

diff --git a/docs/source/cloudfront_tut.rst b/docs/source/cloudfront_tut.rst
index f0104598..3c7a418d 100644
--- a/docs/source/cloudfront_tut.rst
+++ b/docs/source/cloudfront_tut.rst
@@ -93,3 +93,87 @@ comment, enabled and cnames.
 To delete a :class:`boto.cloudfront.distribution.Distribution`::
 
     >>> distro.delete()
+
+Invalidating CloudFront Distribution Paths
+------------------------------------------
+Invalidate a list of paths in a CloudFront distribution::
+
+    >>> paths = ['/path/to/file1.html', '/path/to/file2.html', ...]
+    >>> inval_req = c.create_invalidation_request(u'ECH69MOIW7613', paths)
+    >>> print inval_req
+    <InvalidationBatch: IFCT7K03VUETK>
+    >>> print inval_req.id
+    u'IFCT7K03VUETK'
+    >>> print inval_req.paths
+    [u'/path/to/file1.html', u'/path/to/file2.html', ..]
+
+.. warning::
+
+    Each CloudFront invalidation request can only specify up to 1000 paths. If
+    you need to invalidate more than 1000 paths you will need to split up the
+    paths into groups of 1000 or less and create multiple invalidation requests.
+
+This will return a :class:`boto.cloudfront.invalidation.InvalidationBatch`
+object representing the invalidation request. You can also fetch a single
+invalidaton request for a given distribution using
+``invalidation_request_status``::
+
+    >>> inval_req = c.invalidation_request_status(u'ECH69MOIW7613', u'IFCT7K03VUETK')
+    >>> print inval_req
+    <InvalidationBatch: IFCT7K03VUETK>
+
+The first parameter is the CloudFront distribution id the request belongs to
+and the second parameter is the invalidation request id.
+
+It's also possible to get *all* invalidations for a given CloudFront
+distribution::
+
+    >>> invals = c.get_invalidation_requests(u'ECH69MOIW7613')
+    >>> print invals
+    <boto.cloudfront.invalidation.InvalidationListResultSet instance at 0x15d28d0>
+
+This will return an instance of
+:class:`boto.cloudfront.invalidation.InvalidationListResultSet` which is an
+iterable object that contains a list of
+:class:`boto.cloudfront.invalidation.InvalidationSummary` objects that describe
+each invalidation request and its status::
+
+    >>> for inval in invals:
+    >>>     print 'Object: %s, ID: %s, Status: %s' % (inval, inval.id, inval.status)
+    Object: <InvalidationSummary: ICXT2K02SUETK>, ID: ICXT2K02SUETK, Status: Completed
+    Object: <InvalidationSummary: ITV9SV0PDNY1Y>, ID: ITV9SV0PDNY1Y, Status: Completed
+    Object: <InvalidationSummary: I1X3F6N0PLGJN5>, ID: I1X3F6N0PLGJN5, Status: Completed
+    Object: <InvalidationSummary: I1F3G9N0ZLGKN2>, ID: I1F3G9N0ZLGKN2, Status: Completed
+    ...
+
+Simply iterating over the
+:class:`boto.cloudfront.invalidation.InvalidationListResultSet` object will
+automatically paginate the results on-the-fly as needed by repeatedly
+requesting more results from CloudFront until there are none left.
+
+If you wish to paginate the results manually you can do so by specifying the
+``max_items`` option when calling ``get_invalidation_requests``::
+
+    >>> invals = c.get_invalidation_requests(u'ECH69MOIW7613', max_items=2)
+    >>> print len(list(invals))
+    2
+    >>> for inval in invals:
+    >>>     print 'Object: %s, ID: %s, Status: %s' % (inval, inval.id, inval.status)
+    Object: <InvalidationSummary: ICXT2K02SUETK>, ID: ICXT2K02SUETK, Status: Completed
+    Object: <InvalidationSummary: ITV9SV0PDNY1Y>, ID: ITV9SV0PDNY1Y, Status: Completed
+
+In this case, iterating over the
+:class:`boto.cloudfront.invalidation.InvalidationListResultSet` object will
+*only* make a single request to CloudFront and *only* ``max_items``
+invalidation requests are returned by the iterator. To get the next "page" of
+results pass the ``next_marker`` attribute of the previous
+:class:`boto.cloudfront.invalidation.InvalidationListResultSet` object as the
+``marker`` option to the next call to ``get_invalidation_requests``::
+
+    >>> invals = c.get_invalidation_requests(u'ECH69MOIW7613', max_items=10, marker=invals.next_marker)
+    >>> print len(list(invals))
+    2
+    >>> for inval in invals:
+    >>>     print 'Object: %s, ID: %s, Status: %s' % (inval, inval.id, inval.status)
+    Object: <InvalidationSummary: I1X3F6N0PLGJN5>, ID: I1X3F6N0PLGJN5, Status: Completed
+    Object: <InvalidationSummary: I1F3G9N0ZLGKN2>, ID: I1F3G9N0ZLGKN2, Status: Completed