rquote 0.3.9__tar.gz → 0.4.1__tar.gz

{rquote-0.3.9/rquote.egg-info → rquote-0.4.1}/PKG-INFO

@@ -1,14 +1,16 @@
 Metadata-Version: 2.4
 Name: rquote
-Version: 0.3.9
+Version: 0.4.1
 Summary: Mostly day quotes of cn/hk/us/fund/future markets, side with quote list fetch
-Requires-Python: >=3.6.1
+Requires-Python: >=3.9.0
 Description-Content-Type: text/markdown
 Requires-Dist: build>=0.9.0
 Requires-Dist: httpx>=0.20.0
 Requires-Dist: pandas>=1.0.0
 Requires-Dist: setuptools>=42
 Requires-Dist: twine>=3.8.0
+Provides-Extra: persistent
+Requires-Dist: duckdb>=0.9.0; extra == "persistent"
 
 # rquote
 
@@ -16,7 +18,7 @@ Requires-Dist: twine>=3.8.0
 
 ## 版本信息
 
-当前版本：**0.3.5**
+当前版本：**0.4.1**
 
 ## 主要特性
 
@@ -60,17 +62,67 @@ sid, name, df = get_price('sz000001', sdate='2024-01-01', edate='2024-02-01')
 
 ### 使用缓存
 
+#### 内存缓存（MemoryCache）
+
 ```python
 from rquote import get_price, MemoryCache
 
 # 创建缓存实例
 cache = MemoryCache(ttl=3600)  # 缓存1小时
 
-# 使用缓存（通过dd参数，向后兼容）
-cache_dict = {}
-sid, name, df = get_price('sh000001', dd=cache_dict)
+# 使用缓存（通过dd参数传递MemoryCache实例）
+sid, name, df = get_price('sh000001', dd=cache)
+
+# 注意：MemoryCache 是内存缓存，数据仅在当前进程运行期间有效
+# 脚本运行结束后，缓存数据会丢失
+```
+
+**缓存生命周期说明：**
+- `MemoryCache` 是纯内存缓存，数据存储在进程内存中
+- 缓存数据仅在当前脚本运行期间有效
+- 脚本运行结束后，所有缓存数据会丢失
+
+#### 持久化缓存（PersistentCache）
+
+持久化缓存支持跨进程/跨运行的缓存持久化，数据会保存到本地文件。
+
+**安装可选依赖：**
+```bash
+pip install rquote[persistent]
+# 或
+uv pip install "rquote[persistent]"
+```
+
+**使用持久化缓存：**
+```python
+from rquote import get_price, PersistentCache
+
+# 创建持久化缓存实例
+# 默认使用 duckdb（如果已安装），否则使用 pickle 文件
+cache = PersistentCache(ttl=86400)  # 缓存24小时，默认路径：~/.rquote/cache.db
+
+# 或指定自定义路径
+cache = PersistentCache(db_path='./my_cache.db', use_duckdb=True)
+
+# 使用缓存
+sid, name, df = get_price('sh000001', dd=cache)
+
+# 持久化缓存支持智能扩展：
+# - 当请求的结束日期不在缓存中时，会自动从缓存的最新日期向前扩展
+# - 当请求的开始日期不在缓存中时，会自动从缓存的最早日期向后扩展
+# - 数据会自动合并，避免重复请求
+
+# 关闭缓存（可选，程序退出时会自动保存）
+cache.close()
 ```
 
+**持久化缓存特性：**
+- ✅ 跨进程/跨运行持久化：数据保存在本地文件，下次运行仍可使用
+- ✅ 智能数据合并：相同股票的数据会自动合并，key 不包含日期范围
+- ✅ 智能扩展：当请求的日期范围超出缓存时，自动扩展并合并数据
+- ✅ 支持 TTL：可设置缓存过期时间
+- ✅ 可选 duckdb：如果安装了 duckdb，使用 duckdb 存储（性能更好），否则使用 pickle 文件
+
 ## 主要功能
 
 ### 历史价格数据获取
@@ -147,13 +199,13 @@ stocks = get_cn_stock_list(money_min=5e8)
 
 #### `get_hk_stocks_500()`
 
-获取港股前500只股票列表
+获取港股前500只股票列表(按当日成交额排序)
 
 ```python
 from rquote import get_hk_stocks_500
 
 stocks = get_hk_stocks_500()
-# 返回格式: [[code, name, price, turnover, ...], ...]
+# 返回格式: [[code, name, price, -, -, -, -, volume, turnover, ...], ...]
 ```
 
 #### `get_us_stocks(k=100)`

rquote-0.3.9/PKG-INFO → rquote-0.4.1/README.md

@@ -1,22 +1,10 @@
-Metadata-Version: 2.4
-Name: rquote
-Version: 0.3.9
-Summary: Mostly day quotes of cn/hk/us/fund/future markets, side with quote list fetch
-Requires-Python: >=3.6.1
-Description-Content-Type: text/markdown
-Requires-Dist: build>=0.9.0
-Requires-Dist: httpx>=0.20.0
-Requires-Dist: pandas>=1.0.0
-Requires-Dist: setuptools>=42
-Requires-Dist: twine>=3.8.0
-
 # rquote
 
 `rquote` 是一个提供 A股/港股/美股/ETF基金/期货 历史数据获取的Python库
 
 ## 版本信息
 
