apipool-ng 1.0.0__tar.gz

apipool_ng-1.0.0/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright 2017 Sanhe Hu <https://github.com/MacHu-GWU/apipool-project>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apipool_ng-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md LICENSE.txt requirements.txt release-history.rst
+recursive-include apipool *.*

apipool_ng-1.0.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: apipool-ng
+Version: 1.0.0
+Summary: Multiple API Key Manager (Next Generation, sqlalchemy_mate free)
+Home-page: https://github.com/apipool-ng/apipool-project
+Author: apipool-ng Contributors
+Author-email: 
+Maintainer: apipool-ng Contributors
+Maintainer-email: 
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: sqlalchemy>=1.0.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: maintainer
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# apipool-ng
+
+`apipool-ng` is a next-generation **Multiple API Key Manager**.
+
+It allows developers to manage multiple API keys simultaneously. For example,
+if a single API key has 1000/day quota, you can register 10 API keys and let
+`apipool-ng` automatically rotate them.
+
+## Features
+
+- Automatically rotate API keys across multiple credentials.
+- Built-in usage statistics, searchable by time, status, and apikey.
+  Stats collector can be deployed on any relational database (SQLite by default).
+- Clean API, minimal code required to implement complex features.
+- No uncommon dependencies — only requires `sqlalchemy`.
+
+## Installation
+
+```bash
+pip install apipool-ng
+```
+
+## Quick Start
+
+Implement an `ApiKey` subclass, then create an `ApiKeyManager`:
+
+```python
+from apipool import ApiKey, ApiKeyManager
+
+class MyApiKey(ApiKey):
+    def __init__(self, key):
+        self.key = key
+
+    def user_01_get_primary_key(self):
+        return self.key
+
+    def user_02_create_client(self):
+        return MyApiClient(api_key=self.key)
+
+    def user_03_test_usable(self, client):
+        return client.test_connection()
+
+apikeys = [MyApiKey(k) for k in ["key1", "key2", "key3"]]
+manager = ApiKeyManager(apikey_list=apikeys)
+manager.check_usable()
+
+# Use dummyclient like your real client — keys auto-rotate
+result = manager.dummyclient.some_api_method(arg)
+```
+
+## DummyClient
+
+Use `manager.dummyclient` just like your original API client.
+Under the hood, it automatically selects a usable key, records usage events,
+and rotates keys on rate-limit errors.
+
+```python
+manager.check_usable()
+
+# Keys are automatically rotated
+result = manager.dummyclient.some_method()
+
+for _ in range(10):
+    manager.dummyclient.some_method()
+```
+
+## StatsCollector
+
+Query usage statistics through `manager.stats`:
+
+```python
+from apipool import StatusCollection
+
+# Usage count per key in last hour
+manager.stats.usage_count_stats_in_recent_n_seconds(3600)
+# {"key1": 3, "key2": 5, "key3": 2}
+
+# Count specific events
+count = manager.stats.usage_count_in_recent_n_seconds(
+    n_seconds=3600,
+    status_id=StatusCollection.c9_ReachLimit.id,
+)
+```
+
+## License
+
+MIT License

apipool_ng-1.0.0/README.md

