Metadata-Version: 2.4
Name: tsfile-converter-tool
Version: 0.1.0
Summary: Backend Python API and CLI for converting CSV, Parquet, and Arrow data to TsFile.
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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 :: Database
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pandas>=1.3.0
Requires-Dist: pyarrow>=10.0.0
Requires-Dist: tsfile==2.2.0
Provides-Extra: api
Requires-Dist: Flask>=2.0.0; extra == "api"
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

# TsFile Dataset

本项目是一个基于 TsFile 的时序数据集管理与可视化演示，包含：

- 基于 Flask 的 Web 界面（管理、可视化、文件操作）。
- 简单的客户端示例与脚本（在 `examples/` 下）。

## 功能模块（按项目菜单结构）

### 1. 首页
- **系统概览**：展示系统的主要功能模块和快速导航入口
- **功能导航**：提供各个功能模块的快速访问入口
- **统计信息**：显示系统中的数据集数量、文件数量等关键指标

### 2. 数据接入 (Data Ingestion)

支持多种数据源的接入，方便将外部数据导入系统：

#### TsFile 接入
- **TsFile 上传**：支持上传单个或批量 TsFile 文件到服务端，上传后自动刷新文件列表。
- **TsFile 导入**：从本地文件系统导入 TsFile 文件，支持批量操作。
- **文件管理**：上传的 TsFile 文件会自动添加到文件管理模块，支持后续操作。

#### CSV 接入
- **CSV 上传**：支持上传单个或批量 CSV 文件到服务端。
- **CSV 导入**：从本地文件系统导入 CSV 文件，支持批量操作。
- **数据转换**：上传的 CSV 文件可转换为 TsFile 格式，保留原始数据。

#### Parquet 接入
- **Parquet 上传**：支持上传单个或批量 Parquet 文件到服务端。
- **Parquet 导入**：从本地文件系统导入 Parquet 文件，支持批量操作。
- **数据转换**：上传的 Parquet 文件可转换为 TsFile 格式，保留原始数据。

#### IoTDB 接入
- **IoTDB 连接**：支持连接到 IoTDB 数据库，导入时序数据。
- **数据同步**：从 IoTDB 同步数据到本地 TsFile 文件。
- **实时采集**：支持实时采集 IoTDB 数据并写入 TsFile。

### 3. 数据集管理 (Dataset Management)

用于对多个 TsFile 文件进行逻辑分组、层级组织与血缘管理，包含以下主要模块：

#### 数据集列表
- **层级管理**：支持创建父子数据集，形成树形层级结构，支持折叠/展开。
- **血缘管理 (Lineage)**：记录数据集之间的衍生关系（Source → Derived），注册数据集时可通过 `parent_path` 指定父数据集，Web 界面展示血缘路径。
- **数据集列表**：在管理界面查看所有数据集的摘要信息（名称、描述、关联文件数、统计信息等），支持搜索与分页。
- **文件关联**：将多个 TsFile 文件关联到某一数据集，支持批量添加/移除和快捷跳转到可视化页面。
- **智能删除与 Re-parenting**：删除父数据集时，子节点自动挂载到被删除节点的父节点，避免数据丢失。

#### TsFile 可视化
- **数据表格**：以表格形式展示 TsFile 中的时序数据，支持分页和排序。
- **时序图表**：使用 ECharts 绘制时序数据折线图，支持多系列对比和时间范围筛选。
- **列选择**：可选择要显示的物理量（FIELD）列，支持多列同时展示。
- **时间筛选**：支持按时间范围筛选数据，可设置开始时间和结束时间。
- **数据导出**：支持将表格数据导出为 CSV 格式，方便后续分析。
- **设备筛选**：支持按设备（TAG 值）筛选数据，查看特定设备的时序数据。

### 4. 数据质量评估 (Data Quality Assessment)

对数据集下的文件自动或手动触发质量检查，例如空值比例、时间戳连续性、异常点检测，结果以报告/指标形式展示并可导出。

#### 质量维度
- **完整性**：检测数据是否存在缺失值，计算缺失比例。
- **一致性**：检测同一时间点是否存在重复数据。
- **有效性**：检测数据值是否在合理范围内，识别异常值。
- **时效性**：检测数据是否按时入库，识别延迟数据。

#### 质量报告
- **总体评分**：对四个维度进行综合评分，给出整体质量等级。
- **雷达图**：以雷达图形式展示四个维度的得分情况。
- **详细统计**：显示总数据点数、缺失点数、冗余点数、异常点数、延迟点数等。
- **异常数据**：列出检测到的异常数据，支持点击查看详情。
- **导出功能**：支持将质量报告导出为 CSV 或 PDF 格式。

### 5. 数据标注 (Data Annotation)

支持对时序数据进行标注和标签管理：

#### 标注列表
- **标注浏览**：查看所有标注任务的列表，显示任务状态、标注数量等。
- **标注创建**：创建新的标注任务，支持选择数据集和时间范围。
- **标注编辑**：对已有标注进行编辑，支持添加、修改和删除标注。
- **标注导出**：支持将标注数据导出为标准格式，方便后续使用。

#### 标注功能
- **数据预览**：在标注时预览原始时序数据，辅助标注决策。
- **快捷标注**：提供常用标注快捷键，提高标注效率。
- **标注验证**：支持标注数据的验证和质量检查，确保标注准确性。

## 仓库结构（摘要）

