arxml_sdk/README.md

# arxml_sdk

AUTOSAR ARXML 配置生成 SDK，提供用于创建 AUTOSAR 标准 ARXML 文件的 Python 接口。

**版本**: 2.0.1

## 目录

- [简介](#简介)
- [快速开始](#快速开始)
- [架构设计](#架构设计)
- [核心模块 (core)](#核心模块-core)
- [数据类型模块 (types)](#数据类型模块-types)
- [工具模块 (utils)](#工具模块-utils)
- [使用指南](#使用指南)
- [API 参考](#api-参考)
- [常见问题](#常见问题)

---

## 简介

arxml_sdk 是一个用于生成 AUTOSAR ARXML 配置文件的 Python SDK。它提供了完整的 AUTOSAR 数据类型建模能力，包括：

- 基础数据类型（SW-BASE-TYPE）
- 应用数据类型和实现数据类型
- 数据约束和计算方法
- 软件组件和端口定义
- 接口定义（发送-接收、客户端-服务端等）
- SWC 内部行为（Runnable、Event）

### 特性

- 纯 Python 实现，零外部依赖
- 符合 AUTOSAR R4.4 标准
- 工厂函数模式简化对象创建
- 组合模式支持动态构建
- 所有类型均支持 `to_arxml()` 序列化

---

## 快速开始

### 环境要求

- Python 3.8+

### 安装

将 `src` 目录添加到 Python 路径即可使用：

```python
import sys
sys.path.insert(0, '/path/to/arxml_sdk/src')
```

或直接使用相对导入：

```python
from src import create_arxml_document, write_arxml
```

### 最小示例

```python
from src import (
    create_arxml_document, write_arxml, create_package,
    create_base_type, Category, Encoding
)

doc = create_arxml_document()
base_type = create_base_type("UInt8", size=8, encoding=Encoding.TWO_COMPONENT)
package = create_package("MyPackage", elements=[base_type])
package_element = package.to_arxml(doc)
doc.documentElement.appendChild(package_element)
write_arxml(doc, "minimal.arxml")
```

---

## 架构设计

### 整体架构图

```
arxml_sdk/
├── src/                           # 源代码
│   ├── __init__.py               # 包入口，导出全部公共API
│   ├── core/                      # 核心基础设施层
│   │   ├── __init__.py
│   │   ├── base.py               # Base 基类
│   │   ├── constants.py          # ARXML 标签常量
│   │   └── enums.py              # AUTOSAR 枚举类型
│   ├── types/                     # 数据类型层
│   │   ├── __init__.py
│   │   ├── base_type.py          # 基础数据类型
│   │   ├── unit.py               # 单位类型
│   │   ├── data_constraint.py    # 数据约束
│   │   ├── compu_method.py       # 计算方法
│   │   ├── application_types.py # 应用数据类型
│   │   ├── implementation_types.py # 实现数据类型
│   │   ├── sw_addr_method.py     # 软件地址方法
│   │   ├── data_mapping.py       # 数据类型映射
│   │   ├── sw_component_type.py  # 软件组件类型
│   │   ├── interface.py          # 接口定义
│   │   ├── package.py            # 包管理
│   │   └── swc_internal_behavior.py # SWC内部行为
│   └── utils/                     # 工具层
│       ├── __init__.py
│       └── arxml_writer.py       # ARXML文档写入
└── tests/                         # 测试
```

### 模块职责

#### core 模块 - 核心基础设施层

提供 SDK 运行所需的基础组件，不依赖其他业务模块。

| 文件 | 职责 | 关键类/函数 |
|------|------|-------------|
| base.py | 定义所有类型的基础类 | `Base` (dataclass), `create_uuid()`, `create_text_element()` |
| constants.py | ARXML 标签常量统一管理 | 约140个XML标签常量定义 |
| enums.py | AUTOSAR 枚举类型定义 | `Category`, `Encoding`, `PortDirection` 等12个枚举 |

**Base 类核心属性：**

| 属性 | 类型 | 说明 |
|------|------|------|
| name | str | 元素名称 |
| id | Optional[int] | 元素标识符 |
| parent | Optional[Base] | 父元素引用 |
| description | Optional[str] | 元素描述 |
| package_path | str | 完整包路径 (如 `/Pkg1/Pkg2/Name`) |

**Base 类核心方法：**

| 方法 | 说明 |
|------|------|
| to_arxml(doc) | 抽象方法，将对象序列化为 ARXML DOM 元素 |
| class_name | 属性，获取类型名称 |
| parent_id | 属性，获取父类 ID |

#### types 模块 - 数据类型层

实现 AUTOSAR 数据模型的各个类型，依赖 core 模块。

| 文件 | 职责 | 主要类 |
|------|------|--------|
| base_type.py | 基础数据类型 (SW-BASE-TYPE) | `BaseType` |
| unit.py | 数据单位 | `Unit` |
| data_constraint.py | 数据约束范围 | `DataConstraint` |
| compu_method.py | 计算方法 (线性转换/文本表) | `Linear`, `TextTable`, `CompuMethod` |
| application_types.py | 应用层数据类型 | `ApplicationBooleanDataType`, `ApplicationValueDataType`, `ApplicationStructureDataType`, `ApplicationArrayDataType` |
| implementation_types.py | 实现层数据类型 | `ImplementationValueDataType`, `ImplementationStructureDataType`, `ImplementationArrayDataType` |
| sw_addr_method.py | 软件地址方法 | `SwAddrMethod` |
| data_mapping.py | 应用-实现类型映射 | `DataTypeMapping`, `DataTypeMappingSet` |
| sw_component_type.py | 软件组件类型和端口 | `ApplicationSwComponentType`, `RPortPrototype`, `PPortPrototype`, `PRPortPrototype` |
| interface.py | 接口定义 | `SenderReceiverInterface`, `ClientServerInterface`, `ModeSwitchInterface` |
| package.py | AUTOSAR 包 | `Package` |
| swc_internal_behavior.py | SWC 内部行为 | `RunnableEntity`, `TimingEvent`, `InitEvent`, `SwcInternalBehavior` |

#### utils 模块 - 工具层

提供 ARXML 文档创建和写入功能。

| 文件 | 职责 | 关键函数 |
|------|------|----------|
| arxml_writer.py | ARXML 文档创建和写入 | `create_arxml_document()`, `write_arxml()`, `write_arxml_pretty()` |

### 类型继承体系

```
Base (core.base)
├── BaseType (types.base_type)
├── Unit (types.unit)
├── DataConstraint (types.data_constraint)
├── CompuMethod (types.compu_method)
│   ├── Linear
│   └── TextTable
├── ApplicationDataType (types.application_types)
│   ├── ApplicationBooleanDataType
│   ├── ApplicationValueDataType
│   ├── ApplicationStructureDataType
│   │   └── StructureElement (内部类)
│   └── ApplicationArrayDataType
│       └── ArrayElement (内部类)
├── ImplementationDataType (types.implementation_types)
│   ├── ImplementationValueDataType
│   ├── ImplementationStructureDataType
│   │   └── StructureElement (内部类)
│   └── ImplementationArrayDataType
│       └── ArrayElement (内部类)
├── SwAddrMethod (types.sw_addr_method)
├── DataTypeMapping (types.data_mapping)
│   └── DataTypeMappingSet
├── SwComponentType (types.sw_component_type)
│   ├── AtomicComponentType
│   │   └── ApplicationSwComponentType
│   └── CompositionSwComponentType
├── PortPrototype (types.sw_component_type)
│   ├── RPortPrototype
│   ├── PPortPrototype
│   └── PRPortPrototype
├── Interface (types.interface)
│   ├── SenderReceiverInterface
│   │   └── DataElement (内部类)
│   ├── ClientServerInterface
│   │   ├── Operation (内部类)
│   │   └── Argument (内部类)
│   ├── ModeSwitchInterface
│   ├── ParameterInterface
│   ├── TriggerInterface
│   └── NvDataInterface
├── Package (types.package)
└── SwcInternalBehavior (types.swc_internal_behavior)
    ├── RunnableEntity
    └── EventType (Union)
        ├── InitEvent
        ├── TimingEvent
        ├── OperationInvokedEvent
        └── DataReceivedEvent
```

### 依赖关系图

```
                    ┌─────────────────────────────────────┐
                    │      arxml_sdk (src/__init__.py)     │
                    │   导出全部 193 个公共 API 符号        │
                    └─────────────────────────────────────┘
                                     │
         ┌───────────────────────────┼───────────────────────────┐
         │                           │                           │
         ▼                           ▼                           ▼
┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│   core 模块     │      │   types 模块    │      │   utils 模块    │
│   (基础设施层)  │      │   (业务逻辑层)  │      │   (工具层)      │
├─────────────────┤      ├─────────────────┤      ├─────────────────┤
│ Base 基类       │      │ 数据类型类      │      │ ARXML文档创建   │
│ 常量定义       │◄─────►│ 组件类型类      │      │ ARXML文件写入   │
│ 枚举定义       │      │ 接口定义类      │      │                 │
│ UUID/文本工具  │      │ 包管理类        │      │                 │
└─────────────────┘      │ 内部行为类      │      └─────────────────┘
                         └─────────────────┘
                                    │
                                    ▼
                         ┌─────────────────┐
                         │   tests 模块    │
                         │   (测试层)      │
                         ├─────────────────┤
                         │ 单元测试        │
                         │ 集成测试        │
                         └─────────────────┘
```

**依赖约束：**
- `core` → 无依赖（最底层）
- `types` → 依赖 `core`
- `utils` → 依赖 `core`
- `tests` → 依赖 `src` 所有模块

### 设计模式

#### 1. 工厂函数模式

所有类型都配有 `create_xxx()` 工厂函数，简化对象创建：

```python
# 使用工厂函数
uint8 = create_base_type("UInt8", size=8)

# 替代直接实例化（如果存在构造函数）
uint8 = BaseType(name="UInt8", size=8)
```

#### 2. 组合模式

通过 `add_xxx()` 方法支持动态添加子元素：

```python
component = ApplicationSwComponentType(name="Sensor")
component.add_port(PPortPrototype(name="DataPort"))
```

#### 3. 序列化模式

所有类型都实现 `to_arxml(doc)` 方法，将自身序列化为 ARXML DOM 元素：

```python
element = component.to_arxml(doc)
```

#### 4. 数据类模式

使用 `@dataclass` 简化数据类定义：

```python
@dataclass
class BaseType:
    name: str
    size: int
    category: Optional[Category] = None
    encoding: Optional[Encoding] = None
```

### 数据流

```
用户代码
    │
    ▼
创建对象 (工厂函数)
    │
    ├──► BaseType, ApplicationDataType, SwComponentType 等
    │
    ▼
序列化 (to_arxml)
    │
    ├──► XML DOM Element
    │
    ▼
写入文件 (arxml_writer)
    │
    ▼
.arxml 文件
```

### 技术栈

| 方面 | 详情 |
|------|------|
| 编程语言 | Python 3 |
| 标准库 | `uuid`, `xml.dom.minidom`, `dataclasses`, `typing`, `enum` |
| 测试框架 | pytest |
| 目标格式 | AUTOSAR ARXML (R4.4 schema) |
| 版本 | 2.0.1 |

---

## 核心模块 (core)

### Base 类

所有类型的基类，提供通用的属性和方法。

**文件位置：** `src/core/base.py`

```python
from src.core.base import Base
```

#### 属性

| 属性名 | 类型 | 说明 |
|--------|------|------|
| `name` | str | 元素名称 |
| `id` | Optional[int] | 元素标识符 |
| `parent` | Optional[Base] | 父元素引用 |
| `description` | Optional[str] | 元素描述 |

#### 只读属性

| 属性名 | 类型 | 说明 |
|--------|------|------|
| `class_name` | str | 获取类型名称 (如 "ApplicationValueDataType") |
| `parent_id` | Optional[int] | 获取父类的 id |
| `package_path` | str | 获取完整包路径 (如 "/Package/SubPackage/Name") |

#### 方法

##### `to_arxml(doc: Document) -> Element`

将对象序列化为 ARXML DOM 元素。**必须被子类重写。**

**参数：**
- `doc`: XML Document 对象

**返回：**
- ARXML DOM Element

---

### 公共函数

#### `create_uuid() -> str`

生成一个 UUID 字符串。

```python
from src.core.base import create_uuid

uuid = create_uuid()  # e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
```

#### `create_text_element(doc: Document, tag: str, text: str) -> Element`

创建带有文本内容的 XML 元素。

**参数：**
- `doc`: XML Document 对象
- `tag`: XML 标签名
- `text`: 元素文本内容

**返回：**
- XML Element

**示例：**

```python
from src.core.base import create_text_element
from src.utils import create_arxml_document

doc = create_arxml_document()
element = create_text_element(doc, "SHORT-NAME", "MyElement")
```

---

### 枚举类型

#### Category

数据类型分类枚举。

**文件位置：** `src/core/enums.py`

```python
from src import Category
```

| 枚举值 | 说明 |
|--------|------|
| `FIXED_LENGTH` | 固定长度 |
| `IDENTICAL` | 相同 |
| `TEXT_TABLE` | 文本表 |
| `LINEAR` | 线性 |
| `BOOLEAN` | 布尔 |
| `VALUE` | 值类型 |
| `STRUCTURE` | 结构体 |
| `ARRAY` | 数组 |
| `SCALE_LINEAR` | 缩放线性 |
| `RECORD` | 记录 |
| `UNION` | 联合 |
| `DATA_REFERENCE` | 数据引用 |
| `TYPE_REFERENCE` | 类型引用 |

#### Encoding

数据编码格式枚举。

```python
from src import Encoding
```

| 枚举值 | 说明 |
|--------|------|
| `ONE_COMPONENT` | 单组件 |
| `TWO_COMPONENT` | 双组件 |
| `BCD_P` | BCD Plus |
| `BCD_UP` | BCD Up |
| `IEEE754` | IEEE754 浮点数 |
| `ISO_8859_1` | ISO-8859-1 编码 |
| `UTF_8` | UTF-8 编码 |
| `UCS_2` | UCS-2 编码 |
| `NONE` | 无编码 |
| `VOID` | Void |
| `BOOLEAN` | 布尔 |
| `UTF_16` | UTF-16 编码 |

#### CalibrationAccess

校准访问权限枚举。

```python
from src import CalibrationAccess
```

| 枚举值 | 说明 |
|--------|------|
| `READ_ONLY` | 只读 |
| `NOT_ACCESSIBLE` | 不可访问 |
| `READ_WRITE` | 读写 |
| `NOT_SPECIFIED` | 未指定 |

#### SwCalibrationAccess

校准访问权限枚举（向后兼容版本）。

```python
from src import SwCalibrationAccess
```

| 枚举值 | 说明 |
|--------|------|
| `ReadOnly` | 只读 |
| `NotAccessible` | 不可访问 |
| `ReadWrite` | 读写 |
| `NotSpecified` | 未指定 |

#### UpperSts / LowerSts

上下限区间状态枚举。

```python
from src import UpperSts, LowerSts
```

| 枚举值 | 说明 |
|--------|------|
| `CLOSED` | 闭区间 |
| `OPEN` | 开区间 |

#### ConstraintSpecified

约束指定类型枚举。

```python
from src import ConstraintSpecified
```

| 枚举值 | 说明 |
|--------|------|
| `PHYSICAL` | 物理值约束 |
| `INTERNAL` | 内部值约束 |

#### CompuContents

转换内容方向枚举。

```python
from src import CompuContents
```

| 枚举值 | 说明 |
|--------|------|
| `USE_INTERNAL_TO_PHYSICAL` | 使用内部到物理的转换 |
| `USE_PHYSICAL_TO_INTERNAL` | 使用物理到内部的转换 |

#### ComponentType

组件类型枚举。

```python
from src import ComponentType
```

| 枚举值 | 说明 |
|--------|------|
| `COMPOSITION` | 组合组件 |
| `ATOMIC` | 原子组件 |

#### AtomicType

原子组件类型枚举。

```python
from src import AtomicType
```

| 枚举值 | 说明 |
|--------|------|
| `APPLICATION` | 应用组件 |
| `SENSOR_ACTUATOR` | 传感器/执行器组件 |
| `HARDWARE_ABSTRACTION` | 硬件抽象组件 |
| `COMPLEX_DRIVER` | 复杂驱动组件 |
| `SERVICE_PROXY` | 服务代理组件 |

#### ImplementationCodeType

实现代码类型枚举。

```python
from src import ImplementationCodeType
```

| 枚举值 | 说明 |
|--------|------|
| `SOURCE_CODE` | 源代码 |
| `OBJECT_CODE` | 目标代码 |

#### AccessPoint

访问点枚举。

```python
from src import AccessPoint
```

| 枚举值 | 说明 |
|--------|------|
| `READ` | 读取 |
| `WRITE` | 写入 |

#### PortDirection

端口方向枚举。

```python
from src import PortDirection
```

| 枚举值 | 说明 |
|--------|------|
| `IN` | 输入端口 |
| `OUT` | 输出端口 |

#### Semantic

数组大小语义枚举。

```python
from src import Semantic
```

| 枚举值 | 说明 |
|--------|------|
| `FIXED` | 固定大小 |
| `VARIABLE` | 可变大小 |

#### SectionType

段类型枚举。

```python
from src import SectionType
```

| 枚举值 | 说明 |
|--------|------|
| `CODE` | 代码段 |
| `DATA` | 数据段 |
| `CONST` | 常量段 |

#### Policy

数据策略枚举。

```python
from src import Policy
```

| 枚举值 | 说明 |
|--------|------|
| `STANDARD` | 标准策略 |
| `EXTENDED` | 扩展策略 |

---

## 数据类型模块 (types)

### BaseType

基础数据类型，表示最底层的原生类型定义。

**文件位置：** `src/types/base_type.py`

```python
from src import BaseType, create_base_type
```

#### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 类型名称 |
| `size` | int | 是 | 位大小 (如 8, 16, 32) |
| `category` | Optional[Category] | 否 | 分类类型 |
| `encoding` | Optional[Encoding] | 否 | 编码格式 |
| `native_description` | Optional[str] | 否 | 原生描述 |

#### 工厂函数

##### `create_base_type(name: str, size: int, category: Optional[Category] = None, encoding: Optional[Encoding] = None, native_description: Optional[str] = None) -> BaseType`

创建 BaseType 实例的工厂函数。

**示例：**

```python
# 创建 8 位无符号整数类型
uint8 = create_base_type(
    name="UInt8",
    size=8,
    category=Category.FIXED_LENGTH,
    encoding=Encoding.TWO_COMPONENT
)
```

---

### Unit

数据单位，用于物理量的表示。

**文件位置：** `src/types/unit.py`

```python
from src import Unit, create_unit
```

#### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 单位名称 |
| `display` | Optional[str] | 否 | 显示名称 |
| `factor` | Optional[float] | 否 | 因子 |
| `offset` | Optional[float] | 否 | 偏移量 |

#### 工厂函数

##### `create_unit(name: str, display: Optional[str] = None, factor: Optional[float] = None, offset: Optional[float] = None) -> Unit`

创建 Unit 实例的工厂函数。

**示例：**

```python
unit = create_unit(
    name="km_per_hour",
    display="km/h",
    factor=1.0,
    offset=0.0
)
```

---

### DataConstraint

数据约束，定义有效值范围。

**文件位置：** `src/types/data_constraint.py`

```python
from src import DataConstraint, create_data_constraint
```

#### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 约束名称 |
| `unit` | Optional[Unit] | 否 | 关联的单位 |
| `lower` | Optional[float] | 否 | 下限值 |
| `upper` | Optional[float] | 否 | 上限值 |
| `lower_sts` | Optional[LowerSts] | 否 | 下限状态 (CLOSED/OPEN) |
| `upper_sts` | Optional[UpperSts] | 否 | 上限状态 (CLOSED/OPEN) |
| `constraint_specified` | Optional[ConstraintSpecified] | 否 | 约束类型 |

#### 工厂函数

##### `create_data_constraint(name: str, lower: Optional[float] = None, upper: Optional[float] = None, unit: Optional[Unit] = None, lower_sts: Optional[LowerSts] = None, upper_sts: Optional[UpperSts] = None, constraint_specified: Optional[ConstraintSpecified] = None) -> DataConstraint`

创建 DataConstraint 实例的工厂函数。

**示例：**

```python
constraint = create_data_constraint(
    name="SpeedConstraint",
    lower=0,
    upper=250,
    lower_sts=LowerSts.CLOSED,
    upper_sts=UpperSts.OPEN
)
```

---

### CompuMethod

计算方法，定义内部值与物理值之间的转换关系。

**文件位置：** `src/types/compu_method.py`

```python
from src import CompuMethod, Linear, TextTable, create_linear, create_text_table, create_compu_method
```

#### Linear 类

线性转换方法。

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `factor` | float | 是 | 缩放因子 |
| `offset` | float | 是 | 偏移量 |

转换公式：`physical = factor * internal + offset`

##### 工厂函数

`create_linear(factor: float, offset: float) -> Linear`

#### TextTable 类

文本表转换方法。

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `vt` | str | 是 | 文本值 |
| `lower` | Optional[int] | 否 | 下限 |
| `upper` | Optional[int] | 否 | 上限 |
| `lower_sts` | Optional[LowerSts] | 否 | 下限状态 |
| `upper_sts` | Optional[UpperSts] | 否 | 上限状态 |

##### 工厂函数

`create_text_table(vt: str, lower: Optional[int] = None, upper: Optional[int] = None, lower_sts: Optional[LowerSts] = None, upper_sts: Optional[UpperSts] = None) -> TextTable`

#### CompuMethod 类

完整的计算方法。

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 方法名称 |
| `unit` | Optional[Unit] | 否 | 单位 |
| `linear` | Optional[Linear] | 否 | 线性转换 |
| `text_tables` | Optional[List[TextTable]] | 否 | 文本表列表 |
| `category` | Optional[Category] | 否 | 分类 |
| `compu_contents` | Optional[CompuContents] | 否 | 转换内容方向 |

##### 方法

| 方法 | 说明 |
|------|------|
| `get_text_table(vt: str) -> Optional[TextTable]` | 根据文本值查找文本表 |
| `add_text_table(text_table: TextTable)` | 添加文本表 |

##### 工厂函数

`create_compu_method(name: str, unit: Optional[Unit] = None, linear: Optional[Linear] = None, text_tables: Optional[List[TextTable]] = None, category: Optional[Category] = None, compu_contents: Optional[CompuContents] = None) -> CompuMethod`

**示例：**

```python
# 创建带线性转换的计算方法
linear = create_linear(factor=0.01, offset=0)
compu = create_compu_method(
    name="SpeedConversion",
    linear=linear,
    category=Category.LINEAR
)

# 创建带文本表的计算方法
table = create_text_table(vt="OK", lower=0, upper=0)
compu = create_compu_method(
    name="StatusConversion",
    text_tables=[table],
    category=Category.TEXT_TABLE
)
```

---

### 应用数据类型

#### ApplicationBooleanDataType

布尔类型应用数据。

**文件位置：** `src/types/application_types.py`

```python
from src import ApplicationBooleanDataType, create_boolean_type
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 类型名称 |
| `compu_method` | Optional[CompuMethod] | 否 | 计算方法 |
| `data_constraint` | Optional[DataConstraint] | 否 | 数据约束 |

##### 工厂函数

`create_boolean_type(name: str, compu_method: Optional[CompuMethod] = None, data_constraint: Optional[DataConstraint] = None) -> ApplicationBooleanDataType`

---

#### ApplicationValueDataType

标量值类型应用数据。

```python
from src import ApplicationValueDataType, create_value_type
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 类型名称 |
| `unit` | Optional[Unit] | 否 | 单位 |
| `compu_method` | Optional[CompuMethod] | 否 | 计算方法 |
| `data_constraint` | Optional[DataConstraint] | 否 | 数据约束 |

##### 工厂函数

`create_value_type(name: str, unit: Optional[Unit] = None, compu_method: Optional[CompuMethod] = None, data_constraint: Optional[DataConstraint] = None) -> ApplicationValueDataType`

---

#### ApplicationStructureDataType

结构体类型应用数据。

```python
from src import ApplicationStructureDataType, create_structure_type
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 类型名称 |
| `structure_elements` | Optional[List[StructureElement]] | 否 | 结构体成员列表 |

##### 嵌套类：StructureElement

结构体成员元素。

**构造函数属性：**

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 成员名称 |
| `data_type` | Base | 是 | 数据类型 |
| `offset` | Optional[int] | 否 | 位偏移 |

##### 方法

| 方法 | 说明 |
|------|------|
| `get_element(name: str) -> Optional[StructureElement]` | 查找成员 |
| `add_element(element: StructureElement)` | 添加成员 |

##### 工厂函数

`create_structure_type(name: str, elements: Optional[List[ApplicationStructureDataType.StructureElement]] = None) -> ApplicationStructureDataType`

---

#### ApplicationArrayDataType

数组类型应用数据。

```python
from src import ApplicationArrayDataType, create_array_type
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 类型名称 |
| `element` | Optional[ArrayElement] | 否 | 数组元素 |

##### 嵌套类：ArrayElement

数组元素配置。

**构造函数属性：**

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `length` | int | 是 | 数组长度 |
| `data_type` | Base | 是 | 元素数据类型 |
| `array_size_semantics` | Optional[Semantic] | 否 | 大小语义 |

##### 工厂函数

`create_array_type(name: str, element: Optional[ApplicationArrayDataType.ArrayElement] = None) -> ApplicationArrayDataType`

---

### 实现数据类型

#### ImplementationValueDataType

实现层标量值类型。

**文件位置：** `src/types/implementation_types.py`

```python
from src import ImplementationValueDataType, create_impl_value_type
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 类型名称 |
| `base_type` | Optional[BaseType] | 否 | 基础类型 |
| `compu_method` | Optional[CompuMethod] | 否 | 计算方法 |
| `data_constraint` | Optional[DataConstraint] | 否 | 数据约束 |

##### 工厂函数

`create_impl_value_type(name: str, base_type: Optional[BaseType] = None, compu_method: Optional[CompuMethod] = None, data_constraint: Optional[DataConstraint] = None) -> ImplementationValueDataType`

---

#### ImplementationStructureDataType

实现层结构体类型。

```python
from src import ImplementationStructureDataType, create_impl_structure_type
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 类型名称 |
| `structure_elements` | Optional[List[StructureElement]] | 否 | 结构体成员列表 |

##### 嵌套类：StructureElement

与 ApplicationStructureDataType.StructureElement 结构相同。

##### 工厂函数

`create_impl_structure_type(name: str, elements: Optional[List[ImplementationStructureDataType.StructureElement]] = None) -> ImplementationStructureDataType`

---

#### ImplementationArrayDataType

实现层数组类型。

```python
from src import ImplementationArrayDataType, create_impl_array_type
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 类型名称 |
| `element` | Optional[ArrayElement] | 否 | 数组元素 |

##### 嵌套类：ArrayElement

与 ApplicationArrayDataType.ArrayElement 结构相同。

##### 工厂函数

`create_impl_array_type(name: str, element: Optional[ImplementationArrayDataType.ArrayElement] = None) -> ImplementationArrayDataType`

---

### SwAddrMethod

软件地址方法，定义代码/数据的内存段。

**文件位置：** `src/types/sw_addr_method.py`

```python
from src import SwAddrMethod, create_sw_addr_method, SectionType
```

#### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 方法名称 |
| `section_type` | Optional[SectionType] | 否 | 段类型 (CODE/DATA/CONST) |

#### 工厂函数

`create_sw_addr_method(name: str, section_type: Optional[SectionType] = None) -> SwAddrMethod`

**示例：**

```python
# 代码段地址方法
code_method = create_sw_addr_method("CODE", section_type=SectionType.CODE)

# 数据段地址方法
data_method = create_sw_addr_method("DATA", section_type=SectionType.DATA)
```

---

### 数据类型映射

#### DataTypeMapping

应用类型到实现类型的映射。

**文件位置：** `src/types/data_mapping.py`

```python
from src import DataTypeMapping, create_data_type_mapping
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 映射名称 |
| `application_data_type` | Base | 是 | 应用数据类型 |
| `implementation_data_type` | Base | 是 | 实现数据类型 |

##### 工厂函数

`create_data_type_mapping(name: str, application_data_type: Base, implementation_data_type: Base) -> DataTypeMapping`

---

#### DataTypeMappingSet

数据类型映射集合。

```python
from src import DataTypeMappingSet, create_data_type_mapping_set
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 集合名称 |
| `data_type_mappings` | Optional[List[DataTypeMapping]] | 否 | 映射列表 |

##### 方法

| 方法 | 说明 |
|------|------|
| `get_mapping(name: str) -> Optional[DataTypeMapping]` | 查找映射 |
| `add_mapping(mapping: DataTypeMapping)` | 添加映射 |

##### 工厂函数

`create_data_type_mapping_set(name: str, mappings: Optional[List[DataTypeMapping]] = None) -> DataTypeMappingSet`

---

### 接口

#### Interface

接口基类。

**文件位置：** `src/types/interface.py`

```python
from src import Interface
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 接口名称 |
| `is_service` | bool | 否 | 是否为服务接口 (默认 False) |

---

#### SenderReceiverInterface

发送-接收接口，用于数据信号传递。

```python
from src import SenderReceiverInterface, create_sender_receiver_interface, Policy, CalibrationAccess
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 接口名称 |
| `data_element` | Optional[SenderReceiverInterface.DataElement] | 否 | 数据元素 |
| `is_service` | bool | 否 | 是否为服务接口 |

##### 嵌套类：DataElement

数据元素定义。

**构造函数属性：**

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 元素名称 |
| `sw_addr_method` | Optional[SwAddrMethod] | 否 | 地址方法 |
| `data_constraint` | Optional[DataConstraint] | 否 | 数据约束 |
| `data_type` | Base | 是 | 数据类型 |
| `policy` | Optional[Policy] | 否 | 数据策略 |
| `calibration_access` | Optional[CalibrationAccess] | 否 | 校准访问权限 |

##### 工厂函数

`create_sender_receiver_interface(name: str, data_element: Optional[SenderReceiverInterface.DataElement] = None, is_service: bool = False) -> SenderReceiverInterface`

---

#### ClientServerInterface

客户端-服务端接口，用于服务调用。

```python
from src import ClientServerInterface
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 接口名称 |
| `operations` | Optional[List[Operation]] | 否 | 操作列表 |
| `is_service` | bool | 否 | 是否为服务接口 |

##### 嵌套类：Operation

服务操作定义。

**构造函数属性：**

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 操作名称 |
| `is_server` | bool | 否 | 是否为服务端 |
| `arguments` | Optional[List[Argument]] | 否 | 参数列表 |

##### 嵌套类：Argument

操作参数定义。

**构造函数属性：**

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 参数名称 |
| `direction` | PortDirection | 是 | 参数方向 (IN/OUT) |
| `data_type` | Base | 是 | 参数数据类型 |

##### 方法

| 方法 | 说明 |
|------|------|
| `get_operation(name: str) -> Optional[Operation]` | 查找操作 |
| `add_operation(operation: Operation)` | 添加操作 |

---

### 软件组件类型

#### SwComponentType

软件组件类型基类。

**文件位置：** `src/types/sw_component_type.py`

```python
from src import SwComponentType, ComponentType
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 组件名称 |
| `component_type` | Optional[ComponentType] | 否 | 组件类型 |

---

#### ApplicationSwComponentType

应用软件组件类型。

```python
from src import ApplicationSwComponentType
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 组件名称 |
| `supports_multiple_instantiation` | bool | 否 | 是否支持多实例化 |
| `atomic_type` | Optional[AtomicType] | 否 | 原子类型 |
| `implementation_code_type` | Optional[ImplementationCodeType] | 否 | 实现代码类型 |
| `ports` | Optional[List[PortPrototype]] | 否 | 端口列表 |
| `internal_behavior` | Optional[SwcInternalBehavior] | 否 | 内部行为 |

##### 方法

| 方法 | 说明 |
|------|------|
| `get_port(name: str) -> Optional[PortPrototype]` | 查找端口 |
| `add_port(port: PortPrototype)` | 添加端口 |

---

#### PortPrototype

端口原型基类。

```python
from src import PortPrototype, PortDirection
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 端口名称 |
| `interface` | Optional[Interface] | 否 | 关联接口 |

---

#### RPortPrototype

接收端口 (Required Port)。

```python
from src import RPortPrototype
```

继承自 PortPrototype，用于从其他组件接收数据。

---

#### PPortPrototype

发送端口 (Provided Port)。

```python
from src import PPortPrototype
```

继承自 PortPrototype，用于向其他组件发送数据。

---

#### PRPortPrototype

双向端口 (Provided Required Port)。

```python
from src import PRPortPrototype
```

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 端口名称 |
| `interface` | Optional[Interface] | 否 | 提供接口 |
| `required_interface` | Optional[Interface] | 否 | 需求接口 |

---

### Package

AUTOSAR 包，用于组织和管理元素。

**文件位置：** `src/types/package.py`

```python
from src import Package, create_package
```

#### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 包名称 |
| `elements` | Optional[List[Base]] | 否 | 包内元素列表 |

#### 方法

| 方法 | 说明 |
|------|------|
| `get_element(name: str) -> Optional[Base]` | 查找元素 |
| `add_element(element: Base)` | 添加元素 (支持覆盖同名元素) |

#### 工厂函数

`create_package(name: str, elements: Optional[List[Base]] = None) -> Package`

**示例：**

```python
# 创建包并添加元素
pkg = create_package("SensorPkg", elements=[
    base_type,
    impl_type,
    interface,
    component
])
```

---

### SwcInternalBehavior

软件组件内部行为。

**文件位置：** `src/types/swc_internal_behavior.py`

```python
from src import SwcInternalBehavior, RunnableEntity, create_runnable_entity, create_timing_event, create_init_event
```

#### VariableAccess

变量访问定义。

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 访问名称 |
| `port_prototype_ref` | Optional[str] | 否 | 端口原型引用 |
| `target_data_prototype_ref` | Optional[str] | 否 | 目标数据原型引用 |

---

#### RunnableEntity

可运行实体 (Runnable)。

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | Runnable 名称 |
| `minimum_start_interval` | Optional[float] | 否 | 最小启动间隔 (秒) |
| `can_be_invoked_concurrently` | bool | 否 | 是否可并发调用 |
| `data_receive_points` | Optional[List[VariableAccess]] | 否 | 数据接收点 |
| `data_send_points` | Optional[List[VariableAccess]] | 否 | 数据发送点 |
| `variable_accesses` | Optional[List[VariableAccess]] | 否 | 变量访问列表 |
| `symbol` | Optional[str] | 否 | 符号 (函数名) |
| `sw_addr_method_ref` | Optional[SwAddrMethod] | 否 | 地址方法引用 |

##### 方法

| 方法 | 说明 |
|------|------|
| `add_data_receive_point(access: VariableAccess)` | 添加数据接收点 |
| `add_data_send_point(access: VariableAccess)` | 添加数据发送点 |
| `add_variable_access(access: VariableAccess)` | 添加变量访问 |

##### 工厂函数

`create_runnable_entity(name: str, symbol: Optional[str] = None, minimum_start_interval: Optional[float] = None) -> RunnableEntity`

---

#### 事件类型

##### InitEvent

初始化事件。

```python
from src import InitEvent

event = InitEvent(name="Init", runnable_ref="MyRunnable")
```

##### TimingEvent

定时事件。

```python
from src import TimingEvent, create_timing_event

event = create_timing_event(name="Timing_10ms", period=0.01)
```

**构造函数属性：**

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 事件名称 |
| `period` | float | 是 | 周期 (秒) |

##### OperationInvokedEvent

操作调用事件。

```python
from src import OperationInvokedEvent, create_operation_invoked_event

event = create_operation_invoked_event(name="OpInvoke", operation_ref="MyOperation")
```

##### DataReceivedEvent

数据接收事件。

```python
from src import DataReceivedEvent, create_data_received_event

event = create_data_received_event(name="DataRx", data_element_ref="MyDataElement", period=0.01)
```

---

#### SwcInternalBehavior

软件组件内部行为容器。

##### 构造函数属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | str | 是 | 行为名称 |
| `runnable_entities` | Optional[List[RunnableEntity]] | 否 | Runnable 列表 |
| `events` | Optional[List[Union[InitEvent, TimingEvent, OperationInvokedEvent, DataReceivedEvent]]] | 否 | 事件列表 |
| `symbol` | Optional[str] | 否 | 符号前缀 |

##### 方法

| 方法 | 说明 |
|------|------|
| `get_runnable(name: str) -> Optional[RunnableEntity]` | 查找 Runnable |
| `add_runnable(runnable: RunnableEntity)` | 添加 Runnable |
| `get_event(name: str) -> Optional[Event]` | 查找事件 |
| `add_event(event: Event)` | 添加事件 |

##### 工厂函数

`create_swc_internal_behavior(name: str, runnable_entities: Optional[List[RunnableEntity]] = None, events: Optional[List[Event]] = None) -> SwcInternalBehavior`

---

## 工具模块 (utils)

### create_arxml_document() -> Document

创建标准 ARXML 文档，包含 AUTOSAR 命名空间。

**文件位置：** `src/utils/arxml_writer.py`

```python
from src import create_arxml_document

doc = create_arxml_document()
```

**返回：**
- xml.dom.minidom.Document 对象

---

### write_arxml(doc: Document, filepath: str, encoding: str = 'utf-8') -> None

将 Document 写入文件 (紧凑格式)。

```python
from src import create_arxml_document, write_arxml

doc = create_arxml_document()
# ... 添加内容 ...
write_arxml(doc, "output.arxml")
```

---

### write_arxml_pretty(doc: Document, filepath: str, encoding: str = 'utf-8') -> None

将 Document 写入文件 (格式化输出)。

```python
from src import create_arxml_document, write_arxml_pretty

doc = create_arxml_document()
# ... 添加内容 ...
write_arxml_pretty(doc, "output_formatted.arxml")
```

---

### get_ar_packages_element(doc: Document) -> Element

获取 AR-PACKAGES 根元素。

```python
from src import get_ar_packages_element

doc = create_arxml_document()
packages = get_ar_packages_element(doc)
```

---

### add_package_to_document(doc: Document, package_element: Element) -> None

将 Package 元素添加到文档。

```python
from src import add_package_to_document

pkg_element = package.to_arxml(doc)
add_package_to_document(doc, pkg_element)
```

---

## 使用指南

### 基础类型创建

#### 创建基本整数类型

```python
from src import create_base_type, Category, Encoding

uint8 = create_base_type("UInt8", size=8, encoding=Encoding.TWO_COMPONENT)
uint16 = create_base_type("UInt16", size=16, encoding=Encoding.TWO_COMPONENT)
sint8 = create_base_type("Sint8", size=8, encoding=Encoding.TWO_COMPONENT)
float32 = create_base_type("Float32", size=32, encoding=Encoding.IEEE754)
```

#### 创建带文本表的类型

```python
from src import (
    create_base_type, create_unit, create_data_constraint,
    create_linear, create_text_table, create_compu_method,
    Category, LowerSts, UpperSts
)

unit = create_unit("km/h", display="km/h", factor=1.0, offset=0.0)

constraint = create_data_constraint(
    "SpeedConstraint",
    lower=0, upper=250,
    lower_sts=LowerSts.CLOSED,
    upper_sts=UpperSts.OPEN
)

linear = create_linear(factor=0.01, offset=0)

compu = create_compu_method(
    "SpeedConversion",
    unit=unit,
    linear=linear,
    category=Category.LINEAR
)

value_type = create_value_type(
    "Speed",
    unit=unit,
    compu_method=compu,
    data_constraint=constraint
)
```

---

### 应用数据类型

#### 布尔类型

```python
from src import create_boolean_type, create_compu_method, create_linear, Category

bool_compu = create_compu_method(
    "BoolConversion",
    linear=create_linear(factor=1, offset=0),
    category=Category.BOOLEAN
)

bool_type = create_boolean_type("ErrorFlag", compu_method=bool_compu)
```

#### 值类型

```python
from src import create_value_type, create_unit, create_linear, create_compu_method, Category

unit = create_unit("deg", display="°C")
linear = create_linear(factor=0.1, offset=-40)
compu = create_compu_method("Temperature", unit=unit, linear=linear, category=Category.LINEAR)

temp_type = create_value_type("Temperature", unit=unit, compu_method=compu)
```

#### 结构体类型

```python
from src import (
    ApplicationStructureDataType, create_value_type,
    create_unit, create_linear, create_compu_method
)

unit = create_unit("V")
linear = create_linear(factor=0.001, offset=0)
compu = create_compu_method("Voltage", unit=unit, linear=linear, category=Category.LINEAR)
voltage_type = create_value_type("Voltage", unit=unit, compu_method=compu)

current_type = create_value_type("Current", unit=unit, compu_method=compu)

structure = ApplicationStructureDataType(name="PowerData")
structure.add_element(
    ApplicationStructureDataType.StructureElement(name="voltage", data_type=voltage_type, offset=0)
)
structure.add_element(
    ApplicationStructureDataType.StructureElement(name="current", data_type=current_type, offset=32)
)
```

#### 数组类型

```python
from src import ApplicationArrayDataType, create_value_type, create_unit, Semantic

element_type = create_value_type("SensorValue", unit=create_unit("counts"))

array_type = ApplicationArrayDataType(name="SensorData")
array_type.element = ApplicationArrayDataType.ArrayElement(
    length=10,
    data_type=element_type,
    array_size_semantics=Semantic.FIXED
)
```

---

### 实现数据类型

#### 值类型

```python
from src import create_impl_value_type, create_base_type, create_value_type, Encoding

base_type = create_base_type("UInt16", size=16, encoding=Encoding.TWO_COMPONENT)
app_type = create_value_type("AppCounter")

impl_type = create_impl_value_type("ImplCounter", base_type=base_type)
```

#### 结构体类型

```python
from src import ImplementationStructureDataType, create_impl_value_type, create_base_type, Encoding

base_u8 = create_base_type("UInt8", size=8, encoding=Encoding.TWO_COMPONENT)
base_u16 = create_base_type("UInt16", size=16, encoding=Encoding.TWO_COMPONENT)

impl_u8 = create_impl_value_type("ImplUInt8", base_type=base_u8)
impl_u16 = create_impl_value_type("ImplUInt16", base_type=base_u16)

struct_type = ImplementationStructureDataType(name="ImplStatus")
struct_type.add_element(
    ImplementationStructureDataType.StructureElement(name="status", data_type=impl_u8, offset=0)
)
struct_type.add_element(
    ImplementationStructureDataType.StructureElement(name="value", data_type=impl_u16, offset=8)
)
```

#### 数组类型

```python
from src import ImplementationArrayDataType, create_impl_value_type, create_base_type, Semantic, Encoding

base = create_base_type("UInt32", size=32, encoding=Encoding.TWO_COMPONENT)
element_type = create_impl_value_type("ImplUInt32", base_type=base)

impl_array = ImplementationArrayDataType(name="ImplBuffer")
impl_array.element = ImplementationArrayDataType.ArrayElement(
    length=16,
    data_type=element_type,
    array_size_semantics=Semantic.FIXED
)
```

---

### 数据类型映射

```python
from src import (
    DataTypeMapping, DataTypeMappingSet,
    create_value_type, create_impl_value_type, create_base_type, Encoding
)

base = create_base_type("UInt8", size=8, encoding=Encoding.TWO_COMPONENT)
app_type = create_value_type("AppStatus")
impl_type = create_impl_value_type("ImplStatus", base_type=base)

mapping = DataTypeMapping(
    name="StatusMapping",
    application_data_type=app_type,
    implementation_data_type=impl_type
)

mapping_set = DataTypeMappingSet(name="DefaultMappings")
mapping_set.add_mapping(mapping)
```

---

### 接口定义

#### 发送-接收接口

```python
from src import (
    SenderReceiverInterface, create_sender_receiver_interface,
    create_value_type, create_unit, Policy, CalibrationAccess
)

unit = create_unit("km/h")
data_element = SenderReceiverInterface.DataElement(
    name="Speed",
    data_type=create_value_type("Speed", unit=unit),
    policy=Policy.STANDARD,
    calibration_access=CalibrationAccess.READ_ONLY
)

interface = create_sender_receiver_interface("SpeedInterface", data_element=data_element)
```

#### 客户端-服务端接口

```python
from src import (
    ClientServerInterface, create_value_type, create_unit,
    PortDirection
)

unit = create_unit("counts")

operation = ClientServerInterface.Operation(
    name="Initialize",
    is_server=True,
    arguments=[
        ClientServerInterface.Argument(
            name="config",
            direction=PortDirection.IN,
            data_type=create_value_type("Config", unit=unit)
        )
    ]
)

cs_interface = ClientServerInterface(name="ControlInterface")
cs_interface.add_operation(operation)
```

---

### 软件组件

#### 创建组件

```python
from src import (
    ApplicationSwComponentType, PPortPrototype, RPortPrototype,
    SenderReceiverInterface, create_sender_receiver_interface,
    AtomicType, ComponentType
)

interface = create_sender_receiver_interface("DataInterface")
port = PPortPrototype(name="DataPort", interface=interface)

component = ApplicationSwComponentType(
    name="SensorComponent",
    supports_multiple_instantiation=False,
    atomic_type=AtomicType.APPLICATION
)
component.add_port(port)
```

#### 创建组合组件

```python
from src import SwComponentType, ComponentType, AtomicComponentType, CompositionSwComponentType

child1 = ApplicationSwComponentType(name="Child1")
child2 = ApplicationSwComponentType(name="Child2")

composition = CompositionSwComponentType(name="Composition")
composition._component_type = ComponentType.COMPOSITION
```

---

### 内部行为

#### 创建 Runnable 和事件

```python
from src import (
    SwcInternalBehavior, RunnableEntity, TimingEvent, InitEvent,
    VariableAccess, create_swc_internal_behavior, create_runnable_entity,
    create_timing_event, create_init_event, create_data_received_event
)

runnable = create_runnable_entity(
    name="UpdateMeasurement",
    symbol="UpdateMeasurement",
    minimum_start_interval=0.01
)
runnable.add_variable_access(
    VariableAccess(name="SpeedAccess", port_prototype_ref="SpeedPort")
)

timing_event = create_timing_event(name="Timing_10ms", period=0.01)
init_event = InitEvent(name="Init", runnable_ref="UpdateMeasurement")

data_rx_event = create_data_received_event(
    name="DataReady",
    data_element_ref="ReadyFlag",
    period=0.05
)

behavior = create_swc_internal_behavior(
    name="SensorBehavior",
    runnable_entities=[runnable],
    events=[timing_event, init_event, data_rx_event]
)

component = ApplicationSwComponentType(name="Sensor")
component.internal_behavior = behavior
```

---

### 打包与导出

#### 基本导出流程

```python
from src import (
    create_arxml_document, write_arxml, create_package,
    get_ar_packages_element, add_package_to_document,
    create_base_type, create_value_type, create_unit
)

doc = create_arxml_document()
packages_element = get_ar_packages_element(doc)

base_type = create_base_type("UInt8", size=8)
app_type = create_value_type("AppData")
package = create_package("MyPkg", elements=[base_type, app_type])

package_element = package.to_arxml(doc)
add_package_to_document(doc, package_element)

write_arxml(doc, "output.arxml")
```

#### 格式化输出

```python
from src import write_arxml_pretty

write_arxml_pretty(doc, "output_formatted.arxml")
```

---

### 完整示例

以下示例创建一个完整的 AUTOSAR 软件组件配置：

```python
from src import (
    create_arxml_document, write_arxml_pretty, create_package,
    get_ar_packages_element, add_package_to_document,
    create_base_type, create_unit, create_linear, create_compu_method,
    create_value_type, create_impl_value_type,
    create_sender_receiver_interface, SenderReceiverInterface,
    ApplicationSwComponentType, PPortPrototype, RPortPrototype,
    SwcInternalBehavior, RunnableEntity, TimingEvent, InitEvent,
    Category, Encoding, AtomicType, Policy, CalibrationAccess,
    create_sw_addr_method, SectionType, DataTypeMappingSet, DataTypeMapping
)

doc = create_arxml_document()

base_uint8 = create_base_type("UInt8", size=8, encoding=Encoding.TWO_COMPONENT)
base_uint16 = create_base_type("UInt16", size=16, encoding=Encoding.TWO_COMPONENT)

kmh_unit = create_unit("kmh", display="km/h", factor=1.0, offset=0.0)
speed_linear = create_linear(factor=0.01, offset=0)
speed_compu = create_compu_method("SpeedCompu", unit=kmh_unit, linear=speed_linear, category=Category.LINEAR)

app_speed = create_value_type("AppSpeed", unit=kmh_unit, compu_method=speed_compu)
impl_speed = create_impl_value_type("ImplSpeed", base_type=base_uint16)

mapping = DataTypeMapping(
    name="SpeedMapping",
    application_data_type=app_speed,
    implementation_data_type=impl_speed
)
mapping_set = DataTypeMappingSet(name="SpeedMappingSet")
mapping_set.add_mapping(mapping)

data_element = SenderReceiverInterface.DataElement(
    name="SpeedData",
    data_type=app_speed,
    policy=Policy.STANDARD,
    calibration_access=CalibrationAccess.READ_WRITE
)
speed_interface = create_sender_receiver_interface("SpeedInterface", data_element=data_element)

code_method = create_sw_addr_method("CODE", section_type=SectionType.CODE)

runnable = RunnableEntity(
    name="UpdateSpeed",
    symbol="UpdateSpeed",
    minimum_start_interval=0.01,
    can_be_invoked_concurrently=False
)
runnable.add_variable_access(
    VariableAccess(name="SpeedAccess", port_prototype_ref="SpeedPort")
)

timing = TimingEvent(name="Timing_10ms", period=0.01)
init = InitEvent(name="Init", runnable_ref="UpdateSpeed")

behavior = SwcInternalBehavior(
    name="SpeedSensorBehavior",
    runnable_entities=[runnable],
    events=[timing, init],
    symbol="SpeedSensor"
)

port = PPortPrototype(name="SpeedPort", interface=speed_interface)

component = ApplicationSwComponentType(
    name="SpeedSensorComponent",
    supports_multiple_instantiation=False,
    atomic_type=AtomicType.APPLICATION,
    internal_behavior=behavior
)
component.add_port(port)

package = create_package("SpeedSensorPkg", elements=[
    base_uint8,
    base_uint16,
    kmh_unit,
    app_speed,
    impl_speed,
    mapping_set,
    speed_interface,
    code_method,
    component
])

package_element = package.to_arxml(doc)
add_package_to_document(doc, package_element)

write_arxml_pretty(doc, "SpeedSensor.arxml")
print("Generated: SpeedSensor.arxml")
```

---

## API 参考

### 索引

- [Base](#base-类) - 所有类型的基类
- [Category](#category) - 数据分类枚举
- [create_uuid](#create_uuid--str) - UUID 生成
- [create_arxml_document](#create_arxml_document---document) - 文档创建
- [write_arxml](#write_arxmldoc-document-filepath-str-encoding-str--utf-8---none) - 文件写入
- [create_package](#package) - 包创建
- [create_base_type](#basetype) - 基础类型创建
- [create_value_type](#applicationvaluedatatype) - 值类型创建
- [create_sender_receiver_interface](#senderreceiverinterface) - 接口创建
- [ApplicationSwComponentType](#applicationswcomponenttype) - 组件类型
- [create_swc_internal_behavior](#swcinternalbehavior) - 内部行为创建

---

## 常见问题

### Q: 如何创建多个端口？

```python
interface1 = create_sender_receiver_interface("DataInterface")
interface2 = create_sender_receiver_interface("StatusInterface")

component = ApplicationSwComponentType(name="MyComponent")
component.add_port(PPortPrototype(name="DataPort", interface=interface1))
component.add_port(RPortPrototype(name="StatusPort", interface=interface2))
```

### Q: 如何添加多个 Runnable？

```python
behavior = SwcInternalBehavior(name="Behavior")

runnable1 = create_runnable_entity(name="InitRunnable", symbol="Init")
runnable2 = create_runnable_entity(name="MainRunnable", symbol="Main", minimum_start_interval=0.01)

behavior.add_runnable(runnable1)
behavior.add_runnable(runnable2)

component = ApplicationSwComponentType(name="MyComponent")
component.internal_behavior = behavior
```

### Q: 如何创建嵌套结构体？

```python
inner_type = create_value_type("InnerValue")
inner_struct = ApplicationStructureDataType(name="InnerStruct")
inner_struct.add_element(
    ApplicationStructureDataType.StructureElement(name="value", data_type=inner_type)
)

outer_struct = ApplicationStructureDataType(name="OuterStruct")
outer_struct.add_element(
    ApplicationStructureDataType.StructureElement(name="inner", data_type=inner_struct)
)
```

---

## 相关文档

- [使用指南](docs/guide.md)
- [架构设计](docs/architecture.md)
- [API 参考](docs/api_reference.md)