Python 代码规则详解

概述

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

规则结构

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

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

元数据文件格式

{
  "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"），该函数作为验证逻辑的入口点。

代码文件示例

"""
井坐标验证规则

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

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'
        }
    }

验证结果

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

布尔值：简单地表示验证成功或失败

字典：包含详细的验证结果，推荐格式如下：

{
  'is_valid': True/False,  # 必需，表示验证结果
  'message': '验证结果消息',  # 可选，描述验证结果
  'details': { ... }  # 可选，包含详细信息的字典
}

安全限制

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

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

代码规则存储结构

推荐的存储结构如下：

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 代码规则适用于以下场景：

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

测试代码规则

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

python -m ddms_compliance_suite.test_executor.test_python_external_code

最佳实践

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

4.7 KiB Raw Blame History Unescape Escape