kiarina-lib-falkordb 1.0.0__py3-none-any.whl

kiarina/lib/falkordb/__init__.py

@@ -0,0 +1,27 @@
+import logging
+from importlib import import_module
+from importlib.metadata import version
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._sync.registry import get_falkordb
+    from .settings import settings_manager
+
+__version__ = version("kiarina-lib-falkordb")
+
+__all__ = ["get_falkordb", "settings_manager"]
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+
+def __getattr__(name: str) -> object:
+    if name not in __all__:
+        raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+    module_map = {
+        "get_falkordb": "._sync.registry",
+        "settings_manager": ".settings",
+    }
+
+    globals()[name] = getattr(import_module(module_map[name], __name__), name)
+    return globals()[name]

kiarina/lib/falkordb/_async/registry.py

@@ -0,0 +1,39 @@
+from typing import Any
+
+from falkordb.asyncio import FalkorDB  # type: ignore
+
+from .._core.registry import get_falkordb as _get_falkordb
+
+
+def get_falkordb(
+    config_key: str | None = None,
+    *,
+    cache_key: str | None = None,
+    use_retry: bool | None = None,
+    url: str | None = None,
+    **kwargs: Any,
+) -> FalkorDB:
+    """
+    Get a FalkorDB client (async version - currently uses sync implementation).
+
+    Note: FalkorDB doesn't have native async support yet, so this currently
+    returns the same sync client. This is prepared for future async support.
+
+    Args:
+        config_key (str | None): The configuration key for the FalkorDB client.
+        cache_key (str | None): The cache key for the FalkorDB client.
+        use_retry (bool | None): Whether to use retry for the FalkorDB client.
+        url (str | None): The FalkorDB URL.
+        **kwargs: Additional keyword arguments for the FalkorDB client.
+
+    Returns:
+        FalkorDB: The FalkorDB client.
+    """
+    return _get_falkordb(
+        "async",
+        config_key,
+        cache_key=cache_key,
+        use_retry=use_retry,
+        url=url,
+        **kwargs,
+    )

kiarina/lib/falkordb/_core/registry.py

@@ -0,0 +1,103 @@
+from typing import Any, Literal, overload
+
+import falkordb  # type: ignore
+import falkordb.asyncio  # type: ignore
+import redis
+import redis.asyncio
+from redis.backoff import ExponentialBackoff
+from redis.retry import Retry
+
+from ..settings import settings_manager
+
+_sync_cache: dict[str, falkordb.FalkorDB] = {}
+"""
+Sync FalkorDB clients cache
+"""
+
+_async_cache: dict[str, falkordb.asyncio.FalkorDB] = {}
+"""
+Async FalkorDB clients cache
+"""
+
+
+@overload
+def get_falkordb(
+    mode: Literal["sync"],
+    config_key: str | None = None,
+    *,
+    cache_key: str | None = None,
+    use_retry: bool | None = None,
+    url: str | None = None,
+    **kwargs: Any,
+) -> falkordb.FalkorDB: ...
+
+
+@overload
+def get_falkordb(
+    mode: Literal["async"],
+    config_key: str | None = None,
+    *,
+    cache_key: str | None = None,
+    use_retry: bool | None = None,
+    url: str | None = None,
+    **kwargs: Any,
+) -> falkordb.asyncio.FalkorDB: ...
+
+
+def get_falkordb(
+    mode: Literal["sync", "async"],
+    config_key: str | None = None,
+    *,
+    cache_key: str | None = None,
+    use_retry: bool | None = None,
+    url: str | None = None,
+    **kwargs: Any,
+) -> falkordb.FalkorDB | falkordb.asyncio.FalkorDB:
+    """
+    Get a FalkorDB client with shared logic.
+    """
+    settings = settings_manager.get_settings_by_key(config_key)
+
+    if url is None:
+        url = settings.url
+
+    if use_retry is None:
+        use_retry = settings.use_retry
+
+    params = {**settings.initialize_params, **kwargs}
+
+    if use_retry:
+        params.update(
+            {
+                "socket_timeout": settings.socket_timeout,
+                "socket_connect_timeout": settings.socket_connect_timeout,
+                "health_check_interval": settings.health_check_interval,
+                "retry": Retry(
+                    ExponentialBackoff(cap=settings.retry_delay),
+                    settings.retry_attempts,
+                ),
+            }
+        )
+
+        if mode == "sync":
+            params["retry_on_error"] = [redis.ConnectionError, redis.TimeoutError]
+        else:
+            params["retry_on_error"] = [
+                redis.asyncio.ConnectionError,
+                redis.asyncio.TimeoutError,
+            ]
+
+    if cache_key is None:
+        cache_key = url
+
+    if mode == "sync":
+        if cache_key not in _sync_cache:
+            _sync_cache[cache_key] = falkordb.FalkorDB.from_url(url, **params)
+
+        return _sync_cache[cache_key]
+
+    else:
+        if cache_key not in _async_cache:
+            _async_cache[cache_key] = falkordb.asyncio.FalkorDB.from_url(url, **params)
+
+        return _async_cache[cache_key]

