redis-simplify 0.1.0__tar.gz

redis_simplify-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,342 @@
+# 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