Metadata-Version: 2.4
Name: stock-seek
Version: 1.0.0
Summary: 股票搜索工具 - 支持中国A股和美股的搜索，具有本地缓存和增量更新功能
Author-email: Stock Seek Team <garen@example.com>
License: MIT
Project-URL: Homepage, https://github.com/garen/stock-seek
Project-URL: Issues, https://github.com/garen/stock-seek/issues
Keywords: stock,finance,search,china,us
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: akshare>=1.12.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: tables>=3.9.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: requests>=2.31.0
Requires-Dist: pytz>=2023.3
Requires-Dist: numpy>=1.24.0
Requires-Dist: pytdx>=1.70
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"

# Stock Seek - 重构版

[![PyPI version](https://badge.fury.io/py/stock-seek.svg)](https://pypi.org/project/stock-seek/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 项目概述

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

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

## 安装

### 使用 pip 安装（推荐）

```bash
pip install stock-seek
```

### 从源码安装

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

## 使用方法

### 1. 作为命令行工具使用

#### 更新缓存

```bash
# 全量更新 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
```

#### 搜索股票

```bash
# 搜索 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
```

#### 查看缓存数据

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

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

#### 查看更新历史

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

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

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

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

### 2. 作为 Python 库使用

#### 基础使用

```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())
```

#### 美股使用

```python
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)
```

#### 使用底层类

```python
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（配置管理）

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

```python
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：

```python
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 文件格式：
```json
{
  "cookie": "完整的Cookie字符串",
  "acs_token": "acs-token值"
}
```

详细配置说明请运行：
```bash
stock-seek update -s bd
```

## 向后兼容

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

## 未来改进方向

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

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！