@@ -0,0 +1,87 @@
+# apipool-ng
+
+`apipool-ng` is a next-generation **Multiple API Key Manager**.
+
+It allows developers to manage multiple API keys simultaneously. For example,
+if a single API key has 1000/day quota, you can register 10 API keys and let
+`apipool-ng` automatically rotate them.
+
+## Features
+
+- Automatically rotate API keys across multiple credentials.
+- Built-in usage statistics, searchable by time, status, and apikey.
+  Stats collector can be deployed on any relational database (SQLite by default).
+- Clean API, minimal code required to implement complex features.
+- No uncommon dependencies — only requires `sqlalchemy`.
+
+## Installation
+
+```bash
+pip install apipool-ng
+```
+
+## Quick Start
+
+Implement an `ApiKey` subclass, then create an `ApiKeyManager`:
+
+```python
+from apipool import ApiKey, ApiKeyManager
+
+class MyApiKey(ApiKey):
+    def __init__(self, key):
+        self.key = key
+
+    def user_01_get_primary_key(self):
+        return self.key
+
+    def user_02_create_client(self):
+        return MyApiClient(api_key=self.key)
+
+    def user_03_test_usable(self, client):
+        return client.test_connection()
+
+apikeys = [MyApiKey(k) for k in ["key1", "key2", "key3"]]
+manager = ApiKeyManager(apikey_list=apikeys)
+manager.check_usable()
+
+# Use dummyclient like your real client — keys auto-rotate
+result = manager.dummyclient.some_api_method(arg)
+```
+
+## DummyClient
+
+Use `manager.dummyclient` just like your original API client.
+Under the hood, it automatically selects a usable key, records usage events,
+and rotates keys on rate-limit errors.
+
+```python
+manager.check_usable()
+
+# Keys are automatically rotated
+result = manager.dummyclient.some_method()
+
+for _ in range(10):
+    manager.dummyclient.some_method()
+```
+
+## StatsCollector
+
+Query usage statistics through `manager.stats`:
+
+```python
+from apipool import StatusCollection
+
+# Usage count per key in last hour
+manager.stats.usage_count_stats_in_recent_n_seconds(3600)
+# {"key1": 3, "key2": 5, "key3": 2}
+
+# Count specific events
+count = manager.stats.usage_count_in_recent_n_seconds(
+    n_seconds=3600,
+    status_id=StatusCollection.c9_ReachLimit.id,
+)
+```
+
+## License
+
+MIT License

apipool_ng-1.0.0/apipool/__init__.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+__version__ = "1.0.0"
+__short_description__ = "Multiple API Key Manager (Next Generation, sqlalchemy_mate free)"
+__license__ = "MIT"
+__author__ = "apipool-ng Contributors"
+__author_email__ = ""
+__maintainer__ = "apipool-ng Contributors"
+__maintainer_email__ = ""
+__github_username__ = ""
+
+try:
+    from .apikey import ApiKey
+    from .manager import ApiKeyManager
+    from .stats import StatusCollection
+except Exception as e:  # pragma: no cover
+    pass

apipool_ng-1.0.0/apipool/apikey.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+
+class ApiKey(object):
+    """
+    API key abstract class.
+
+    User has to implement these three methods to make it works.
+
+    - :meth:`ApiKey.user_01_get_primary_key`.
+    - :meth:`ApiKey.user_02_create_client`.
+    - :meth:`ApiKey.user_03_test_usable`.
+    """
+
+    _client = None
+    _apikey_manager = None
+
+    def user_01_get_primary_key(self):
+        """
+        Get the unique identifier of this api key. Usually it is a string or
+        integer. For example, the AWS Access Key is the primary key of an
+        aws api key pair.
+
+        :return: str or int.
+        """
+
+        raise NotImplementedError
+
+    def user_02_create_client(self):
+        """
+        Create a client object to perform api call.
+
+        This method will use api key data to create a client class.
+
+        For example, if you use `geopy <https://geopy.readthedocs.io/en/stable/>`_,
+        and you want to use Google Geocoding API, then
+
+        .. code-block:: python
+
+            >>> from geopy.geocoders import GoogleV3
+            >>> class YourApiKey(ApiKey):
+            ...     def __init__(self, apikey):
+            ...         self.apikey = apikey
+            ...
+            ...     def user_02_create_client(self):
+            ...         return GoogleV3(api_key=self.apikey)
+
+        api for ``geopy.geocoder.GoogleV3``: https://geopy.readthedocs.io/en/stable/#googlev3
+
+        :return: client object.
+        """
+        raise NotImplementedError
+
+    def user_03_test_usable(self, client):
+        """
+        Test if this api key is usable for making api call.
+
+        Usually this method is just to make a simple, guarantee successful
+        api call, and then check the response.
+
+        :return: bool, or raise Exception
+        """
+        raise NotImplementedError
+
+    @property
+    def primary_key(self):
+        return self.user_01_get_primary_key()
+
+    def connect_client(self):
+        """
+        connect
+        :return:
+        """
+        self._client = self.user_02_create_client()
+
+    def is_usable(self):
+        if self._client is None:
+            self.connect_client()
+        try:
+            return self.user_03_test_usable(self._client)
+        except:  # pragma: no cover
+            return False