kiarina/lib/falkordb/_sync/registry.py

@@ -0,0 +1,36 @@
+from typing import Any
+
+from falkordb import FalkorDB  # type: ignore
+
+from .._core.registry import get_falkordb as _get_falkordb
+
+
+def get_falkordb(
+    config_key: str | None = None,
+    *,
+    cache_key: str | None = None,
+    use_retry: bool | None = None,
+    url: str | None = None,
+    **kwargs: Any,
+) -> FalkorDB:
+    """
+    Get a FalkorDB client.
+
+    Args:
+        config_key (str | None): The configuration key for the FalkorDB client.
+        cache_key (str | None): The cache key for the FalkorDB client.
+        use_retry (bool | None): Whether to use retry for the FalkorDB client.
+        url (str | None): The FalkorDB URL.
+        **kwargs: Additional keyword arguments for the FalkorDB client.
+
+    Returns:
+        FalkorDB: The FalkorDB client.
+    """
+    return _get_falkordb(
+        "sync",
+        config_key,
+        cache_key=cache_key,
+        use_retry=use_retry,
+        url=url,
+        **kwargs,
+    )

kiarina/lib/falkordb/asyncio.py

@@ -0,0 +1,25 @@
+import logging
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._async.registry import get_falkordb
+    from .settings import settings_manager
+
+__all__ = ["get_falkordb", "settings_manager"]
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+
+def __getattr__(name: str) -> object:
+    if name not in __all__:
+        raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+    module_map = {
+        "get_falkordb": "._async.registry",
+        "settings_manager": ".settings",
+    }
+
+    parent = __name__.rsplit(".", 1)[0]
+    globals()[name] = getattr(import_module(module_map[name], parent), name)
+    return globals()[name]

kiarina/lib/falkordb/settings.py