```
.
├── data/                   # 服务端数据存储（datasets.json, datasets/...）
├── examples/               # 示例脚本与示例数据
├── src/
│   ├── tsfiledataset/      # 客户端 SDK（注册/管理数据集）
│   ├── web/                # Flask Web 应用
│   │   └── app.py          # Flask 主程序
│   └── utils/              # 工具脚本（inspect, debug 等）
├── tests/                  # pytest 测试
├── requirements.txt        # 推荐依赖（用于开发/运行）
└── README.md               # 本文件
```

快速导航：查看 `src/web/app.py` 启动 Web 服务；示例脚本在 `examples/` 下。

## 安装 Python 依赖

### 方法一：使用虚拟环境（推荐）

创建并激活虚拟环境：

**Windows PowerShell：**
```powershell
# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境
.venv\Scripts\Activate.ps1

# 安装依赖
pip install -r requirements.txt
```

**Linux/Mac：**
```bash
# 创建虚拟环境
python3 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

### 方法二：直接安装（不推荐，可能影响系统环境）

```bash
# Windows
pip install -r requirements.txt

# Linux/Mac
pip3 install -r requirements.txt
```

### 依赖说明

主要依赖已列在 `requirements.txt` 中。关键依赖包括：

- **Flask**：Web 框架，用于提供 HTTP 服务
- **pandas**：数据处理库，用于数据操作和分析
- **tsfile**：TsFile 格式支持库（若需操作 TsFile 格式）
- **pytest**：测试框架，用于运行单元测试和集成测试

### 常见安装问题

**1. 找不到包 (ModuleNotFoundError)：**
- 请确认已激活虚拟环境
- 在该环境中安装了依赖
- 检查 Python 版本是否兼容（推荐 Python 3.8+）

**2. Windows DLL 加载失败：**
- 请确保已安装 Visual C++ Redistributable
- 或将包含 DLL 的目录加入系统 PATH
- `src/web/app.py` 已尝试自动修复，但部分环境仍需手动处理

**3. 权限问题：**
- Windows：可能需要以管理员身份运行
- Linux/Mac：可能需要使用 `sudo` 或 `--user` 参数

**4. 网络问题：**
- 如果安装速度慢，可以使用国内镜像源：
  ```bash
  pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
  ```

### 验证安装

安装完成后，可以验证依赖是否正确安装：

```bash
# 查看已安装的包
pip list

# 检查特定包
pip show flask
pip show pandas
```

## 运行应用

### 环境清理（可选）

在启动服务前，如果需要清理之前的 Python/Flask 进程，可运行：

```bash
# Windows
taskkill /F /IM python.exe

# Linux/Mac
pkill -9 python
```

### 启动服务

在项目根目录运行：

```bash
python src/web/app.py
```

默认服务地址： http://127.0.0.1:5000

## 示例脚本

### 注册示例数据集（不启动 Web）：

```bash
python examples/user_demo.py
```

### 注册示例数据集并带血缘关系：

```bash
python examples/lineage_demo.py
```

在运行这些脚本后，打开 Web 界面可以看到新注册的数据集与血缘关系。

## 转换性能测试

项目内置了 `Arrow/Parquet -> TsFile` 转换 benchmark 脚本，可自动生成样本、执行转换、输出 CSV、绘制曲线并生成 Markdown 报告：

```bash
python3 scripts/benchmark_conversion.py --sizes 4M 20M 100M --repeats 3
```

更完整的说明见：[docs/conversion_benchmark.md](docs/conversion_benchmark.md)

## 无界面转换工具包

仓库已抽出独立后端包 `tsfile_converter`，用于将 CSV/Parquet/Arrow 转为 TsFile，可作为 Python API、CLI 或可选 HTTP API 发布到 PyPI：

```bash
python3 -m pip install -e ".[api,dev]"
tsfile-convert input.parquet output.tsfile --format parquet --overwrite --json
tsfile-converter-api --host 127.0.0.1 --port 8000 --output-dir converted_tsfiles
```

Python API 示例：

```python
from tsfile_converter import ConversionOptions, convert_parquet_to_tsfile

result = convert_parquet_to_tsfile(
    "input.parquet",
    "output.tsfile",
    options=ConversionOptions(time_column="time", table_name="metrics", tablet_rows=262_144, overwrite=True),
)
print(result.to_dict())
```

运行报告见：[docs/tsfile_converter_run_report.md](docs/tsfile_converter_run_report.md)

发布说明见：[docs/pypi_conversion_tool.md](docs/pypi_conversion_tool.md)

## 运行测试

项目包含若干基于 `pytest` 的测试。运行：

```bash
pytest -q
```

如果希望只运行单个测试文件，例如：

```bash
pytest tests/test_app_utils.py -q
```

更多测试用例与执行说明见：[docs/testcases.md](docs/testcases.md)

### 快速运行测试：

```bash
# 运行所有测试并生成 junit + coverage
pytest --junitxml=reports/junit-result.xml --cov=src --cov-report=xml -q
```

## 依赖

主要依赖已列在 `requirements.txt` 中。关键依赖包括：

- Flask
- pandas
- tsfile（若需操作 TsFile 格式）
- pytest（测试）

### 常见问题（FAQ）

- **找不到包 (ModuleNotFoundError)**：请确认已激活虚拟环境，并在该环境中安装了依赖。
- **Windows DLL 加载失败**：请确保已安装 Visual C++ Redistributable，或将包含 DLL 的目录加入系统 PATH。`src/web/app.py` 已尝试自动修复，但部分环境仍需手动处理。

## 开发与贡献

欢迎提交 issue 或 PR：

- 若想添加新特性，请先打开 issue 讨论。
- 测试和文档改进尤为受欢迎。

## 许可证与联系方式

本仓库未指定特定开源许可证（请在需要时添加 LICENSE 文件）。如需沟通，请在仓库 issue 中留言。
