sprockets.clients.http
======================
Simplifies calling HTTP APIs from Tornado-based applications.
This library implements a mix-in class that adds a single method which
makes a HTTP request and calls a callback when an error occurs. The
request is made using Tornado's asynchronous HTTP client so it does
not block the active IO loop.
.. code-block:: python
from sprockets.clients import http
from tornado import gen, web
class MyHandler(http.ClientMixin, web.RequestHandler):
@gen.coroutine
def get(self):
response = yield self.make_http_request(
'GET', some_server_url, on_error=self.handle_api_error)
if self._finished:
yield gen.Return()
# handle response as you wish
# ...
self.finish()
def handle_api_error(self, request, error):
self.send_error(error.code)
That's it. What you do not see is asynchronous client usage and logging
that happens inside of the library. There is some setup code in
``ClientMixin.initialize`` so make sure to call the super implementation
if you implement ``initialize`` in your request handler.
Running Tests
-------------
The test cases use the most excellent httpbin.org site to poke an HTTP API
that responds to errors in a reliable manner. However this can cause failures
if you happen to get rate limited by httpbin.org. If you want to be nice to
the maintainers of httpbin.org, you can run a version in `docker`_ and point
the tests at it instead. The following snippet shows how to do this using
`docker-machine`_ installed via `docker-toolbox`_:
.. code-block:: bash
$ eval "$(docker-machine env default)"
$ machine_id=$(docker run -d -p 8000 citizenstig/httpbin)
$ export HTTPBIN_HOST=$(docker-machine ip default)
$ export HTTPBIN_PORT=$(docker port $machine_id 8000 | cut -d: -f2)
$ env/bin/nosetests
........
----------------------------------------------------------------------
Ran 8 tests in 0.255s
OK
$ docker stop $machine_id | xargs docker rm
.. _docker: https://www.docker.com
.. _docker-machine: https://www.docker.com/products/docker-machine
.. _docker-toolbox: https://www.docker.com/products/docker-toolbox