# Python 代码规则详解

## 概述

Python 代码规则是 DDMS 合规性验证软件中最灵活的规则类型，允许使用 Python 编写复杂的验证逻辑。与其他基于JSON结构的规则不同，Python 代码规则能够实现任何自定义逻辑，如复杂的数学计算、字符串处理、条件判断等。

## 规则结构

Python 代码规则由两部分组成：

1. **元数据文件** (JSON格式)：包含规则的基本信息和配置参数
2. **代码文件** (Python格式)：包含实际的验证逻辑代码

### 元数据文件格式

```json
{
  "id": "rule-id",
  "name": "规则名称",
  "description": "规则描述",
  "category": "PythonCode",
  "version": "1.0.0",
  "severity": "error",
  "source": "Standard-2023",
  "is_enabled": true,
  "tags": ["tag1", "tag2"],
  "target_type": "DataObject",
  "target_identifier": "TargetName",
  "allow_imports": true,
  "allowed_modules": ["math", "re", "json", "datetime"],
  "entry_function": "validate",
  "expected_parameters": ["param1", "param2"],
  "timeout": 5,
  "code_file": "path/to/code/file.py"
}
```

### 主要字段说明

- **id**: 规则的唯一标识符
- **name**: 规则名称
- **description**: 规则功能描述
- **category**: 固定为 "PythonCode"
- **version**: 规则版本号
- **severity**: 规则严重级别，如 "error", "warning", "info"
- **is_enabled**: 规则是否启用
- **tags**: 用于分类和筛选的标签列表
- **target_type**: 规则适用的目标类型，如 "DataObject", "API", "Process"
- **target_identifier**: 具体目标的标识符，如 "Well", "Seismic"
- **allow_imports**: 是否允许导入外部模块
- **allowed_modules**: 允许导入的模块列表
- **entry_function**: 入口函数名（默认为 "validate"）
- **expected_parameters**: 规则执行所需的参数列表
- **timeout**: 代码执行超时时间（秒）
- **code_file**: 外部Python代码文件的路径（相对于rules目录）

## 代码文件

代码文件应包含与 `entry_function` 字段指定的同名函数（默认是 "validate"），该函数作为验证逻辑的入口点。

### 代码文件示例

```python
"""
井坐标验证规则

此规则验证井的坐标是否在有效范围内，并检查与参考井的距离。
"""

import math

def is_valid_coordinate(lat, lon):
    # 验证逻辑
    return True

def calculate_distance(lat1, lon1, lat2, lon2):
    # 计算距离的逻辑
    return 0.0

def validate():
    """
    验证入口函数
    
    在这里实现完整的验证逻辑
    """
    # 从全局命名空间获取参数
    param1 = globals().get('param1')
    
    # 执行验证逻辑
    # ...
    
    # 返回验证结果
    return {
        'is_valid': True,
        'message': '验证通过',
        'details': {
            'additional_info': 'some value'
        }
    }
```

## 验证结果

验证函数应返回以下格式的结果：

1. **布尔值**：简单地表示验证成功或失败
2. **字典**：包含详细的验证结果，推荐格式如下：
   ```python
   {
     'is_valid': True/False,  # 必需，表示验证结果
     'message': '验证结果消息',  # 可选，描述验证结果
     'details': { ... }  # 可选，包含详细信息的字典
   }
   ```

## 安全限制

为了确保系统安全，Python 代码规则在执行时受到以下限制：

1. 只能导入明确允许的模块
2. 代码执行有超时限制
3. 无法访问文件系统、网络或系统命令
4. 在隔离的执行环境中运行

## 代码规则存储结构

推荐的存储结构如下：

```
rules/
  python_code/
    <rule-id>/
      <version>.json  # 元数据文件
      <version>.py    # Python代码文件
```

例如：

```
rules/
  python_code/
    well-coordinates-validation/
      1.0.0.json
      1.0.0.py
```

## 使用场景

Python 代码规则适用于以下场景：

1. **复杂的数值计算**：如坐标转换、距离计算、范围检查等
2. **字符串处理**：解析和验证具有特定格式的字符串
3. **条件逻辑**：需要多个条件组合的复杂判断
4. **时间处理**：日期和时间的验证和计算
5. **数据转换**：在验证前需要对数据进行转换或规范化

## 测试代码规则

可以使用提供的测试工具来验证规则的正确性：

```bash
python -m ddms_compliance_suite.test_executor.test_python_external_code
```

## 最佳实践

1. **代码注释**：添加详细的注释，特别是对于复杂的逻辑
2. **模块化**：将复杂逻辑拆分为多个小函数
3. **错误处理**：使用异常处理捕获可能的错误
4. **参数验证**：在函数开始时验证参数的有效性
5. **详细结果**：返回详细的验证结果，便于理解验证失败的原因
6. **版本管理**：为每个版本的规则创建单独的代码文件