Metadata-Version: 2.1
Name: aisky
Version: 0.1.0
Summary: aisky 系列子模型的云端预报数据读取与缓存工具
Author: aisky contributors
License: MIT License
        
        Copyright (c) 2026 aisky contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        
Project-URL: Homepage, https://github.com/your-org/aisky
Project-URL: Repository, https://github.com/your-org/aisky
Project-URL: Documentation, https://github.com/your-org/aisky#readme
Project-URL: Issues, https://github.com/your-org/aisky/issues
Keywords: forecast,xarray,netcdf,meteorology,aisky
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: xarray (>=2023.1.0)
Requires-Dist: netCDF4 (>=1.6.0)
Requires-Dist: numpy (>=1.23.0)
Requires-Dist: pandas (>=1.5.0)
Requires-Dist: scipy (>=1.9.0)
Provides-Extra: dev
Requires-Dist: pytest (>=7.0) ; extra == 'dev'
Requires-Dist: pytest-cov (>=4.0) ; extra == 'dev'
Requires-Dist: build (>=1.2.0) ; extra == 'dev'
Requires-Dist: twine (>=5.0) ; extra == 'dev'

# aisky

`aisky` 是一个面向 **aisky 系列子模型** 的云端预报数据读取与缓存 Python 包。不同子模型的起报时制、步长规则、变量集合、URL 规则可能不同，因此以“模型客户端”形式提供能力。

```python
from aisky import aisky

client = aisky(model="aisky-aerosol")
print(client.info().to_dict())

da = client.get_forecast(
    init_time="20260101_0130",
    step_hours=3,
    count=8,
    variable="TOTEXTTAU",
)
print(da)
```

一次取多个变量（返回 `xarray.Dataset`）：

```python
from aisky import aisky

client = aisky("aisky-aerosol")
ds = client.get_forecast(
    "20260101_0130",
    step_hours=3,
    count=8,
    variable=["TOTEXTTAU", "DUEXTTAU"],
)
print(ds)
```

## 安装

```bash
pip install aisky
```

依赖：`xarray`, `netCDF4`, `numpy`, `pandas`, `scipy`。

## 快速开始（以 aisky-aerosol 为例）

### 1) 查看可用模型

```python
import aisky

print(aisky.available_models())
```

### 2) 查看模型信息（时制/变量/规则）

```python
from aisky import aisky

client = aisky("aisky-aerosol")
info = client.info()

print(info.cycle_times)
print(info.variables)
```

### 3) 读取预报

```python
from aisky import aisky

client = aisky("aisky-aerosol")
da = client.get_forecast("20260101_0130", step_hours=3, count=8, variable="TOTEXTTAU")
```

### 4) 缓存到本地目录

`store_dir` 会以起报时刻创建子目录（例如 `./data/20260101_0130/`）：

```python
from aisky import aisky

client = aisky("aisky-aerosol")
da = client.get_forecast(
    "20260101_0130",
    count=8,
    variable="TOTEXTTAU",
    store_dir="./data",
)
```

## API

### `aisky(model=...)`

返回一个模型客户端对象，支持：

- `client.info()`：返回该子模型的元信息（起报时制、变量、规则、默认值等）
- `client.get_forecast(...)`：下载/缓存/读取该子模型数据

### `client.get_forecast(...)`

- `init_time`: 起报时刻，支持 `"YYYYMMDD_HHMM"` 字符串、`datetime`、`pandas.Timestamp`
- `step_hours`: 步长（小时），由子模型规则约束（`aisky-aerosol` 必须是 3 的倍数）
- `count`: 预报场数量（`>= 1`；`1` 表示只取一个预报时刻）
- `store_dir`: 可选；如果提供，则以 `store_dir/init_time/` 的形式落盘
- `cache_dir`: 可选；默认使用系统缓存目录（Windows 为 `%LOCALAPPDATA%\\aisky\\cache`）
- `variable`: 可选；要返回的变量名或变量列表（对 `aisky-aerosol` 必须来自 `client.info().variables`）
- `engine`: `xarray.open_dataset` 的引擎（默认 `netcdf4`）
- `timeout`: 下载超时（秒）
- `retries`: 下载重试次数
- `overwrite`: 是否覆盖已缓存的文件
- `return_dataset`: 是否直接返回 `xarray.Dataset`

更多示例见 [docs/usage.md](docs/usage.md)。

## 数据来源与 URL 规则

云端数据 URL 模板为（外部产品名称不依赖该路径命名）：

```
https://obs.cstcloud.cn/s/ai-gamfs/AI-GAMFS/forecast_data/{init}/AI_GAMFS.{init}+{valid}.V01.nc
```

其中 `init` 与 `valid` 都是 `YYYYMMDD_HHMM`。

## 许可证

MIT License，详见 [LICENSE](LICENSE)。
