Skip to main content
Join the official 2020 Python Developers SurveyStart the survey!

Service Client Framework powered by Python asyncio.

Project description

|travis-master| |coverall-master| |doc-master| |pypi-downloads| |pypi-lastrelease| |python-versions|
|project-status| |project-license| |project-format| |project-implementation|

.. |travis-master| image::

.. |coverall-master| image::

.. |doc-master| image::
:alt: Documentation Status

.. |pypi-downloads| image::
:alt: Downloads

.. |pypi-lastrelease| image::
:alt: Latest Version

.. |python-versions| image::
:alt: Supported Python versions

.. |project-status| image::
:alt: Development Status

.. |project-license| image::
:alt: License

.. |project-format| image::
:alt: Download format

.. |project-implementation| image::
:alt: Supported Python implementations

Service Client Framework

Service Client Framework powered by Python asyncio.

The easiest way to implement a client to work with a service REST API.


- Easy way to make request to service.
- AsyncIO implementation using aiohttp.
- Powerful plugin system.
- Useful plugins.
- Mock plugin in order to make tests.
- Opensource license: GNU LGPLv3


.. code-block:: bash

$ pip install aio-service-client

Getting started

Service client framework is used to call HTTP service API's. So, you must define how to
communicate with this service API defining its endpoint:

.. code-block:: python

spec = {"get_users": {"path": "/user",
"method": "get"},
"get_user_detail": {"path": "/user/{user_id}",
"method": "get"},
"create_user": {"path": "/user",
"method": "post"},
"update_user": {"path": "/user/{user_id}",
"method": "put"}}

Imagine you are using a Rest JSON API in order to manage users. So, your data must be sent
as a JSON and response must be a JSON string. It mean you must serialize every request payload
to a JSON, and parse every response as JSON. So, you only need to define JSON parser and serializer
for your service:

.. code-block:: python

service = ServiceClient(spec=spec,

So, you are ready to make request to service API:

.. code-block:: python

resp = yield from"get_users")
# it could be called directly
# resp = yield from service.get_users()

# if response is like:
# {"users": {"item": [{"userId": "12", "username": "foo"}, {"userId": "13", "username": "bar"}], "count": 2}
print("Count: %d" %['users']['count'])
for user in['users']['items']:
print("User `%s`: %s" % (user['userId'], user['username']))

In order to send a payload you must use ``payload`` keyword on call:

.. code-block:: python

resp = yield from"create_user", payload={"username": "foobar"})
# it could be called directly
# resp = yield from service.create_user(payload={"username": "foobar"})

# it will make a request like:
# {"username": "foobar"}



- Pool plugin now add ``blocked_by_pool`` attribute to session containing elapsed time (seconds) on pool. It allows
to log this time using log plugins.

- RateLimit plugin now add ``blocked_by_ratelimit`` attribute to session containing elapsed time (seconds) blocked by
rate limit. It allows to log this time using log plugins.

- Tests improved.

- Added new exceptions: :class:`~service_client.plugins.TooManyRequestsPendingError` and

- Added decorator in order to help to build service clients. It allows to define a method using a request model
but to call it using keywords to build request model which will be used to call method.

.. code-block:: python

class RequestModel:
def __init__(param_1=None):
self.param_1 = param_1

class Service:

async def method_1(request: RequestModel):
return do_something(request)

serv = Service()
await serv.method_1(param_1=23)


- Improved Pool plugin. It now allows to set hard limit of pending requests, if it reach limit requests will
fail raising :class:`RequestLimitError`. In same way, it allows to set a timeout, in seconds, for pending requests and
it will raise same exception.

- Added new RateLimit plugin. It is similar to Pool plugin but using a period parameter, in seconds, in order to limit number
of request in this period.

- Improved error logging.

- Added new hook ``close`` in order to notify plugins that client is going to close.

- Removed compatibility with Python 3.4.


- Made compatible with aiohttp 2.0.x.


- Made compatible with aiohttp 1.0.x.
- Simplified factory code.


- Resolved problem with requests streamed.


- Added factories
- Added spec loaders


- Fix elapsed data on logs.


- Added new ``Pool`` plugin.
- Improved ``Elapsed`` plugin.
- Added new hook in order to allow plugins to override response methods.


- Fix response when using Timeout plugin.


- Added TrackingToken plugin. Token is added to session and to response.
- Added a log formatter.
- Removed tracking token stuff from log plugins.
- Improved log plugins. They avoid to print body if it is streamed or must be hidden.
- Improved session wrapper.



It allows to fill placeholders on path in order to build uri.

.. code-block:: python

service = ServiceClient(spec={"endpoint1": {"method": "get",
"path": "/endpoint/{placeholder1}/{placeholder2}"}},

resp = yield from"endpoint1", placeholder1=21, placeholder1="foo")
# It will make request:


It allows to define default headers, endpoint headers and request headers.

.. code-block:: python

service = ServiceClient(spec={"endpoint1": {"method": "get",
"path": "/endpoint/foo/bar",
"headers": {"X-fake-header": "header; data"}}},
plugins=[Headers(headers={"content-type": "application/json"})],

resp = yield from"endpoint1", headers={"X-other-fake-header": "foo"})
# It will make request:
# X-fake-header: header; data
# content-type: application/json
# X-other-fake-header: foo


It allows to define default timeout for service request, endpoint or request.


It adds elapsed time to response.


It allows to assign a token for each pair request/response in order to identify them.


It allows to use query parameters on request. They could be defined at service client, endpoint or request.


It allows to log request after serialize and response before parse.


It allows to log request before serialize and response after parse.


It allows to limit concurrent requests. Besides it allows to set a hard limit of pending requests and a timeout
for blocked ones.


It allows to limit number of requests in a time period. Besides it allows to set a hard limit of
pending requests and a timeout for blocked ones.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for aio-service-client, version 0.7.0
Filename, size File type Python version Upload date Hashes
Filename, size aio-service-client-0.7.0.tar.gz (13.4 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page