Pymaidol 文档

• 1: 入门
• 2: 语法参考
• 3: API 目录
• 3.1: AnnotationType 模块
• 3.1.1: AnnotationTypeEnum 枚举
• 3.1.2: MultiLineAnnotationTypeEnum 枚举
• 3.1.3: SingleLineAnnotationTypeEnum 枚举
• 3.2: Position 类
• 3.3: TemplateBase 类
• 3.4: TemplateRenderer 类

1 - 入门

环境要求与安装

python >= 3.10

pip install Pymaidol -i https://pypi.python.org/simple

第一个 Pymaidol 模板

创建模板文件

首先，假设你创建了一个名为 pymaidol_test 的文件夹。使用编辑器或者 IDE 打开该文件夹作为工作目录。

在 pymaidol_test 文件夹下打开命令行，输入以下命令：

python -m pymaidol -n FirstTemplate

FirstTemplate 是模板类的类名。命令行会输出以下内容，同时文件夹中会生成 FirstTemplate.pymd 和 FirstTemplate.py 两个文件：

Success: file "FirstTemplate.pymd" created
Success: file "FirstTemplate.py" created

编写模板设计文件

首先，用以下代码将 FirstTemplate.pymd 中的全部内容替换掉：

from pymaidol import TemplateBase
from pymaidol.AnnotationType import FULL_ANNOTATION_TYPE, AnnotationTypeEnum

class FirstTemplate(TemplateBase):
    def __init__(self, 
                 package_name:str, 
                 template: str | None = None, 
                 template_file_path: str | None = None, 
                 supported_annotation_types: list[AnnotationTypeEnum] = FULL_ANNOTATION_TYPE,
                 disable_annotation_types: list[AnnotationTypeEnum] = []) -> None:
        super().__init__(template, template_file_path, supported_annotation_types, disable_annotation_types)
        self.package_name = package_name
        
def main():
    template = FirstTemplate("Pymaidol")
    string = template.Render({"says": "Hello World"})
    print(string)
    
if __name__ == "__main__":
    main()

这段代码主要修改了以下部分：

• 为 FirstTemplate 类添加了 package_name 属性。
• 添加了 main 函数，以实例化 FirstTemplate 类。向 FirstTemplate 类的构造函数传入了 package_name 参数，该参数的值为 Pymaidol。
• 调用了 Render 方法，向其传入了一个字典 {"says": "Hello World"}。

然后，用以下代码替换 FirstTemplate 类中的全部内容：

@{import time}
Now (@(time.ctime())), Say "@(says)" using @(self.package_name)!

运行 FirstTemplate.py，命令行会输出以下内容：

Now (Tue May 23 19:21:19 2023), Say "Hello World" using Pymaidol!

另请参阅

• Pymaidol 语法参考
• Pymaidol API 目录

2 - 语法参考

Pymaidol 模板文件的创建与结构

使用命令行创建模板文件（推荐）

使用以下命令创建模板文件：

python -m pymaidol -n <类名> [-d <目录>]

会在当前目录下生成 <类名>.pymd 和 <类名>.py 两个文件。

Pymaidol 模板文件的组成

模板文件由模板设计文件 .pymd 和模板后台文件 .py 组成。

模板设计文件 .pymd：包含了模板的设计内容，如字符串和使用 Pymaidol 语法嵌入的 Python 代码/呈现表达式。

模板后台文件 .py：包含了模板的后台逻辑，如模板类的定义。

可以在设计文件中访问在后台文件中定义的变量和方法，但不能在后台文件中访问在设计文件中定义的元素。此外，两者的 import 语句是独立的。

若手动创建 Pymaidol 模板文件，模板设计文件 .pymd 和模板后台文件 .py 的文件名必须相同，且位于同一个文件夹下；模板后台文件的文件名必须与模板类的类名相同。

Pymaidol 语法

Pymaidol 使用 @ 作为标记符，用于标记 Pymaidol 表达式、关键字和代码块。若要在文本中使用 @，请使用 @@ 代替。

Pymaidol 表达式

