Metadata-Version: 2.4
Name: stock-seek
Version: 1.0.5
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: APScheduler>=3.10.0
Requires-Dist: exchange-calendars>=4.2.0
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

**股票价格历史数据搜索工具** | 支持 A股和美股

[![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)
[![Python Versions](https://img.shields.io/pypi/pyversions/stock-seek.svg)](https://pypi.org/project/stock-seek/)
[![Downloads](https://pepy.tech/badge/stock-seek)](https://pepy.tech/project/stock-seek)

---

Stock Seek 是一个高效的股票价格搜索工具，支持根据历史价格（最高价、最低价、开盘价、收盘价）在 A股和美股历史数据中搜索匹配的股票。

**核心功能**：本地缓存 + 增量更新 + 定时自动更新

---

## 特性

- **多市场支持**：A股（沪深）、美股（NYSE/NASDAQ）
- **多数据源**：新浪、百度财经
- **高效存储**：Parquet 列式存储，节省空间且查询快
- **增量更新**：仅获取最新数据，避免重复下载
- **定时任务**：支持交易日自动更新（可配置）
- **丰富搜索**：支持按价格、位置、类型多维度搜索
- **简单 API**：易于集成到其他 Python 项目

---

## 安装

### 方式一：pip 安装（推荐）

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

### 方式二：conda 安装

```bash
conda install -c conda-forge stock-seek
```

### 方式三：源码安装

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

### 可选依赖

```bash
# 开发依赖
pip install stock-seek[dev]
```

---

## 快速开始

### 1. 更新股票数据

```bash
# 首次使用，全量更新 A股数据
stock-seek update -t 8

# 增量更新（后续使用，只获取最新数据）
stock-seek update_inc

# 更新美股
stock-seek update_us -t 6
stock-seek update_us_inc
```

### 2. 搜索股票

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

# 搜索 5 天前最低价为 12.5 的 A股（交互模式）
stock-seek find -p 12.5 -pos 5 -t low -i

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

### 3. 查看缓存数据

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

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

### 4. 查询股票历史数据

```bash
# 查询 A股历史数据（从本地缓存）
stock-seek query -c 600519                          # 返回全部数据
stock-seek query -c 600519 -s 20240101              # 从指定日期到最新
stock-seek query -c 600519 -e 20240301              # 从最旧到指定日期
stock-seek query -c 600519 -s 20240101 -e 20240301  # 日期范围

# 查询美股历史数据
stock-seek query -c AAPL --us                        # 返回全部数据
stock-seek query -c AAPL -s 20240101 --us           # 日期范围
```

### 5. 导出/导入缓存数据

```bash
# 导出缓存到zip文件
stock-seek export                          # 导出到 stock_seek_backup.zip
stock-seek export -o my_backup.zip         # 指定输出文件
stock-seek export --no-token               # 不包含百度Token配置

# 从zip文件导入缓存
stock-seek import -i my_backup.zip
```

---

## 定时任务部署

### 启动调度器

```bash
# 前台运行
stock-seek scheduler start

# 后台运行
stock-seek scheduler start -d
```

### 查看状态

```bash
stock-seek scheduler status
```

### 配置调度时间

```bash
# A股调度时间（默认 16:00）
stock-seek scheduler config --china-time "16:30"

# 美股调度时间（默认 05:00）
stock-seek scheduler config --us-time "05:30"
```

### 手动触发更新

```bash
# 触发 A股更新
stock-seek scheduler trigger

# 触发美股更新
stock-seek scheduler trigger --us
```

### 开机自启动

**Linux (systemd)**

创建服务文件 `/etc/systemd/system/stock-seek-scheduler.service`：

```ini
[Unit]
Description=Stock Seek Scheduler Service
After=network.target

[Service]
Type=simple
User=your_username
WorkingDirectory=/path/to/project
ExecStart=/path/to/python -m stock_seek.scheduler.service
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

启用服务：

```bash
sudo systemctl enable stock-seek-scheduler
sudo systemctl start stock-seek-scheduler
```

**Windows (计划任务)**

```bash
# 创建开机启动计划任务
schtasks /create /tn "StockSeekScheduler" /tr "python -m stock_seek.scheduler.service" /sc onlogon /ru YOUR_USERNAME
```

### 查看日志

```bash
# 实时查看日志
tail -f ~/.stock_cache/stock_seek.log

# 查看日志文件位置
ls ~/.stock_cache/stock_seek.log*
```

---

## Python API

### 基础使用

```python
import stock_seek

# 更新数据
stock_seek.update_cache(source="bd", max_workers=8)

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

# 打印结果
for r in results:
    print(f"{r['code']} {r['name']} - 价格: {r['price']}")
```

### 增量更新

```python
# 增量更新（自动判断全量/增量）
stock_seek.update_cache_incrementally()
```

### 获取股票数据

```python
# 获取单只股票历史数据
df = stock_seek.get_stock_data("600519")
print(df.tail())

# 查询股票历史数据（从远程API）
df = stock_seek.query_stock_data("600519", "20240101", "20240301")
print(df)
```

### 配置缓存目录

```python
from pathlib import Path

stock_seek.set_cache_dir(Path("/path/to/cache"))
```

---

## 配置参考

### 数据源

| 数据源 | 命令参数 | 说明 |
|--------|---------|------|
| 新浪 | `-s xl` | 默认，稳定性好 |
| 百度财经 | `-s bd` | 需要配置 Token |

### 配置百度财经Token

```bash
# 设置Token
stock-seek config --baidu-cookie "你的Cookie" --baidu-acs-token "你的acs-token"

# 查看当前配置状态
stock-seek config --baidu-show
```

### 配置历史数据年数

```bash
# 设置A股历史数据年数（默认2年）
stock-seek config --china-years 2

# 设置美股历史数据年数（默认2年）
stock-seek config --us-years 3
```

> 注意：修改历史数据年数后需要执行全量更新才能生效

### 缓存目录

```
~/.stock_cache/
├── parquet/           # A股数据
├── parquet_us/        # 美股数据
├── stock_code_name.json
├── update_log.json    # 更新记录
├── scheduler_config.json  # 调度配置
└── app_config.json    # 应用配置
```

### 调度配置

配置文件：`~/.stock_cache/scheduler_config.json`

```json
{
  "enabled": true,
  "china_schedule_time": "16:00",
  "us_schedule_time": "05:00",
  "smart_update": true,
  "source": "bd",
  "max_workers": 8,
  "trading_days_only": true
}
```

### 应用配置

配置文件：`~/.stock_cache/app_config.json`

```json
{
  "a_share_history_years": 2,
  "us_stock_history_years": 2
}
```

---

## 常见问题

### Q: 定时任务在电脑重启后还能执行吗？

需要配置开机自启动。详见上文「开机自启动」章节。

### Q: 日历数据过期了怎么办？

调度器会自动检测并尝试升级 `exchange-calendars` 包。如自动升级失败，会输出提示命令，请手动执行：

```bash
pip install --upgrade exchange-calendars
# 或
conda install -y exchange-calendars
```

### Q: A股调休工作日判断不准确？

`exchange-calendars` 对中国调休工作日支持有限。如遇特殊情况，可手动触发更新：

```bash
stock-seek scheduler trigger
```

### Q: 如何查看更新是否成功？

```bash
stock-seek history --last
```

---

## 项目结构

```
stock_seek/
├── api/                    # 高级 API
├── cache/                  # 缓存管理
│   ├── cache_manager.py    # 缓存管理器
│   └── update_log_manager.py
├── cli/                    # 命令行入口
│   └── main.py
├── core/                   # 核心模块
│   ├── config.py
│   ├── exceptions.py
│   └── searcher.py
├── fetchers/               # 数据获取
│   ├── base_fetcher.py
│   ├── china_fetcher.py
│   ├── us_fetcher.py
│   └── baidu_fetcher.py
├── scheduler/              # 定时任务
│   ├── cache_watcher.py
│   ├── config_store.py
│   ├── scheduler_manager.py
│   ├── service.py
│   └── trade_calendar.py
└── utils/
    ├── data_api.py
    ├── helpers.py
    └── logger.py
```

---

## 贡献

欢迎提交 Issue 和 Pull Request！

```bash
# 克隆仓库
git clone https://github.com/garen/stock-seek.git

# 创建开发分支
git checkout -b feature/your-feature

# 安装开发依赖
pip install -e .[dev]

# 运行测试
pytest

# 代码格式化和检查
black .
ruff check .
```

---

## 许可证

MIT License

---

## 致谢

- [akshare](https://github.com/akfamily/akshare) - A股数据源
- [exchange-calendars](https://exchange-calendars.readthedocs.io/) - 交易日历
- [APScheduler](https://apscheduler.readthedocs.io/) - 定时任务调度
