redis-simplify 0.1.0__py3-none-any.whl

redis_simplify/__init__.py

@@ -0,0 +1,19 @@
+import tomllib
+from pathlib import Path
+
+def _get_version():
+    try:
+        from importlib.metadata import version
+        return version("redis-simplify")
+    except Exception:
+        # Fallback: lê do pyproject.toml
+        try:
+            pyproject = Path(__file__).parent.parent / "pyproject.toml"
+            if pyproject.exists():
+                data = tomllib.loads(pyproject.read_text())
+                return data["project"]["version"]
+        except Exception:
+            pass
+        return "0.1.0"  # último recurso
+
+__version__ = _get_version()

redis_simplify/client.py

@@ -0,0 +1,323 @@
+# app/core/redis_client.py
+import redis
+import os
+import logging
+from typing import Optional, Set, List
+import json
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+class RedisClient:
+    """Cliente Redis genérico SÍNCRONO - pode ser usado por qualquer parte do sistema"""
+    
+    def __init__(
+       self,
+        host: str,
+        port: int = 6379,
+        password: Optional[str] = None,
+        db: int = 0,
+        decode_responses: bool = True,
+        socket_keepalive: bool = True,
+        health_check_interval: int = 30
+    ):
+        # Configuração obrigatória via parâmetros (não lê .env)
+        self.host = host
+        self.port = port
+        self.password = password
+        self.db = db
+        
+        self.decode_responses = decode_responses
+        self.socket_keepalive = socket_keepalive
+        self.health_check_interval = health_check_interval
+        
+        self.client: Optional[redis.Redis] = None
+        self._connect()
+    
+    def _connect(self):
+        """Estabelece conexão com Redis (síncrona)"""
+        try:
+            self.client = redis.Redis(
+                host=self.host,
+                port=self.port,
+                password=self.password or None,
+                db=self.db,
+                decode_responses=self.decode_responses,
+                socket_keepalive=self.socket_keepalive,
+                health_check_interval=self.health_check_interval
+            )
+            # Testa conexão
+            self.client.ping()
+            logger.info(f"RedisClient síncrono conectado: {self.host}:{self.port}")
+        except Exception as e:
+            logger.error(f"Erro ao conectar Redis: {e}")
+            self.client = None
+
+    def _ensure_connection(self) -> bool:
+        """Verifica conexão e tenta reconectar se necessário"""
+        if self.client:
+            try:
+                self.client.ping()
+                return True
+            except Exception:
+                self.client = None
+        
+        self._connect()
+        return self.client is not None
+        
+    def ping(self) -> bool:
+        """Testa conectividade"""
+        if not self._ensure_connection():
+            return False
+        try:
+            return self.client.ping()
+        except Exception as e:
+            logger.error(f"Erro no ping: {e}")
+            return False
+    
+
+
+    def scan(self, cursor: int = 0, match: Optional[str] = None, count: Optional[int] = None) -> tuple:
+        """
+        Implementação do comando SCAN do Redis
+        Retorna (nova_cursor, lista_de_chaves)
+        """
+        if not self._ensure_connection():
+            return 0, []
+        try:
+            # Redis-py retorna (cursor, keys)
+            return self.client.scan(cursor=cursor, match=match, count=count)
+        except Exception as e:
+            logger.error(f"Erro no scan: {e}")
+            return 0, []
+    # ========== OPERAÇÕES DE STRING ==========
+    
+    def set(self, key: str, value: str, expire_seconds: Optional[int] = None) -> bool:
+        """Define valor de uma chave"""
+        if not self._ensure_connection():
+            return False
+        try:
+            if expire_seconds:
+                self.client.setex(key, expire_seconds, value)
+            else:
+                self.client.set(key, value)
+            return True
+        except Exception as e:
+            logger.error(f"Erro no set {key}: {e}")
+            return False
+    
+    def get(self, key: str) -> Optional[str]:
+        """Obtém valor de uma chave"""
+        if not self._ensure_connection():
+            return None
+        try:
+            return self.client.get(key)
+        except Exception as e:
+            logger.error(f"Erro no get {key}: {e}")
+            return None
+    
+    def delete(self, *keys: str) -> int:
+        """Deleta uma ou mais chaves"""
+        if not self._ensure_connection():
+            return 0
+        try:
+            return self.client.delete(*keys)
+        except Exception as e:
+            logger.error(f"Erro no delete {keys}: {e}")
+            return 0
+    
+    def exists(self, key: str) -> bool:
+        """Verifica se chave existe"""
+        if not self._ensure_connection():
+            return False
+        try:
+            result = self.client.exists(key)
+            return bool(result)
+        except Exception as e:
+            logger.error(f"Erro no exists {key}: {e}")
+            return False
+    
+    def expire(self, key: str, seconds: int) -> bool:
+        """Define tempo de expiração"""
+        if not self._ensure_connection():
+            return False
+        try:
+            result = self.client.expire(key, seconds)
+            return bool(result)
+        except Exception as e:
+            logger.error(f"Erro no expire {key}: {e}")
+            return False
+    
+    def incr(self, key: str) -> int:
+        """Incrementa contador"""
+        if not self._ensure_connection():
+            return 0
+        try:
+            return self.client.incr(key)
+        except Exception as e:
+            logger.error(f"Erro no incr {key}: {e}")
+            return 0
+        
+    def decr(self, key: str) -> int:
+        """Decrementa contador"""
+        if not self._ensure_connection():
+            return 0
+        try:
+            return self.client.decr(key)
+        except Exception as e:
+            logger.error(f"Erro no decr {key}: {e}")
+            return 0
+    
+    # ========== OPERAÇÕES DE SET (CONJUNTOS) ==========
+    
+    def sadd(self, key: str, *values: str) -> int:
+        """Adiciona valores a um set"""
+        if not self._ensure_connection():
+            return 0
+        try:
+            return self.client.sadd(key, *values)
+        except Exception as e:
+            logger.error(f"Erro no sadd {key}: {e}")
+            return 0
+    
+    def srem(self, key: str, *values: str) -> int:
+        """Remove valores de um set"""
+        if not self._ensure_connection():
+            return 0
+        try:
+            return self.client.srem(key, *values)
+        except Exception as e:
+            logger.error(f"Erro no srem {key}: {e}")
+            return 0
+    
+    def smembers(self, key: str) -> Set[str]:
+        """Retorna todos os membros de um set"""
+        if not self._ensure_connection():
+            return set()
+        try:
+            return self.client.smembers(key)
+        except Exception as e:
+            logger.error(f"Erro no smembers {key}: {e}")
+            return set()
+    
+    def sismember(self, key: str, value: str) -> bool:
+        """Verifica se valor está no set"""
+        if not self._ensure_connection():
+            return False
+        try:
+            result = self.client.sismember(key, value)
+            return bool(result)
+        except Exception as e:
+            logger.error(f"Erro no sismember {key}: {e}")
+            return False
+    
+    def scard(self, key: str) -> int:
+        """Retorna tamanho do set"""
+        if not self._ensure_connection():
+            return 0
+        try:
+            return self.client.scard(key)
+        except Exception as e:
+            logger.error(f"Erro no scard {key}: {e}")
+            return 0
+    
+    # ========== OPERAÇÕES DE HASH ==========
+    
+    def hset(self, key: str, field: str, value: str) -> int:
+        """Define campo em hash"""
+        if not self._ensure_connection():
+            return 0
+        try:
+            return self.client.hset(key, field, value)
+        except Exception as e:
+            logger.error(f"Erro no hset {key}: {e}")
+            return 0
+    
+    def hget(self, key: str, field: str) -> Optional[str]:
+        """Obtém campo de hash"""
+        if not self._ensure_connection():
+            return None
+        try:
+            return self.client.hget(key, field)
+        except Exception as e:
+            logger.error(f"Erro no hget {key}: {e}")
+            return None
+    
+    def hgetall(self, key: str) -> dict:
+        """Obtém todo hash"""
+        if not self._ensure_connection():
+            return {}
+        try:
+            return self.client.hgetall(key)
+        except Exception as e:
+            logger.error(f"Erro no hgetall {key}: {e}")
+            return {}
+    
+    # ========== OPERAÇÕES DE LISTA ==========
+    
+    def lpush(self, key: str, *values: str) -> int:
+        """Adiciona ao início da lista"""
+        if not self._ensure_connection():
+            return 0
+        try:
+            return self.client.lpush(key, *values)
+        except Exception as e:
+            logger.error(f"Erro no lpush {key}: {e}")
+            return 0
+    
+    def rpush(self, key: str, *values: str) -> int:
+        """Adiciona ao final da lista"""
+        if not self._ensure_connection():
+            return 0
+        try:
+            return self.client.rpush(key, *values)
+        except Exception as e:
+            logger.error(f"Erro no rpush {key}: {e}")
+            return 0
+    
+    def lrange(self, key: str, start: int, end: int) -> List[str]:
+        """Retorna range da lista"""
+        if not self._ensure_connection():
+            return []
+        try:
+            return self.client.lrange(key, start, end)
+        except Exception as e:
+            logger.error(f"Erro no lrange {key}: {e}")
+            return []
+    
+    # ========== OPERAÇÕES COM JSON ==========
+    
+    def set_json(self, key: str, data: dict, expire_seconds: Optional[int] = None) -> bool:
+        """Armazena dados JSON"""
+        return self.set(key, json.dumps(data), expire_seconds)
+    
+    def get_json(self, key: str) -> Optional[dict]:
+        """Recupera dados JSON"""
+        value = self.get(key)
+        return json.loads(value) if value else None
+    
+    # ========== OPERAÇÕES DE PIPELINE ==========
+    
+    def pipeline(self):
+        """Retorna pipeline para operações em lote"""
+        if not self._ensure_connection():
+            return None
+        return self.client.pipeline()
+    
+    # ========== OPERAÇÕES DE ADMIN ==========
+    
+    def flush_all(self):
+        """Limpa tudo (CUIDADO: apenas para testes!)"""
+        if not self._ensure_connection():
+            return
+        try:
+            self.client.flushall()
+            logger.warning("Redis flushall executado!")
+        except Exception as e:
+            logger.error(f"Erro no flushall: {e}")
+    
+    def close(self):
+        """Fecha conexão"""
+        if self.client:
+            self.client.close()
+            logger.info("Conexão Redis fechada")