apipool_ng-1.0.0/apipool/manager.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+built-in stats collector service for api usage and status.
+"""
+
+import sys
+import random
+from collections import OrderedDict
+from sqlalchemy import create_engine
+
+from .apikey import ApiKey
+from .stats import StatusCollection, StatsCollector
+
+
+def validate_is_apikey(obj):
+    if not isinstance(obj, ApiKey):  # pragma: no cover
+        raise TypeError
+
+
+class ApiCaller(object):
+    def __init__(self, apikey, apikey_manager, call_method, reach_limit_exc):
+        self.apikey = apikey
+        self.apikey_manager = apikey_manager
+        self.call_method = call_method
+        self.reach_limit_exc = reach_limit_exc
+
+    def __call__(self, *args, **kwargs):
+        try:
+            res = self.call_method(*args, **kwargs)
+            self.apikey_manager.stats.add_event(
+                self.apikey.primary_key, StatusCollection.c1_Success.id,
+            )
+            return res
+        except self.reach_limit_exc as e:
+            self.apikey_manager.remove_one(self.apikey.primary_key)
+            self.apikey_manager.stats.add_event(
+                self.apikey.primary_key, StatusCollection.c9_ReachLimit.id,
+            )
+            raise e
+        except Exception as e:
+            self.apikey_manager.stats.add_event(
+                self.apikey.primary_key, StatusCollection.c5_Failed.id,
+            )
+            raise e
+
+
+class DummyClient(object):
+    def __init__(self):
+        self._apikey_manager = None
+
+    def __getattr__(self, item):
+        apikey = self._apikey_manager.random_one()
+        call_method = getattr(apikey._client, item)
+        return ApiCaller(
+            apikey=apikey,
+            apikey_manager=self._apikey_manager,
+            call_method=call_method,
+            reach_limit_exc=self._apikey_manager.reach_limit_exc,
+        )
+
+
+class NeverRaisesError(Exception):
+    pass
+
+
+class ApiKeyManager(object):
+    _settings_api_client_class = None
+
+    def __init__(self, apikey_list, reach_limit_exc=None, db_engine=None):
+        # validate
+        for apikey in apikey_list:
+            validate_is_apikey(apikey)
+
+        # stats collector
+        if db_engine is None:
+            db_engine = create_sqlite()
+
+        self.stats = StatsCollector(engine=db_engine)
+        self.stats.add_all_apikey(apikey_list)
+
+        # initiate apikey chain data
+        self.apikey_chain = OrderedDict()
+        for apikey in apikey_list:
+            self.add_one(apikey, upsert=False)
+
+        self.archived_apikey_chain = OrderedDict()
+
+        if reach_limit_exc is None:
+            reach_limit_exc = NeverRaisesError
+        self.reach_limit_exc = reach_limit_exc
+        self.dummyclient = DummyClient()
+        self.dummyclient._apikey_manager = self
+
+    def add_one(self, apikey, upsert=False):
+        validate_is_apikey(apikey)
+        primary_key = apikey.primary_key
+
+        do_insert = False
+        if primary_key in self.apikey_chain:
+            if upsert:
+                do_insert = True
+        else:
+            do_insert = True
+
+        if do_insert:
+            try:
+                apikey.connect_client()
+                self.apikey_chain[primary_key] = apikey
+            except Exception as e:  # pragma: no cover
+                sys.stdout.write(
+                    "\nCan't create api client with {}, error: {}".format(
+                        apikey.primary_key, e)
+                )
+
+        # update stats collector
+        self.stats.add_all_apikey([apikey, ])
+
+    def fetch_one(self, primary_key):
+        return self.apikey_chain[primary_key]
+
+    def remove_one(self, primary_key):
+        apikey = self.apikey_chain.pop(primary_key)
+        self.archived_apikey_chain[primary_key] = apikey
+        return apikey
+
+    def random_one(self):
+        return random.choice(list(self.apikey_chain.values()))
+
+    def check_usable(self):
+        for primary_key, apikey in self.apikey_chain.items():
+            if apikey.is_usable():
+                self.stats.add_event(
+                    primary_key, StatusCollection.c1_Success.id)
+            else:
+                self.remove_one(primary_key)
+                self.stats.add_event(
+                    primary_key, StatusCollection.c5_Failed.id)
+
+        if len(self.apikey_chain) == 0:
+            sys.stdout.write("\nThere's no API Key usable!")
+        elif len(self.archived_apikey_chain) == 0:
+            sys.stdout.write("\nAll API Key are usable.")
+        else:
+            sys.stdout.write("\nThese keys are not usable:")
+            for key in self.archived_apikey_chain:
+                sys.stdout.write("\n    %s: %r" % (key, apikey))
+
+
+def create_sqlite():
+    return create_engine("sqlite:///:memory:")

apipool_ng-1.0.0/apipool/stats.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+stats用于统计API的使用记录. 我们使用一个RDS数据库(通常是本地的sqlite), 记录每个
+API Call所使用的api key, 返回的状态 以及 完成API Call的时间.
+"""
+
+from datetime import datetime, timedelta
+from collections import OrderedDict
+
+from sqlalchemy import Column, ForeignKey, create_engine
+from sqlalchemy import String, Integer, DateTime, func
+from sqlalchemy.orm import declarative_base, relationship, sessionmaker
+
+Base = declarative_base()
+
+
+class ApiKey(Base):
+    __tablename__ = "apikey"
+
+    id = Column(Integer, primary_key=True)
+    key = Column(String, unique=True)
+
+    events = relationship("Event", back_populates="apikey")
+
+    def __repr__(self):
+        return "ApiKey(id=%r, key=%r)" % (self.id, self.key)
+
+
+class Status(Base):
+    __tablename__ = "status"
+
+    id = Column(Integer, primary_key=True)
+    description = Column(String, unique=True)
+
+    events = relationship("Event", back_populates="status")
+
+    def __repr__(self):
+        return "Status(id=%r, description=%r)" % (self.id, self.description)
+
+
+class Event(Base):
+    __tablename__ = "event"
+
+    apikey_id = Column(Integer, ForeignKey("apikey.id"), primary_key=True)
+    finished_at = Column(DateTime, primary_key=True)
+    status_id = Column(Integer, ForeignKey("status.id"))
+
+    apikey = relationship("ApiKey")
+    status = relationship("Status")
+
+
+class StatusCollection(object):
+    class c1_Success(object):
+        id = 1
+        description = "success"
+
+    class c5_Failed(object):
+        id = 5
+        description = "failed"
+
+    class c9_ReachLimit(object):
+        id = 9
+        description = "reach limit"
+
+    @classmethod
+    def get_subclasses(cls):
+        return [cls.c1_Success, cls.c5_Failed, cls.c9_ReachLimit]
+
+    @classmethod
+    def get_id_list(cls):
+        return [klass.id for klass in cls.get_subclasses()]
+
+    @classmethod
+    def get_description_list(cls):
+        return [klass.description for klass in cls.get_subclasses()]
+
+    @classmethod
+    def get_mapper_id_to_description(cls):
+        return {
+            klass.id: klass.description
+            for klass in cls.get_subclasses()
+        }
+
+    @classmethod
+    def get_mapper_description_to_id(cls):
+        return {
+            klass.description: klass.id
+            for klass in cls.get_subclasses()
+        }
+
+    @classmethod
+    def get_status_list(cls):
+        return [
+            Status(id=klass.id, description=klass.description)
+            for klass in cls.get_subclasses()
+        ]
+
+
+def get_n_seconds_before(n_seconds):
+    return datetime.now() - timedelta(seconds=n_seconds)
+
+
+class StatsCollector(object):
+    def __init__(self, engine):
+        Base.metadata.create_all(engine)
+        self.engine = engine
+        self.ses = self.create_session()
+
+        self._add_all_status()
+
+        self._cache_apikey = dict()
+        self._cache_status = StatusCollection.get_mapper_id_to_description()
+
+    def create_session(self):
+        return sessionmaker(bind=self.engine)()
+
+    def close(self):
+        self.ses.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def _add_all_status(self):
+        ses = self.create_session()
+        for status in StatusCollection.get_status_list():
+            existing = (
+                ses.query(Status)
+                .filter(Status.id == status.id)
+                .first()
+            )
+            if existing is None:
+                ses.add(status)
+        ses.commit()
+        ses.close()
+
+    def add_all_apikey(self, apikey_list):
+        data = [ApiKey(key=apikey.primary_key) for apikey in apikey_list]
+        ses = self.create_session()
+        for item in data:
+            existing = (
+                ses.query(ApiKey)
+                .filter(ApiKey.key == item.key)
+                .first()
+            )
+            if existing is None:
+                ses.add(item)
+        ses.commit()
+        ses.close()
+        self._update_cache()
+
+    def _update_cache(self):
+        ses = self.create_session()
+        apikey_list = ses.query(ApiKey).all()
+        for apikey in apikey_list:
+            self._cache_apikey.setdefault(apikey.key, apikey.id)
+        ses.close()
+
+    def add_event(self, primary_key, status_id):
+        event = Event(
+            apikey_id=self._cache_apikey[primary_key],
+            finished_at=datetime.now(),
+            status_id=status_id,
+        )
+        ses = self.create_session()
+        ses.add(event)
+        ses.commit()
+        ses.close()
+
+    def query_event_in_recent_n_seconds(self,
+                                        n_seconds,
+                                        primary_key=None,
+                                        status_id=None):
+        n_seconds_before = get_n_seconds_before(n_seconds)
+        filters = [Event.finished_at >= n_seconds_before, ]
+        if not (primary_key is None):
+            filters.append(Event.apikey_id == self._cache_apikey[primary_key])
+        if not (status_id is None):
+            filters.append(Event.status_id == status_id)
+        return self.ses.query(Event).filter(*filters)
+
+    def usage_count_in_recent_n_seconds(self,
+                                        n_seconds,
+                                        primary_key=None,
+                                        status_id=None):
+        q = self.query_event_in_recent_n_seconds(
+            n_seconds,
+            primary_key=primary_key,
+            status_id=status_id,
+        )
+        return q.count()
+
+    def usage_count_stats_in_recent_n_seconds(self, n_seconds):
+        n_seconds_before = get_n_seconds_before(n_seconds)
+        q = self.ses.query(ApiKey.key, func.count(Event.apikey_id)) \
+            .select_from(Event).join(ApiKey) \
+            .filter(Event.finished_at >= n_seconds_before) \
+            .group_by(Event.apikey_id) \
+            .order_by(ApiKey.key)
+        return OrderedDict(q.all())

