redis-simplify 0.1.0

Wrapper de conveniência para Redis - conexão, JSON helpers e reconexão automática

redis-simplify

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

pip install redis-simplify

---

Requirements

• Python >= 3.8
• redis-py >= 4.0.0

---

Quick Start

from redis_simplify import RedisClient

client = RedisClient(
    host="localhost",
    port=6379
)

---

Basic Usage

Strings

from redis_simplify import RedisClient

client = RedisClient(host="localhost", port=6379)

client.set("chave", "valor")

print(client.get("chave"))

Output:

valor

---

JSON Helpers

Store Python dictionaries directly in Redis.

client.set_json(
    "usuario:1",
    {
        "nome": "João",
        "idade": 30
    }
)

print(client.get_json("usuario:1"))

Output:

{
    "nome": "João",
    "idade": 30
}

---

Sets

client.sadd("tags", "python", "redis")

print(client.smembers("tags"))

Possible output:

{"python", "redis"}

---

Connection Check

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

pipe = client.pipeline()

pipe.set("user:1", "John")
pipe.set("user:2", "Jane")

pipe.execute()

---

SCAN Example

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:

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.

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