ny-sync 0.1.1

A Python SDK for ny_sync: Distributed Token Bucket Rate Limiter

NySync

Any Data, Any Source, Any Destination.

NySync 是一个 AI-First 的数据同步与任务编排平台：用声明式任务把“任何数据源”持续、可靠地同步到“任何目的地”，并让 Agent 能够安全地生成、校验与运维这些任务。

当前进展（Milestone）

• 已完成：分布式令牌桶限流（Python SDK，基于 Redis）
  • 实现包含：LuaTokenBucket（默认）、NumericTokenBucket（GCRA）、StringTokenBucket（Slot-based）
  • 支持 Dashboard 可视化与并发/批量场景验证
• 主线目标：平台层的作业管理、调度编排、执行引擎与观测体系

快速开始（Python SDK）：

import redis
from ny_sync import TokenBucket, RateUnit

r = redis.Redis(host="localhost", port=6379, db=0, decode_responses=True)
bucket = TokenBucket(r)

key = "demo"
capacity = 10
rate = 60 / RateUnit.MINUTE  # 每分钟 60 个

allowed = bucket.allow(key, capacity, rate)

提供分布式令牌桶限流，基于 Redis 实现。内置三种实现：

• LuaTokenBucket（默认）：并发能力强，适合通用场景
• NumericTokenBucket（GCRA）：高吞吐批量场景
• StringTokenBucket（Slot-based）：一个 Token 一个 String Key，便于峰值与历史可视化

安装

pip install ny_sync

快速开始

import redis
from ny_sync import TokenBucket, RateUnit, RateLimit, RateLimitExceeded

r = redis.Redis(host="localhost", port=6379, db=0, decode_responses=True)

# 手动使用（TokenBucket 是 RedisTokenBucket 的简化别名）
bucket = TokenBucket(r)
key = "demo"
capacity = 10  # 桶容量10个
rate = 60 / RateUnit.MINUTE  # 每分钟补充 60 个
allowed = bucket.allow(key, capacity, rate)


# 装饰器使用（RateLimit 是 RateLimitDecorator 的简化别名）
@RateLimit(r, "api", capacity, rate)
def my_api():
    return "ok"

可视化 Dashboard

运行简单的 Streamlit Dashboard：

# Windows
c:\project\ny_sync\python_sdk\run_dashboard.bat

主要导出

• TokenBucket / RedisTokenBucket / LuaTokenBucket / NumericTokenBucket / StringTokenBucket
• RateUnit（SECOND / MINUTE / HOUR / DAY / WEEK）
• RateLimit / RateLimitExceeded

许可证

MIT