stock-seek 1.0.0

股票搜索工具 - 支持中国A股和美股的搜索，具有本地缓存和增量更新功能

Stock Seek - 重构版

项目概述

Stock Seek 是一个股票价格搜索工具，支持根据特定价格水平（最高价、最低价、开盘价、收盘价）在历史数据中搜索股票。支持中国 A 股和美股，具有本地缓存和增量更新功能。

本项目既可以作为命令行工具使用，也可以作为 Python 库被其他项目依赖。

安装

使用 pip 安装（推荐）

pip install stock-seek

从源码安装

git clone https://github.com/garen/stock-seek.git
cd stock-seek
pip install -e .

使用方法

1. 作为命令行工具使用

更新缓存

# 全量更新 A 股缓存（使用百度数据源）
stock-seek update -t 8 -s bd

# 全量更新美股缓存
stock-seek update_us -t 6

# 增量更新 A 股缓存
stock-seek update_inc

# 增量更新美股缓存
stock-seek update_us_inc

# 从通达信数据更新
stock-seek update_tdx

搜索股票

# 搜索 A 股：2 天前最高价为 15.8 的股票
stock-seek find -p 15.8 -pos 2 -t high

# 搜索 A 股：5 天前最低价为 12.5 的股票，进入交互模式
stock-seek find -p 12.5 -pos 5 -t low -i

# 搜索美股：3 天前收盘价为 150.5 的股票
stock-seek find_us -p 150.5 -pos 3 -t close

查看缓存数据

# 查看 A 股缓存
stock-seek print_cache -s 600519

# 查看美股缓存
stock-seek print_cache_us -s AAPL

查看更新历史

# 查看全部更新历史
stock-seek history

# 查看最近 5 条记录
stock-seek history -n 5

# 查看最后一条记录
stock-seek history --last

# 查看美股更新历史
stock-seek history --us

2. 作为 Python 库使用

基础使用

import stock_seek

# 设置自定义缓存目录（可选）
stock_seek.set_cache_dir("/path/to/custom/cache")

# 更新 A 股缓存
stock_seek.update_cache(source="bd", max_workers=8)

# 搜索 A 股
results = stock_seek.search_stock(
    price=15.8,
    position=2,
    search_type="high"
)

# 打印搜索结果
for result in results:
    print(f"{result['code']} {result['name']} - {result['price']}")

# 获取单只股票数据
df = stock_seek.get_stock_data("600519")
print(df.head())

美股使用

import stock_seek

# 更新美股缓存
stock_seek.update_us_cache(source="bd", max_workers=6)

# 搜索美股
results = stock_seek.search_us_stock(
    price=150.5,
    position=3,
    search_type="close"
)

# 获取美股数据
df = stock_seek.get_stock_data("AAPL", us=True)

使用底层类

import stock_seek

# 使用 StockSearcher 类
searcher = stock_seek.StockSearcher(us=False)
results = searcher.search(price=15.8, position=2, search_type="high")
searcher.print_results(results)

# 使用 CacheManager 类
cache_manager = stock_seek.CacheManager(us=False, source="bd")
cache_manager.update_cache(max_workers=8)

# 获取所有已缓存的股票代码
stocks = stock_seek.get_all_cached_stocks(us=False)
print(f"已缓存 {len(stocks)} 只股票")

重构亮点

1. 模块化设计

• core: 核心功能模块（配置、异常、搜索引擎）
• fetchers: 数据获取模块（支持多数据源）
• cache: 缓存管理模块
• api: 高级 API 模块
• cli: 命令行接口模块
• utils: 工具函数模块

2. 设计模式应用

• 策略模式: 不同数据源使用不同的获取策略
• 工厂模式: DataFetcherFactory 创建数据获取器
• 模板方法模式: BaseDataFetcher 定义统一的数据处理流程
• 单一职责原则: 每个类只负责一个功能

3. 代码质量提升

• 完整的类型提示（Type Hints）
• 统一的异常处理机制
• 详细的文档字符串
• 消除代码重复
• 配置集中管理