-当前版本：**0.3.5**
+当前版本：**0.4.1**
 
 ## 主要特性
 
@@ -60,17 +48,67 @@ sid, name, df = get_price('sz000001', sdate='2024-01-01', edate='2024-02-01')
 
 ### 使用缓存
 
+#### 内存缓存（MemoryCache）
+
 ```python
 from rquote import get_price, MemoryCache
 
 # 创建缓存实例
 cache = MemoryCache(ttl=3600)  # 缓存1小时
 
-# 使用缓存（通过dd参数，向后兼容）
-cache_dict = {}
-sid, name, df = get_price('sh000001', dd=cache_dict)
+# 使用缓存（通过dd参数传递MemoryCache实例）
+sid, name, df = get_price('sh000001', dd=cache)
+
+# 注意：MemoryCache 是内存缓存，数据仅在当前进程运行期间有效
+# 脚本运行结束后，缓存数据会丢失
+```
+
+**缓存生命周期说明：**
+- `MemoryCache` 是纯内存缓存，数据存储在进程内存中
+- 缓存数据仅在当前脚本运行期间有效
+- 脚本运行结束后，所有缓存数据会丢失
+
+#### 持久化缓存（PersistentCache）
+
+持久化缓存支持跨进程/跨运行的缓存持久化，数据会保存到本地文件。
+
+**安装可选依赖：**
+```bash
+pip install rquote[persistent]
+# 或
+uv pip install "rquote[persistent]"
 ```
 
+**使用持久化缓存：**
+```python
+from rquote import get_price, PersistentCache
+
+# 创建持久化缓存实例
+# 默认使用 duckdb（如果已安装），否则使用 pickle 文件
+cache = PersistentCache(ttl=86400)  # 缓存24小时，默认路径：~/.rquote/cache.db
+
+# 或指定自定义路径
+cache = PersistentCache(db_path='./my_cache.db', use_duckdb=True)
+
+# 使用缓存
+sid, name, df = get_price('sh000001', dd=cache)
+
+# 持久化缓存支持智能扩展：
+# - 当请求的结束日期不在缓存中时，会自动从缓存的最新日期向前扩展
+# - 当请求的开始日期不在缓存中时，会自动从缓存的最早日期向后扩展
+# - 数据会自动合并，避免重复请求
+
+# 关闭缓存（可选，程序退出时会自动保存）
+cache.close()
+```
+
+**持久化缓存特性：**
+- ✅ 跨进程/跨运行持久化：数据保存在本地文件，下次运行仍可使用
+- ✅ 智能数据合并：相同股票的数据会自动合并，key 不包含日期范围
+- ✅ 智能扩展：当请求的日期范围超出缓存时，自动扩展并合并数据
+- ✅ 支持 TTL：可设置缓存过期时间
+- ✅ 可选 duckdb：如果安装了 duckdb，使用 duckdb 存储（性能更好），否则使用 pickle 文件
+
 ## 主要功能
 
 ### 历史价格数据获取
@@ -147,13 +185,13 @@ stocks = get_cn_stock_list(money_min=5e8)
 
 #### `get_hk_stocks_500()`
 
-获取港股前500只股票列表
+获取港股前500只股票列表(按当日成交额排序)
 
 ```python
 from rquote import get_hk_stocks_500
 
 stocks = get_hk_stocks_500()
-# 返回格式: [[code, name, price, turnover, ...], ...]
+# 返回格式: [[code, name, price, -, -, -, -, volume, turnover, ...], ...]
 ```
 
 #### `get_us_stocks(k=100)`

{rquote-0.3.9 → rquote-0.4.1}/pyproject.toml

@@ -4,10 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rquote"
-version = "0.3.9"
+version = "0.4.1"
 description = "Mostly day quotes of cn/hk/us/fund/future markets, side with quote list fetch"
 readme = "README.md"
-requires-python = ">=3.6.1"
+# requires-python = ">=3.6.1" # duckdb requires higher python version
+requires-python = ">=3.9.0"
 dependencies = [
     "build>=0.9.0",
     "httpx>=0.20.0",
@@ -15,3 +16,5 @@ dependencies = [
     "setuptools>=42",
     "twine>=3.8.0",
 ]
+[project.optional-dependencies]
+persistent = ["duckdb>=0.9.0"]

{rquote-0.3.9 → rquote-0.4.1}/rquote/__init__.py

@@ -35,6 +35,11 @@ from .plots import PlotUtils
 from . import config
 from . import exceptions
 from .cache import MemoryCache, Cache
+# 尝试导入持久化缓存（可选依赖）
+try:
+    from .cache import PersistentCache
+except ImportError:
+    PersistentCache = None
 from .utils.http import HTTPClient
 
 
@@ -93,5 +98,6 @@ __all__ = [
     'exceptions',
     'MemoryCache',
     'Cache',
+    'PersistentCache',
     'HTTPClient',
 ]

rquote-0.4.1/rquote/cache/__init__.py

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""
+缓存模块
+"""
+from .base import Cache
+from .memory import MemoryCache
+
+# 尝试导入持久化缓存（可选依赖）
+try:
+    from .persistent import PersistentCache
+    __all__ = ['Cache', 'MemoryCache', 'PersistentCache']
+except ImportError:
+    __all__ = ['Cache', 'MemoryCache']
+