Metadata-Version: 2.4
Name: jupyter-data-fetch
Version: 0.2.3
Summary: fetch data from jupyter notebook
License-File: LICENSE
Requires-Python: >=3.9
Requires-Dist: jupyter-kernel-client
Requires-Dist: pandas<3.0
Requires-Dist: pillow
Provides-Extra: playwright
Requires-Dist: loguru; extra == 'playwright'
Requires-Dist: playwright; extra == 'playwright'
Requires-Dist: playwright-stealth; extra == 'playwright'
Requires-Dist: psutil; extra == 'playwright'
Description-Content-Type: text/markdown

# jupyter-data-fetch

从`JupyterLab`、`Jupyter Notebook`、`VSCode网页版/code-server`中抓取数据的示例

## 优点

1. 与`ksrpc`比，通用性更强，理论上全平台通用
2. 不需中转服务器，网页能打开就能使用

## 安装

1. `uv pip install jupyter-data-fetch -U` # Jupyter消息协议版
2. `uv pip install jupyter-data-fetch[playwright] -U` # playwright网页自动化版

## Jupyter消息协议版(推荐)

1. 根据Jupyter消息协议，模拟浏览器直接连接服务器进行代码的执行和获取，效率高
2. 支持`JupyterLab`、`Jupyter Notebook`
3. 参考[examples/message](examples/message)

## playwright网页自动化版

1. 网页自动化控制，通用性更高，支持`JupyterLab`、`Jupyter Notebook`
2. 支持`VSCode网页版/code-server`
3. 暂时不支持的网站也可以定制开发
4. 效率较低，因为多了网页渲染
5. 参考[examples/automation](examples/automation)

## HTTP下载版

1. 数据获取阶段，不通过网页展示提取数据，而是得到下载地址后HTTP下载
2. 直接是二进制，不用base64/base85编码，文件更小，下载速度更快。更适合大数据文件。但每个网站都需要针对性调整
3. 部分平台由于权限问题，服务器上文件可能需要手工删除
4. 部分平台HTTP下载可能有流量限制
5. 参考[examples/download](examples/download)

## 使用方法

1. `examples`下提供了示例
2. 以`joinquant`为例，打开浏览器，登录研究环境，按`F12`打开开发者工具
3. 搜索`kernels`，复制`Cookie`
   ![devtool.png](docs/devtool.png)
4. 替换示例中`COOKIE`即可
   ![ide.png](docs/ide.png)
5. 会自动从`COOKIE`提取`用户ID`，并更新`SERVER_URL`

## 最简示例

```python
from jupyter_kernel_client import KernelClient

from jupyter_data_fetch.codec import TextCodec
from jupyter_data_fetch import extract_from_reply

# ... 省去部分代码。更多参考examples/message/joinquant.py

with KernelClient(server_url="https://www.joinquant.com/user/12345678901", token=None, headers=headers) as kernel:
    # 一定要保证缩进正确
    code = """
df = get_fundamentals(query(
        valuation, income
    ).filter(
        # 这里不能使用 in 操作, 要使用in_()函数
        valuation.code.in_(['000001.XSHE', '600000.XSHG'])
    ), date='2015-10-15')
"""
    reply = kernel.execute(TextCodec.generate_code(code, var_name='df'), store_history=False)
    print(reply)
    obj = TextCodec.decode(extract_from_reply(reply))
    print(obj)

```

## 自动登录并获取数据的完整示例

参考[examples/experimental/cookie_playwright.py](examples/experimental/cookie_playwright.py)

## 核心代码

1. `TextCodec`: 目前使用`base85`编解码器，使用字符串传输数据，压缩率高。如果字符串被截断，必须使用`ImageCodec`
2. `ImageCodec`: 图片编解码器，使用图片传输数据，`base64`编码压缩率低
3. `generate_code`生成可在`Notebook`单元格中运行的代码字符串，一定要指定需要获取的变量名`var_name`
4. `kernel.execute`在服务段执行字符串代码，返回`json`对象
5. `extract_from_reply`从`json`中提取数据
6. `decode`字符串解码成对象

## 注意

1. 由于各平台限制，`generate_code`生成的代码可能无法运行，可以复制到`Notebook`中测试
2. `python3.6`问题太多，可以打开一个`ipynb`文件后，通过菜单更改内核为最新版
3. 可以连接到已经打开的内核，只要提供`kernel_id`参数即可。参考`ricequant.py`示例
4. `Notebook`中可以导入当前目录中`py`，但本项目直接使用当前目录是`/`，导致导入失败，通过指定`kernel_id`可解决