apipool_ng-1.0.0/apipool/tests/__init__.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from ..apikey import ApiKey
+
+
+class ReachLimitError(Exception):
+    pass
+
+
+class GoogleMapApiClient(object):
+    def __init__(self, apikey):
+        self.apikey = apikey
+
+    def get_lat_lng_by_address(self, address):
+        return {"lat": 40.762882, "lng": -73.973700}
+
+    def raise_other_error(self, address):
+        raise ValueError
+
+    def raise_reach_limit_error(self, address):
+        raise ReachLimitError
+
+
+class GoogleMapApiKey(ApiKey):
+    def __init__(self, apikey):
+        self.apikey = apikey
+
+    def user_01_get_primary_key(self):
+        return self.apikey
+
+    def user_02_create_client(self):
+        return GoogleMapApiClient(self.apikey)
+
+    def user_03_test_usable(self, client):
+        if "99" in self.apikey:
+            return False
+        response = client.get_lat_lng_by_address(
+            "123 North St, NewYork, NY 10001")
+        if ("lat" in response) and ("lng" in response):
+            return True
+        else:
+            return False
+
+
+apikeys = [
+    "example1@gmail.com",
+    "example2@gmail.com",
+    "example3@gmail.com",
+    "example99@gmail.com",
+]

apipool_ng-1.0.0/apipool_ng.egg-info/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: apipool-ng
+Version: 1.0.0
+Summary: Multiple API Key Manager (Next Generation, sqlalchemy_mate free)
+Home-page: https://github.com/apipool-ng/apipool-project
+Author: apipool-ng Contributors
+Author-email: 
+Maintainer: apipool-ng Contributors
+Maintainer-email: 
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: sqlalchemy>=1.0.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: maintainer
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# apipool-ng
+
+`apipool-ng` is a next-generation **Multiple API Key Manager**.
+
+It allows developers to manage multiple API keys simultaneously. For example,
+if a single API key has 1000/day quota, you can register 10 API keys and let
+`apipool-ng` automatically rotate them.
+
+## Features
+
+- Automatically rotate API keys across multiple credentials.
+- Built-in usage statistics, searchable by time, status, and apikey.
+  Stats collector can be deployed on any relational database (SQLite by default).
+- Clean API, minimal code required to implement complex features.
+- No uncommon dependencies — only requires `sqlalchemy`.
+
+## Installation
+
+```bash
+pip install apipool-ng
+```
+
+## Quick Start
+
+Implement an `ApiKey` subclass, then create an `ApiKeyManager`:
+
+```python
+from apipool import ApiKey, ApiKeyManager
+
+class MyApiKey(ApiKey):
+    def __init__(self, key):
+        self.key = key
+
+    def user_01_get_primary_key(self):
+        return self.key
+
+    def user_02_create_client(self):
+        return MyApiClient(api_key=self.key)
+
+    def user_03_test_usable(self, client):
+        return client.test_connection()
+
+apikeys = [MyApiKey(k) for k in ["key1", "key2", "key3"]]
+manager = ApiKeyManager(apikey_list=apikeys)
+manager.check_usable()
+
+# Use dummyclient like your real client — keys auto-rotate
+result = manager.dummyclient.some_api_method(arg)
+```
+
+## DummyClient
+
+Use `manager.dummyclient` just like your original API client.
+Under the hood, it automatically selects a usable key, records usage events,
+and rotates keys on rate-limit errors.
+
+```python
+manager.check_usable()
+
+# Keys are automatically rotated
+result = manager.dummyclient.some_method()
+
+for _ in range(10):
+    manager.dummyclient.some_method()
+```
+
+## StatsCollector
+
+Query usage statistics through `manager.stats`:
+
+```python
+from apipool import StatusCollection
+
+# Usage count per key in last hour
+manager.stats.usage_count_stats_in_recent_n_seconds(3600)
+# {"key1": 3, "key2": 5, "key3": 2}
+
+# Count specific events
+count = manager.stats.usage_count_in_recent_n_seconds(
+    n_seconds=3600,
+    status_id=StatusCollection.c9_ReachLimit.id,
+)
+```
+
+## License
+
+MIT License