Pymaidol 表达式用于向模板中嵌入/呈现数据。Pymaidol 表达式的格式为 @(<表达式>) ，如：

@("Hello World!")

渲染后的文本为：

Hello World!

Pymaidol 关键字

关键字的格式为 @<关键字>;，如：

@break; # 跳出当前循环
@continue; # 跳过当前循环

Pymaidol 代码块

Pymaidol 代码块用于在模板渲染时执行一些 python 代码。格式为 @{<代码块>}，如：

@{answer = 42}
The answer of this universe is @(answer)

渲染后的文本为：

The answer of this universe is 42

因为渲染 Pymaidol 代码块是按照由上至下、由左至右的顺序进行的，所以可以使用 Pymaidol 代码块来定义一些变量、函数等，在之后的表达式或代码块中使用。

if, elif, else 代码块

使用方式为 @if (<条件表达式>){<模板设计语句>}，如：

@{answer = 42}
@if (answer > 0) {answer == @(answer), and it is positive.}
@elif (answer < 0) {answer == @(answer), and it is negative.}
@else {answer == @(answer), and it is zero.}

渲染后的文本为：

answer == 42, and it is positive.

while 代码块

使用方式为 @while (<条件表达式>){<模板设计语句>}，如：

@{i = 0}
@while (i < 5){
i = @(i)
@{i += 1}
}

渲染后的文本为：

i = 0
i = 1
i = 2
i = 3
i = 4

for 代码块

使用方式为 @for (<变量> in <可迭代对象>){<模板设计语句>}，如：

@for (i in range(5)){
i = @(i)
@if (i == 3) {@break;}
}

渲染后的文本为：

i = 0
i = 1
i = 2
i = 3

3 - API 目录

模块

类

3.1 - AnnotationType 模块

概述

AnnotationType 模块提供了可在模板设计文件中.pymd使用的注释的枚举类型。

模块：pymaidol

导入

from pymaidol import AnnotationType

类

静态变量

3.1.1 - AnnotationTypeEnum 枚举

概述

AnnotationTypeEnum 枚举是所有注释种类枚举类的基类。内部无枚举值，只用于被继承。

模块：pymaidol.AnnotationType

继承自：enum.Enum

导入

from pymaidol import AnnotationTypeEnum

或

from pymaidol.AnnotationType import AnnotationTypeEnum

3.1.2 - MultiLineAnnotationTypeEnum 枚举

概述

包含了可在模板设计文件中.pymd使用的多行注释的类型。

模块：pymaidol.AnnotationType

继承自：pymaidol.AnnotationType.AnnotationTypeEnum

导入

from pymaidol import MultiLineAnnotationTypeEnum

或

from pymaidol.AnnotationType import MultiLineAnnotationTypeEnum

枚举项

3.1.3 - SingleLineAnnotationTypeEnum 枚举

概述

包含了可在模板设计文件中.pymd使用的单行注释的类型。

模块：pymaidol.AnnotationType

继承自：pymaidol.AnnotationType.AnnotationTypeEnum

导入

from pymaidol import SingleLineAnnotationTypeEnum

或

from pymaidol.AnnotationType import SingleLineAnnotationTypeEnum

枚举项

另请参阅

AnnotationTypeEnum 枚举

3.2 - Position 类

概述

Position 类用于定位在原始模板字符串中的位置。

Position 的对象里的属性是只读的，初始化之后不允许被修改。

注意：当 Position 类用于结束位置时，是包括该位置的字符的。比如：如果 start.total = 20， end.total = 30，那么对原模板字符串的切片应该为 template[20:31]。

模块：pymaidol.Positions

导入

from pymaidol import Position

或

from pymaidol.Positions import Position

构造函数

Position(line_index, char_index, total)

参数

• line_index (int): 行索引。从 0 开始。
• char_index (int): 当前行的字符索引。从 0 开始。
• total (int): 字符索引。从 0 开始。

属性

line_index (int，readonly)

行索引。从 0 开始。

char_index (int，readonly)

