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

kiarina/lib/redis/__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_redis
+    from .settings import settings_manager
+
+__version__ = version("kiarina-lib-redis")
+
+__all__ = ["get_redis", "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_redis": "._sync.registry",
+        "settings_manager": ".settings",
+    }
+
+    globals()[name] = getattr(import_module(module_map[name], __name__), name)
+    return globals()[name]

kiarina/lib/redis/_async/registry.py

@@ -0,0 +1,36 @@
+from typing import Any
+
+import redis.asyncio as redis
+
+from .._core.registry import get_redis as _get_redis
+
+
+def get_redis(
+    config_key: str | None = None,
+    *,
+    cache_key: str | None = None,
+    use_retry: bool | None = None,
+    url: str | None = None,
+    **kwargs: Any,
+) -> redis.Redis:
+    """
+    Get a Redis client.
+
+    Args:
+        config_key (str | None): The configuration key for the Redis client.
+        cache_key (str | None): The cache key for the Redis client.
+        use_retry (bool | None): Whether to use retry for the Redis client.
+        url (str | None): The Redis URL.
+        **kwargs: Additional keyword arguments for the Redis client.
+
+    Returns:
+        redis.Redis: The Redis client.
+    """
+    return _get_redis(
+        "async",
+        config_key,
+        cache_key=cache_key,
+        use_retry=use_retry,
+        url=url,
+        **kwargs,
+    )

kiarina/lib/redis/_core/registry.py

@@ -0,0 +1,101 @@
+from typing import Any, Literal, overload
+
+import redis
+import redis.asyncio
+from redis.backoff import ExponentialBackoff
+from redis.retry import Retry
+
+from ..settings import settings_manager
+
+_sync_cache: dict[str, redis.Redis] = {}
+"""
+Sync Redis clients cache
+"""
+
+_async_cache: dict[str, redis.asyncio.Redis] = {}
+"""
+Async Redis clients cache
+"""
+
+
+@overload
+def get_redis(
+    mode: Literal["sync"],
+    config_key: str | None = None,
+    *,
+    cache_key: str | None = None,
+    use_retry: bool | None = None,
+    url: str | None = None,
+    **kwargs: Any,
+) -> redis.Redis: ...
+
+
+@overload
+def get_redis(
+    mode: Literal["async"],
+    config_key: str | None = None,
+    *,
+    cache_key: str | None = None,
+    use_retry: bool | None = None,
+    url: str | None = None,
+    **kwargs: Any,
+) -> redis.asyncio.Redis: ...
+
+
+def get_redis(
+    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,
+) -> redis.Redis | redis.asyncio.Redis:
+    """
+    Get a Redis 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] = redis.Redis.from_url(url, **params)
+
+        return _sync_cache[cache_key]
+
+    else:
+        if cache_key not in _async_cache:
+            _async_cache[cache_key] = redis.asyncio.Redis.from_url(url, **params)
+
+        return _async_cache[cache_key]

kiarina/lib/redis/_sync/registry.py

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

kiarina/lib/redis/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_redis
+    from .settings import settings_manager
+
+__all__ = ["get_redis", "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_redis": "._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/redis/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 RedisSettings(BaseSettings):
+    """
+    Redis Settings
+    """
+
+    model_config = SettingsConfigDict(env_prefix="KIARINA_LIB_REDIS_")
+
+    url: str = "redis://localhost:6379"
+    """
+    Redis URL
+
+    Example:
+    - redis://[[username]:[password]]@localhost:6379
+    - rediss://[[username]:[password]]@localhost:6379
+    """
+
+    initialize_params: dict[str, Any] = Field(default_factory=dict)
+    """
+    Additional parameters to initialize the Redis 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(RedisSettings, multi=True)

