Metadata-Version: 2.4
Name: geodesy-data-collector
Version: 0.1.1a3
Summary: A command-line tool for downloading and organizing geodesy-related scientific data from FTP/HTTPS repositories.
Author: Shuhao Liu
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: PyYAML>=6.0.1
Requires-Dist: tqdm>=4.66.0
Dynamic: license-file

# GeodesyDataCollector

**GeodesyDataCollector** 是一个用于下载和管理大地测量相关公开科研数据的命令行工具。  
它支持从 FTP 和 HTTPS 目录索引站点中批量抓取文件，提供目录浏览、递归搜索、正则匹配、多线程下载、断点续传和自动解压等功能。

---

## 功能特性

- 支持 **FTP / HTTPS** 两种数据源
- 支持命令行交互式操作
- 支持 `cd`、`ls`、`pwd`、`get` 等常用命令
- 支持 **通配符匹配** 与 **正则表达式匹配**
- 支持 **递归搜索子目录**
- 支持 **多线程下载**
- 支持 **断点续传**
- 支持下载后 **自动解压**
- 支持解压后删除原压缩包
- 支持通过 `config.yaml` 配置服务器别名和默认参数

---

## 项目结构

```text
GeodesyDataCollector/
├── config/
│   └── config.yaml
├── output/
├── temp/
├── src/
│   └── gdc/
│       ├── cli.py
│       ├── downloader.py
│       ├── extractor.py
│       └── utils.py
├── pyproject.toml
├── requirements.txt
├── README.md
├── MANIFEST.in
├── LICENSE
└── .gitignore

---

## 环境要求

- Python 3.9 或更高版本
- 建议使用虚拟环境
- 依赖库：
- `requests`
- `beautifulsoup4`
- `PyYAML`
- `tqdm`

---

## 安装依赖

### 使用 pip 安装

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

### 使用虚拟环境（推荐）

```bash
python -m venv .venv
source .venv/bin/activate # Linux / macOS
# .venv\Scripts\activate # Windows

pip install -r requirements.txt
```

---

## 安装为可执行命令

如果你已经配置了 `pyproject.toml`，可以使用以下方式安装本项目：

```bash
pip install -e .
```

安装完成后，可以直接运行：

```bash
gdc
```

---

## 配置说明

项目默认读取 `config/config.yaml`。

### 示例配置

```yaml
settings:
dir_output: "/Users/yourname/GeodesyDataCollector/output/"
dir_temp: "/Users/yourname/GeodesyDataCollector/temp/"
default_threads: 4

aliases:
itsg: https://ftp.tugraz.at/pub/ITSG/
gfz: https://isdc-data.gfz.de/
```

### 配置项说明

#### `settings.dir_output`
下载文件保存目录。

#### `settings.dir_temp`
临时下载文件保存目录。

#### `settings.default_threads`
默认下载线程数。

#### `aliases`
服务器别名配置，便于快速连接。

例如：

```bash
connect itsg
```

等价于：

```bash
connect https://ftp.tugraz.at/pub/ITSG/
```

---

## 使用方法

启动交互式命令行：

```bash
python src/gdc/cli.py
```

或者安装后直接运行：

```bash
gdc
```

---

## 命令说明

### 1. 连接服务器

```bash
connect itsg
connect https://ftp.tugraz.at/pub/ITSG/
connect ftp://user:password@host/path/
```

---

### 2. 查看当前目录

```bash
pwd
```

---

### 3. 列出当前目录内容

```bash
ls
```

---

### 4. 切换目录

```bash
cd GRACE
cd ITSG-Grace_operational
cd ..
cd /pub/ITSG/
```

---

### 5. 下载文件

#### 普通下载

```bash
get "*.gfc"
```

#### 使用正则表达式

```bash
get -r ".*\.gfc"
```

#### 递归搜索并下载

```bash
get -R "*.gfc"
```

#### 递归 + 正则

```bash
get -R -r "monthly_n(60|96)/.*\.gfc"
```

#### 多线程下载

```bash
get -t 4 -R "*.gfc"
```

#### 下载后自动解压

```bash
get -e "*.zip"
```

#### 解压后删除压缩包

```bash
get -e -d "*.zip"
```

#### 指定输出子目录

```bash
get -o itsg_data "*.gfc"
```

---

## 示例流程

### 下载 ITSG GRACE 数据

```bash
connect itsg
pwd
ls
cd GRACE
ls
cd ITSG-Grace_operational
ls
get -R -r ".*\.gfc"
```

### 下载 monthly 目录下的文件

```bash
connect itsg
cd GRACE/ITSG-Grace_operational/monthly
get "*.gfc"
```

---

## 常见问题

### 1. `cd` 成功后，`get -R` 仍然扫描到上层目录

通常是路径归一化或递归目录筛选逻辑有问题。
本项目在 `downloader.py` 中已经加入：

- 当前目录标准化
- `visited` 去重
- 父目录链接过滤
- 仅允许当前目录子树递归

---

### 2. `ls` 返回空列表

可能原因：

- 目标目录不存在
- 网站目录索引不是标准 HTML 列表
- 服务器限制访问频率
- 网络连接失败

建议先用浏览器打开对应 URL，确认目录页是否可访问。

---

### 3. 下载文件不完整

本项目支持断点续传，但并非所有 FTP/HTTP 服务器都支持 Range 或 REST 断点续传。
如果服务器不支持，下载可能会重新开始。

---

### 4. 正则没有匹配到文件

正则匹配的是**相对路径字符串**，不是只匹配文件名。
例如：

```bash
get -r "monthly_n60/.*\.gfc"
```

比单纯的：

```bash
get -r ".*\.gfc"
```

更精确。

---

## 开发说明

### 主要模块

- `cli.py`
- 命令行交互入口

- `downloader.py`
- FTP/HTTPS 下载逻辑
- 文件列表递归遍历

- `extractor.py`
- 压缩包解压逻辑

- `utils.py`
- 工具函数预留模块

---

## 许可证

本项目采用 MIT License。

---

## 致谢

感谢以下开源库和公开科研数据源：

- Python `requests`
- Python `ftplib`
- `BeautifulSoup4`
- `tqdm`
- ITSG / GFZ 等公开大地测量数据服务站点

---

## 免责声明

本工具仅用于访问公开可用的科研数据资源。
请遵守数据提供方的使用条款、访问限制与版权要求。
