{"id":18779157,"url":"https://github.com/trisongz/aiokeydb-py","last_synced_at":"2025-08-07T09:05:16.584Z","repository":{"id":51855125,"uuid":"493476022","full_name":"trisongz/aiokeydb-py","owner":"trisongz","description":"Async KeyDB Python Client","archived":false,"fork":false,"pushed_at":"2024-01-18T04:37:05.000Z","size":1012,"stargazers_count":16,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-28T05:51:46.393Z","etag":null,"topics":["keydb","keydb-client","python","redis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trisongz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOGS.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-18T02:06:22.000Z","updated_at":"2025-03-03T20:09:28.000Z","dependencies_parsed_at":"2024-11-07T20:29:27.451Z","dependency_job_id":null,"html_url":"https://github.com/trisongz/aiokeydb-py","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/trisongz/aiokeydb-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trisongz%2Faiokeydb-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trisongz%2Faiokeydb-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trisongz%2Faiokeydb-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trisongz%2Faiokeydb-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trisongz","download_url":"https://codeload.github.com/trisongz/aiokeydb-py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trisongz%2Faiokeydb-py/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269229167,"owners_count":24381902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-07T02:00:09.698Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["keydb","keydb-client","python","redis"],"created_at":"2024-11-07T20:19:00.574Z","updated_at":"2025-08-07T09:05:16.526Z","avatar_url":"https://github.com/trisongz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aiokeydb\n  \n  **Latest Version**: [![PyPI version](https://badge.fury.io/py/aiokeydb.svg)](https://badge.fury.io/py/aiokeydb)\n\n  Unified Syncronous and Asyncronous Python client for [KeyDB](https://github.com/Snapchat/KeyDB) and [Redis](https://github.com/redis).\n\n  It implements the majority of `redis-py` API methods and is fully compatible with `redis-py` API methods, while also providing a unified Client for both `sync` and `async` methods.\n\n  Additionally, newer apis such as `KeyDBClient` are strongly typed to provide a more robust experience. \n\n\n---\n\n## Usage\n\n`aiokeydb` can be installed from `pypi` using `pip` or from source.\n\n### Installation\n\n```bash\n\n# Install from pypi\npip install aiokeydb\n\n# Install from source\npip install git+https://github.com/trisongz/aiokeydb-py.git\n\n```\n\n### Examples\n\nBelow are some examples of how to use `aiokeydb`. Additional examples can be found in the `tests` directory.\n\n```python\n\nimport time\nimport asyncio\nimport uuid\nfrom aiokeydb import KeyDBClient\n\n# The session can be explicitly initialized, or\n# will be lazily initialized on first use\n# through environment variables with all \n# params being prefixed with `KEYDB_`\n\nkeydb_uri = \"keydb://localhost:6379/0\"\n\n# Initialize the Unified Client\nKeyDBClient.init_session(\n    uri = keydb_uri,\n)\n\n# Cache the results of these functions\n# cachify works for both sync and async functions\n# and has many params to customize the caching behavior\n# and supports both `redis` and `keydb` backends\n# as well as `api` frameworks such as `fastapi` and `starlette`\n\n@KeyDBClient.cachify()\nasync def async_fibonacci(number: int):\n    if number == 0: return 0\n    elif number == 1: return 1\n    return await async_fibonacci(number - 1) + await async_fibonacci(number - 2)\n\n@KeyDBClient.cachify()\ndef fibonacci(number: int):\n    if number == 0: return 0\n    elif number == 1: return 1\n    return fibonacci(number - 1) + fibonacci(number - 2)\n\nasync def test_fib(n: int = 100, runs: int = 10):\n    # Test that both results are the same.\n    sync_t, async_t = 0.0, 0.0\n\n    for i in range(runs):\n        t = time.time()\n        print(f'[Async - {i}/{runs}] Fib Result: {await async_fibonacci(n)}')\n        tt = time.time() - t\n        print(f'[Async - {i}/{runs}] Fib Time: {tt:.2f}s')\n        async_t += tt\n\n        t = time.time()\n        print(f'[Sync  - {i}/{runs}] Fib Result: {fibonacci(n)}')\n        tt = time.time() - t\n        print(f'[Sync  - {i}/{runs}] Fib Time: {tt:.2f}s')\n        sync_t += tt\n    \n    print(f'[Async] Cache Average Time: {async_t / runs:.2f}s | Total Time: {async_t:.2f}s')\n    print(f'[Sync ] Cache Average Time: {sync_t / runs:.2f}s | Total Time: {sync_t:.2f}s')\n        \nasync def test_setget(runs: int = 10):\n    # By default, the client utilizes `pickle` to serialize\n    # and deserialize objects. This can be changed by setting\n    # the `serializer`\n\n    sync_t, async_t = 0.0, 0.0\n    for i in range(runs):\n        value = str(uuid.uuid4())\n        key = f'async-test-{i}'\n        t = time.time()\n        await KeyDBClient.async_set(key, value)\n        assert await KeyDBClient.async_get(key) == value\n        tt = time.time() - t\n        print(f'[Async - {i}/{runs}] Get/Set: {key} -\u003e {value} = {tt:.2f}s')\n        async_t += tt\n\n        value = str(uuid.uuid4())\n        key = f'sync-test-{i}'\n        t = time.time()\n        KeyDBClient.set(key, value)\n        assert KeyDBClient.get(key) == value\n        tt = time.time() - t\n        print(f'[Sync  - {i}/{runs}] Get/Set: {key}  -\u003e {value} = {tt:.2f}s')\n        sync_t += tt\n    \n    print(f'[Async] GetSet Average Time: {async_t / runs:.2f}s | Total Time: {async_t:.2f}s')\n    print(f'[Sync ] GetSet Average Time: {sync_t / runs:.2f}s | Total Time: {sync_t:.2f}s')\n\n\nasync def run_tests(fib_n: int = 100, fib_runs: int = 10, setget_runs: int = 10):\n    \n    # You can explicitly wait for the client to be ready\n    # Sync version\n    # KeyDBClient.wait_for_ready()\n    await KeyDBClient.async_wait_for_ready()\n\n    # Run the tests\n    await test_fib(n = fib_n, runs = fib_runs)\n    await test_setget(runs = setget_runs)\n\n\n    # Utilize the current session\n    await KeyDBClient.async_set('async_test_0', 'test')\n    assert await KeyDBClient.async_get('async_test_0') == 'test'\n\n    KeyDBClient.set('sync_test_0', 'test')\n    assert KeyDBClient.get('sync_test_0') == 'test'\n\n\n    # you can access the `KeyDBSession` object directly\n    # which mirrors the APIs in `KeyDBClient`\n\n    await KeyDBClient.session.async_set('async_test_1', 'test')\n    assert await KeyDBClient.session.async_get('async_test_1') == 'test'\n\n    KeyDBClient.session.set('sync_test_1', 'test')\n    assert KeyDBClient.session.get('sync_test_1') == 'test'\n\n    # The underlying client can be accessed directly\n    # if the desired api methods aren't mirrored\n\n    # KeyDBClient.keydb\n    # KeyDBClient.async_keydb\n    # Since encoding / decoding is not handled by the client\n    # you must encode / decode the data yourself\n    await KeyDBClient.async_keydb.set('async_test_2', b'test')\n    assert await KeyDBClient.async_keydb.get('async_test_2') == b'test'\n\n    KeyDBClient.keydb.set('sync_test_2', b'test')\n    assert KeyDBClient.keydb.get('sync_test_2') == b'test'\n\n    # You can also explicitly close the client\n    # However, this closes the connectionpool and will terminate\n    # all connections. This is not recommended unless you are\n    # explicitly closing the client.\n\n    # Sync version\n    # KeyDBClient.close()\n    await KeyDBClient.aclose()\n\nasyncio.run(run_tests())\n\n```\n\nAdditionally, you can use the previous APIs that are expected to be present\n\n```python\n\nfrom aiokeydb import KeyDB, AsyncKeyDB, from_url\n\nsync_client = KeyDB()\nasync_client = AsyncKeyDB()\n\n# Alternative methods\nsync_client = from_url('keydb://localhost:6379/0')\nasync_client = from_url('keydb://localhost:6379/0', asyncio = True)\n\n```\n\n### Setting the Global Client Settings\n\nThe library is designed to be explict and not have any global state. However, you can set the global client settings by using the `KeyDBClient.configure` method. This is useful if you are using the `KeyDBClient` class directly, or if you are using the `KeyDBClient` class in a library that you are developing.\n\nFor example, if you initialize a session with a specific `uri`, the global client settings will still inherit from the default settings. \n\n```python\n\nfrom aiokeydb import KeyDBClient\nfrom lazyops.utils import logger\n\nkeydb_uris = {\n    'default': 'keydb://127.0.0.1:6379/0',\n    'cache': 'keydb://localhost:6379/1',\n    'public': 'redis://public.redis.db:6379/0',\n}\n\nsessions = {}\n\n# these will now be initialized\nfor name, uri in keydb_uris.items():\n    sessions[name] = KeyDBClient.init_session(\n        name = name,\n        uri = uri,\n    )\n    logger.info(f'Session {name}: uri: {sessions[name].uri}')\n\n# however if you initialize another session\n# it will use the global environment vars\n\nsessions['test'] = KeyDBClient.init_session(\n    name = 'test',\n)\nlogger.info(f'Session test: uri: {sessions[\"test\"].uri}')\n```\n\nBy configuring the global settings, any downstream sessions will inherit the global settings.\n\n```python\nfrom aiokeydb import KeyDBClient\nfrom lazyops.utils import logger\n\ndefault_uri = 'keydb://public.host.com:6379/0'\nkeydb_dbs = {\n    'cache': {\n        'db_id': 1,\n    },\n    'db': {\n        'uri': 'keydb://127.0.0.1:6379/0',\n    },\n}\n\nKeyDBClient.configure(\n    url = default_uri,\n    debug_enabled = True,\n    queue_db = 1,\n)\n\n# now any sessions that are initialized will use the global settings\n\nsessions = {}\n# these will now be initialized\n\n# Initialize the first default session\n# which should utilize the `default_uri`\nKeyDBClient.init_session()\n\nfor name, config in keydb_dbs.items():\n    sessions[name] = KeyDBClient.init_session(\n        name = name,\n        **config\n    )\n    logger.info(f'Session {name}: uri: {sessions[name].uri}')\n\n```\n\n---\n\n### KeyDB Worker Queues\n\nReleased since `v0.1.1`\n\nKeyDB Worker Queues is a simple, fast, and reliable queue system for KeyDB. It is designed to be used in a distributed environment, where multiple KeyDB instances are used to process jobs. It is also designed to be used in a single instance environment, where a single KeyDB instance is used to process jobs.\n\n```python\nimport asyncio\nfrom aiokeydb import KeyDBClient\nfrom aiokeydb.queues import TaskQueue, Worker\nfrom lazyops.utils import logger\n\n\n# Configure the KeyDB Client - the default keydb client will use \n# db = 0, and queue uses 2 so that it doesn't conflict with other\n# by configuring it here, you can explicitly set the db to use\nkeydb_uri = \"keydb://127.0.0.1:6379/0\"\n\n# Configure the Queue to use db = 1 instead of 2\nKeyDBClient.configure(\n    url = keydb_uri,\n    debug_enabled = True,\n    queue_db = 1,\n)\n\n@Worker.add_cronjob(\"*/1 * * * *\")\nasync def test_cron_task(*args, **kwargs):\n    logger.info(\"Cron task ran\")\n    await asyncio.sleep(5)\n\n@Worker.add_function()\nasync def test_task(*args, **kwargs):\n    logger.info(\"Task ran\")\n    await asyncio.sleep(5)\n\nasync def run_tests():\n    queue = TaskQueue(\"test_queue\")\n    worker = Worker(queue)\n    await worker.start()\n\nasyncio.run(run_tests())\n\n```\n\n---\n\n### Requirements\n\n- `deprecated\u003e=1.2.3`\n\n- `packaging\u003e=20.4`\n\n- `importlib-metadata \u003e= 1.0; python_version \u003c \"3.8\"`\n\n- `typing-extensions; python_version\u003c\"3.8\"`\n\n- `async-timeout\u003e=4.0.2`\n\n- `pydantic`\n\n- `anyio`\n\n- `lazyops`\n\n---\n\n**Major Changes**:\n  \n- `v0.0.8` -\u003e `v0.0.11`: \n\n    Fully Migrates away from `aioredis` to `redis-py` @ `v4.3.4`.\n\n    This inherits all API methods from [`redis-py`](https://github.com/redis/redis-py) to enforce compatability since deprecation of `aioredis` [going forward](https://github.com/aio-libs/aioredis-py/issues/1273)\n\n    This fork of `redis-py` has some modified semantics, while attempting to replicate all the API methods of `redis-py` to avoid compatibility issues with underlying libraries that require a pinned `redis` version.\n\n    Notably, all `async` Classes and methods are prefixed by `Async` to avoid name collisions with the `sync` version.\n\n- `v0.0.11` -\u003e `v0.1.0`: \n\n    Migration of `aiokeydb.client` -\u003e `aiokeydb.core` and `aiokeydb.asyncio.client` -\u003e `aiokeydb.asyncio.core`\n    However these have been aliased to their original names to avoid breaking changes.\n\n    Creating a unified API available through new `KeyDBClient` class that creates `sessions` which are `KeyDBSession` inherits from `KeyDB` and `AsyncKeyDBClient` class that inherits from `AsyncKeyDB` class\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrisongz%2Faiokeydb-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrisongz%2Faiokeydb-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrisongz%2Faiokeydb-py/lists"}