Merge pull request #1 from wolever/master

Adding documentation and TODO.

README.rst

@@ -16,35 +16,59 @@ Highlights
 Examples
 ========
 
-How to make your own super-simple client API library: ::
+How to make your own super-simple client API library::
 
-    from apiclient import APIClient
+    >>> from apiclient import APIClient
+    >>> class AcmePublicAPI(APIClient):
+    ...    BASE_URL = 'https://localhost:1234/'
+    ...
+    >>>
+    >>> acme_api = AcmePublicAPI()
+    >>> acme_api.call('/hello')
+    {'what': 'world'}
+    >>> acme_api.call('/echo', params={"ping": "pong"})
+    {'ping': 'pong'}
+    >>> 
 
-    class AcmePublicAPI(APIClient):
-        BASE_URL = 'https://localhost:1234/'
 
+How to add rate limiting to your client API library so that we don't exceed 10
+requests per minute::
 
-    acme_api = AcmePublicAPI()
-    r = acme_api.call('/stream') # <- Returns parsed JSON response
+    >>> from apiclient import RateLimiter
+    >>> lock = RateLimiter(max_messages=10, every_seconds=60)
+    >>> acme_api = AcmePublicAPI(rate_limit_lock=lock)
+    >>> # Get the first 100 pages
+    >>> for page in xrange(100):
+    ...     # Whenever our request rate exceeds the specifications of the API's
+    ...     # RateLimiter, the next request will block until the next request window
+    ...     r = acme_api.call('/stream', page=str(page))
 
+For more specific API examples, see the
+`examples/ <https://github.com/shazow/apiclient/blob/master/examples/>`_ directory.
 
-How to add rate limiting to your client API library so that we don't exceed 10
-requests per minute: ::
 
-    from apiclient import RateLimiter
+Extending
+=========
 
-    lock = RateLimiter(max_messages=10, every_seconds=60)
+To handle different calling conventions, ``apiclient`` can be extended through
+subclassing.
 
-    acme_api = AcmePublicAPI(rate_limit_lock=lock)
+For example, if an API requires that all arguments be JSON encoded, the
+``_compose_url`` method could be implemented like this::
 
-    # Get the first 100 pages
-    for page in xrange(100):
-        # Whenever our request rate exceeds the specifications of the API's
-        # RateLimiter, the next request will block until the next request window
-        r = acme_api.call('/stream', page=str(page))
+    >>> class JSONArgsAPIClient(APIClient):
+    ...     def _compose_url(self, path, params=None):
+    ...         if params is not None:
+    ...             params = dict((key, json.dumps(val))
+    ...                            for (key, val) in params.iteritems())
+    ...         return APIClient._compose_url(self, path, params=params)
 
-For more specific API examples, see the
-`examples/ <https://github.com/shazow/apiclient/blob/master/examples/>`_ directory.
+Or if an API returns YAML instead of JSON, the ``_handle_response`` method
+could be overridden::
+
+    >>> class YAMLResponseAPIClient(APIClient):
+    ...     def _handle_response(self, response):
+    ...         return yaml.load(response.data)
 
 
 TODO

apiclient/base.py

@@ -40,6 +40,7 @@ def __init__(self, api_key, *args, **kw):
         self.api_key = api_key
 
     def _compose_url(self, path, params=None):
+        # TODO: fix this, as per our conversation at Oct. 4, 2011, 05:10 UTC
         p = {self.API_KEY_PARAM: self.api_key}
 
         if params: