Metadata-Version: 2.4
Name: ssim-parser
Version: 1.1.0
Summary: Comprehensive IATA SSIM file parser with advanced filtering, split, and route map generation
Author-email: "Zhang, Jianchao" <zhangjc@csair.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/zhjch/ssim-parser
Project-URL: Repository, https://github.com/zhjch/ssim-parser
Project-URL: Issues, https://github.com/zhjch/ssim-parser/issues
Keywords: ssim,iata,aviation,airline,schedule,parser,filter,split,map
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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
Classifier: Topic :: Office/Business :: Scheduling
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: pandas
Requires-Dist: pandas>=1.0.0; extra == "pandas"
Provides-Extra: parquet
Requires-Dist: pandas>=1.0.0; extra == "parquet"
Requires-Dist: pyarrow>=10.0.0; extra == "parquet"
Provides-Extra: map
Requires-Dist: folium>=0.12.0; extra == "map"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# ssim-parser

[![PyPI version](https://badge.fury.io/py/ssim-parser.svg)](https://badge.fury.io/py/ssim-parser)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

---

## English

A comprehensive Python parser for IATA SSIM (Standard Schedules Information Manual) flight schedule files (Chapter 7) with advanced filtering, splitting, and route mapping capabilities.

### Features

- Parse SSIM Chapter 7 – Record Types 1, 2, 3, 4, 5
- Full field coverage for Header, Season, Flight Leg, Segment, Trailer
- Expand weekly schedules into daily flight lists
- Advanced filtering:
  - Date range (`--start-date`, `--end-date`)
  - Airlines, departure/arrival stations, flight numbers
  - **Wildcards** (`*`, `?`) and **regular expressions** (prefix `~`)
  - **Exclude** conditions (`--exclude-airlines`, etc.)
- Export to CSV, JSON, Pandas DataFrame, Parquet
- Command-line and Python API
- Statistics: shows filtered counts
- Strict validation mode
- **Split SSIM by airline** (`ssim-split`)
- **Generate interactive route maps** (`ssim-map`)
- Apache 2.0 License (explicit patent grants)

### Installation

```bash
pip install ssim-parser
```

For extra features:

```bash
pip install ssim-parser[pandas]      # DataFrame support
pip install ssim-parser[parquet]     # Parquet export
pip install ssim-parser[map]         # Route map generation (folium)
```

### Usage

#### 1. Parse and Filter Flights (ssim-parser)

Basic command:

```bash
ssim-parser -i schedule.ssim -o flights.csv
```

Filtering examples:

```bash
# Date range and airlines
ssim-parser -i schedule.ssim -o output.csv \
    --start-date 2026-07-01 --end-date 2026-07-31 \
    --airlines UA,AA

# Wildcard: flight numbers starting with "32"
ssim-parser -i schedule.ssim -o output.csv --flight-numbers "32*"

# Regex: airlines starting with 'U'
ssim-parser -i schedule.ssim -o output.csv --airlines "~^U.*"

# Exclude AA and DL
ssim-parser -i schedule.ssim -o output.csv --exclude-airlines AA,DL

# Complex: date + airline + departure + exclusion
ssim-parser -i schedule.ssim -o out.csv \
    --start-date 2026-08-08 --end-date 2026-08-15 \
    --airlines CZ --flight-numbers "327,328" \
    --departure JFK --exclude-arrival LAX

# Stream mode for large files (auto‑enabled for >500 MB):
ssim-parser -i huge.ssim -o out.csv --stream --log-file parser.log
```

#### 2. Split SSIM by Airline (ssim-split)

Split a multi‑carrier SSIM into separate files, each containing a complete SSIM structure (Records 1‑5) for one airline.

```bash
ssim-split -i multi_carrier.ssim -o split_prefix
```

This produces files like split_prefix-CZ.dat, split_prefix-UA.dat, etc.

#### 3. Generate Route Map (ssim-map)

Create an interactive HTML map showing departure (solid lines) and arrival (dashed lines) routes from a hub airport for selected airlines.

```bash
ssim-map -i schedule.ssim --hub LAX --airlines CZ,UA -o lax_routes.html
```

##### Filter Pattern Syntax

+ Exact match: UA

+ Wildcard: * (any sequence), ? (single character)

Example: 32* matches 321, 3220, etc.

+ Regular expression: prefix with ~, e.g. ~^UA.* matches all airlines starting with UA.

##### Export Formats

+ CSV (default)

+ JSON (-f json)

+ Parquet (-f parquet – requires ssim-parser[parquet])

##### Strict Mode

Use --strict to enable validation (throws errors on malformed records).

##### Python API
```python
from ssim_parser import SsimParser, expand_flights, filter_flights

parser = SsimParser()
data = parser.parse_file("schedule.ssim")
all_flights = expand_flights(data)

filtered = filter_flights(
    all_flights,
    start_date="2026-07-01",
    airlines=["UA", "AA"],
    exclude_arrival=["LAX"]
)
print(f"Filtered: {len(filtered)} flights")
```

### Documentation
See the [IATA SSIM Manual](https://www.iata.org/en/publications/manuals/standard-schedules-information/) for field definitions.

### Contributing
Pull requests are welcome. For major changes, please open an issue first.

### License
Apache License 2.0

## 中文版

### 简介

ssim-parser 是一个功能完整的 Python 工具，用于解析 IATA SSIM（标准航班时刻表手册）第 7 章的航班计划文件，并支持高级过滤、按航司拆分及航线地图可视化。

### 功能特点

+ 解析 SSIM 第 7 章所有记录类型（1‑5）

+ 完整覆盖标题、航季、航段、子段、尾记录字段

+ 将周计划展开为每日航班列表

+ 高级过滤：

    - 日期范围（--start-date、--end-date）

    - 航司、起降机场、航班号

    - 通配符（*、?）和正则表达式（前缀 ~）

    - 排除条件（--exclude-airlines 等）

+ 导出为 CSV、JSON、Pandas DataFrame、Parquet

+ 命令行和 Python API

+ 统计信息（显示过滤前后数量）

+ 严格校验模式

+ 按航司拆分 SSIM（ssim-split）

+ 生成交互式航线地图（ssim-map）

+ Apache 2.0 许可证（含专利授权）

### 安装
```bash
pip install ssim-parser
```
如需额外功能：

```bash
pip install ssim-parser[pandas]      # DataFrame 支持
pip install ssim-parser[parquet]     # Parquet 导出
pip install ssim-parser[map]         # 地图生成（folium）
```

### 使用说明

#### 1. 解析并过滤航班（ssim-parser）

基本命令：

```bash
ssim-parser -i schedule.ssim -o flights.csv
```

过滤示例：

```bash
# 日期范围和航司
ssim-parser -i schedule.ssim -o output.csv \
    --start-date 2026-07-01 --end-date 2026-07-31 \
    --airlines UA,AA

# 通配符：航班号以 "32" 开头
ssim-parser -i schedule.ssim -o output.csv --flight-numbers "32*"

# 正则：航司以 'U' 开头
ssim-parser -i schedule.ssim -o output.csv --airlines "~^U.*"

# 排除 AA 和 DL
ssim-parser -i schedule.ssim -o output.csv --exclude-airlines AA,DL

# 组合筛选：日期 + 航司 + 出发机场 + 排除到达
ssim-parser -i schedule.ssim -o out.csv \
    --start-date 2026-08-08 --end-date 2026-08-15 \
    --airlines CZ --flight-numbers "301,302,327,328" \
    --departure CAN --exclude-arrival LAX

# 大文件流式处理（>500MB 自动启用）：
ssim-parser -i huge.ssim -o out.csv --stream --log-file parser.log
```

#### 2. 按航司拆分 SSIM（ssim-split）

将包含多家航司的 SSIM 文件拆分成每个航司独立的文件，每个文件包含完整的 SSIM 结构（记录 1‑5）。

```bash
ssim-split -i multi_carrier.ssim -o split_prefix
```

生成 split_prefix-CZ.dat、split_prefix-UA.dat 等文件。

#### 3. 生成航线地图（ssim-map）

针对指定枢纽机场和航司列表，生成交互式 HTML 地图，出港航线显示为实线，到港航线显示为虚线。

```bash
ssim-map -i schedule.ssim --hub LAX --airlines CZ,UA -o lax_routes.html
```

#### 过滤模式语法

+ 精确匹配：UA

+ 通配符：*（任意字符）、?（单个字符）

例如：32* 匹配 321、3220 等。

+ 正则表达式：以 ~ 开头，如 ~^UA.* 匹配所有以 UA 开头的航司。

#### 导出格式

+ CSV（默认）

+ JSON（-f json）

+ Parquet（-f parquet – 需要安装 ssim-parser[parquet]）

#### 严格模式

使用 --strict 启用校验（遇到格式错误时会抛出异常）。

#### Python API
```python
from ssim_parser import SsimParser, expand_flights, filter_flights

parser = SsimParser()
data = parser.parse_file("schedule.ssim")
all_flights = expand_flights(data)

filtered = filter_flights(
    all_flights,
    start_date="2026-07-01",
    airlines=["UA", "AA"],
    exclude_arrival=["LAX"]
)
print(f"筛选后航班数: {len(filtered)}")
```

### 文档
字段定义请参考 [IATA SSIM 手册](https://www.iata.org/en/publications/manuals/standard-schedules-information/)。

### 贡献
欢迎提交 Pull Request。重大变更请先开 Issue 讨论。

### 许可证
Apache License 2.0