redis_simplify-0.1.0.dist-info/METADATA

@@ -0,0 +1,364 @@
+Metadata-Version: 2.4
+Name: redis-simplify
+Version: 0.1.0
+Summary: Wrapper de conveniência para Redis - conexão, JSON helpers e reconexão automática
+Author-email: Paulo Ricardo Tebet Lyrio <tebetpaulo91@yahoo.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Paulouuul/redis-simplify
+Project-URL: Repository, https://github.com/Paulouuul/redis-simplify
+Project-URL: Issues, https://github.com/Paulouuul/redis-simplify/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: redis>=4.0.0
+
+# redis-simplify
+
+[![PyPI Version](https://img.shields.io/pypi/v/redis-simplify)](https://pypi.org/project/redis-simplify/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/redis-simplify)](https://pypi.org/project/redis-simplify/)
+[![License](https://img.shields.io/pypi/l/redis-simplify)](LICENSE)
+
+A lightweight synchronous convenience wrapper for Redis built on top of **redis-py**.
+
+`redis-simplify` was created to reduce repetitive Redis boilerplate in Python applications by providing a simple and consistent interface with automatic reconnection, JSON helpers, centralized logging, and defensive error handling.
+
+> This package is not a Redis client replacement. It is a convenience layer built on top of `redis-py` to simplify common Redis operations.
+
+---
+
+## Features
+
+* Explicit Redis configuration (`host`, `port`, `password`, `db`)
+* Does **not** automatically read `.env` files
+* Automatic reconnection when Redis becomes unavailable
+* Centralized logging and error handling
+* JSON helpers for storing Python dictionaries
+* Safe fallback values on failures
+* Fully tested with `pytest`
+* Lightweight implementation
+* Synchronous API
+* Support for the most commonly used Redis operations:
+
+  * Strings
+  * Sets
+  * Hashes
+  * Lists
+  * Pipelines
+  * SCAN iteration
+
+---
+
+## Installation
+
+```bash
+pip install redis-simplify
+```
+
+---
+
+## Requirements
+
+* Python >= 3.8
+* redis-py >= 4.0.0
+
+---
+
+## Quick Start
+
+```python
+from redis_simplify import RedisClient
+
+client = RedisClient(
+    host="localhost",
+    port=6379
+)
+```
+
+---
+
+## Basic Usage
+
+### Strings
+
+```python
+from redis_simplify import RedisClient
+
+client = RedisClient(host="localhost", port=6379)
+
+client.set("chave", "valor")
+
+print(client.get("chave"))
+```
+
+Output:
+
+```python
+valor
+```
+
+---
+
+### JSON Helpers
+
+Store Python dictionaries directly in Redis.
+
+```python
+client.set_json(
+    "usuario:1",
+    {
+        "nome": "João",
+        "idade": 30
+    }
+)
+
+print(client.get_json("usuario:1"))
+```
+
+Output:
+
+```python
+{
+    "nome": "João",
+    "idade": 30
+}
+```
+
+---
+
+### Sets
+
+```python
+client.sadd("tags", "python", "redis")
+
+print(client.smembers("tags"))
+```
+
+Possible output:
+
+```python
+{"python", "redis"}
+```
+
+---
+
+### Connection Check
+
+```python
+if client.ping():
+    print("Redis online")
+else:
+    print("Redis unavailable")
+```
+
+---
+
+## Automatic Reconnection
+
+Before executing operations, the client verifies the connection status.
+
+If Redis becomes unavailable, the wrapper automatically attempts to reconnect before executing the requested command.
+
+This behavior is transparent to application code and helps reduce connection-management boilerplate.
+
+---
+
+## Error Handling
+
+All operations include consistent exception handling and logging.
+
+Instead of propagating Redis exceptions, the wrapper logs errors and returns safe fallback values whenever possible.
+
+### Fallback Values
+
+| Return Type     | Fallback |
+| --------------- | -------- |
+| Object / String | `None`   |
+| Boolean         | `False`  |
+| Numeric         | `0`      |
+| List            | `[]`     |
+| Dictionary      | `{}`     |
+| Set             | `set()`  |
+
+This approach helps keep application code clean and reduces repetitive `try/except` blocks.
+
+---
+
+## Available Methods
+
+### Strings
+
+| Method                                 | Description             |
+| -------------------------------------- | ----------------------- |
+| `set(key, value, expire_seconds=None)` | Set a value             |
+| `get(key)`                             | Retrieve a value        |
+| `delete(*keys)`                        | Delete one or more keys |
+| `exists(key)`                          | Check if a key exists   |
+| `expire(key, seconds)`                 | Set expiration time     |
+| `incr(key)`                            | Increment a value       |
+| `decr(key)`                            | Decrement a value       |
+
+---
+
+### JSON
+
+| Method                                     | Description                   |
+| ------------------------------------------ | ----------------------------- |
+| `set_json(key, data, expire_seconds=None)` | Store a dictionary as JSON    |
+| `get_json(key)`                            | Retrieve and deserialize JSON |
+
+---
+
+### Sets
+
+| Method                  | Description          |
+| ----------------------- | -------------------- |
+| `sadd(key, *values)`    | Add members          |
+| `srem(key, *values)`    | Remove members       |
+| `smembers(key)`         | Retrieve all members |
+| `sismember(key, value)` | Check membership     |
+| `scard(key)`            | Count members        |
+
+---
+
+### Hashes
+
+| Method                    | Description         |
+| ------------------------- | ------------------- |
+| `hset(key, field, value)` | Set a hash field    |
+| `hget(key, field)`        | Retrieve a field    |
+| `hgetall(key)`            | Retrieve all fields |
+
+---
+
+### Lists
+
+| Method                    | Description                  |
+| ------------------------- | ---------------------------- |
+| `lpush(key, *values)`     | Push values to the beginning |
+| `rpush(key, *values)`     | Push values to the end       |
+| `lrange(key, start, end)` | Retrieve a range of values   |
+
+---
+
+### Utilities
+
+| Method                                   | Description                |
+| ---------------------------------------- | -------------------------- |
+| `ping()`                                 | Verify connectivity        |
+| `pipeline()`                             | Create a Redis pipeline    |
+| `scan(cursor=0, match=None, count=None)` | Iterate keys using SCAN    |
+| `flush_all()`                            | Remove all Redis databases |
+| `close()`                                | Close the connection       |
+
+---
+
+## Pipeline Example
+
+```python
+pipe = client.pipeline()
+
+pipe.set("user:1", "John")
+pipe.set("user:2", "Jane")
+
+pipe.execute()
+```
+
+---
+
+## SCAN Example
+
+```python
+cursor = 0
+
+while True:
+    cursor, keys = client.scan(
+        cursor=cursor,
+        match="user:*",
+        count=100
+    )
+
+    print(keys)
+
+    if cursor == 0:
+        break
+```
+
+---
+
+## Shared Instance Pattern
+
+`redis-simplify` does not enforce a Singleton pattern.
+
+However, many applications create a single shared instance and reuse it throughout the project:
+
+```python
+from redis_simplify import RedisClient
+
+redis_client = RedisClient(
+    host="localhost",
+    port=6379
+)
+```
+
+---
+
+## Why redis-simplify?
+
+Many projects repeatedly implement:
+
+* Redis connection setup
+* Health checks
+* Reconnection logic
+* JSON serialization and deserialization
+* Logging
+* Defensive exception handling
+
+`redis-simplify` centralizes these concerns into a small reusable wrapper while preserving the familiar Redis workflow provided by `redis-py`.
+
+---
+
+## Running Tests
+
+The project includes automated tests built with `pytest`.
+
+```bash
+pytest
+```
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+To contribute:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add or update tests when applicable
+5. Open a Pull Request
+
+Bug reports, improvements, and feature suggestions are appreciated.
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+
+---
+
+## Author
+
+**Paulo Ricardo Tebet Lyrio**
+
+GitHub: https://github.com/Paulouuul/redis-simplify

redis_simplify-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+redis_simplify/__init__.py,sha256=uAcB3kC0h5vr1_zKZx_GMa7lCY7MDOGKozjlsrbZtB0,584
+redis_simplify/client.py,sha256=IYjt7UYmA69z-1A2JBvxoWByjO7r2SOtwjalSYjlUjM,10796
+redis_simplify-0.1.0.dist-info/METADATA,sha256=SgLtV4BlfXTxOgswVYv5uPIzSGjC9NmeybaHDlAyvts,8620
+redis_simplify-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+redis_simplify-0.1.0.dist-info/top_level.txt,sha256=5exHW7LkFNhYgELOqOPbubOiiSJfLdqJdpjZsPwPSRE,15
+redis_simplify-0.1.0.dist-info/RECORD,,

redis_simplify-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

redis_simplify-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+redis_simplify