@@ -0,0 +1,70 @@
+from typing import Any
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings_manager import SettingsManager
+
+
+class FalkorDBSettings(BaseSettings):
+    """
+    FalkorDB Settings
+    """
+
+    model_config = SettingsConfigDict(env_prefix="KIARINA_LIB_FALKORDB_")
+
+    url: str = "falkor://localhost:6379"
+    """
+    FalkorDB URL
+
+    Example:
+    - falkor://[[username]:[password]]@localhost:6379
+    - falkors://[[username]:[password]]@localhost:6379
+    """
+
+    initialize_params: dict[str, Any] = Field(default_factory=dict)
+    """
+    Additional parameters to initialize the FalkorDB client.
+    """
+
+    use_retry: bool = False
+    """
+    Whether to enable automatic retries
+
+    When enabled, it is configured to retry upon occurrence of
+    redis.ConnectionError or redis.TimeoutError.
+    """
+
+    socket_timeout: float = 6.0
+    """
+    Socket timeout in seconds
+
+    After sending a command, if this time is exceeded, a redis.TimeoutError will be raised.
+    """
+
+    socket_connect_timeout: float = 3.0
+    """
+    Socket connection timeout in seconds
+
+    If this time is exceeded when establishing a new connection, a redis.ConnectionError will occur.
+    """
+
+    health_check_interval: int = 60
+    """
+    Health check interval in seconds
+
+    When acquiring a connection from the pool,
+    if the time since last use has elapsed, execute a PING to verify the connection status.
+    """
+
+    retry_attempts: int = 3
+    """
+    Number of retry attempts
+    """
+
+    retry_delay: float = 1.0
+    """
+    Delay between retry attempts in seconds
+    """
+
+
+settings_manager = SettingsManager(FalkorDBSettings, multi=True)

