diff --git a/README.md b/README.md index 81b0a16..a15d972 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,9 @@ Devourer is a generic REST API client for Python 2.7 and 3.3+. You can also subclass it to wrap a set of system calls, FFI or a messy dependency. It features an object-oriented, declarative approach to simplify the communication. -It depends on the brilliant requests package as the gateway to API server. A simple example: +It depends on the brilliant requests package as the gateway to API server. + +### Basic usage ```python from devourer import GenericAPI, APIMethod, APIError @@ -45,6 +47,27 @@ The init function gives details so you don't need to repeat them elsewhere, enab raising exceptions on error. You can also obtain raw string with `load_json=False` and silence errors getting None instead when they happen with `throw_on_error=False`. +### Async usage + +If you want to use non-blocking calls, put following attribute in API class declaration: + +```python +class AsyncTestApi(GenericAPI): + generate_async_methods = True + posts = APIMethod('get', 'posts/') +``` + +This will generate additional async method for each defined APIMethod attribute, appending '_async' to the name. +In the above example, two methods will be generated: `posts()` and `posts_async()`. The former one returns parsed +JSON or string containing API response, while the latter returns AsyncRequest object, which can be later queried for +the result: + +```python +api = AsyncTestApi() +posts_r = api.posts_async() # send HTTP request, but don't block +posts = posts_r.result() # retrieve result, blocking if the request hasn't finished yet +``` + Installation ------------ You can just `pip install devourer`. diff --git a/setup.py b/setup.py index 4c56a3a..0248f4f 100644 --- a/setup.py +++ b/setup.py @@ -3,9 +3,10 @@ setup( name='devourer', packages=['devourer'], - version='0.3.2', + version='0.3.3', install_requires=[ 'requests', + 'gevent', 'six', ], description='Devourer is a generic API client.' @@ -13,7 +14,7 @@ author='Bonnier Business Polska / Krzysztof Bujniewicz', author_email='racech@gmail.com', url='https://github.com/bonnierpolska/devourer', - download_url='https://github.com/bonnierpolska/devourer/tarball/0.3.2', + download_url='https://github.com/bonnierpolska/devourer/tarball/0.3.3', keywords=['api', 'generic api', 'api client'], classifiers=[] )