kiarina_lib_redis-1.0.0.dist-info/METADATA

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: kiarina-lib-redis
+Version: 1.0.0
+Summary: Redis 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-redis/CHANGELOG.md
+Project-URL: Documentation, https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-lib-redis#readme
+Author-email: kiarina <kiarinadawa@gmail.com>
+Maintainer-email: kiarina <kiarinadawa@gmail.com>
+License: MIT
+Keywords: async,cache,client,database,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: 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-redis
+
+A Python client library for [Redis](https://redis.io/) 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-redis
+```
+
+## Quick Start
+
+### Basic Usage (Sync)
+
+```python
+from kiarina.lib.redis import get_redis
+
+# Get a Redis client with default settings
+redis = get_redis()
+
+# Basic operations
+redis.set("key", "value")
+value = redis.get("key")
+print(value)  # b'value'
+
+# With decode_responses=True for string values
+redis = get_redis(decode_responses=True)
+redis.set("key", "value")
+value = redis.get("key")
+print(value)  # 'value'
+```
+
+### Async Usage
+
+```python
+from kiarina.lib.redis.asyncio import get_redis
+
+async def main():
+    # Get an async Redis client
+    redis = get_redis(decode_responses=True)
+
+    # Basic operations
+    await redis.set("key", "value")
+    value = await redis.get("key")
+    print(value)  # 'value'
+```
+
+## Configuration
+
+This library uses [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) for flexible configuration management.
+
+### Environment Variables
+
+Configure the Redis connection using environment variables:
+
+```bash
+# Redis connection URL
+export KIARINA_LIB_REDIS_URL="redis://localhost:6379"
+
+# Enable retry mechanism
+export KIARINA_LIB_REDIS_USE_RETRY="true"
+
+# Timeout settings
+export KIARINA_LIB_REDIS_SOCKET_TIMEOUT="6.0"
+export KIARINA_LIB_REDIS_SOCKET_CONNECT_TIMEOUT="3.0"
+
+# Retry settings
+export KIARINA_LIB_REDIS_RETRY_ATTEMPTS="3"
+export KIARINA_LIB_REDIS_RETRY_DELAY="1.0"
+```
+
+### Programmatic Configuration
+
+```python
+from kiarina.lib.redis import settings_manager
+
+# Configure for multiple environments
+settings_manager.user_config = {
+    "development": {
+        "url": "redis://localhost:6379",
+        "use_retry": True,
+        "retry_attempts": 3
+    },
+    "production": {
+        "url": "redis://prod-server:6379",
+        "use_retry": True,
+        "retry_attempts": 5,
+        "socket_timeout": 10.0
+    }
+}
+
+# Switch to production configuration
+settings_manager.active_key = "production"
+redis = get_redis()
+```
+
+### Runtime Overrides
+
+```python
+from kiarina.lib.redis import get_redis
+
+# Override settings at runtime
+redis = get_redis(
+    url="redis://custom-server:6379",
+    use_retry=True,
+    decode_responses=True
+)
+```
+
+## Advanced Usage
+
+### Connection Caching
+
+```python
+from kiarina.lib.redis import get_redis
+
+# These will return the same cached connection
+redis1 = get_redis()
+redis2 = get_redis()
+assert redis1 is redis2
+
+# Use different cache keys for separate connections
+redis3 = get_redis(cache_key="secondary")
+assert redis1 is not redis3
+```
+
+### Custom Configuration Keys
+
+```python
+from kiarina.lib.redis import settings_manager, get_redis
+
+# Configure multiple named configurations
+settings_manager.user_config = {
+    "cache": {
+        "url": "redis://cache-db:6379",
+        "socket_timeout": 5.0
+    },
+    "session": {
+        "url": "redis://session-db:6379",
+        "socket_timeout": 10.0
+    }
+}
+
+# Use specific configurations
+cache_redis = get_redis("cache")
+session_redis = get_redis("session")
+```
+
+### Error Handling and Retries
+
+```python
+from kiarina.lib.redis import get_redis
+import redis
+
+# Enable automatic retries for connection issues
+redis_client = get_redis(use_retry=True)
+
+try:
+    redis_client.set("key", "value")
+    value = redis_client.get("key")
+except redis.ConnectionError as e:
+    print(f"Connection failed: {e}")
+except redis.TimeoutError as e:
+    print(f"Operation timed out: {e}")
+```
+
+## Configuration Reference
+
+| Setting | Environment Variable | Default | Description |
+|---------|---------------------|---------|-------------|
+| `url` | `KIARINA_LIB_REDIS_URL` | `"redis://localhost:6379"` | Redis connection URL |
+| `use_retry` | `KIARINA_LIB_REDIS_USE_RETRY` | `false` | Enable automatic retries |
+| `socket_timeout` | `KIARINA_LIB_REDIS_SOCKET_TIMEOUT` | `6.0` | Socket timeout in seconds |
+| `socket_connect_timeout` | `KIARINA_LIB_REDIS_SOCKET_CONNECT_TIMEOUT` | `3.0` | Connection timeout in seconds |
+| `health_check_interval` | `KIARINA_LIB_REDIS_HEALTH_CHECK_INTERVAL` | `60` | Health check interval in seconds |
+| `retry_attempts` | `KIARINA_LIB_REDIS_RETRY_ATTEMPTS` | `3` | Number of retry attempts |
+| `retry_delay` | `KIARINA_LIB_REDIS_RETRY_DELAY` | `1.0` | Delay between retries in seconds |
+
+## URL Formats
+
+Redis URLs support the following formats:
+
+- `redis://localhost:6379` - Basic connection
+- `redis://username:password@localhost:6379` - With authentication
+- `rediss://localhost:6379` - SSL/TLS connection
+- `rediss://username:password@localhost:6379` - SSL/TLS with authentication
+- `redis://localhost:6379/0` - Specify database number
+- `unix:///path/to/socket.sock` - Unix socket connection
+
+## Development
+
+### Prerequisites
+
+- Python 3.12+
+- Docker (for running Redis 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 Redis for testing
+docker compose up -d redis
+```
+
+### Running Tests
+
+```bash
+# Run format, lint, type checks and tests
+mise run package kiarina-lib-redis
+
+# Coverage report
+mise run package:test kiarina-lib-redis --coverage
+
+# Run specific tests
+uv run --group test pytest packages/kiarina-lib-redis/tests/test_sync.py
+uv run --group test pytest packages/kiarina-lib-redis/tests/test_async.py
+```
+
+## Dependencies
+
+- [redis](https://github.com/redis/redis-py) - Redis client for Python
+- [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
+
+## 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
+- [Redis](https://redis.io/) - The in-memory data structure store this library connects to
+- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Configuration management library used by this package

kiarina_lib_redis-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+kiarina/lib/redis/__init__.py,sha256=ryMfPJYw8-TKcyG-NhZZHZ47UeTC2A94mzENlwjxR50,740
+kiarina/lib/redis/asyncio.py,sha256=1khCmaPAPemFIxozT9ymY9w3a3etMfQAy7pImLztBzM,697
+kiarina/lib/redis/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kiarina/lib/redis/settings.py,sha256=NQtWauZjurSAASVrOu4qvZzlRvxW_9Gmo-mIpyBYHHo,1675
+kiarina/lib/redis/_async/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kiarina/lib/redis/_async/registry.py,sha256=uO3MYcadjBqHbwOMlcIdo4TN-mofm6u3kWRv96v3K_g,895
+kiarina/lib/redis/_core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kiarina/lib/redis/_core/registry.py,sha256=uFRYkTTT4GmDZ_LzHysUT_q6sXb_HO6o_3zk127LWtE,2495
+kiarina/lib/redis/_sync/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kiarina/lib/redis/_sync/registry.py,sha256=yIgZFQu580oD_t2z3-Rs6jfAmBRmpHjxpTX8VICvyGo,877
+kiarina_lib_redis-1.0.0.dist-info/METADATA,sha256=vODAiV6MSSapXnZXlJZzHLwyva3gnV4vnBOdoAJ7rXQ,8126
+kiarina_lib_redis-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kiarina_lib_redis-1.0.0.dist-info/RECORD,,

kiarina_lib_redis-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