当前行的字符索引。从 0 开始。

total (int，readonly)

字符索引。从 0 开始。

full_description (str，readonly)

完整的、人类可读的位置描述。

方法

Position.Default()

@ classmethod

新建并返回一个默认的 Position 对象，其所有属性均为 0。

参数

无。

返回值 (Position)

默认的 Position 对象。

Copy()

复制并返回一个新的 Position 对象。

参数

无。

返回值 (Position)

新的 Position 对象，且其所有属性与原对象相同。

3.3 - TemplateBase 类

概述

TemplateBase 类是 Pymaidol 模板的后台类，是所有 Pymaidol 模板类的基类。是不可实例化的抽象类，需要被继承使用。

模块：pymaidol.TemplateBase

继承自：abc.ABC

导入

from pymaidol import TemplateBase

或

from pymaidol.TemplateBase import TemplateBase

构造函数

TemplateBase(template, template_file_path, supported_annotation_types, disable_annotation_types) (virtual)

参数

• template (str, optional): 模板字符串。默认为 None。
• template_file_path (str, optional): 模板文件路径。默认为 None。
• supported_annotation_types (list[AnnotationTypeEnum], optional): 支持的注释类型列表。默认为所有注释类型（Python、C的单行与多行注释、HTML注释）。
• disable_annotation_types (list[AnnotationTypeEnum], optional): 禁用的注释类型列表，使这些注释出现在渲染后的文本中。默认为空。禁用的优先级高于支持。例如，如果 disable_annotation_types 中包含 AnnotationTypeEnum.SingleLineAnnotationTypeEnum.Python （python 单行注释），则 supported_annotation_types 中无论是否包含它，都将被视为禁用该注释类型。

当 template 与 template_file_path 都为 None 时，TemplateBase 类及其子类将试图读取在与其同一目录下、与其同名的模板文件 .pymd。如果两个都不为空，则优先使用 template。

属性

rendered（str，readonly）

渲染后的字符串。如果自初始化或调用 HotReload() 方法以来没有调用过 Render() 方法，则为 None。

template（str，readonly）

模板字符串。

方法

HotReload(template, template_file_path) (final)

重新加载模板。

参数

• template (str, optional): 模板字符串。默认为 None。
• template_file_path (str, optional): 模板文件路径。默认为 None。

当 template 与 template_file_path 都为 None 时，TemplateBase 类及其子类将试图读取在与其同一目录下、与其同名的模板文件 .pymd。如果两个都不为空，则优先使用 template。

返回值 (None)

无。

Render(inject_kwargs) (final)

给与数据并渲染模板字符串。

参数

• inject_kwargs (dict, Optional): 用于渲染模板字符串的外部注入变量。默认为 None。注入的变量将会作为局部变量。

返回值 (str)

渲染后的字符串。

3.4 - TemplateRenderer 类

概述

将模板字符串渲染为字符串的类。

模块：pymaidol.TemplateRenderer

导入

from pymaidol import TemplateRenderer

或

from pymaidol.TemplateRenderer import TemplateRenderer

构造函数

TemplateRenderer(template, supported_annotation_types)

参数

• template (str): 模板字符串。
• supported_annotation_types (list[AnnotationTypeEnum], optional): 支持的注释类型列表。默认为所有注释类型（Python、C的单行与多行注释、HTML注释）。

属性

template（str，readonly）

模板字符串。

方法

TemplateRenderer.ReadFromFile(template_file_path, supported_annotation_types) (classmethod)

给定模板文件路径，返回一个 TemplateRenderer 对象。

参数

• template_file_path (str): 模板文件路径。
• supported_annotation_types (list[AnnotationTypeEnum]): 支持的注释类型列表。

返回值

TemplateRenderer: TemplateRenderer 对象。

Render(local_vars, global_vars) (final)

给与数据并渲染模板字符串。

参数

• local_vars (dict): 用于渲染模板字符串的局部变量。
• global_vars (dict，可选): 用于渲染模板字符串的全局变量。默认为 None。

返回值

str: 渲染后的字符串。