kiarina-lib-falkordb

PyPI version Python License: MIT

[!NOTE] What is this? A package for creating synchronous and asynchronous FalkorDB clients with settings, retries, and connection caching.

Dependencies

Package Version License
FalkorDB >=1.7.1 MIT
Pydantic Settings >=2.10.1 MIT
pydantic-settings-manager >=3.2.0 MIT
redis-py >=6.4.0 MIT

Installation

pip install kiarina-lib-falkordb

Features

  • Using a Synchronous Client Create a synchronous FalkorDB client from settings.
  • Using an Asynchronous Client Create an asynchronous FalkorDB client from the same settings.
  • Managing Multiple Configurations Manage multiple named FalkorDB connection settings.
  • Caching Clients Reuse a client instance for the same cache key.
  • Retrying Connection Errors Retry Redis connection and timeout errors.
  • Overriding Client Parameters Override the URL, retry behavior, and initialization arguments per call.

Using a Synchronous Client

from kiarina.lib.falkordb import get_falkordb

client = get_falkordb()
graph = client.select_graph("example")
result = graph.query("RETURN 1")

It connects to falkor://localhost:6379 by default.

Using an Asynchronous Client

from kiarina.lib.falkordb.asyncio import get_falkordb

client = get_falkordb()
graph = client.select_graph("example")
result = await graph.query("RETURN 1")

Managing Multiple Configurations

settings_manager uses multiple-settings mode. Place named settings under configs.

kiarina.lib.falkordb:
  default: development
  configs:
    development:
      url: falkor://localhost:6379
    production:
      url: falkors://user:password@falkordb.example.com:6379
      use_retry: true

import yaml
from pydantic_settings_manager import load_user_configs

from kiarina.lib.falkordb import get_falkordb

with open("config.yaml", encoding="utf-8") as file:
    load_user_configs(yaml.safe_load(file) or {})

client = get_falkordb("production")

A single configuration can also be supplied through environment variables. Set initialize_params as a JSON object.

export KIARINA_LIB_FALKORDB_URL="falkor://localhost:6379"
export KIARINA_LIB_FALKORDB_USE_RETRY="true"
export KIARINA_LIB_FALKORDB_INITIALIZE_PARAMS='{}'

Caching Clients

Synchronous and asynchronous clients use separate caches. The connection URL is the default cache key. Arguments supplied after a client has been cached under the same key do not affect the existing instance.

from kiarina.lib.falkordb import get_falkordb

default_client = get_falkordb()
assert get_falkordb() is default_client

analytics_client = get_falkordb(cache_key="analytics")
assert analytics_client is not default_client

Retrying Connection Errors

With use_retry=True, the client retries redis.ConnectionError and redis.TimeoutError with exponential backoff. The asynchronous client retries the corresponding redis.asyncio exceptions.

from kiarina.lib.falkordb import get_falkordb

client = get_falkordb(use_retry=True)

The socket_timeout, socket_connect_timeout, health_check_interval, retry_attempts, and retry_delay settings apply in retry mode.

Overriding Client Parameters

Additional keyword arguments override initialize_params and are passed to FalkorDB.from_url().

from kiarina.lib.falkordb import get_falkordb

client = get_falkordb(
    url="falkor://localhost:6379",
    use_retry=True,
)

API Reference

kiarina.lib.falkordb

from kiarina.lib.falkordb import (
    FalkorDBSettings,
    get_falkordb,
    settings_manager,
)

get_falkordb

def get_falkordb(
    settings_key: str | None = None,
    *,
    cache_key: str | None = None,
    use_retry: bool | None = None,
    url: str | None = None,
    **kwargs: Any,
) -> falkordb.FalkorDB: ...

Returns a synchronous FalkorDB client.

Parameters

  • settings_key (str | None): Name of the settings to retrieve.
  • cache_key (str | None): Key that identifies the client instance. Defaults to the connection URL.
  • use_retry (bool | None): Whether to enable retries. Defaults to the setting.
  • url (str | None): FalkorDB connection URL. Defaults to the setting.
  • **kwargs (Any): Client initialization arguments that override initialize_params.

Returns

  • falkordb.FalkorDB: Cached synchronous FalkorDB client.

FalkorDBSettings

class FalkorDBSettings(BaseSettings):
    def __init__(
        self,
        *,
        url: SecretStr = SecretStr("falkor://localhost:6379"),
        initialize_params: dict[str, Any] = {},
        use_retry: bool = False,
        socket_timeout: float = 6.0,
        socket_connect_timeout: float = 3.0,
        health_check_interval: int = 60,
        retry_attempts: int = 3,
        retry_delay: float = 1.0,
    ) -> None: ...

FalkorDB client settings.

