redis-xsync 1.0.1__tar.gz

redis_xsync-1.0.1/PKG-INFO

@@ -0,0 +1,333 @@
+Metadata-Version: 2.4
+Name: redis-xsync
+Version: 1.0.1
+Summary: Sync/Async unified Redis client with distributed lock and rate limiter
+Author: Jay
+License: MIT
+Project-URL: Homepage, https://github.com/jaygarage/RedisXsync
+Project-URL: Repository, https://github.com/jaygarage/RedisXsync
+Project-URL: Issues, https://github.com/jaygarage/RedisXsync/issues
+Keywords: redis,async,sync,distributed-lock,redis-xsync,rate-limit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Distributed Computing
+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
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: redis>=5.0.0
+
+# RedisXsync
+
+![PyPI](https://img.shields.io/pypi/v/redis-xsync) ![Python](https://img.shields.io/pypi/pyversions/redis-xsync) ![License](https://img.shields.io/badge/license-MIT-green)
+
+RedisXsync 是一个 **同步 / 异步统一 Redis 客户端**，专为 **分布式锁** 和 **爬虫账号池限流** 场景设计，支持多实例、多
+DB，线程安全和协程安全。
+
+---
+
+## ✨ 核心特性
+
+| 特性          | 描述                               |
+|-------------|----------------------------------|
+| 同步 / 异步统一接口 | 同一套 API 支持 `with` 和 `async with` |
+| 多实例 / 多 DB  | 支持不同 Redis 实例与数据库同时管理            |
+| 分布式锁        | 单键锁、组合锁，阻塞 / 非阻塞模式               |
+| 账号池限流       | 基于 Lua 原子操作的令牌桶限流，可等待可用 token    |
+| 线程 & 协程安全   | 避免多线程 / 协程冲突                     |
+| 自动连接管理      | Context manager 自动释放连接           |
+
+---
+
+## 🏗 架构概览
+
+| RedisXsync               |
+|--------------------------|
+| Sync / Async Interfaces  |
+| Distributed Lock Manager |
+| Rate Limiter / TokenPool |
+
+- 分布式锁：通过单键或多键原子操作保证并发安全
+- 限流/账号池：Lua 脚本保证跨进程/跨机器的原子性，精确到毫秒
+
+---
+
+## 📦 安装
+
+```bash
+pip install redis-xsync
+
+---
+
+## 🚀 快速开始
+
+### 1️⃣ 注册 Redis
+
+​```python
+from redis_xsync import register_redis, resolve_redis, redisXsync
+
+redis1 = register_redis(
+    label="redis_xsync",
+    host="127.0.0.1",
+    port=6379,
+    db=0,
+    password=None,
+    decode_responses=True
+)
+
+# 通过 label 获取
+redis2 = resolve_redis("redis_xsync")
+
+
+# 使用方式说明：
+# 1️⃣ 全局默认实例 redisXsync
+#    - 在首次调用 register_redis 注册任意 Redis 时，首次注册会自动赋值给 redisXsync，非并发安全
+#    - 后续可以直接使用 redisXsync，无需通过 label 获取
+#
+# 2️⃣ 通过 label 显式管理 Redis
+#    - register_redis(label=..., ...) 注册 Redis 实例
+#    - resolve_redis(label) 根据 label 获取对应 Redis 实例
+#
+# 3️⃣ 独立实例
+#    - 可以直接创建 RedisXsync() 实例，不必参与 register_redis 、resolve_redis、 redisXsync 全局管理
+#    - 适合临时或隔离使用场景
+```
+
+## 🔄 同步 / 异步使用
+
+### ✅ 同步
+
+```python
+with redis1(db=1) as r:
+    r.setnx("key", "value")
+    print(r.get("key"))
+```
+
+---
+
+### ✅ 异步
+
+```python
+import asyncio
+
+
+async def main():
+    async with redis1(db=1) as r:
+        await r.setnx("key", "value")
+        print(await r.get("key"))
+
+
+asyncio.run(main())
+```
+
+---
+
+## 🔐 分布式锁（支持组合锁）
+
+### 特性
+
+* 多 key 原子加锁
+* 所有 key 释放才算解锁
+* 支持阻塞等待
+
+---
+
+### 示例（多线程 + 协程混合）
+
+```python
+import threading
+import asyncio
+from redis_xsync import register_redis
+
+cx = 0
+redis = register_redis(label="redis_xsync", host="127.0.0.1", port=6379)
+Lock = redis.AsyncRedisAtomicMultiLock
+
+
+def sync_worker():
+    global cx
+    for _ in range(5):
+        with Lock("lock_key", db=0, ttl_ms=10, blocking=True):
+            with redis(db=2) as r:
+                r.setnx("db2", str(cx))
+                cx += 1
+                print(f"[SYNC] {cx=}")
+
+
+async def async_worker():
+    global cx
+    for _ in range(5):
+        with Lock("lock_key", db=0, ttl_ms=10, blocking=True):
+            async with redis(db=3) as r:
+                await r.setnx("db3", str(cx))
+                cx += 1
+                print(f"[ASYNC] {cx=}")
+        await asyncio.sleep(0.2)
+
+
+# 启动线程
+threading.Thread(target=sync_worker).start()
+
+# 启动协程
+asyncio.run(async_worker())
+```
+
+---
+
+## 🚦 爬虫账号池限流
+
+基于 Redis + Lua，实现**分布式限流 + 自动等待可用账号**
+
+📦 Limited — Redis 容器操作方法对照表
+
+| 方法                                                  | 异步 | 阻塞 | 遵循限流 | 数量 | 描述                     |
+|-----------------------------------------------------|----|----|------|----|------------------------|
+| `set_available_containers(*containers)`             | ✅  | ❌  | ✅    | N  | 存储/更新容器配置（生产者）         |
+| `ask_available_containers(quantity)`                | ✅  | ❌  | ✅    | N  | 获取 N 个可用容器，若无返回 `None` |
+| `ask_available_container()`                         | ✅  | ❌  | ✅    | 1  | 获取单个可用容器，若无返回 `None`   |
+| `wait_ask_available_containers(quantity, timeout)`  | ✅  | ✅  | ✅    | N  | 阻塞等待 N 个可用容器           |
+| `wait_ask_available_container(timeout)`             | ✅  | ✅  | ✅    | 1  | 阻塞等待单个可用容器             |
+| `acquire_random_containers(quantity)`               | ✅  | ❌  | ❌    | N  | 随机获取 N 个容器，忽略限流        |
+| `acquire_random_container()`                        | ✅  | ❌  | ❌    | 1  | 随机获取单个容器，忽略限流          |
+| `wait_acquire_random_containers(quantity, timeout)` | ✅  | ✅  | ❌    | N  | 阻塞等待 N 个随机容器，忽略限流      |
+| `wait_acquire_random_container(timeout)`            | ✅  | ✅  | ❌    | 1  | 阻塞等待单个随机容器，忽略限流        |
+
+---
+
+### 写入账号（生产者）
+
+## LimitedModel 说明
+
+`LimitedModel` 用于表示受限访问（rate-limited）的容器条目，每条数据包含唯一标识、时间戳、TTL、访问间隔和访问计数等信息。
+
+### 字段说明
+
+| 字段                    | 类型    | 默认值       | 描述                  |
+|-----------------------|-------|-----------|---------------------|
+| `id`                  | `str` | —         | 数据唯一标识符，必须提供        |
+| `ct`                  | `int` | 当前时间戳（毫秒） | 记录条目的收集时间，无需设置      |
+| `ttl_ms`              | `int` | `0`       | 条目的生存时间（毫秒），0 表示无限期 |
+| `interval_ms`         | `int` | `0`       | 访问间隔（毫秒），0 表示不限速    |
+| `next_time_available` | `int` | 当前时间戳（毫秒） | 下次可访问时间，用于限流控制，无需设置 |
+| `containers`          | `str` | `None`    | 存储容器数据，可为空          |
+| `usage_count`         | `int` | `0`       | 条目被访问的次数，无需设置       |
+### 使用说明
+
+- `ct` 和 `next_time_available` 都以毫秒为单位，便于高精度限流。
+- `interval_ms > 0` 时，访问条目会更新 `next_time_available` 为当前时间 + 间隔。
+- 每次访问条目时，都会通过 `usage_count` 记录被访问次数，以统计和调度。
+- `ttl_ms` 可配合 Redis 等存储设置过期时间，实现自动清理。
+
+```python
+import random
+from redis_xsync import register_redis
+from redis_xsync.rtypes import LimitedModel
+
+redis = register_redis(label="redis_xsync", host="127.0.0.1", port=6379)
+Limited = redis.Limited
+
+
+async def produce_container():
+    async with Limited(redis_key="crawler:identity:flow_limit") as lt:
+        for i in range(10):
+            token = LimitedModel(
+                id=f"user_{i}",
+                ttl_ms=random.randint(30000, 60000),
+                interval_ms=random.randint(1000, 6000),
+                containers="cookies"
+            )
+            await lt.set_available_containers(token)
+```
+
+---
+
+### 获取账号（消费者，阻塞等待）
+
+```python
+async def consume_token():
+    async with Limited(redis_key="crawler:identity:flow_limit") as lt:
+        # 等待可用 token，超时 10 秒
+        token = await lt.wait_ask_available_containers(quantity=1, timeout=10)
+        print("获取到账号:", token)
+```
+
+---
+
+### 同步调用
+
+```python
+def consume_sync():
+    with Limited(redis_key="crawler:identity:flow_limit") as lt:
+        token = lt.wait_ask_available_containers(quantity=1, timeout=10)
+        print("获取到账号:", token)
+```
+
+## ⚡ 说明：
+
+- produce_container 写入 token 到 Redis，带过期时间和间隔限流
+- consume_token 或 consume_sync 从 Redis 中获取可用 token，如果当前没有可用，会等待直到 timeout
+- 支持异步和同步，且保证跨进程 / 跨机器原子性
+
+---
+
+## 🧠 设计说明
+
+### 🔐 分布式锁
+
+* 基于 Redis 原子操作
+* 支持多 key（组合锁）
+* 防止并发冲突
+
+---
+
+### 🚦 限流模型
+
+* 每个 token：
+
+    * 独立 TTL
+    * 独立间隔（interval）
+* Lua 保证原子性
+* 支持多进程 / 多机器共享
+
+---
+
+## ⚠️ 注意事项
+
+### Windows 建议
+
+```python
+import asyncio
+
+asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+```
+
+---
+
+## 📌 适用场景
+
+* 单机非集群
+* 爬虫账号池
+* 接口限流
+* 分布式任务调度
+* 多服务并发控制
+
+---
+
+## 🤝 贡献
+
+欢迎 Issue / PR！
+
+---
+
+## 📄 License
+
+MIT License

redis_xsync-1.0.1/README.md

@@ -0,0 +1,305 @@
+# RedisXsync
+
+![PyPI](https://img.shields.io/pypi/v/redis-xsync) ![Python](https://img.shields.io/pypi/pyversions/redis-xsync) ![License](https://img.shields.io/badge/license-MIT-green)
+
+RedisXsync 是一个 **同步 / 异步统一 Redis 客户端**，专为 **分布式锁** 和 **爬虫账号池限流** 场景设计，支持多实例、多
+DB，线程安全和协程安全。
+
+---
+
+## ✨ 核心特性
+
+| 特性          | 描述                               |
+|-------------|----------------------------------|
+| 同步 / 异步统一接口 | 同一套 API 支持 `with` 和 `async with` |
+| 多实例 / 多 DB  | 支持不同 Redis 实例与数据库同时管理            |
+| 分布式锁        | 单键锁、组合锁，阻塞 / 非阻塞模式               |
+| 账号池限流       | 基于 Lua 原子操作的令牌桶限流，可等待可用 token    |
+| 线程 & 协程安全   | 避免多线程 / 协程冲突                     |
+| 自动连接管理      | Context manager 自动释放连接           |
+
+---
+
+## 🏗 架构概览
+
+| RedisXsync               |
+|--------------------------|
+| Sync / Async Interfaces  |
+| Distributed Lock Manager |
+| Rate Limiter / TokenPool |
+
+- 分布式锁：通过单键或多键原子操作保证并发安全
+- 限流/账号池：Lua 脚本保证跨进程/跨机器的原子性，精确到毫秒
+
+---
+
+## 📦 安装
+
+```bash
+pip install redis-xsync
+
+---
+
+## 🚀 快速开始
+
+### 1️⃣ 注册 Redis
+
+​```python
+from redis_xsync import register_redis, resolve_redis, redisXsync
+
+redis1 = register_redis(
+    label="redis_xsync",
+    host="127.0.0.1",
+    port=6379,
+    db=0,
+    password=None,
+    decode_responses=True
+)
+
+# 通过 label 获取
+redis2 = resolve_redis("redis_xsync")
+
+
+# 使用方式说明：
+# 1️⃣ 全局默认实例 redisXsync
+#    - 在首次调用 register_redis 注册任意 Redis 时，首次注册会自动赋值给 redisXsync，非并发安全
+#    - 后续可以直接使用 redisXsync，无需通过 label 获取
+#
+# 2️⃣ 通过 label 显式管理 Redis
+#    - register_redis(label=..., ...) 注册 Redis 实例
+#    - resolve_redis(label) 根据 label 获取对应 Redis 实例
+#
+# 3️⃣ 独立实例
+#    - 可以直接创建 RedisXsync() 实例，不必参与 register_redis 、resolve_redis、 redisXsync 全局管理
+#    - 适合临时或隔离使用场景
+```
+
+## 🔄 同步 / 异步使用
+
+### ✅ 同步
+
+```python
+with redis1(db=1) as r:
+    r.setnx("key", "value")
+    print(r.get("key"))
+```
+
+---
+
+### ✅ 异步
+
+```python
+import asyncio
+
+
+async def main():
+    async with redis1(db=1) as r:
+        await r.setnx("key", "value")
+        print(await r.get("key"))
+
+
+asyncio.run(main())
+```
+
+---
+
+## 🔐 分布式锁（支持组合锁）
+
+### 特性
+
+* 多 key 原子加锁
+* 所有 key 释放才算解锁
+* 支持阻塞等待
+
+---
+
+### 示例（多线程 + 协程混合）
+
+```python
+import threading
+import asyncio
+from redis_xsync import register_redis
+
+cx = 0
+redis = register_redis(label="redis_xsync", host="127.0.0.1", port=6379)
+Lock = redis.AsyncRedisAtomicMultiLock
+
+
+def sync_worker():
+    global cx
+    for _ in range(5):
+        with Lock("lock_key", db=0, ttl_ms=10, blocking=True):
+            with redis(db=2) as r:
+                r.setnx("db2", str(cx))
+                cx += 1
+                print(f"[SYNC] {cx=}")
+
+
+async def async_worker():
+    global cx
+    for _ in range(5):
+        with Lock("lock_key", db=0, ttl_ms=10, blocking=True):
+            async with redis(db=3) as r:
+                await r.setnx("db3", str(cx))
+                cx += 1
+                print(f"[ASYNC] {cx=}")
+        await asyncio.sleep(0.2)
+
+
+# 启动线程
+threading.Thread(target=sync_worker).start()
+
+# 启动协程
+asyncio.run(async_worker())
+```
+
+---
+
+## 🚦 爬虫账号池限流
+
+基于 Redis + Lua，实现**分布式限流 + 自动等待可用账号**
+
+📦 Limited — Redis 容器操作方法对照表
+
+| 方法                                                  | 异步 | 阻塞 | 遵循限流 | 数量 | 描述                     |
+|-----------------------------------------------------|----|----|------|----|------------------------|
+| `set_available_containers(*containers)`             | ✅  | ❌  | ✅    | N  | 存储/更新容器配置（生产者）         |
+| `ask_available_containers(quantity)`                | ✅  | ❌  | ✅    | N  | 获取 N 个可用容器，若无返回 `None` |
+| `ask_available_container()`                         | ✅  | ❌  | ✅    | 1  | 获取单个可用容器，若无返回 `None`   |
+| `wait_ask_available_containers(quantity, timeout)`  | ✅  | ✅  | ✅    | N  | 阻塞等待 N 个可用容器           |
+| `wait_ask_available_container(timeout)`             | ✅  | ✅  | ✅    | 1  | 阻塞等待单个可用容器             |
+| `acquire_random_containers(quantity)`               | ✅  | ❌  | ❌    | N  | 随机获取 N 个容器，忽略限流        |
+| `acquire_random_container()`                        | ✅  | ❌  | ❌    | 1  | 随机获取单个容器，忽略限流          |
+| `wait_acquire_random_containers(quantity, timeout)` | ✅  | ✅  | ❌    | N  | 阻塞等待 N 个随机容器，忽略限流      |
+| `wait_acquire_random_container(timeout)`            | ✅  | ✅  | ❌    | 1  | 阻塞等待单个随机容器，忽略限流        |
+
+---
+
+### 写入账号（生产者）
+
+## LimitedModel 说明
+
+`LimitedModel` 用于表示受限访问（rate-limited）的容器条目，每条数据包含唯一标识、时间戳、TTL、访问间隔和访问计数等信息。
+
+### 字段说明
+
+| 字段                    | 类型    | 默认值       | 描述                  |
+|-----------------------|-------|-----------|---------------------|
+| `id`                  | `str` | —         | 数据唯一标识符，必须提供        |
+| `ct`                  | `int` | 当前时间戳（毫秒） | 记录条目的收集时间，无需设置      |
+| `ttl_ms`              | `int` | `0`       | 条目的生存时间（毫秒），0 表示无限期 |
+| `interval_ms`         | `int` | `0`       | 访问间隔（毫秒），0 表示不限速    |
+| `next_time_available` | `int` | 当前时间戳（毫秒） | 下次可访问时间，用于限流控制，无需设置 |
+| `containers`          | `str` | `None`    | 存储容器数据，可为空          |
+| `usage_count`         | `int` | `0`       | 条目被访问的次数，无需设置       |
+### 使用说明
+
+- `ct` 和 `next_time_available` 都以毫秒为单位，便于高精度限流。
+- `interval_ms > 0` 时，访问条目会更新 `next_time_available` 为当前时间 + 间隔。
+- 每次访问条目时，都会通过 `usage_count` 记录被访问次数，以统计和调度。
+- `ttl_ms` 可配合 Redis 等存储设置过期时间，实现自动清理。
+
+```python
+import random
+from redis_xsync import register_redis
+from redis_xsync.rtypes import LimitedModel
+
+redis = register_redis(label="redis_xsync", host="127.0.0.1", port=6379)
+Limited = redis.Limited
+
+
+async def produce_container():
+    async with Limited(redis_key="crawler:identity:flow_limit") as lt:
+        for i in range(10):
+            token = LimitedModel(
+                id=f"user_{i}",
+                ttl_ms=random.randint(30000, 60000),
+                interval_ms=random.randint(1000, 6000),
+                containers="cookies"
+            )
+            await lt.set_available_containers(token)
+```
+
+---
+
+### 获取账号（消费者，阻塞等待）
+
+```python
+async def consume_token():
+    async with Limited(redis_key="crawler:identity:flow_limit") as lt:
+        # 等待可用 token，超时 10 秒
+        token = await lt.wait_ask_available_containers(quantity=1, timeout=10)
+        print("获取到账号:", token)
+```
+
+---
+
+### 同步调用
+
+```python
+def consume_sync():
+    with Limited(redis_key="crawler:identity:flow_limit") as lt:
+        token = lt.wait_ask_available_containers(quantity=1, timeout=10)
+        print("获取到账号:", token)
+```
+
+## ⚡ 说明：
+
+- produce_container 写入 token 到 Redis，带过期时间和间隔限流
+- consume_token 或 consume_sync 从 Redis 中获取可用 token，如果当前没有可用，会等待直到 timeout
+- 支持异步和同步，且保证跨进程 / 跨机器原子性
+
+---
+
+## 🧠 设计说明
+
+### 🔐 分布式锁
+
+* 基于 Redis 原子操作
+* 支持多 key（组合锁）
+* 防止并发冲突
+
+---
+
+### 🚦 限流模型
+
+* 每个 token：
+
+    * 独立 TTL
+    * 独立间隔（interval）
+* Lua 保证原子性
+* 支持多进程 / 多机器共享
+
+---
+
+## ⚠️ 注意事项
+
+### Windows 建议
+
+```python
+import asyncio
+
+asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+```
+
+---
+
+## 📌 适用场景
+
+* 单机非集群
+* 爬虫账号池
+* 接口限流
+* 分布式任务调度
+* 多服务并发控制
+
+---
+
+## 🤝 贡献
+
+欢迎 Issue / PR！
+
+---
+
+## 📄 License
+
+MIT License

redis_xsync-1.0.1/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "redis-xsync"
+version = "1.0.1"
+description = "Sync/Async unified Redis client with distributed lock and rate limiter"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.8"
+
+authors = [
+    { name = "Jay" }
+]
+
+license = { text = "MIT" }
+
+keywords = [
+    "redis",
+    "async",
+    "sync",
+    "distributed-lock",
+    "redis-xsync",
+    "rate-limit",
+]
+
+dependencies = [
+    "pydantic>=2.0",
+    "redis>=5.0.0"
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Distributed Computing",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]
+
+[project.urls]
+Homepage = "https://github.com/jaygarage/RedisXsync"
+Repository = "https://github.com/jaygarage/RedisXsync"
+Issues = "https://github.com/jaygarage/RedisXsync/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["redis_xsync*"]
+
+[tool.setuptools]
+include-package-data = true