apipool 0.0.2
Multiple API Key Manager
License: MIT

.. image:: https://travis-ci.org/MacHu-GWU/apipool-project.svg?branch=master
    :target: https://travis-ci.org/MacHu-GWU/apipool-project?branch=master

.. image:: https://codecov.io/gh/MacHu-GWU/apipool-project/branch/master/graph/badge.svg
  :target: https://codecov.io/gh/MacHu-GWU/apipool-project

.. image:: https://img.shields.io/pypi/v/apipool.svg
    :target: https://pypi.python.org/pypi/apipool

.. image:: https://img.shields.io/pypi/l/apipool.svg
    :target: https://pypi.python.org/pypi/apipool

.. image:: https://img.shields.io/pypi/pyversions/apipool.svg
    :target: https://pypi.python.org/pypi/apipool

.. image:: https://img.shields.io/badge/Star_Me_on_GitHub!--None.svg?style=social
    :target: https://github.com/MacHu-GWU/apipool-project


Welcome to ``apipool`` Documentation
==============================================================================

``apipool`` allows developer manipulate multi api key at same time. For example, if single api key has 1k/day quota, then you can register 10 api keys, and let ``apipool`` to automatically rotate the key.


**Features**:

- automatically rotate apikey.
- built-in usage statistics, easy to search by ``time``, ``status``, ``apikey``. You can deploy stats collector on any cloud relational database.
- clean api, minimal code is required to implement complex feature.


**Example**:

there's a google geocoding example at: https://github.com/MacHu-GWU/apipool-project/blob/master/examples/google_geocoding.py


**Tutorial**

Let's walk through with a twitter api example, the api client we use is ``python-twitter``: https://github.com/bear/python-twitter.

The ``python-twitter`` usage:

.. code-block:: python

    import twitter

    # create api client
    api = twitter.Api(
        consumer_key="consumer_key"z,
        consumer_secret="consumer_secret",
        access_token_key="access_token",
        access_token_secret="access_token_secret",
    )

    # make api call
    statuses = api.GetUserTimeline(screen_name="trump")


The ``apipool`` usage:

.. code-block:: python

    import twitter
    from apipool import ApiKey, ApiKeyManager

    class TwitterApiKey(ApiKey):
        def __init__(self,
                     consumer_key,
                     consumer_secret,
                     access_token_key,
                     access_token_secret)
            self.consumer_key = consumer_key
            self.consumer_secret = consumer_secret
            self.access_token_key = access_token_key
            self.access_token_secret = access_token_secret

        def user_01_get_primary_key(self):
            return self.access_token_key

        def user_02_create_client(self):
            return twitter.Api(
                consumer_key=self.consumer_key,
                consumer_secret=self.consumer_secret,
                access_token_key=self.access_token_key,
                access_token_secret=self.access_token_secret,
            )

        def user_03_test_usable(self, client):
            statuses = client.GetUserTimeline(screen_name="trump")
            if len(statuses) >= 5:
                return True
            else:
                return False

    apikey_data_list = [
        {
            "consumer_key": xxx,
            "consumer_secret": xxx,
            "access_token_key": xxx,
            "access_token_secret": xxx,
        },
        {...},
        {...},
    ]

    apikey_list = [
        TwitterApiKey(**apikey_data)
        for apikey_data in apikey_data_list
    ]

    manager = ApiKeyManager(apikey_list=apikey_list)


**DummyClient**:

now we can use the ``manager.dummyclient`` object like how we use the ``twitter.Api()`` object. However, the apikey is automatically rotated, and usage events are also automatically recorded.

.. code-block:: python

    manager.check_usable()

    # the api key is automatically rotated under the hood
    statuses = manager.dummyclient.GetUserTimeline(screen_name="trump")

    for _ in range(10):
        manager.dummyclient.GetUserTimeline(screen_name="trump")


**StatsCollector**:

now we can use ``manager.stats`` object to access usage stats, and also query usage events.

.. code-block:: python

    >>> manager.stats.usage_count_stats_in_recent_n_seconds()
    {"xxx access_token_key": 3, "xxx access_token_key": 4, "xxx access_token_key": 3}

    >>> from apipool import StatusCollection
    >>> events_list = list(manager.stats.query_event_in_recent_n_seconds(
        n_seconds=24*3600,
        status_id=StatusCollection.c1_Success.id,
    ))
    >>> events_list
    [
        Event(apikey_id=xxx, finished_at=datetime(xxx), status_id=xxx),
        Event(...),
        ...
    ]


Quick Links
------------------------------------------------------------------------------
- .. image:: https://img.shields.io/badge/Link-Document-red.svg
      :target: https://apipool.readthedocs.io/index.html

- .. image:: https://img.shields.io/badge/Link-API_Reference_and_Source_Code-red.svg
      :target: https://apipool.readthedocs.io/py-modindex.html

- .. image:: https://img.shields.io/badge/Link-Install-red.svg
      :target: `install`_

- .. image:: https://img.shields.io/badge/Link-GitHub-blue.svg
      :target: https://github.com/MacHu-GWU/apipool-project

- .. image:: https://img.shields.io/badge/Link-Submit_Issue_and_Feature_Request-blue.svg
      :target: https://github.com/MacHu-GWU/apipool-project/issues

- .. image:: https://img.shields.io/badge/Link-Download-blue.svg
      :target: https://pypi.python.org/pypi/apipool#downloads


.. _install:

Install
------------------------------------------------------------------------------

``apipool`` is released on PyPI, so all you need is:

.. code-block:: console

    $ pip install apipool

To upgrade to latest version:

.. code-block:: console

    $ pip install --upgrade apipool