apipool_ng-1.0.0/apipool_ng.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+LICENSE.txt
+MANIFEST.in
+README.md
+release-history.rst
+requirements.txt
+setup.py
+apipool/__init__.py
+apipool/apikey.py
+apipool/manager.py
+apipool/stats.py
+apipool/__pycache__/__init__.cpython-314.pyc
+apipool/__pycache__/apikey.cpython-314.pyc
+apipool/__pycache__/manager.cpython-314.pyc
+apipool/__pycache__/stats.cpython-314.pyc
+apipool/tests/__init__.py
+apipool/tests/__pycache__/__init__.cpython-314.pyc
+apipool_ng.egg-info/PKG-INFO
+apipool_ng.egg-info/SOURCES.txt
+apipool_ng.egg-info/dependency_links.txt
+apipool_ng.egg-info/requires.txt
+apipool_ng.egg-info/top_level.txt
+tests/test_apipool.py
+tests/test_import.py
+tests/test_stats.py

apipool_ng-1.0.0/apipool_ng.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

apipool_ng-1.0.0/apipool_ng.egg-info/requires.txt

@@ -0,0 +1 @@
+sqlalchemy>=1.0.0

apipool_ng-1.0.0/apipool_ng.egg-info/top_level.txt

@@ -0,0 +1 @@
+apipool