kiarina_lib_falkordb-1.0.0.dist-info/METADATA

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: kiarina-lib-falkordb
+Version: 1.0.0
+Summary: FalkorDB client library for kiarina namespace
+Project-URL: Homepage, https://github.com/kiarina/kiarina-python
+Project-URL: Repository, https://github.com/kiarina/kiarina-python
+Project-URL: Issues, https://github.com/kiarina/kiarina-python/issues
+Project-URL: Changelog, https://github.com/kiarina/kiarina-python/blob/main/packages/kiarina-lib-falkordb/CHANGELOG.md
+Project-URL: Documentation, https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-lib-falkordb#readme
+Author-email: kiarina <kiarinadawa@gmail.com>
+Maintainer-email: kiarina <kiarinadawa@gmail.com>
+License: MIT
+Keywords: client,database,falkordb,graph,pydantic,redis,settings
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: falkordb
+Requires-Dist: pydantic-settings-manager>=2.1.0
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: redis>=6.4.0
+Description-Content-Type: text/markdown
+
+# kiarina-lib-falkordb
+
+A Python client library for [FalkorDB](https://falkordb.com/) with configuration management and connection pooling.
+
+## Features
+
+- **Configuration Management**: Use `pydantic-settings-manager` for flexible configuration
+- **Connection Pooling**: Automatic connection caching and reuse
+- **Retry Support**: Built-in retry mechanism for connection failures
+- **Sync & Async**: Support for both synchronous and asynchronous operations
+- **Type Safety**: Full type hints and Pydantic validation
+
+## Installation
+
+```bash
+pip install kiarina-lib-falkordb
+```
+
+## Quick Start
+
+### Basic Usage (Sync)
+
+```python
+from kiarina.lib.falkordb import get_falkordb
+
+# Get a FalkorDB client with default settings
+db = get_falkordb()
+
+# Select a graph and run a query
+graph = db.select_graph("social")
+result = graph.query("CREATE (p:Person {name: 'Alice', age: 30}) RETURN p")
+print(result.result_set)
+```
+
+### Async Usage
+
+```python
+from kiarina.lib.falkordb.asyncio import get_falkordb
+
+async def main():
+    # Get an async FalkorDB client
+    db = get_falkordb()
+
+    # Select a graph and run a query
+    graph = db.select_graph("social")
+    result = await graph.query("CREATE (p:Person {name: 'Bob', age: 25}) RETURN p")
+    print(result.result_set)
+```
+
+## Configuration
+
+This library uses [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) for flexible configuration management.
+
+### Environment Variables
+
+Configure the FalkorDB connection using environment variables:
+
+```bash
+# FalkorDB connection URL
+export KIARINA_LIB_FALKORDB_URL="falkor://localhost:6379"
+
+# Enable retry mechanism
+export KIARINA_LIB_FALKORDB_USE_RETRY="true"
+
+# Timeout settings
+export KIARINA_LIB_FALKORDB_SOCKET_TIMEOUT="6.0"
+export KIARINA_LIB_FALKORDB_SOCKET_CONNECT_TIMEOUT="3.0"
+
+# Retry settings
+export KIARINA_LIB_FALKORDB_RETRY_ATTEMPTS="3"
+export KIARINA_LIB_FALKORDB_RETRY_DELAY="1.0"
+```
+
+### Programmatic Configuration
+
+```python
+from kiarina.lib.falkordb import settings_manager
+
+# Configure for multiple environments
+settings_manager.user_config = {
+    "development": {
+        "url": "falkor://localhost:6379",
+        "use_retry": True,
+        "retry_attempts": 3
+    },
+    "production": {
+        "url": "falkor://prod-server:6379",
+        "use_retry": True,
+        "retry_attempts": 5,
+        "socket_timeout": 10.0
+    }
+}
+
+# Switch to production configuration
+settings_manager.active_key = "production"
+db = get_falkordb()
+```
+
+### Runtime Overrides
+
+```python
+from kiarina.lib.falkordb import get_falkordb
+
+# Override settings at runtime
+db = get_falkordb(
+    url="falkor://custom-server:6379",
+    use_retry=True
+)
+```
+
+## Advanced Usage
+
+### Connection Caching
+
+```python
+from kiarina.lib.falkordb import get_falkordb
+
+# These will return the same cached connection
+db1 = get_falkordb()
+db2 = get_falkordb()
+assert db1 is db2
+
+# Use different cache keys for separate connections
+db3 = get_falkordb(cache_key="secondary")
+assert db1 is not db3
+```
+
+### Custom Configuration Keys
+
+```python
+from kiarina.lib.falkordb import settings_manager, get_falkordb
+
+# Configure multiple named configurations
+settings_manager.user_config = {
+    "analytics": {
+        "url": "falkor://analytics-db:6379",
+        "socket_timeout": 30.0
+    },
+    "cache": {
+        "url": "falkor://cache-db:6379",
+        "socket_timeout": 5.0
+    }
+}
+
+# Use specific configurations
+analytics_db = get_falkordb("analytics")
+cache_db = get_falkordb("cache")
+```
+
+### Error Handling and Retries
+
+```python
+from kiarina.lib.falkordb import get_falkordb
+
+# Enable automatic retries for connection issues
+db = get_falkordb(use_retry=True)
+
+try:
+    graph = db.select_graph("mydata")
+    result = graph.query("MATCH (n) RETURN count(n)")
+except Exception as e:
+    print(f"Query failed: {e}")
+```
+
+## Configuration Reference
+
+| Setting | Environment Variable | Default | Description |
+|---------|---------------------|---------|-------------|
+| `url` | `KIARINA_LIB_FALKORDB_URL` | `"falkor://localhost:6379"` | FalkorDB connection URL |
+| `use_retry` | `KIARINA_LIB_FALKORDB_USE_RETRY` | `false` | Enable automatic retries |
+| `socket_timeout` | `KIARINA_LIB_FALKORDB_SOCKET_TIMEOUT` | `6.0` | Socket timeout in seconds |
+| `socket_connect_timeout` | `KIARINA_LIB_FALKORDB_SOCKET_CONNECT_TIMEOUT` | `3.0` | Connection timeout in seconds |
+| `health_check_interval` | `KIARINA_LIB_FALKORDB_HEALTH_CHECK_INTERVAL` | `60` | Health check interval in seconds |
+| `retry_attempts` | `KIARINA_LIB_FALKORDB_RETRY_ATTEMPTS` | `3` | Number of retry attempts |
+| `retry_delay` | `KIARINA_LIB_FALKORDB_RETRY_DELAY` | `1.0` | Delay between retries in seconds |
+
+## URL Formats
+
+FalkorDB URLs support the following formats:
+
+- `falkor://localhost:6379` - Basic connection
+- `falkor://username:password@localhost:6379` - With authentication
+- `falkors://localhost:6379` - SSL/TLS connection
+- `falkors://username:password@localhost:6379` - SSL/TLS with authentication
+
+## Development
+
+### Prerequisites
+
+- Python 3.12+
+- Docker (for running FalkorDB in tests)
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/kiarina/kiarina-python.git
+cd kiarina-python
+
+# Setup development environment (installs tools, syncs dependencies, downloads test data)
+mise run setup
+
+# Start FalkorDB for testing
+docker compose up -d falkordb
+```
+
+### Running Tests
+
+```bash
+# Run format, lint, type checks and tests
+mise run package kiarina-lib-falkordb
+
+# Coverage report
+mise run package:test kiarina-lib-falkordb --coverage
+
+# Run specific tests
+uv run --group test pytest packages/kiarina-lib-falkordb/tests/test_sync.py
+uv run --group test pytest packages/kiarina-lib-falkordb/tests/test_async.py
+```
+
+## Dependencies
+
+- [falkordb](https://github.com/kiarina/falkordb-py) - FalkorDB Python client (fork with redis-py 6.x support and async bug fixes)
+- [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) - Settings management
+- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Advanced settings management
+- [redis](https://github.com/redis/redis-py) - Redis client (FalkorDB is Redis-compatible)
+
+### Note on FalkorDB Client
+
+This library uses a [fork of the official FalkorDB Python client](https://github.com/kiarina/falkordb-py) instead of the [upstream version](https://github.com/FalkorDB/falkordb-py). The fork includes:
+
+- **Redis-py 6.x compatibility**: Support for redis-py 6.4.0+ (upstream only supports 5.x)
+- **Async client bug fixes**: Fixes for issues in the asynchronous client implementation
+- **Enhanced stability**: Additional improvements for production use
+
+The fork is based on the upstream `develop` branch and will be synchronized with upstream changes. Once these improvements are merged upstream, this library will migrate back to the official client.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.
+
+## Contributing
+
+This is a personal project, but contributions are welcome! Please feel free to submit issues or pull requests.
+
+## Related Projects
+
+- [kiarina-python](https://github.com/kiarina/kiarina-python) - The main monorepo containing this package
+- [FalkorDB](https://www.falkordb.com/) - The graph database this library connects to
+- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Configuration management library used by this package

kiarina_lib_falkordb-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+kiarina/lib/falkordb/__init__.py,sha256=6R2-ayazk1ijNbsB3U4lpPcp1a_ZgwU92m2vyFDaxBE,752
+kiarina/lib/falkordb/asyncio.py,sha256=XcYevSI3xtwNZzecfcs4foc0_WQU__o_iZasM2z8xo0,706
+kiarina/lib/falkordb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kiarina/lib/falkordb/settings.py,sha256=b1ktZqBKF-5cW_vALbhCK2uVIlE8xm4oqDnnjEcnknU,1696
+kiarina/lib/falkordb/_async/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kiarina/lib/falkordb/_async/registry.py,sha256=VsyriOprYjllNrfZnX0q_uC8OKiZKWvNo4HrcFQo3Xc,1153
+kiarina/lib/falkordb/_core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kiarina/lib/falkordb/_core/registry.py,sha256=b3ch2JMWLvcyELQQCnOyF28u2ckzKwp5-Y8cTER4Zms,2633
+kiarina/lib/falkordb/_sync/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kiarina/lib/falkordb/_sync/registry.py,sha256=SEnCMjOaOtu_5rNkv7DKxq4KGGnH3o0xtjbePdVc7s8,937
+kiarina_lib_falkordb-1.0.0.dist-info/METADATA,sha256=xS9OxhdzVQqh9s2iGVbJUswkkXlg7q8PoWy4NQajQVs,8855
+kiarina_lib_falkordb-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kiarina_lib_falkordb-1.0.0.dist-info/RECORD,,

kiarina_lib_falkordb-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any