gpdatacached 0.1.0__tar.gz

gpdatacached-0.1.0/.gitignore

@@ -0,0 +1,197 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# git
+.git/
+.worktrees/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# UV
+uv.lock
+
+# poetry
+poetry.lock
+poetry.toml
+
+# pdm
+pdm.lock
+pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# Abstra
+.abstra/
+
+# Visual Studio Code
+.vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+.cursorignore
+.cursorindexingignore
+
+# Calude Code
+CLAUDE.md
+.claude/
+
+# OpenCode
+AGENTS.md
+.opencode/
+
+# Github Copilot
+.github/copilot-instructions.md
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# User drafts
+draft/
+dev_docs/
+
+# user progress
+PROGRESS.md
+progress.md
+
+# user ignore
+tests/mocks/log/

gpdatacached-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LinnetCodes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gpdatacached-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: gpdatacached
+Version: 0.1.0
+Summary: Redis-based cross-process data sharing and caching library
+Project-URL: Homepage, https://github.com/linnetcodes/gpdatacached
+Project-URL: Documentation, https://linnetcodes.github.io/gpdatacached
+Project-URL: Repository, https://github.com/linnetcodes/gpdatacached
+Project-URL: Issues, https://github.com/linnetcodes/gpdatacached/issues
+Project-URL: Changelog, https://github.com/LinnetCodes/gpdatacached/releases
+Author-email: Linnet Codes <linnet.codes@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cache,cross-process,data-sharing,redis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: gpconfig>=0.3.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: redis>=5.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.7; extra == 'docs'
+Requires-Dist: mkdocs-static-i18n>=1.3; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# gpdatacached
+
+> *General-Purpose Data Cached*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![Development Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://pypi.org/project/gpdatacached/)
+
+A Redis-based **cross-process data sharing and caching** library for Python. Any process that can reach the same Redis instance can share live, mutable, typed data structures — scalars, lists, dicts, sets — with reference semantics, lifecycle control, and optional distributed locking.
+
+> Read this in another language: [简体中文](./README.zh-CN.md)
+
+---
+
+## Why
+
+Sharing mutable state across processes is painful. `multiprocessing.Manager` is single-process-bottlenecked; raw Redis forces you to (de)serialize everything by hand and gives you no type safety, no reference tracking, no TTL cascades. `gpdatacached` gives you a dict-like API on top of Redis with:
+
+- **Typed objects** — store `int`, `str`, `datetime`, `list`, `dict`, `set`, … and get the same type back.
+- **Live containers** — `ns["tags"].append("x")` mutates Redis directly; no read-modify-write races on the whole structure.
+- **Reference sharing** — bind the same container under multiple names inside a namespace; the data is stored once.
+- **Lifecycle control** — per-object `permanent` / `ttl` / `sliding-window` cache modes, with cascade propagation to owned subtrees.
+- **Background GC** — reclaims expired and orphaned anonymous objects.
+- **Opt-in distributed locking** — serialize writes across processes with `obj.lock()`.
+- **Optional extensions** — cache [pydantic](https://docs.pydantic.dev/) `BaseModel` records and [pandas](https://pandas.pydata.org/) `Series` / `DataFrame` (see [Extensions](#extensions)).
+
+---
+
+## Install
+
+```bash
+pip install gpdatacached
+```
+
+Optional extras:
+
+```bash
+pip install "gpdatacached[pandas]"   # pandas DataFrame / Series support
+```
+
+Requirements: **Python ≥ 3.10**, **Redis ≥ 5.0**.
+
+---
+
+## Quick Start
+
+```python
+from gpdatacached import GPDCDomain, GPDCDomainConfig
+
+config = GPDCDomainConfig(
+    redis_host="127.0.0.1",
+    redis_port=6379,
+    redis_password="secret",
+)
+domain = GPDCDomain("mydomain", config)
+ns = domain.ensure_namespace("analytics")
+
+# Scalars read back as native Python values.
+ns["counter"] = 42
+assert ns["counter"] == 42
+
+# Containers are live Redis-backed objects.
+ns["tags"] = ["a", "b", "c"]
+ns["tags"].append("d")
+ns["tags"].pop(0)
+assert ns["tags"].value == ["b", "c", "d"]
+
+# Lifecycle control.
+ns["temp"] = "x"
+ns.get_object("temp").expire_in(60)   # requires cache_mode="ttl"
+
+domain.close()
+```
+
+---
+
+## Core Concepts
+
+```
+GPDCDomain ── GPDCNamespace ── GPDCDataObject (scalar | container)
+```
+
+| Concept | Role |
+|---|---|
+| **Domain** | Configuration root + Redis connection pool + lock/GC defaults. |
+| **Namespace** | Logical isolation space; behaves like a `MutableMapping`. Cross-namespace references are unsupported by design. |
+| **Data Object** | A named, typed value. Scalars return native Python values on read; containers return live objects. |
+
+**Cache modes:** `permanent` (default, never expires), `ttl` (fixed expiry), `sliding` (refreshed on every mutation).
+
+---
+
+## Documentation
+
+📖 **[Full documentation index](./docs/index.md)** — the entry point to all guides and references below.
+
+- **[Overview](./docs/overview.md)** — design purpose, philosophy, and end-to-end architecture (start here to understand the library as a whole).
+- **[API Reference](./docs/api.md)** — complete public API reference.
+- **[Lifecycle Management](./docs/lifecycle.md)** — how object creation, expiry, refresh, and deletion work, including anonymous and reference objects (read this to set correct expectations).
+- **[Extensibility](./docs/extensibility.md)** — the type system explained, with worked examples for adding your own scalar and container types (codecs, object classes, registration).
+- **[Performance Guide](./docs/performance-guide.md)** — usage patterns that degrade performance (sliding TTL overuse, deep nesting, unnecessary GC/locking) and their recommended alternatives. Read before putting GPDC on a hot path.
+- **[Multi-Process Locking](./docs/locking.md)** — when to lock, performance impact, recommended usage, deadlock avoidance, and GC interaction.
+
+## Extensions
+
+Optional built-in extensions under `gpdatacached.extensions`:
+
+- **[Pydantic Support](./docs/pydantic-support.md)** — cache pydantic `BaseModel` records. Two storage modes: scalar (atomic JSON) for scalar-only models, container (Redis hash) for models needing field-level access or nested `list`/`dict`/`set` fields. Pydantic is a core dependency; no extra install needed.
+- **[Pandas Support](./docs/pandas-support.md)** — cache pandas `Series` / `DataFrame` as live objects. Online selective accessors (`.iloc`, `.loc`, `df[col]`) for one-shot subset reads; `.value` for full restore; `extend` for appends. Requires `pip install "gpdatacached[pandas]"`.
+
+---
+
+## Running Tests
+
+The test suite expects a **local Redis instance** reachable at `127.0.0.1:6379` with password `123456`:
+
+- **Linux** — run Redis directly on the host.
+- **Windows** — run Redis inside WSL; it will be reachable at `localhost` / `127.0.0.1` from the Windows side.
+
+> ⚠️ Some tests **flush the Redis database** (`FLUSHDB`). Always use a dedicated Redis instance for testing — never point the tests at a production database.
+
+Run the suite with:
+
+```bash
+pytest
+```
+
+You can edit the Redis settings in `tests/conftest.py` to point at a different instance, but this is not recommended — running a dedicated throwaway test Redis is usually cheaper and safer.
+
+---
+
+## License
+
+[MIT](./LICENSE) © Linnet Codes

gpdatacached-0.1.0/README.md

@@ -0,0 +1,134 @@
+# gpdatacached
+
+> *General-Purpose Data Cached*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![Development Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://pypi.org/project/gpdatacached/)
+
+A Redis-based **cross-process data sharing and caching** library for Python. Any process that can reach the same Redis instance can share live, mutable, typed data structures — scalars, lists, dicts, sets — with reference semantics, lifecycle control, and optional distributed locking.
+
+> Read this in another language: [简体中文](./README.zh-CN.md)
+
+---
+
+## Why
+
+Sharing mutable state across processes is painful. `multiprocessing.Manager` is single-process-bottlenecked; raw Redis forces you to (de)serialize everything by hand and gives you no type safety, no reference tracking, no TTL cascades. `gpdatacached` gives you a dict-like API on top of Redis with:
+
+- **Typed objects** — store `int`, `str`, `datetime`, `list`, `dict`, `set`, … and get the same type back.
+- **Live containers** — `ns["tags"].append("x")` mutates Redis directly; no read-modify-write races on the whole structure.
+- **Reference sharing** — bind the same container under multiple names inside a namespace; the data is stored once.
+- **Lifecycle control** — per-object `permanent` / `ttl` / `sliding-window` cache modes, with cascade propagation to owned subtrees.
+- **Background GC** — reclaims expired and orphaned anonymous objects.
+- **Opt-in distributed locking** — serialize writes across processes with `obj.lock()`.
+- **Optional extensions** — cache [pydantic](https://docs.pydantic.dev/) `BaseModel` records and [pandas](https://pandas.pydata.org/) `Series` / `DataFrame` (see [Extensions](#extensions)).
+
+---
+
+## Install
+
+```bash
+pip install gpdatacached
+```
+
+Optional extras:
+
+```bash
+pip install "gpdatacached[pandas]"   # pandas DataFrame / Series support
+```
+
+Requirements: **Python ≥ 3.10**, **Redis ≥ 5.0**.
+
+---
+
+## Quick Start
+
+```python
+from gpdatacached import GPDCDomain, GPDCDomainConfig
+
+config = GPDCDomainConfig(
+    redis_host="127.0.0.1",
+    redis_port=6379,
+    redis_password="secret",
+)
+domain = GPDCDomain("mydomain", config)
+ns = domain.ensure_namespace("analytics")
+
+# Scalars read back as native Python values.
+ns["counter"] = 42
+assert ns["counter"] == 42
+
+# Containers are live Redis-backed objects.
+ns["tags"] = ["a", "b", "c"]
+ns["tags"].append("d")
+ns["tags"].pop(0)
+assert ns["tags"].value == ["b", "c", "d"]
+
+# Lifecycle control.
+ns["temp"] = "x"
+ns.get_object("temp").expire_in(60)   # requires cache_mode="ttl"
+
+domain.close()
+```
+
+---
+
+## Core Concepts
+
+```
+GPDCDomain ── GPDCNamespace ── GPDCDataObject (scalar | container)
+```
+
+| Concept | Role |
+|---|---|
+| **Domain** | Configuration root + Redis connection pool + lock/GC defaults. |
+| **Namespace** | Logical isolation space; behaves like a `MutableMapping`. Cross-namespace references are unsupported by design. |
+| **Data Object** | A named, typed value. Scalars return native Python values on read; containers return live objects. |
+
+**Cache modes:** `permanent` (default, never expires), `ttl` (fixed expiry), `sliding` (refreshed on every mutation).
+
+---
+
+## Documentation
+
+📖 **[Full documentation index](./docs/index.md)** — the entry point to all guides and references below.
+
+- **[Overview](./docs/overview.md)** — design purpose, philosophy, and end-to-end architecture (start here to understand the library as a whole).
+- **[API Reference](./docs/api.md)** — complete public API reference.
+- **[Lifecycle Management](./docs/lifecycle.md)** — how object creation, expiry, refresh, and deletion work, including anonymous and reference objects (read this to set correct expectations).
+- **[Extensibility](./docs/extensibility.md)** — the type system explained, with worked examples for adding your own scalar and container types (codecs, object classes, registration).
+- **[Performance Guide](./docs/performance-guide.md)** — usage patterns that degrade performance (sliding TTL overuse, deep nesting, unnecessary GC/locking) and their recommended alternatives. Read before putting GPDC on a hot path.
+- **[Multi-Process Locking](./docs/locking.md)** — when to lock, performance impact, recommended usage, deadlock avoidance, and GC interaction.
+
+## Extensions
+
+Optional built-in extensions under `gpdatacached.extensions`:
+
+- **[Pydantic Support](./docs/pydantic-support.md)** — cache pydantic `BaseModel` records. Two storage modes: scalar (atomic JSON) for scalar-only models, container (Redis hash) for models needing field-level access or nested `list`/`dict`/`set` fields. Pydantic is a core dependency; no extra install needed.
+- **[Pandas Support](./docs/pandas-support.md)** — cache pandas `Series` / `DataFrame` as live objects. Online selective accessors (`.iloc`, `.loc`, `df[col]`) for one-shot subset reads; `.value` for full restore; `extend` for appends. Requires `pip install "gpdatacached[pandas]"`.
+
+---
+
+## Running Tests
+
+The test suite expects a **local Redis instance** reachable at `127.0.0.1:6379` with password `123456`:
+
+- **Linux** — run Redis directly on the host.
+- **Windows** — run Redis inside WSL; it will be reachable at `localhost` / `127.0.0.1` from the Windows side.
+
+> ⚠️ Some tests **flush the Redis database** (`FLUSHDB`). Always use a dedicated Redis instance for testing — never point the tests at a production database.
+
+Run the suite with:
+
+```bash
+pytest
+```
+
+You can edit the Redis settings in `tests/conftest.py` to point at a different instance, but this is not recommended — running a dedicated throwaway test Redis is usually cheaper and safer.
+
+---
+
+## License
+
+[MIT](./LICENSE) © Linnet Codes

gpdatacached-0.1.0/README.zh-CN.md

@@ -0,0 +1,134 @@
+# gpdatacached
+
+> *General-Purpose Data Cached*（通用数据缓存）
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![Development Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://pypi.org/project/gpdatacached/)
+
+一个基于 Redis 的**跨进程数据共享与缓存** Python 库。任何能够访问同一 Redis 实例的进程，都可以共享活跃的、可变的、带类型的数据结构 —— 标量、list、dict、set —— 并具备引用语义、生命周期控制以及可选的分布式锁。
+
+> 其他语言：[English](./README.md)
+
+---
+
+## 为什么需要它
+
+跨进程共享可变状态一直很麻烦：`multiprocessing.Manager` 会形成单进程瓶颈；直接使用 Redis 又需要你手动序列化所有数据，且没有类型安全、没有引用追踪、没有 TTL 级联。`gpdatacached` 在 Redis 之上提供了一套类 dict 的 API，特性包括：
+
+- **带类型的对象** —— 存储 `int`、`str`、`datetime`、`list`、`dict`、`set` …，读取时得到相同类型。
+- **活跃容器** —— `ns["tags"].append("x")` 直接修改 Redis，避免对整个结构的“读-改-写”竞态。
+- **引用共享** —— 在同一 namespace 内，同一个容器可绑定到多个名称；数据仅存储一份。
+- **生命周期控制** —— 每个对象可设置 `permanent` / `ttl` / `sliding`（滑动窗口）缓存模式，并将策略级联传播到所拥有的子树。
+- **后台 GC** —— 自动回收过期或成为孤儿的匿名对象。
+- **可选的分布式锁** —— 通过 `obj.lock()` 在多进程间串行化写入。
+- **可选扩展** —— 可缓存 [pydantic](https://docs.pydantic.dev/) `BaseModel` 记录与 [pandas](https://pandas.pydata.org/) `Series` / `DataFrame`（见[扩展](#扩展)）。
+
+---
+
+## 安装
+
+```bash
+pip install gpdatacached
+```
+
+可选扩展：
+
+```bash
+pip install "gpdatacached[pandas]"   # 支持 pandas DataFrame / Series
+```
+
+环境要求：**Python ≥ 3.10**，**Redis ≥ 5.0**。
+
+---
+
+## 快速开始
+
+```python
+from gpdatacached import GPDCDomain, GPDCDomainConfig
+
+config = GPDCDomainConfig(
+    redis_host="127.0.0.1",
+    redis_port=6379,
+    redis_password="secret",
+)
+domain = GPDCDomain("mydomain", config)
+ns = domain.ensure_namespace("analytics")
+
+# 标量读取出来是原生 Python 值。
+ns["counter"] = 42
+assert ns["counter"] == 42
+
+# 容器是活跃的、由 Redis 支撑的对象。
+ns["tags"] = ["a", "b", "c"]
+ns["tags"].append("d")
+ns["tags"].pop(0)
+assert ns["tags"].value == ["b", "c", "d"]
+
+# 生命周期控制。
+ns["temp"] = "x"
+ns.get_object("temp").expire_in(60)   # 要求 cache_mode="ttl"
+
+domain.close()
+```
+
+---
+
+## 核心概念
+
+```
+GPDCDomain ── GPDCNamespace ── GPDCDataObject (标量 | 容器)
+```
+
+| 概念 | 角色 |
+|---|---|
+| **Domain（域）** | 配置根 + Redis 连接池 + 锁/GC 默认值。 |
+| **Namespace（命名空间）** | 逻辑隔离空间，行为类似 `MutableMapping`。**不支持**跨 namespace 的引用。 |
+| **Data Object（数据对象）** | 一个具名、带类型的值。标量读取返回原生 Python 值；容器返回活跃对象。 |
+
+**缓存模式：** `permanent`（默认，永不过期）、`ttl`（固定过期）、`sliding`（每次变更都刷新）。
+
+---
+
+## 文档
+
+📖 **[完整文档索引](./docs/zh-CN/index.md)** —— 以下所有指南与参考的入口。
+
+- **[总体概览](./docs/zh-CN/overview.md)** —— 设计目的、设计理念与端到端整体架构（从这里开始，从整体上理解本库）。
+- **[API 参考](./docs/zh-CN/api.md)** —— 完整的公共 API 参考。
+- **[生命周期管理](./docs/zh-CN/lifecycle.md)** —— 对象的创建、过期、刷新与删除如何运作，含匿名对象与引用对象（阅读本文以建立合理预期）。
+- **[可扩展性](./docs/zh-CN/extensibility.md)** —— 类型系统详解，含添加自定义标量与容器类型的完整示例（codec、对象类、注册）。
+- **[性能指南](./docs/zh-CN/performance-guide.md)** —— 会拖累性能的用法（滥用 sliding TTL、过深嵌套、不必要地启用 GC/加锁）及其推荐替代。把 GPDC 放上热路径前必读。
+- **[多进程加锁](./docs/zh-CN/locking.md)** —— 何时需要加锁、性能影响、推荐用法、避免死锁的顺序以及与 GC 的交互。
+
+## 扩展
+
+`gpdatacached.extensions` 下的可选内建扩展：
+
+- **[Pydantic 支持](./docs/zh-CN/pydantic-support.md)** —— 缓存 pydantic `BaseModel` 记录。两种存储模式：标量模式（原子 JSON，适用于纯标量模型）和容器模式（Redis hash，适用于需要字段级访问或嵌套 `list`/`dict`/`set` 字段的模型）。pydantic 是核心依赖，无需额外安装。
+- **[Pandas 支持](./docs/zh-CN/pandas-support.md)** —— 将 pandas `Series` / `DataFrame` 缓存为活跃对象。在线选择性访问器（`.iloc`、`.loc`、`df[col]`）用于一次性子集读取；`.value` 用于完整还原；`extend` 用于追加。需要 `pip install "gpdatacached[pandas]"`。
+
+---
+
+## 运行测试
+
+测试套件需要一个**本地 Redis 实例**，可通过 `127.0.0.1:6379` 访问，密码为 `123456`：
+
+- **Linux** —— 直接在主机上运行 Redis。
+- **Windows** —— 在 WSL 中运行 Redis；从 Windows 侧可通过 `localhost` / `127.0.0.1` 访问。
+
+> ⚠️ 某些测试会**清空 Redis 数据库**（`FLUSHDB`）。请务必使用专供测试用的 Redis 实例 —— 切勿将测试指向生产数据库。
+
+运行测试：
+
+```bash
+pytest
+```
+
+你也可以修改 `tests/conftest.py` 中的 Redis 配置来适配自己的实例，但不推荐这样做 —— 运行一个专用的、一次性的测试 Redis 通常成本更低也更安全。
+
+---
+
+## 许可证
+
+[MIT](./LICENSE) © Linnet Codes