semvec/pypi-packages huggingface dataset:
ltws-parser 1.5.1
LTWS 协议解析器
License: MIT
Requires Python: >=3.8

# LTWS 解析器

用于解析和验证 LTWS (Little Tree Wallpaper Source) 协议 v3.0 的 Python 库。

## 特性

- 🚀 支持解析 `.ltws` 文件（不压缩的 TAR 格式）
- 📝 支持解析目录结构的壁纸源
- ✅ 完整的配置验证
- 🛠️ 提供打包工具
- 🔧 变量替换引擎
- 📊 详细的错误报告

## 协议适配说明（v3.0 新版要点）

- `source.toml` 支持用 `categories` / `config` 指向任意相对路径
- `identifier` 允许小写字母/数字/点/下划线（反向域名风格）
- JSON Pointer 映射支持 `*` 与 `**` 通配
- 变量函数参数支持协议示例的冒号分隔（如 `{{random_int:1:10}}`）

更多细节见：`USAGE.md` 与 `llms.txt`。

## 安装

```bash
pip install ltws-parser
```


## 快速开始

### 1. 解析壁纸源

python

```
from ltws import LTWSParser

# 创建解析器
parser = LTWSParser()

# 解析 .ltws 文件
source = parser.parse("my_wallpaper_source.ltws")

# 或解析目录
source = parser.parse("my_wallpaper_source/")

# 使用壁纸源
print(f"名称: {source.name}")
print(f"版本: {source.version}")
print(f"API数量: {len(source.apis)}")
```



### 2. 验证壁纸源

python

```
from ltws import LTWSValidator

# 创建验证器
validator = LTWSValidator()

# 验证壁纸源
is_valid = validator.validate_source(source)

# 获取验证报告
report = validator.get_validation_report()
print(f"验证通过: {report['passed']}")
print(f"错误: {report['errors']}")
print(f"警告: {report['warnings']}")
```



### 3. 使用变量引擎

python

```
from ltws import VariableEngine

# 创建变量引擎
engine = VariableEngine()

# 替换变量
template = "https://api.example.com/wallpapers?date={{date_iso}}&random={{random_string:8}}"
result = engine.replace(template)
print(result)  # https://api.example.com/wallpapers?date=2024-01-15&random=abc123de
```



### 4. 打包壁纸源

python

```
from ltws import LTWSPackager

# 创建打包工具
packager = LTWSPackager()

# 打包目录为 .ltws 文件
packager.pack("my_wallpaper_source/", "output.ltws")
```



## 命令行工具

安装后可以使用 `ltws` 命令行工具：

bash

```
# 验证壁纸源
ltws validate my_wallpaper_source/

# 打包壁纸源
ltws pack my_wallpaper_source/ output.ltws

# 查看 .ltws 文件信息
ltws inspect output.ltws

# 测试壁纸源
ltws test my_wallpaper_source/
```



## API 参考

### LTWSParser

主要解析器类，用于解析壁纸源。

python

```
parser = LTWSParser(strict=True)
source = parser.parse(path)
errors = parser.get_errors()
warnings = parser.get_warnings()
```



### LTWSValidator

验证器类，用于验证壁纸源配置。

python

```
validator = LTWSValidator()
is_valid = validator.validate_source(source)
report = validator.get_validation_report()
```



### LTWSPackager

打包工具类，用于创建 `.ltws` 文件。

python

```
packager = LTWSPackager(strict=True)
packager.pack(source_dir, output_file, overwrite=False)
```



### VariableEngine

变量替换引擎，支持内置变量和自定义变量。

python

```
engine = VariableEngine()
result = engine.replace(template, context)
```



## 数据模型

库提供完整的数据模型：

- `WallpaperSource`: 壁纸源完整对象
- `WallpaperAPI`: API 定义
- `Category`: 分类定义
- `Parameter`: 参数定义
- `RequestConfig`: 请求配置
- `FieldMapping`: 字段映射