arxml_sdk/docs/api_reference.md

# API 参考

## 目录

- [核心模块 (core)](#核心模块-core)
  - [Base 类](#base-类)
  - [公共函数](#公共函数)
  - [枚举类型](#枚举类型)
- [数据类型模块 (types)](#数据类型模块-types)
  - [BaseType](#basetype)
  - [Unit](#unit)
  - [DataConstraint](#dataconstraint)
  - [CompuMethod](#compumethod)
  - [应用数据类型](#应用数据类型)
  - [实现数据类型](#实现数据类型)
  - [SwAddrMethod](#swaddrmethod)
  - [数据类型映射](#数据类型映射)
  - [接口](#接口)
  - [软件组件类型](#软件组件类型)
  - [Package](#package)
  - [SwcInternalBehavior](#swcinternalbehavior)
- [工具模块 (utils)](#工具模块-utils)

---

## 核心模块 (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)
```

---

## 索引

- [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) - 内部行为创建