Merge 7549398 into da1345f

docs/index.rst

@@ -7,6 +7,68 @@ A client for the `Akamai Fast Purge API`_.
    :maxdepth: 2
    :caption: Contents:
 
+- `Source <https://github.com/release-engineering/python-fastpurge>`_
+- `Documentation <https://release-engineering.github.io/python-fastpurge/>`_
+- `PyPI <https://pypi.org/project/fastpurge>`_
+
+Quick Start
+-----------
+
+Install the fastpurge client from PyPI:
+
+::
+
+    pip install fastpurge
+
+Authorize a client in the `Akamai Control Center`_.
+
+Place the client credentials in an `edgerc`_ file located at ``$HOME/.edgerc``;
+this is an INI-style configuration file with the following structure:
+
+::
+
+    [default]
+    host = <Base hostname without the scheme>
+    client_token = <Client token>
+    client_secret = <Secret>
+    access_token = <Access Token>
+
+In your Python code, construct a ``FastPurgeClient`` and call the
+purge methods.  Make sure to block on the returned ``Future``
+if you want to wait for the purge to complete.
+
+.. code-block:: python
+
+    from fastpurge import FastPurgeClient
+    client = FastPurgeClient()
+
+    # start a purge of two URLs
+    future = client.purge_by_url(["https://example.com/resource1",
+                                  "https://example.com/resource2"])
+
+    # wait for the purge to complete (or raise if purge fails)
+    future.result()
+
+Usage of ``$HOME/.edgerc`` for credentials is a convention supported
+by other clients in the Akamai ecosystem.  If you'd like to configure
+the credentials separately, you can pass them to the client constructor
+explicitly, as in example:
+
+.. code-block:: python
+
+    from fastpurge import FastPurgeClient
+    client = FastPurgeClient({
+        # The entries from ~/.edgerc can be supplied directly here
+        "host": "akaa-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net",
+        "client_token": "akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx",
+        "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+        "access_token": "akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx",
+    })
+
+
+API Reference
+-------------
+
 .. autoclass:: fastpurge.FastPurgeClient(auth=None, scheme='https', port=443)
    :members: purge_by_url, purge_by_tag, purge_by_cpcode
 
@@ -15,4 +77,6 @@ A client for the `Akamai Fast Purge API`_.
 .. autoclass:: fastpurge.FastPurgeError
    :members:
 
+.. _Akamai Control Center: https://developer.akamai.com/legacy/introduction/Luna_Setup.html
 .. _Akamai Fast Purge API: https://developer.akamai.com/api/core_features/fast_purge/v3.html
+.. _edgerc: https://developer.akamai.com/legacy/introduction/Conf_Client.html

fastpurge/_client.py

@@ -25,7 +25,9 @@
 
 
 class FastPurgeError(RuntimeError):
-    """An error raised during a Fast Purge operation."""
+    """Raised when the Fast Purge API reports an error.
+
+    The exception message contains a summary of the error encountered."""
 
 
 class FastPurgeClient(object):
@@ -259,7 +261,7 @@ def purge_objects(self, object_type, objects, **kwargs):
 
                 result:
                     If a purge succeeds, the result is a list of responses from the
-                    Fast Purge API (:class:`dict`). See the Akamai Fast Purge documentation
+                    Fast Purge API (:class:`dict`). See the `fast purge resources`_
                     for the expected fields in the response.
 
                     Typically, the result would contain only a single response object.
@@ -274,6 +276,8 @@ def purge_objects(self, object_type, objects, **kwargs):
                     If purge(s) fail, an exception will be set; typically, though
                     not always, an instance of :class:`FastPurgeError`.
 
+        .. _fast purge resources:
+           https://developer.akamai.com/api/core_features/fast_purge/v3.html#resources
         .. _fast purge concepts:
            https://developer.akamai.com/api/core_features/fast_purge/v3.html#concepts
         """