Fields

  • url (SecretStr): FalkorDB connection URL.
  • initialize_params (dict[str, Any]): Additional arguments passed to FalkorDB.from_url().
  • use_retry (bool): Whether to retry connection and timeout errors.
  • socket_timeout (float): Socket read and write timeout in seconds in retry mode.
  • socket_connect_timeout (float): Socket connection timeout in seconds in retry mode.
  • health_check_interval (int): Health check interval in seconds in retry mode.
  • retry_attempts (int): Number of retry attempts.
  • retry_delay (float): Maximum exponential backoff delay in seconds.

settings_manager

settings_manager: SettingsManager[FalkorDBSettings]

Global instance that manages named FalkorDB client settings.

kiarina.lib.falkordb.asyncio

from kiarina.lib.falkordb.asyncio import (
    FalkorDBSettings,
    get_falkordb,
    settings_manager,
)

get_falkordb

def get_falkordb(
    settings_key: str | None = None,
    *,
    cache_key: str | None = None,
    use_retry: bool | None = None,
    url: str | None = None,
    **kwargs: Any,
) -> falkordb.asyncio.FalkorDB: ...

Returns an asynchronous FalkorDB client. Its parameters and caching behavior match the synchronous version.

FalkorDBSettings

The same class as kiarina.lib.falkordb.FalkorDBSettings.

settings_manager

The same instance as kiarina.lib.falkordb.settings_manager.

Project links

Data verified by PyPI on Sep 5, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for kiarina from gravatar.com kiarina

Credits

PyPI data
Data sourced directly from PyPI's database.

Author/Maintainer: kiarina

GitHub Statistics

Data verified by PyPI on Sep 5, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Tags

client database falkordb graph pydantic redis settings

Classifiers

Report project as malware

Download files

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

Source Distribution

kiarina_lib_falkordb-2.28.0.tar.gz (7.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

kiarina_lib_falkordb-2.28.0-py3-none-any.whl (8.4 kB view details)

Uploaded Python 3

File details

Details for the file kiarina_lib_falkordb-2.28.0.tar.gz.

File metadata

  • Download URL: kiarina_lib_falkordb-2.28.0.tar.gz
  • Upload date:
  • Size: 7.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for kiarina_lib_falkordb-2.28.0.tar.gz
Algorithm Hash digest
SHA256 7bbd1bbafe3428b0fe6a69ad7509150c26073ced21079f4a4ebcb264bf31d1df
MD5 8fa12854d871485b54884afb4b2d66c2
BLAKE2b-256 4cdfaacc2946e41cf5debf9880cf419283dd52907cdb67708ad37b65f5494b78

See more details on using hashes here.

Provenance

The following attestation bundles were made for kiarina_lib_falkordb-2.28.0.tar.gz:

Publisher: release-pypi.yml on kiarina/kiarina-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kiarina_lib_falkordb-2.28.0-py3-none-any.whl.

File metadata

File hashes

Hashes for kiarina_lib_falkordb-2.28.0-py3-none-any.whl
Algorithm Hash digest
SHA256 49567e4cc7cb6d12098b77b644d8e066c34627a719e4a41ab027234af4d9e6c3
MD5 68ddc02206eabf2745d890675145bdee
BLAKE2b-256 c446c6179eefbac1f357fc110ca3ba5520e7db5b50ed12444b43c49072b78d40

See more details on using hashes here.

Provenance

The following attestation bundles were made for kiarina_lib_falkordb-2.28.0-py3-none-any.whl:

Publisher: release-pypi.yml on kiarina/kiarina-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

2.28.0 This release

2 files

2.3.1

2 files

2.1.0

2 files

2.0.0

2 files

1.37.0

2 files

1.36.0

2 files

1.35.0

2 files

1.34.0

2 files

1.33.1

2 files

1.33.0

2 files

1.32.0

2 files

1.31.1

2 files

1.31.0

2 files

1.30.0

2 files

1.29.0

2 files

1.28.0

2 files

1.27.0

2 files

1.26.0

2 files

1.25.1

2 files

1.25.0

2 files

1.24.0

2 files

1.23.0

2 files

1.22.1

2 files

1.22.0

2 files

1.21.1

2 files

1.21.0

2 files

1.20.1

2 files

1.20.0

2 files

1.19.0

2 files

1.18.2

2 files

1.18.1

2 files

1.18.0

2 files

1.17.0

2 files

1.16.0

2 files

1.15.1

2 files

1.15.0

2 files

1.14.0

2 files

1.13.0

2 files

1.12.0

2 files

1.11.2

2 files

1.11.1

2 files

1.11.0

2 files

1.10.0

2 files

1.9.0

2 files

1.8.0

2 files

1.7.0

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.0

2 files

1.4.0

2 files

1.3.0

2 files

1.2.0

2 files

1.1.1

2 files

1.1.0

2 files

1.0.1

2 files

1.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page