apipool_ng-1.0.0/release-history.rst

@@ -0,0 +1,31 @@
+Release and Version History
+==============================================================================
+
+
+0.0.3 (todo)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**Features and Improvements**
+
+**Minor Improvements**
+
+**Bugfixes**
+
+**Miscellaneous**
+
+
+0.0.2 (2018-08-21)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**Features and Improvements**
+
+- rewrite the core code.
+- add database backed stats collector feature. convinent events query is provided.
+
+**Minor Improvements**
+
+- use pygitrepo skeleton.
+
+
+0.0.1 (2017-04-06)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- First release

apipool_ng-1.0.0/requirements.txt

@@ -0,0 +1 @@
+sqlalchemy>=1.0.0

apipool_ng-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

apipool_ng-1.0.0/setup.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from setuptools import setup, find_packages
+
+import apipool as package
+
+setup(
+    name="apipool-ng",
+    version=package.__version__,
+    description=package.__short_description__,
+    long_description=open("README.md", "rb").read().decode("utf-8"),
+    long_description_content_type="text/markdown",
+    author=package.__author__,
+    author_email=package.__author_email__,
+    maintainer=package.__maintainer__,
+    maintainer_email=package.__maintainer_email__,
+    license=package.__license__,
+    packages=["apipool"] + ["apipool.%s" % i for i in find_packages("apipool")],
+    include_package_data=True,
+    url="https://github.com/apipool-ng/apipool-project",
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Natural Language :: English",
+        "Operating System :: Microsoft :: Windows",
+        "Operating System :: MacOS",
+        "Operating System :: Unix",
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+    ],
+    python_requires=">=3.8",
+    install_requires=[line.strip() for line in open("requirements.txt") if line.strip() and not line.startswith("#")],
+)

