chongming
Repositories
23
 Projects Packages

chongming-cache (0.1.0)

Published 2026-08-25 10:49:56 +08:00 by chakcy

Installation

pip install --index-url http://124.71.68.6:3000/api/packages/chongming/pypi/simple/ --extra-index-url https://pypi.org/simple chongming-cache

About this package

统一缓存封装：兼容 diskcache / redis 后端

chongming-cache

统一缓存封装，dict-like 接口，后端可切换 diskcache / redis，通过配置一行切换，业务代码零改动。

安装

uv pip install -e utils/cache
# 或作为依赖接入（与 chongming-database 等同约定）：
#   [tool.uv.sources]
#   chongming-cache = { git = "http://124.71.68.6:3000/chongming/chongming-utils-cache.git" }

快速开始

from chongming_cache import Cache

# 方式一：从配置创建（主项目 config.toml 的 [cache] 段）
cache = Cache.from_config(config["cache"])

# 方式二：显式参数
cache = Cache("diskcache", cache_store_path="./cache_data")
# cache = Cache("redis", redis_host="127.0.0.1", redis_port=6379, redis_prefix="chongming:")

映射协议（与 diskcache 用法一致）

cache["key"] = {"a": 1}        # 写入（无 TTL）
if "key" in cache:             # 存在性检查（含 TTL 判断）
    value = cache["key"]       # 读取，未命中抛 KeyError
del cache["key"]               # 删除，未命中抛 KeyError
len(cache)                     # 条目数
for k in cache: ...            # 迭代 key

扩展接口

cache.get("key", default=None)            # 未命中返回 default
cache.set("key", value, expire=60)        # 写入，TTL 秒（None = 永久）
cache.touch("key", expire=120)            # 刷新 TTL，返回是否命中（未命中 False）
cache.delete("key")                        # 删除，返回是否命中
cache.clear()                              # 清空（redis 仅清本前缀命名空间）
cache.close()                              # 释放连接

with Cache.from_config(cfg) as cache: ...  # 上下文管理器，退出自动 close

cache.client  # 底层客户端逃生口（diskcache.Cache / redis.Redis）

后端配置（config.toml [cache] 段）

[cache]
backend = "diskcache"          # "diskcache"（默认） | "redis"
cache_store_path = "./cache_data"

# redis 后端专用（backend = "redis" 时生效，均有默认值）
# redis_host = "127.0.0.1"
# redis_port = 6379
# redis_db = 0
# redis_password = ""
# redis_prefix = "chongming:"

所有键均可缺省：旧配置（只有 cache_store_path）自动按 diskcache 后端工作。

双后端语义对齐

行为 diskcache redis
值序列化 pickle pickle（保持任意 Python 对象语义一致）
未命中 cache[key] KeyError KeyError
set(..., expire=N) 秒级 TTL，读时惰性淘汰 SET EX N，到期即消失
touch(未命中) 返回 False 返回 False
clear() 清空本地缓存 仅清 redis_prefix 命名空间（不 flushdb）
多进程安全 是（SQLite + 锁） 是（服务端原子性）

依赖

  • diskcache — 本地持久化后端
  • redis — 远程后端（懒加载，diskcache-only 打包产物不引入）

Requirements

Requires Python: >=3.12
Details
PyPI
2026-08-25 10:49:56 +08:00
8
18 KiB
Assets (2)
chongming_cache-0.1.0-py3-none-any.whl 8.1 KiB
chongming_cache-0.1.0.tar.gz 10 KiB
Versions (4) View all
0.2.2 2026-09-04
0.2.1 2026-09-04
0.2.0 2026-08-27
0.1.0 2026-08-25