4. 性能优化

• 多线程并发处理
• Parquet 列式存储
• 分块并行搜索
• 增量更新机制

项目结构

stock_seek/
├── pyproject.toml           # 项目配置
├── README.md                # 本文档
├── requirements.txt         # 依赖列表
├── stock_seek/
│   ├── __init__.py          # 包入口，导出公共 API
│   ├── __main__.py          # 支持 python -m stock_seek
│   ├── api/                 # 高级 API 模块
│   │   ├── __init__.py
│   │   └── simple.py        # 简化 API
│   ├── cli/                 # 命令行接口
│   │   ├── __init__.py
│   │   └── main.py          # CLI 主入口
│   ├── core/                # 核心模块
│   │   ├── __init__.py
│   │   ├── config.py        # 配置管理
│   │   ├── exceptions.py    # 自定义异常
│   │   └── searcher.py      # 搜索引擎
│   ├── fetchers/            # 数据获取模块
│   │   ├── __init__.py
│   │   ├── base_fetcher.py  # 基类
│   │   ├── china_fetcher.py # A 股数据获取
│   │   ├── us_fetcher.py    # 美股数据获取
│   │   ├── baidu_fetcher.py # 百度财经数据获取
│   │   ├── tdx_fetcher.py   # 通达信数据获取
│   │   └── data_fetcher.py  # 工厂类
│   ├── cache/               # 缓存模块
│   │   ├── __init__.py
│   │   ├── cache_manager.py # 缓存管理器
│   │   └── update_log_manager.py # 更新日志管理
│   └── utils/               # 工具模块
│       ├── __init__.py
│       └── helpers.py       # 辅助函数

核心类说明

Config（配置管理）

集中管理所有配置项，包括缓存路径、线程数、数据源等。支持设置全局缓存目录：

import stock_seek
from pathlib import Path

# 设置全局缓存目录
stock_seek.Config.set_global_cache_dir(Path("/custom/cache/path"))

# 或者使用简化 API
stock_seek.set_cache_dir("/custom/cache/path")

StockSearcher（搜索引擎）

多线程搜索股票，支持交互式浏览结果。

CacheManager（缓存管理器）

负责数据的缓存、更新和读取，支持全量和增量更新。

BaseDataFetcher（数据获取器基类）

定义数据获取的统一接口，包含数据验证和衍生指标计算。

ChinaStockFetcher / USStockFetcher / BaiduStockFetcher / TDXDataFetcher

具体的数据获取器，分别支持不同数据源。

异常处理

自定义异常层次：

• StockFinderError: 基础异常
  • DataFetchError: 数据获取异常
  • CacheError: 缓存操作异常
  • InvalidParameterError: 参数验证异常
  • StockNotFoundError: 股票未找到异常
  • DataValidationError: 数据验证异常

扩展性

添加新数据源

1. 继承 BaseDataFetcher
2. 实现 fetch_stock_data 和 get_stock_list 方法
3. 在 DataFetcherFactory 中注册

添加新功能

1. 在对应的模块中添加新类或函数
2. 在 stock_seek/api/simple.py 中添加简化 API
3. 在 stock_seek/__init__.py 中导出

百度财经 Token 配置

使用百度数据源（bd）时需要配置 Token：

import stock_seek
from stock_seek.fetchers import baidu_config

# 设置自定义 Token 文件路径
baidu_config.set_token_file_path("/path/to/token.json")

# 获取帮助信息
print(baidu_config.get_token_help_message())

Token 文件格式：

{
  "cookie": "完整的Cookie字符串",
  "acs_token": "acs-token值"
}

详细配置说明请运行：

stock-seek update -s bd

向后兼容

重构版保持了所有原有功能，原有的类方法调用方式仍然有效。

未来改进方向

1. 添加单元测试和集成测试
2. 支持更多数据源
3. 添加 Web 界面
4. 支持更多股票市场（港股、欧洲等）
5. 添加技术指标计算
6. 支持自定义搜索条件组合

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！