# 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
Raw data
{
"_id": null,
"home_page": null,
"name": "kiarina-lib-redis",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "kiarina <kiarinadawa@gmail.com>",
"keywords": "async, cache, client, database, pydantic, redis, settings",
"author": null,
"author_email": "kiarina <kiarinadawa@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/94/bf/6c9998274b38489ed8e4f8bd8ec5f7939461d75a8111596be338a2c07e49/kiarina_lib_redis-1.6.3.tar.gz",
"platform": null,
"description": "# kiarina-lib-redis\n\nA Python client library for [Redis](https://redis.io/) with configuration management and connection pooling.\n\n## Features\n\n- **Configuration Management**: Use `pydantic-settings-manager` for flexible configuration\n- **Connection Pooling**: Automatic connection caching and reuse\n- **Retry Support**: Built-in retry mechanism for connection failures\n- **Sync & Async**: Support for both synchronous and asynchronous operations\n- **Type Safety**: Full type hints and Pydantic validation\n\n## Installation\n\n```bash\npip install kiarina-lib-redis\n```\n\n## Quick Start\n\n### Basic Usage (Sync)\n\n```python\nfrom kiarina.lib.redis import get_redis\n\n# Get a Redis client with default settings\nredis = get_redis()\n\n# Basic operations\nredis.set(\"key\", \"value\")\nvalue = redis.get(\"key\")\nprint(value) # b'value'\n\n# With decode_responses=True for string values\nredis = get_redis(decode_responses=True)\nredis.set(\"key\", \"value\")\nvalue = redis.get(\"key\")\nprint(value) # 'value'\n```\n\n### Async Usage\n\n```python\nfrom kiarina.lib.redis.asyncio import get_redis\n\nasync def main():\n # Get an async Redis client\n redis = get_redis(decode_responses=True)\n\n # Basic operations\n await redis.set(\"key\", \"value\")\n value = await redis.get(\"key\")\n print(value) # 'value'\n```\n\n## Configuration\n\nThis library uses [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) for flexible configuration management.\n\n### Environment Variables\n\nConfigure the Redis connection using environment variables:\n\n```bash\n# Redis connection URL\nexport KIARINA_LIB_REDIS_URL=\"redis://localhost:6379\"\n\n# Enable retry mechanism\nexport KIARINA_LIB_REDIS_USE_RETRY=\"true\"\n\n# Timeout settings\nexport KIARINA_LIB_REDIS_SOCKET_TIMEOUT=\"6.0\"\nexport KIARINA_LIB_REDIS_SOCKET_CONNECT_TIMEOUT=\"3.0\"\n\n# Retry settings\nexport KIARINA_LIB_REDIS_RETRY_ATTEMPTS=\"3\"\nexport KIARINA_LIB_REDIS_RETRY_DELAY=\"1.0\"\n```\n\n### Programmatic Configuration\n\n```python\nfrom kiarina.lib.redis import settings_manager\n\n# Configure for multiple environments\nsettings_manager.user_config = {\n \"development\": {\n \"url\": \"redis://localhost:6379\",\n \"use_retry\": True,\n \"retry_attempts\": 3\n },\n \"production\": {\n \"url\": \"redis://prod-server:6379\",\n \"use_retry\": True,\n \"retry_attempts\": 5,\n \"socket_timeout\": 10.0\n }\n}\n\n# Switch to production configuration\nsettings_manager.active_key = \"production\"\nredis = get_redis()\n```\n\n### Runtime Overrides\n\n```python\nfrom kiarina.lib.redis import get_redis\n\n# Override settings at runtime\nredis = get_redis(\n url=\"redis://custom-server:6379\",\n use_retry=True,\n decode_responses=True\n)\n```\n\n## Advanced Usage\n\n### Connection Caching\n\n```python\nfrom kiarina.lib.redis import get_redis\n\n# These will return the same cached connection\nredis1 = get_redis()\nredis2 = get_redis()\nassert redis1 is redis2\n\n# Use different cache keys for separate connections\nredis3 = get_redis(cache_key=\"secondary\")\nassert redis1 is not redis3\n```\n\n### Custom Configuration Keys\n\n```python\nfrom kiarina.lib.redis import settings_manager, get_redis\n\n# Configure multiple named configurations\nsettings_manager.user_config = {\n \"cache\": {\n \"url\": \"redis://cache-db:6379\",\n \"socket_timeout\": 5.0\n },\n \"session\": {\n \"url\": \"redis://session-db:6379\",\n \"socket_timeout\": 10.0\n }\n}\n\n# Use specific configurations\ncache_redis = get_redis(\"cache\")\nsession_redis = get_redis(\"session\")\n```\n\n### Error Handling and Retries\n\n```python\nfrom kiarina.lib.redis import get_redis\nimport redis\n\n# Enable automatic retries for connection issues\nredis_client = get_redis(use_retry=True)\n\ntry:\n redis_client.set(\"key\", \"value\")\n value = redis_client.get(\"key\")\nexcept redis.ConnectionError as e:\n print(f\"Connection failed: {e}\")\nexcept redis.TimeoutError as e:\n print(f\"Operation timed out: {e}\")\n```\n\n## Configuration Reference\n\n| Setting | Environment Variable | Default | Description |\n|---------|---------------------|---------|-------------|\n| `url` | `KIARINA_LIB_REDIS_URL` | `\"redis://localhost:6379\"` | Redis connection URL |\n| `use_retry` | `KIARINA_LIB_REDIS_USE_RETRY` | `false` | Enable automatic retries |\n| `socket_timeout` | `KIARINA_LIB_REDIS_SOCKET_TIMEOUT` | `6.0` | Socket timeout in seconds |\n| `socket_connect_timeout` | `KIARINA_LIB_REDIS_SOCKET_CONNECT_TIMEOUT` | `3.0` | Connection timeout in seconds |\n| `health_check_interval` | `KIARINA_LIB_REDIS_HEALTH_CHECK_INTERVAL` | `60` | Health check interval in seconds |\n| `retry_attempts` | `KIARINA_LIB_REDIS_RETRY_ATTEMPTS` | `3` | Number of retry attempts |\n| `retry_delay` | `KIARINA_LIB_REDIS_RETRY_DELAY` | `1.0` | Delay between retries in seconds |\n\n## URL Formats\n\nRedis URLs support the following formats:\n\n- `redis://localhost:6379` - Basic connection\n- `redis://username:password@localhost:6379` - With authentication\n- `rediss://localhost:6379` - SSL/TLS connection\n- `rediss://username:password@localhost:6379` - SSL/TLS with authentication\n- `redis://localhost:6379/0` - Specify database number\n- `unix:///path/to/socket.sock` - Unix socket connection\n\n## Development\n\n### Prerequisites\n\n- Python 3.12+\n- Docker (for running Redis in tests)\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/kiarina/kiarina-python.git\ncd kiarina-python\n\n# Setup development environment (installs tools, syncs dependencies, downloads test data)\nmise run setup\n\n# Start Redis for testing\ndocker compose up -d redis\n```\n\n### Running Tests\n\n```bash\n# Run format, lint, type checks and tests\nmise run package kiarina-lib-redis\n\n# Coverage report\nmise run package:test kiarina-lib-redis --coverage\n\n# Run specific tests\nuv run --group test pytest packages/kiarina-lib-redis/tests/test_sync.py\nuv run --group test pytest packages/kiarina-lib-redis/tests/test_async.py\n```\n\n## Dependencies\n\n- [redis](https://github.com/redis/redis-py) - Redis client for Python\n- [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) - Settings management\n- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Advanced settings management\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.\n\n## Contributing\n\nThis is a personal project, but contributions are welcome! Please feel free to submit issues or pull requests.\n\n## Related Projects\n\n- [kiarina-python](https://github.com/kiarina/kiarina-python) - The main monorepo containing this package\n- [Redis](https://redis.io/) - The in-memory data structure store this library connects to\n- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Configuration management library used by this package\n",
"bugtrack_url": null,
"license": null,
"summary": "Redis client library for kiarina namespace",
"version": "1.6.3",
"project_urls": {
"Changelog": "https://github.com/kiarina/kiarina-python/blob/main/packages/kiarina-lib-redis/CHANGELOG.md",
"Documentation": "https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-lib-redis#readme",
"Homepage": "https://github.com/kiarina/kiarina-python",
"Issues": "https://github.com/kiarina/kiarina-python/issues",
"Repository": "https://github.com/kiarina/kiarina-python"
},
"split_keywords": [
"async",
" cache",
" client",
" database",
" pydantic",
" redis",
" settings"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f1125c55f43e7dc9a3f12563c5ba896d73464b692ee0ee1fce862b1815a666cf",
"md5": "99bcd7410d7d4d617988729cffdc25ea",
"sha256": "2841a774cfce5864cd20e18eaa50b6d93506d9179f4d4b1a6c7a23707ac0e10f"
},
"downloads": -1,
"filename": "kiarina_lib_redis-1.6.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "99bcd7410d7d4d617988729cffdc25ea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 7970,
"upload_time": "2025-10-12T17:48:26",
"upload_time_iso_8601": "2025-10-12T17:48:26.519864Z",
"url": "https://files.pythonhosted.org/packages/f1/12/5c55f43e7dc9a3f12563c5ba896d73464b692ee0ee1fce862b1815a666cf/kiarina_lib_redis-1.6.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "94bf6c9998274b38489ed8e4f8bd8ec5f7939461d75a8111596be338a2c07e49",
"md5": "de54511b13ac8fb698f04d523cadcae0",
"sha256": "e1f22e3ff3b0e19cadabadb0f8dd8d9c9ff63f02ae57686457544eaec54121d9"
},
"downloads": -1,
"filename": "kiarina_lib_redis-1.6.3.tar.gz",
"has_sig": false,
"md5_digest": "de54511b13ac8fb698f04d523cadcae0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 6454,
"upload_time": "2025-10-12T17:48:35",
"upload_time_iso_8601": "2025-10-12T17:48:35.644916Z",
"url": "https://files.pythonhosted.org/packages/94/bf/6c9998274b38489ed8e4f8bd8ec5f7939461d75a8111596be338a2c07e49/kiarina_lib_redis-1.6.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-12 17:48:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kiarina",
"github_project": "kiarina-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kiarina-lib-redis"
}
JSON
