docs

README.md

@@ -36,4 +36,8 @@ export CSST_DFS_TOKEN=XXXX
 
 ## 数据模型说明
 
-[查看文档](docs/model.md)
\ No newline at end of file
+[查看文档](docs/model.md)
+
+## 接口使用说明
+
+[查看文档](docs/usage.md)
\ No newline at end of file

csst_dfs_client/level0.py

@@ -85,6 +85,16 @@ def find(project_id: Optional[str] = None,
     return request.post("/api/level0", params)
 
 def get_by_id(_id: str) -> Result:
+    """
+    根据内部ID获取0级数据
+    
+    Args:
+        _id (str): 0级数据的内部ID
+    
+    Returns:
+        Result: 查询结果
+    
+    """
     return request.get(f"/api/level0/_id/{_id}")
 
 def find_by_level0_id(level0_id: str) -> Result:

docs/catalog.md

+# 星表数据查询
+
+## 概述
+
+`csst_dfs_client.catalog` 模块提供了一个 `search` 函数，用于根据给定的参数，使用锥形检索指定范围内的天体数据。
+
+## 使用示例
+
+```python
+from csst_dfs_client import catalog
+
+# 查询参数
+ra = 90  # 天体赤经（以度为单位）
+dec = 24.5  # 天体赤纬（以度为单位）
+radius = 0.21  # 查询半径（以度为单位）
+catalog_name = 'gaia3'  # 星表名称
+columns = ['ref_epoch', 'ra', 'ra_error', 'dec', 'dec_error', 'parallax', 'parallax_error', 'pmra', 'pmra_error', 'pmdec', 'pmdec_error', 'phot_g_mean_mag', 'source_id']  # 查询的列名
+min_mag = -1  # 最小星等，默认为 -1（无限制）
+max_mag = -1  # 最大星等，默认为 -1（无限制）
+obstime = -1  # 观测时间，默认为 0（暂无用）
+limit = 10  # 查询结果的数量限制，默认为 0（无限制）
+
+# 调用 search 函数进行查询
+result = catalog.search(ra=ra, 
+        dec=dec, 
+        radius=radius, 
+        catalog_name=catalog_name, 
+        columns=columns, 
+        min_mag=min_mag, 
+        max_mag=max_mag, 
+        obstime=obstime, 
+        limit=limit
+    )
+# 打印查询结果
+print(result.data) #result.data为pd.DataFrame对象
+```
+
+- [其他接口](./usage.md)
+  
\ No newline at end of file

docs/common.md

+# 通用接口使用说明
+
+## 概述
+
+该模块包含了从指定路径下载文件、读取文件、获取文件头信息的函数。
+
+## 函数列表
+
+1. **download_file**
+   - 功能： 从指定路径下载文件。
+   - 参数： 文件相对路径。
+   - 返回值：字节。
+
+2. **read_file**
+   - 功能： 读取指定路径的文件。
+   - 参数： 文件相对路径。
+   - 返回值：io.BytesIO。
+
+3. **get_free_header**
+   - 功能： 获取指定文件路径的文件头信息。
+   - 参数： 文件相对路径。
+   - 返回值：dict。
+
+## 示例
+
+### 1. `download_file` 函数
+
+```python
+from csst_dfs_client import download_file
+
+try:
+    file_content = download_file("path/to/your/file")
+    print(type(file_content))
+except AppError as e:
+    print(f"Error: {e}")
+```
+
+### 2. `read_file` 函数
+
+```python
+from csst_dfs_client import read_file
+
+try:
+    file_io = read_file("path/to/your/file.txt")
+    print(file_io.getvalue())
+except AppError as e:
+    print(f"Error: {e}")
+```
+
+### 3. `get_free_header` 函数
+
+```python
+from csst_dfs_client import get_free_header
+
+try:
+    header_info = get_free_header("path/to/your/file.txt")
+    print(header_info)
+except AppError as e:
+    print(f"Error: {e}")
+```
+
+- [其他接口](./usage.md)

docs/level0.md

+# 0级数据接口使用说明
+
+## 概述
+
+0级数据接口模块是 `csst_dfs_client.level0`。该模块包含了搜索0级数据文件记录、将本地文件写入DFS等功能的函数。
+
+## 函数列表
+
+1. **find**
+   - 功能：根据给定的参数搜索0级数据文件记录。
+   - 参数：包括项目ID、观测ID、模块ID、探测器编号、文件类型、滤光片、观测时间范围、创建时间范围等。
+   - 返回值：搜索结果对象。
+
+2. **get_by_id**
+   - 功能：通过0级数据内部ID获取对应的0级数据文件记录。
+   - 参数：0级数据内部ID。
+   - 返回值：查询结果对象。
+
+3. **find_by_level0_id**
+   - 功能：通过0级数据ID获取对应的0级数据文件记录。
+   - 参数：0级数据ID。
+   - 返回值：查询结果对象。
+
+4. **update_qc0_status**
+   - 功能：更新0级数据的QC0状态。
+   - 参数：0级数据ID、文件类型、QC0状态、数据集名称（可选）。
+   - 返回值：操作结果对象，包含操作是否成功以及相关的错误信息。
+  
+5. **update_prc_status**
+   - 功能：更新0级数据的处理状态。
+   - 参数：0级数据ID、文件类型、处理状态、数据集名称（可选）。
+   - 返回值：操作结果对象，包含操作是否成功以及相关的错误信息。
+
+6. **write**
+   - 功能：将本地文件写入DFS中。
+   - 参数：本地文件路径、数据集名称（可选）、其他可选的关键字参数。
+   - 返回值：操作结果对象，包含操作是否成功以及相关的错误信息。
+
+7. **write_cat**
+   - 功能：将主巡天仿真数据的星表本地文件写入DFS中。
+   - 参数：本地文件路径、数据集名称（可选）、其他可选的关键字参数。
+   - 返回值：操作结果对象，包含操作是否成功以及相关的错误信息。
+
+8. **process_list**
+   - 功能：通过0级数据ID获取对应的0级数据处理记录。
+   - 参数：0级数据ID。
+   - 返回值：查询结果对象。
+  
+9. **add_process**
+   - 功能：添加0级数据处理记录。
+   - 参数：0级数据ID、管线ID、运行ID、数据集名称（可选）
+   - 返回值：操作结果对象，包含操作是否成功以及相关的错误信息。
+
+## 使用示例
+
+### 1.搜索0级数据文件记录
+
+```python
+from csst_dfs_client import level0
+
+# 搜索0级数据文件记录
+result = level0.find(obs_id='some_obs_id', module_id='MSC', page=1, limit=10)
+print(result) # result.data为list类型，包含0级数据文件记录列表
+```
+
+### 2. 通过0级数据内部ID获取对应的0级数据文件记录
+
+```python
+from csst_dfs_client import level0
+result = level0.get_by_id(_id='some_internal_id')
+print(result) # result.data为0级数据文件单条记录
+```
+
+### 3. 通过0级数据ID获取对应的0级数据
+
+```python
+
+from csst_dfs_client import level0
+result = level0.find_by_level0_id(level0_id='some_level0_id')
+print(result) # result.data为list类型，包含0级数据的列表
+```
+
+### 4. 更新0级数据的QC0状态 
+
+```python
+from csst_dfs_client import level0
+result = level0.update_qc0_status(level0_id='some_level0_id', filetype='SCI', qc0_status=1)
+print(result)
+```
+
+### 5. 更新0级数据的处理状态
+
+```python
+from csst_dfs_client import level0
+result = level0.update_prc_status(level0_id='some_level0_id', filetype='SCI', prc_status=1)
+print(result)
+```
+
+### 6.将本地文件写入DFS
+
+```python
+from csst_dfs_client import level0
+
+# 将本地文件写入DFS
+local_file_path = 'path/to/your/level0_data.fits'
+dataset = 'default_dataset'  # 可选参数，默认为None
+result = level0.write(local_file_path, dataset=dataset)
+print(result)
+```
+
+### 7.将主巡天仿真数据的星表本地文件写入DFS
+
+```python
+from csst_dfs_client import level0
+
+# 将主巡天仿真数据的星表本地文件写入DFS
+local_catalog_file_path = 'path/to/your/catalog.cat'
+dataset = 'default_dataset'  # 可选参数，默认为None
+result = level0.write_cat(local_catalog_file_path, dataset=dataset)
+print(result)
+```
+
+### 8. 通过0级数据ID获取对应的0级数据处理记录
+
+```python
+from csst_dfs_client import level0
+result = level0.process_list(level0_id='some_level0_id')
+print(result)# result.data为list类型，包含0级数据处理记录列表
+
+```
+
+### 9. 添加0级数据处理记录
+
+```python
+
+from csst_dfs_client import level0
+result = level0.add_process(
+      level0_id='some_level0_id', 
+      pipeline_id='some_pipeline_id', 
+      run_id='some_run_id', 
+      batch_id='some_batch_id',
+      dataset='default_dataset',
+      prc_status=1,
+      prc_time='2024-11-07 10:24:12',
+      prc_module='some_function_name',
+      message='some_message')
+print(result)
+```
+
+- [其他接口](./usage.md)

docs/level1.md

+# 1级数据接口使用说明
+
+## 概述
+
+1级数据接口模块是 `csst_dfs_client.level1`。该模块包含了搜索1级数据文件记录、更新1级数据状态、将本地文件写入DFS以及管理1级数据处理记录等功能的函数。
+
+## 函数列表
+
+1. **find**
+   - 功能：根据给定的参数搜索1级数据文件记录。
+   - 参数：包括项目ID、观测ID、模块ID、探测器编号、文件类型、滤光片、观测时间范围、创建时间范围、QC1状态、处理状态、文件名、目标赤经、目标赤纬、搜索半径、天体名称、RSS ID、Cube ID、数据集名称、批次ID、页码、每页数量等。
+   - 返回值：搜索结果对象。
+
+2. **find_by_level1_id**
+   - 功能：通过1级数据的ID查询1级数据。
+   - 参数：1级数据的ID。
+   - 返回值：查询结果对象。
+
+3. **find_by_brick_id**
+   - 功能：通过brick的ID查询1级数据。
+   - 参数：brick的ID。
+   - 返回值：查询结果对象。
+
+4. **sls_find_by_qc1_status**
+   - 功能：通过QC1状态查询1级数据。
+   - 参数：QC1状态、查询结果数量限制、批次ID。
+   - 返回值：查询结果对象。
+
+5. **update_qc1_status**
+   - 功能：更新1级数据的QC1状态。
+   - 参数：1级数据的ID、文件类型、QC1状态、批次ID。
+   - 返回值：更新结果对象。
+
+6. **update_prc_status**
+   - 功能：更新1级数据的处理状态。
+   - 参数：1级数据的ID、文件类型、处理状态、批次ID。
+   - 返回值：操作结果对象。
+
+7. **write**
+   - 功能：将本地的1级数据文件写入到DFS中。
+   - 参数：本地文件路径或文件对象、模块ID、1级数据的ID、文件类型、文件名、管线ID、CCDS pmap名称、构建号、0级数据的ID、数据集名称、批次ID、QC1状态等。
+   - 返回值：操作的结果对象。
+
+8. **generate_prc_msg**
+   - 功能：生成流水线的处理消息。
+   - 参数：模块ID、1级数据的ID、数据集、批次ID。
+   - 返回值：处理消息生成的结果对象。
+
+9. **process_list**
+   - 功能：通过1级数据的ID查询1级数据处理记录。
+   - 参数：1级数据的ID。
+   - 返回值：查询结果对象。
+
+10. **add_process**
+  - 功能：添加1级数据处理记录。
+  - 参数：1级数据的ID、管线ID、运行ID、数据集、批次ID、处理时间、处理状态、处理模块、处理消息。
+  - 返回值：操作结果对象。
+
+## 使用示例
+
+### 1. 搜索1级数据文件记录
+
+```python
+# 搜索1级数据文件记录
+result = level1.find(obs_id='some_obs_id', module_id='MSC', page=1, limit=10)
+print(result) # result.data为list类型，包含1级数据文件记录列表
+```
+
+### 2. 通过1级数据的ID查询1级数据
+
+```python
+from csst_dfs_client import level1
+result = level1.find_by_level1_id(level1_id='some_level1_id')
+print(result) # result.data为list类型，包含1级数据文件记录列表
+```
+
+### 3. 通过brick的ID查询1级数据
+
+```python
+from csst_dfs_client import level1
+result = level1.find_by_brick_id(brick_id=123456)
+print(result) # result.data为list类型，包含1级数据文件记录列表
+```
+
+### 4. 通过QC1状态查询1级数据(SLS专用)
+
+```python
+from csst_dfs_client import level1
+result = level1.sls_find_by_qc1_status(qc1_status='GOOD', limit=5)
+print(result) # result.data为list类型，包含1级数据文件记录列表
+```
+
+### 5. 更新1级数据的QC1状态
+
+```python
+from csst_dfs_client import level1
+result = level1.update_qc1_status(level1_id='some_level1_id', filetype='SCI', qc1_status=1, batch_id='some_batch_id')
+print(result)
+```
+
+### 6. 更新1级数据的处理状态
+
+```python
+from csst_dfs_client import level1
+result = level1.update_prc_status(level1_id='some_level1_id', filetype='SCI', prc_status=1, batch_id='some_batch_id')
+print(result)
+```
+
+### 7. 将本地文件写入DFS
+
+```python
+from csst_dfs_client import level1
+
+# 将本地的1级数据文件写入到DFS中
+local_file_path = '/path/to/your/level1_data.fits'
+module_id = 'MSC'
+level1_id = 'some_level1_id'
+file_type = 'SCI'
+file_name = 'level1_data.fits'
+pipeline_id = 'some_pipeline_id'
+pmapname = 'some_pmapname'
+build = 1
+level0_id = 'some_level0_id'
+dataset = 'default_dataset'
+batch_id = 'default_batch_id'
+qc1_status = 0
+
+result = level1.write(local_file_path, module_id, level1_id, file_type, file_name, pipeline_id, pmapname, build, level0_id, dataset, batch_id, qc1_status)
+print(result)
+
+```
+
+### 8. 生成流水线的处理消息
+
+```python
+from csst_dfs_client import level1
+result = level1.generate_prc_msg(module_id='some_module_id', level1_id='some_level1_id', dataset='some_dataset', batch_id='some_batch_id')
+print(result)
+```
+
+### 9. 通过1级数据的ID查询1级数据处理记录
+
+```python
+from csst_dfs_client import level1
+result = level1.process_list(level1_id='some_level1_id')
+print(result) # result.data为list类型，包含1级数据处理记录列表
+```
+
+### 10. 添加1级数据处理记录
+
+```python
+from csst_dfs_client import level1
+result = level1.add_process(
+      level1_id='some_level1_id', 
+      pipeline_id='some_pipeline_id', 
+      run_id='some_run_id', 
+      batch_id='some_batch_id',
+      dataset='default_dataset',
+      prc_status=1,
+      prc_time='2024-11-07 10:24:12',
+      prc_module='some_function_name',
+      message='some_message')
+print(result)
+```
+
+- [其他接口](./usage.md)

docs/level2.md

+# 2级数据接口使用说明
+
+## 概述
+
+2级数据接口模块是 `csst_dfs_client.level2`。该模块包含了搜索2级数据文件记录、更新2级数据状态、将本地文件写入DFS以及管理2级数据处理记录等功能的函数。
+
+## 函数列表
+
+1. **find**
+   - 功能：根据给定的参数搜索2级数据文件记录。
+   - 参数：包括项目ID、观测ID、模块ID、探测器编号、文件类型、滤光片、观测时间范围、创建时间范围、QC2状态、处理状态、文件名、目标赤经、目标赤纬、搜索半径、天体名称、RSS ID、Cube ID、数据集名称、批次ID、页码、每页数量等。
+   - 返回值：搜索结果对象。
+
+2. **find_by_level2_id**
+   - 功能：通过2级数据的ID查询2级数据。
+   - 参数：2级数据的ID。
+   - 返回值：查询结果对象。
+
+3. **update_qc2_status**
+   - 功能：更新2级数据的QC2状态。
+   - 参数：2级数据的ID、文件类型、QC2状态、批次ID。
+   - 返回值：更新结果对象。
+
+4. **update_prc_status**
+   - 功能：更新2级数据的处理状态。
+   - 参数：2级数据的ID、文件类型、处理状态、批次ID。
+   - 返回值：操作结果对象。
+
+5. **write**
+   - 功能：将本地的2级数据文件写入到DFS中。
+   - 参数：本地文件路径或文件对象、模块ID、2级数据的ID、文件类型、文件名、管线ID、构建号、0级数据的ID、1级数据的ID、数据集名称、批次ID、QC2状态等。
+   - 返回值：操作的结果对象。
+
+6. **catalog_query**
+   - 功能：查询2级数据的星表数据。
+   - 参数：SQL查询语句，limit参数限制查询结果的数量。
+   - 返回值：查询结果对象， result.data为pd.DataFrame。
+
+## 使用示例
+
+### 1. 搜索2级数据文件记录
+
+```python
+
+
+# 搜索2级数据文件记录
+result = level2.find(obs_id='some_obs_id', data_type='csst-msc-l2-mbi' module_id='MSC', page=1, limit=10)
+print(result) # result.data为list类型，包含2级数据文件记录列表
+
+```
+
+### 2. 通过ID查询2级数据
+
+```python
+from csst_dfs_client import level2
+result = level2.find_by_level2_id(level2_id='some_level2_id')
+print(result) # result.data为list类型，包含2级数据文件记录列表
+```
+
+### 3. 更新2级数据的QC2状态
+
+```python
+from csst_dfs_client import level2
+result = level2.update_qc2_status(level2_id='some_level2_id', data_type='SCI', qc2_status=1, batch_id='some_batch_id')
+print(result)
+```
+
+### 4. 更新2级数据的处理状态
+
+```python
+from csst_dfs_client import level2
+result = level2.update_prc_status(level2_id='some_level2_id', data_type='SCI', prc_status=1, batch_id='some_batch_id')
+print(result)
+```
+
+### 5. 将本地文件写入DFS
+
+```python
+from csst_dfs_client import level2
+
+# 将本地的2级数据文件写入到DFS中
+local_file_path = '/path/to/your/level2_data.fits'
+module_id = 'MSC'
+level2_id = 'some_level2_id'
+file_type = 'SCI'
+file_name = 'level2_data.fits'
+pipeline_id = 'some_pipeline_id'
+build = 1
+level0_id = 'some_level0_id'
+level1_id = 'some_level1_id'
+dataset = 'default_dataset'
+batch_id = 'default_batch_id'
+qc2_status = 0
+
+result = level2.write(local_file_path, module_id, level2_id, file_type, file_name, pipeline_id, build, level0_id, level1_id, dataset, batch_id, qc2_status)
+print(result)
+```
+
+### 6. 查询2级数据的星表数据
+
+```python
+from csst_dfs_client import level2
+data_type = 'csst-msc-l2-mbi-cat'
+table_name = data_type.replace('-', '_')
+sql_query = f"SELECT * FROM {table_name}"
+result = level2.catalog_query(sql_query, limit=10)
+print(result) # result.data为pd.DataFrame类型，包含查询结果
+```
+
+- [其他接口](./usage.md)

docs/model.md

@@ -127,3 +127,6 @@
 
 **注释**：
 暂无其他信息
+
+
+- [接口](./usage.md)

docs/plan.md

+# CSST-DFS 编排接口使用说明
+
+## 概述
+
+编排接口模块是 `csst_dfs_client.plan` ，用于与DFS（分布式文件系统）中的编排（plan）数据进行交互。该模块用于搜索、获取、写入和新建编排数据。
+
+## 函数列表
+
+1. **find**
+   - 功能：根据给定的参数在DFS中搜索编排数据。
+   - 参数：包括观测模式、观测ID、后端模块ID等。
+   - 返回值：搜索结果对象。
+
+2. **get_by_id**
+   - 功能：通过编排ID获取对应的编排数据。
+   - 参数：编排ID。
+   - 返回值：查询结果对象。
+
+3. **find_by_opid**
+   - 功能：通过编排的opid查询对应的编排数据。
+   - 参数：opid。
+   - 返回值：查询结果对象。
+
+4. **write_file**
+   - 功能：将本地的JSON文件或JSON数据流写入DFS中。
+   - 参数：本地文件路径或文件对象，以及其他可选的关键字参数。
+   - 返回值：操作结果对象。
+
+5. **new**
+   - 功能：新建编排数据。
+   - 参数：编排数据的字典表示。
+   - 返回值：操作结果对象。
+
+## 使用示例
+
+以下是一些使用 `plan` 模块的示例代码。
+
+### 1. 搜索编排数据
+
+```python
+from csst_dfs_client import plan
+
+# 搜索编排数据
+result = plan.find(mode='SCIENCE', backend='MSC', page=1, limit=10)
+print(result)
+```
+
+### 2. 通过编排数据中的ID获取编排数据
+
+```python
+from csst_dfs_client import plan
+
+# 通过编排ID获取编排数据
+_id = 12345
+result = plan.get_by_id(_id)
+print(result)
+```
+
+### 3. 通过编排数据中的opid查询编排数据
+
+```python
+from csst_dfs_client import plan
+
+# 通过opid查询编排数据
+opid = 'some_opid'
+result = plan.find_by_opid(opid)
+print(result)
+```
+
+### 4. 批量写入编排的JSON数据到DFS
+
+```python
+from csst_dfs_client import plan
+
+# 写入编排数据到DFS
+local_file_path = '/path/to/your/plan_data.json'
+result = plan.write_file(local_file_path)
+print(result)
+```
+
+### 5. 写入单条编排数据
+
+```python
+from csst_dfs_client import plan
+
+# 写入单条编排数据
+plan_data = {
+    'id': 67890,
+    'opid': 'new_opid',
+    'backend': 'MSC',
+    # 其他编排数据字段
+}
+result = plan.new(plan_data)
+print(result)
+```
+
+- [其他接口](./usage.md)

docs/usage.md

+# CSST DFS数据服务客户端
+
+## 安装与配置
+
+- [安装与配置](../README.md)
+
+## 使用说明
+
+- [通用方法](./common.md)
+- [0级数据](./level0.md)
+- [1级数据](./level1.md)
+- [2级数据](./level2.md)
+- [星表数据](./catalog.md)
+- [编排数据](./plan.md)
+
+## 返回数据
+
+所有接口的返回数据为csst_dfs_client.common.Result对象
+
+Result包含3个属性
+
+- success (bool): True表示成功，False表示失败。
+- message (str): 错误信息（如果失败）。
+- data (any): 数据（如果成功）。