apipool_ng-1.0.0/tests/test_apipool.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import pytest
+from apipool import ApiKey, ApiKeyManager, StatusCollection
+from apipool.tests import (
+    ReachLimitError,
+    GoogleMapApiClient,
+    GoogleMapApiKey,
+    apikeys,
+)
+
+
+class TestBaseApiKey(object):
+    def test(self):
+        apikey = GoogleMapApiKey(apikey="example@gmail.com")
+        assert apikey.primary_key == "example@gmail.com"
+        assert apikey.is_usable() is True
+
+
+class TestApiKeyManager(object):
+    def test(self):
+        address = "123st, NewYork, NY 10001"
+
+        manager = ApiKeyManager(
+            apikey_list=[
+                GoogleMapApiKey(apikey=apikey)
+                for apikey in apikeys
+            ],
+            reach_limit_exc=ReachLimitError,
+        )
+        manager.check_usable()  # use each key once
+
+        res = manager.dummyclient.get_lat_lng_by_address(
+            address)  # make a call
+        assert "lat" in res and "lng" in res
+        assert manager.stats.usage_count_in_recent_n_seconds(3600) == 5
+        assert max(
+            list(manager.stats.usage_count_stats_in_recent_n_seconds(3600).values())) == 2
+
+        # make 100 successful call
+        for _ in range(100):
+            manager.dummyclient.get_lat_lng_by_address(address)
+        assert manager.stats.usage_count_in_recent_n_seconds(3600) == 105
+
+        assert len(manager.apikey_chain) == 3
+        assert len(manager.archived_apikey_chain) == 1
+
+        # raise other error
+        try:
+            manager.dummyclient.raise_other_error(address)
+        except:
+            pass
+
+        assert len(manager.apikey_chain) == 3
+        assert len(manager.archived_apikey_chain) == 1
+
+        # raise ReachLimitError
+        try:
+            manager.dummyclient.raise_reach_limit_error(address)
+        except:
+            pass
+
+        assert len(manager.apikey_chain) == 2
+        assert len(manager.archived_apikey_chain) == 2
+
+        assert manager.stats.usage_count_in_recent_n_seconds(
+            3600, status_id=StatusCollection.c5_Failed.id) == 2
+        assert manager.stats.usage_count_in_recent_n_seconds(
+            3600, status_id=StatusCollection.c9_ReachLimit.id) == 1
+
+
+if __name__ == "__main__":
+    import os
+
+    basename = os.path.basename(__file__)
+    pytest.main([basename, "-s", "--tb=native"])

apipool_ng-1.0.0/tests/test_import.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import pytest
+from pytest import raises, approx
+
+
+def test():
+    import apipool
+
+    apipool.ApiKey
+    apipool.ApiKeyManager
+    apipool.StatusCollection
+
+
+if __name__ == "__main__":
+    import os
+
+    basename = os.path.basename(__file__)
+    pytest.main([basename, "-s", "--tb=native"])

apipool_ng-1.0.0/tests/test_stats.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import pytest
+import random
+from apipool.stats import StatsCollector, StatusCollection
+from apipool.tests import GoogleMapApiKey, apikeys
+from sqlalchemy import create_engine
+
+
+@pytest.fixture()
+def collector():
+    engine = create_engine("sqlite:///:memory:")
+    collector = StatsCollector(engine=engine)
+    collector.add_all_apikey(
+        [GoogleMapApiKey(apikey=apikey) for apikey in apikeys]
+    )
+
+    status_id_list = StatusCollection.get_id_list()
+    for _ in range(100):
+        primary_key = random.choice(apikeys)
+        status_id = random.choice(status_id_list)
+        collector.add_event(primary_key, status_id)
+    return collector
+
+
+class TestDashboardQuery(object):
+    def test_usage_count_in_recent_n_seconds(self, collector):
+        assert collector.usage_count_in_recent_n_seconds(3600) == 100
+
+        assert sum([
+            collector.usage_count_in_recent_n_seconds(3600, primary_key=key)
+            for key in apikeys
+        ]) == 100
+
+        assert sum([
+            collector.usage_count_in_recent_n_seconds(
+                3600, status_id=status_id)
+            for status_id in StatusCollection.get_id_list()
+        ]) == 100
+
+    def test_usage_count_stats_in_recent_n_seconds(self, collector):
+        stats = collector.usage_count_stats_in_recent_n_seconds(3600)
+        assert sum(list(stats.values()))
+
+
+class TestDashboardConstructor(object):
+    def test(self):
+        engine = create_engine("sqlite:///:memory:")
+        collector = StatsCollector(engine=engine)
+        assert len(collector._cache_apikey) == 0
+        collector.add_all_apikey(
+            [GoogleMapApiKey(apikey=apikey) for apikey in apikeys]
+        )
+        assert len(collector._cache_apikey) == 4
+
+
+if __name__ == "__main__":
+    import os
+
+    basename = os.path.basename(__file__)
+    pytest.main([basename, "-s", "--tb=native"])