初始化项目，由ModelHub XC社区提供模型
Model: XuehangCang/EasyPL-1B Source: Original Platform
This commit is contained in:
ModelHub XC
35
.gitattributes
vendored
Normal file
35
.gitattributes
vendored
Normal file
@@ -0,0 +1,35 @@
|
||||
*.7z filter=lfs diff=lfs merge=lfs -text
|
||||
*.arrow filter=lfs diff=lfs merge=lfs -text
|
||||
*.bin filter=lfs diff=lfs merge=lfs -text
|
||||
*.bz2 filter=lfs diff=lfs merge=lfs -text
|
||||
*.ckpt filter=lfs diff=lfs merge=lfs -text
|
||||
*.ftz filter=lfs diff=lfs merge=lfs -text
|
||||
*.gz filter=lfs diff=lfs merge=lfs -text
|
||||
*.h5 filter=lfs diff=lfs merge=lfs -text
|
||||
*.joblib filter=lfs diff=lfs merge=lfs -text
|
||||
*.lfs.* filter=lfs diff=lfs merge=lfs -text
|
||||
*.mlmodel filter=lfs diff=lfs merge=lfs -text
|
||||
*.model filter=lfs diff=lfs merge=lfs -text
|
||||
*.msgpack filter=lfs diff=lfs merge=lfs -text
|
||||
*.npy filter=lfs diff=lfs merge=lfs -text
|
||||
*.npz filter=lfs diff=lfs merge=lfs -text
|
||||
*.onnx filter=lfs diff=lfs merge=lfs -text
|
||||
*.ot filter=lfs diff=lfs merge=lfs -text
|
||||
*.parquet filter=lfs diff=lfs merge=lfs -text
|
||||
*.pb filter=lfs diff=lfs merge=lfs -text
|
||||
*.pickle filter=lfs diff=lfs merge=lfs -text
|
||||
*.pkl filter=lfs diff=lfs merge=lfs -text
|
||||
*.pt filter=lfs diff=lfs merge=lfs -text
|
||||
*.pth filter=lfs diff=lfs merge=lfs -text
|
||||
*.rar filter=lfs diff=lfs merge=lfs -text
|
||||
*.safetensors filter=lfs diff=lfs merge=lfs -text
|
||||
saved_model/**/* filter=lfs diff=lfs merge=lfs -text
|
||||
*.tar.* filter=lfs diff=lfs merge=lfs -text
|
||||
*.tar filter=lfs diff=lfs merge=lfs -text
|
||||
*.tflite filter=lfs diff=lfs merge=lfs -text
|
||||
*.tgz filter=lfs diff=lfs merge=lfs -text
|
||||
*.wasm filter=lfs diff=lfs merge=lfs -text
|
||||
*.xz filter=lfs diff=lfs merge=lfs -text
|
||||
*.zip filter=lfs diff=lfs merge=lfs -text
|
||||
*.zst filter=lfs diff=lfs merge=lfs -text
|
||||
*tfevents* filter=lfs diff=lfs merge=lfs -text
|
||||
186
README.md
Normal file
186
README.md
Normal file
@@ -0,0 +1,186 @@
|
||||
---
|
||||
license: mit
|
||||
datasets:
|
||||
- XuehangCang/e_style_code
|
||||
language:
|
||||
- zh
|
||||
base_model:
|
||||
- openbmb/MiniCPM5-1B
|
||||
base_model_relation: finetune
|
||||
pipeline_tag: text-generation
|
||||
library_name: transformers
|
||||
tags:
|
||||
- text-generation
|
||||
- code
|
||||
- chinese
|
||||
- easypl
|
||||
- minicpm
|
||||
- lora
|
||||
- sft
|
||||
---
|
||||
|
||||
# EasyPL-1B
|
||||
|
||||
EasyPL-1B 是一个面向 EasyPL（易语言 Easy Programming Language）编程场景的中文代码助手模型
|
||||
|
||||
模型目标是根据中文需求生成清晰、简洁、可运行的代码，同时提供必要的中文解释，适合教学示例、语法演示和轻量级编程辅助
|
||||
|
||||
## Model Details
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| Model name | EasyPL-1B |
|
||||
| Base model | `openbmb/MiniCPM5-1B` |
|
||||
| Dataset | `XuehangCang/e_style_code` |
|
||||
| Language | Chinese |
|
||||
| Training method | SFT + LoRA |
|
||||
| Task | Text generation / Code generation |
|
||||
| License | MIT |
|
||||
|
||||
## Intended Use
|
||||
|
||||
EasyPL-1B 主要适用于：
|
||||
|
||||
- 根据中文需求生成示例代码
|
||||
- 解释代码片段的执行逻辑
|
||||
- 生成函数、字符串处理、循环、条件判断等基础编程示例
|
||||
- 将结构化题目、自然语言描述整理为代码或中文说明
|
||||
|
||||
该模型更偏向编程教学与示例生成，不建议作为通用问答模型或复杂工程自动化模型使用
|
||||
|
||||
## Coding Style Skill
|
||||
|
||||
EasyPL-1B 配套提供 [易语言风格 Python 编码规范 SKILL.md](./易语言风格%20Python%20编码规范%20SKILL.md)，用于说明模型推荐遵循的中文化 Python 编码风格。
|
||||
|
||||
该规范覆盖中文函数名和变量名、模块组织、函数设计、中文注释、异常处理、PEP8 格式约束、常用代码模板与质量检查清单。需要了解 EasyPL 风格代码的命名规则、生成边界和示例模板时，可以点击上方链接查看详情文件。
|
||||
|
||||
|
||||
## How to Use
|
||||
|
||||
```python
|
||||
from transformers import AutoModelForCausalLM, AutoTokenizer
|
||||
|
||||
model_id = "XuehangCang/EasyPL-1B"
|
||||
|
||||
tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
|
||||
model = AutoModelForCausalLM.from_pretrained(
|
||||
model_id,
|
||||
torch_dtype="auto",
|
||||
device_map="auto",
|
||||
trust_remote_code=True,
|
||||
)
|
||||
|
||||
messages = [
|
||||
{"role": "user", "content": "生成随机UUID"},
|
||||
]
|
||||
|
||||
inputs = tokenizer.apply_chat_template(
|
||||
messages,
|
||||
tokenize=True,
|
||||
add_generation_prompt=True,
|
||||
enable_thinking=False,
|
||||
return_tensors="pt",
|
||||
)
|
||||
inputs = {key: value.to(model.device) for key, value in inputs.items()}
|
||||
|
||||
outputs = model.generate(**inputs, max_new_tokens=2048)
|
||||
prompt_len = inputs["input_ids"].shape[-1]
|
||||
print(tokenizer.decode(outputs[0][prompt_len:], skip_special_tokens=True))
|
||||
```
|
||||
|
||||
如果使用的 `transformers` 或 tokenizer 版本不支持 `enable_thinking` 参数，可以移除该参数后再运行
|
||||
|
||||
|
||||
## Example Outputs
|
||||
|
||||
以下示例均使用模型实际调用生成
|
||||
|
||||
### 生成随机UUID
|
||||
|
||||
```python
|
||||
import uuid
|
||||
|
||||
def 生成随机UUID():
|
||||
"""生成随机UUID"""
|
||||
return str(uuid.uuid4())
|
||||
|
||||
# 测试
|
||||
print(生成随机UUID())
|
||||
```
|
||||
|
||||
### 判断一个数字是否为偶数，并输出结果
|
||||
|
||||
```python
|
||||
def 取模( 数字, 基数):
|
||||
"""取模函数，返回 数字 % 基数 结果"""
|
||||
return 数字 % 基数
|
||||
|
||||
def 取余( 数字, 基数):
|
||||
"""取余函数，返回 数字 % 基数 结果"""
|
||||
return 取模( 数字, 基数)
|
||||
|
||||
def 判断偶数( 数字):
|
||||
"""判断数字是否为偶数"""
|
||||
return 取余( 数字, 2) == 0
|
||||
|
||||
def 判断奇数( 数字):
|
||||
"""判断数字是否为奇数"""
|
||||
return 取余( 数字, 2) != 0
|
||||
|
||||
# 测试
|
||||
if __name__ == '__main__':
|
||||
结果1 = 判断偶数(64)
|
||||
print(f"64 是偶数：{结果1}")
|
||||
|
||||
结果2 = 判断奇数(64)
|
||||
print(f"64 是奇数：{结果2}")
|
||||
|
||||
结果3 = 判断偶数(7)
|
||||
print(f"7 是偶数：{结果3}")
|
||||
|
||||
结果4 = 判断奇数(10)
|
||||
print(f"10 是奇数：{结果4}")
|
||||
|
||||
结果5 = 判断偶数(3)
|
||||
print(f"3 是偶数：{结果5}")
|
||||
```
|
||||
|
||||
### 计算字符串的MD5值
|
||||
|
||||
```python
|
||||
import hashlib
|
||||
|
||||
def 计算MD5(数据文本):
|
||||
"""
|
||||
计算字符串的MD5值
|
||||
参数:
|
||||
数据文本: 需要计算MD5的字符串
|
||||
返回:
|
||||
MD5值字符串
|
||||
"""
|
||||
md5 = hashlib.md5()
|
||||
md5.update(数据文本.encode('utf-8'))
|
||||
return md5.hexdigest()
|
||||
```
|
||||
|
||||
这些输出体现了模型对易语言风格的适配：短中文需求进入，返回带中文函数名、中文注释、测试代码或简要说明的代码片段
|
||||
|
||||
## Limitations
|
||||
|
||||
- EasyPL-1B 是针对中文编程场景微调的模型，通用知识问答能力不是主要优化目标
|
||||
- 生成代码仍可能出现语法或逻辑错误，建议在实际使用前进行人工检查和运行验证
|
||||
- 模型能力受训练数据质量、训练样本规模、训练轮数和基座模型能力影响
|
||||
|
||||
## Citation
|
||||
|
||||
如果你使用了本模型，请同时关注并引用相关基座模型与数据集：
|
||||
|
||||
- Base model: `openbmb/MiniCPM5-1B`
|
||||
- Dataset: `XuehangCang/e_style_code`
|
||||
|
||||
## License
|
||||
|
||||
This model card is released under the MIT License.
|
||||
|
||||
|
||||
|
||||
179
chat_template.jinja
Normal file
179
chat_template.jinja
Normal file
@@ -0,0 +1,179 @@
|
||||
{{- bos_token }}{%- if tools %}
|
||||
{%- set tool_definitions %}
|
||||
{{- "# Tools\n\nYou are provided with function signatures within <tools></tools> XML tags:\n<tools>" }}
|
||||
{%- for tool in tools %}
|
||||
{{- "\n" }}
|
||||
{{- tool | tojson(ensure_ascii=False) }}
|
||||
{%- endfor %}
|
||||
{{- '\n</tools>\n\nTool usage guidelines:\n- You may call zero or more functions. If no function calls are needed, just answer normally and do not include any <function ... </function>.\n- When calling a function, return an XML object within <function ... </function> using:\n<function name="function-name"><param name="param-name">param-value</param></function>\n- param-value may be multi-line. If it contains <, & or newline characters, wrap it in a CDATA block: <param name="param-name"><![CDATA[...multi-line value...]]></param>' }}
|
||||
{%- endset %}
|
||||
|
||||
{{- '<|im_start|>system\n' }}
|
||||
{%- if messages[0].role == 'system' %}
|
||||
{%- if '<tool_def_sep>' in messages[0].content %}
|
||||
{{- messages[0].content.replace('<tool_def_sep>', tool_definitions) }}
|
||||
{%- else %}
|
||||
{{- messages[0].content + '\n\n' + tool_definitions }}
|
||||
{%- endif %}
|
||||
{%- else %}
|
||||
{{- tool_definitions.lstrip() }}
|
||||
{%- endif %}
|
||||
{{- '<|im_end|>\n' }}
|
||||
{%- else %}
|
||||
{%- if messages[0].role == 'system' %}
|
||||
{{- '<|im_start|>system\n' + messages[0].content + '<|im_end|>\n' }}
|
||||
{%- endif %}
|
||||
{%- endif %}
|
||||
{%- set ns = namespace(multi_step_tool=true, last_query_index=messages|length - 1) %}
|
||||
{%- for message in messages[::-1] %}
|
||||
{%- set index = (messages|length - 1) - loop.index0 %}
|
||||
{%- if ns.multi_step_tool and message.role == "user" and message.content is string and not(message.content.startswith('<tool_response>') and message.content.endswith('</tool_response>')) %}
|
||||
{%- set ns.multi_step_tool = false %}
|
||||
{%- set ns.last_query_index = index %}
|
||||
{%- endif %}
|
||||
{%- endfor %}
|
||||
{%- for message in messages %}
|
||||
{%- if message.content is string %}
|
||||
{%- set content = message.content %}
|
||||
{%- else %}
|
||||
{%- set content = '' %}
|
||||
{%- endif %}
|
||||
{%- if (message.role == "user") or (message.role == "system" and not loop.first) %}
|
||||
{{- '<|im_start|>' + message.role + '\n' + content + '<|im_end|>' + '\n' }}
|
||||
{%- elif message.role == "assistant" %}
|
||||
{%- set reasoning_content = '' %}
|
||||
{%- if message.reasoning_content is string %}
|
||||
{%- set reasoning_content = message.reasoning_content %}
|
||||
{%- else %}
|
||||
{%- if '</think>' in content %}
|
||||
{%- set reasoning_content = content.split('</think>')[0].rstrip('\n').split('<think>')[-1].lstrip('\n') %}
|
||||
{%- set content = content.split('</think>')[-1].lstrip('\n') %}
|
||||
{%- endif %}
|
||||
{%- endif %}
|
||||
|
||||
{%- if message.tool_calls %}
|
||||
{%- set content_parts = content.split('<tool_sep>') %}
|
||||
{%- set processed_content = content_parts[0] %}
|
||||
{%- set tool_calls_count = message.tool_calls|length %}
|
||||
{%- set tool_sep_count = content_parts|length - 1 %}
|
||||
{%- set min_count = [tool_calls_count, tool_sep_count]|min %}
|
||||
|
||||
{%- for i in range(1, content_parts|length) %}
|
||||
{%- set tool_index = i - 1 %}
|
||||
{%- if tool_index < tool_calls_count %}
|
||||
{%- set tool_call = message.tool_calls[tool_index] %}
|
||||
{%- if tool_call.function %}
|
||||
{%- set tool_call = tool_call.function %}
|
||||
{%- endif %}
|
||||
{%- set single_tool_xml %}
|
||||
{{- '<function name="' ~ tool_call.name ~ '">' }}
|
||||
{%- if tool_call.arguments %}
|
||||
{%- set args_dict = tool_call.arguments %}
|
||||
{%- for param_name, param_value in args_dict.items() %}
|
||||
{{- '<param name="' ~ param_name ~ '">' }}
|
||||
{%- if param_value is string and ('<' in param_value or '&' in param_value or '\n' in param_value) %}
|
||||
{{- '<![CDATA[' + param_value + ']]>' }}
|
||||
{%- else %}
|
||||
{{- param_value }}
|
||||
{%- endif %}
|
||||
{{- '</param>' }}
|
||||
{%- endfor %}
|
||||
{%- endif %}
|
||||
{{- '</function>' }}
|
||||
{%- endset %}
|
||||
{%- set processed_content = processed_content + single_tool_xml + content_parts[i] %}
|
||||
{%- else %}
|
||||
{%- set processed_content = processed_content + content_parts[i] %}
|
||||
{%- endif %}
|
||||
{%- endfor %}
|
||||
|
||||
{%- if tool_calls_count > tool_sep_count %}
|
||||
{%- for remaining_index in range(tool_sep_count, tool_calls_count) %}
|
||||
{%- set tool_call = message.tool_calls[remaining_index] %}
|
||||
{%- if tool_call.function %}
|
||||
{%- set tool_call = tool_call.function %}
|
||||
{%- endif %}
|
||||
{%- set remaining_tool_xml %}
|
||||
{{- '<function name="' ~ tool_call.name ~ '">' }}
|
||||
{%- if tool_call.arguments %}
|
||||
{%- set args_dict = tool_call.arguments %}
|
||||
{%- for param_name, param_value in args_dict.items() %}
|
||||
{{- '<param name="' ~ param_name ~ '">' }}
|
||||
{%- if param_value is string and ('<' in param_value or '&' in param_value or '\n' in param_value) %}
|
||||
{{- '<![CDATA[' + param_value + ']]>' }}
|
||||
{%- else %}
|
||||
{{- param_value }}
|
||||
{%- endif %}
|
||||
{{- '</param>' }}
|
||||
{%- endfor %}
|
||||
{%- endif %}
|
||||
{{- '</function>' }}
|
||||
{%- endset %}
|
||||
{%- set processed_content = processed_content + remaining_tool_xml %}
|
||||
{%- endfor %}
|
||||
{%- endif %}
|
||||
|
||||
{%- set content = processed_content %}
|
||||
{%- endif %}
|
||||
|
||||
{%- if loop.index0 > ns.last_query_index %}
|
||||
{%- if reasoning_content %}
|
||||
{{- '<|im_start|>' + message.role + '\n<think>\n' + reasoning_content.strip('\n') + '\n</think>\n\n' + content.lstrip('\n') }}
|
||||
{%- else %}
|
||||
{{- '<|im_start|>' + message.role + '\n' + content }}
|
||||
{%- endif %}
|
||||
{%- else %}
|
||||
{{- '<|im_start|>' + message.role + '\n' + content }}
|
||||
{%- endif %}
|
||||
|
||||
{%- if message.tool_calls and not has_tool_sep %}
|
||||
{%- for tool_call in message.tool_calls %}
|
||||
{%- if (loop.first and content) or (not loop.first) %}
|
||||
{{- '\n' }}
|
||||
{%- endif %}
|
||||
{%- if tool_call.function %}
|
||||
{%- set tool_call = tool_call.function %}
|
||||
{%- endif %}
|
||||
{{- '<function name="' ~ tool_call.name ~ '">' }}
|
||||
{%- if tool_call.arguments %}
|
||||
{%- set args_dict = tool_call.arguments %}
|
||||
{%- for param_name, param_value in args_dict.items() %}
|
||||
{{- '<param name="' ~ param_name ~ '">' }}
|
||||
{%- if param_value is string and ('<' in param_value or '&' in param_value or '\n' in param_value) %}
|
||||
{{- '<![CDATA[' + param_value + ']]>' }}
|
||||
{%- else %}
|
||||
{{- param_value }}
|
||||
{%- endif %}
|
||||
{{- '</param>' }}
|
||||
{%- endfor %}
|
||||
{%- endif %}
|
||||
{{- '</function>' }}
|
||||
{%- endfor %}
|
||||
{%- endif %}
|
||||
{{- '<|im_end|>\n' }}
|
||||
{%- elif message.role == "tool" %}
|
||||
{%- if loop.first or (messages[loop.index0 - 1].role != "tool") %}
|
||||
{{- '<|im_start|>user' }}
|
||||
{%- endif %}
|
||||
{{- '\n<tool_response>\n' }}
|
||||
{%- if message.content is string %}
|
||||
{{- content }}
|
||||
{%- else %}
|
||||
{{- message.content | tojson(ensure_ascii=False) }}
|
||||
{%- endif %}
|
||||
{{- '\n</tool_response>' }}
|
||||
{%- if loop.last or (messages[loop.index0 + 1].role != "tool") %}
|
||||
{{- '<|im_end|>\n' }}
|
||||
{%- endif %}
|
||||
{%- endif %}
|
||||
{%- endfor %}
|
||||
{%- if add_generation_prompt %}
|
||||
{{- '<|im_start|>assistant\n' }}
|
||||
{%- if enable_thinking is defined %}
|
||||
{%- if enable_thinking is false %}
|
||||
{{- '<think>\n\n</think>\n\n' }}
|
||||
{%- elif enable_thinking is true %}
|
||||
{{- '<think>\n' }}
|
||||
{%- endif %}
|
||||
{%- endif %}
|
||||
{%- endif %}
|
||||
35
config.json
Normal file
35
config.json
Normal file
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"architectures": [
|
||||
"LlamaForCausalLM"
|
||||
],
|
||||
"attention_bias": false,
|
||||
"attention_dropout": 0.0,
|
||||
"bos_token_id": 0,
|
||||
"dtype": "bfloat16",
|
||||
"eos_token_id": [
|
||||
1,
|
||||
130073
|
||||
],
|
||||
"head_dim": 128,
|
||||
"hidden_act": "silu",
|
||||
"hidden_size": 1536,
|
||||
"initializer_range": 0.02,
|
||||
"intermediate_size": 4608,
|
||||
"max_position_embeddings": 131072,
|
||||
"mlp_bias": false,
|
||||
"model_type": "llama",
|
||||
"num_attention_heads": 16,
|
||||
"num_hidden_layers": 24,
|
||||
"num_key_value_heads": 2,
|
||||
"pad_token_id": 1,
|
||||
"pretraining_tp": 1,
|
||||
"rms_norm_eps": 1e-06,
|
||||
"rope_parameters": {
|
||||
"rope_theta": 5000000,
|
||||
"rope_type": "default"
|
||||
},
|
||||
"tie_word_embeddings": false,
|
||||
"transformers_version": "5.8.0",
|
||||
"use_cache": true,
|
||||
"vocab_size": 130560
|
||||
}
|
||||
13
generation_config.json
Normal file
13
generation_config.json
Normal file
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"_from_model_config": true,
|
||||
"bos_token_id": 0,
|
||||
"do_sample": true,
|
||||
"eos_token_id": [
|
||||
1,
|
||||
130073
|
||||
],
|
||||
"pad_token_id": 1,
|
||||
"temperature": 0.9,
|
||||
"top_p": 0.95,
|
||||
"transformers_version": "5.8.0"
|
||||
}
|
||||
3
model.safetensors
Normal file
3
model.safetensors
Normal file
@@ -0,0 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:201a0411f160bd29dfa26b5e62c8cd572eabe33ecdfe7417687d33f388610d22
|
||||
size 2161290944
|
||||
653947
tokenizer.json
Normal file
653947
tokenizer.json
Normal file
File diff suppressed because it is too large
Load Diff
17
tokenizer_config.json
Normal file
17
tokenizer_config.json
Normal file
@@ -0,0 +1,17 @@
|
||||
{
|
||||
"add_prefix_space": null,
|
||||
"backend": "tokenizers",
|
||||
"bos_token": "<s>",
|
||||
"clean_up_tokenization_spaces": false,
|
||||
"eos_token": "</s>",
|
||||
"is_local": true,
|
||||
"legacy": true,
|
||||
"local_files_only": false,
|
||||
"model_max_length": 1000000000000000019884624838656,
|
||||
"pad_token": "</s>",
|
||||
"sp_model_kwargs": {},
|
||||
"spaces_between_special_tokens": false,
|
||||
"tokenizer_class": "TokenizersBackend",
|
||||
"unk_token": "<unk>",
|
||||
"use_default_system_prompt": false
|
||||
}
|
||||
422
易语言风格 Python 编码规范 SKILL.md
Normal file
422
易语言风格 Python 编码规范 SKILL.md
Normal file
@@ -0,0 +1,422 @@
|
||||
# 易语言风格 Python 编码规范
|
||||
|
||||
## 目标
|
||||
|
||||
本规范用于约束一种“易语言风格”的 Python 编码方式：用中文表达程序意图，用接近自然语言的函数名、变量名和注释降低阅读门槛，同时遵守 Python 语法、PEP8 格式和基本工程质量要求。
|
||||
|
||||
这种风格不是简单把英文 API 翻译成中文，而是让代码像中文命令一样直接表达“做什么”。
|
||||
|
||||
核心目标：
|
||||
|
||||
- 代码可运行，符合 Python 语法
|
||||
- 命名中文化，语义清晰
|
||||
- 函数职责单一，像“命令”一样可组合
|
||||
- 注释解释意图和边界，不重复代码
|
||||
- 格式遵循 PEP8，便于工具格式化和维护
|
||||
- 尽量使用标准库实现通用能力
|
||||
|
||||
## 总体风格
|
||||
|
||||
易语言风格代码强调“读代码像读中文说明”。
|
||||
|
||||
推荐：
|
||||
|
||||
```python
|
||||
import uuid
|
||||
|
||||
|
||||
def 取UUID() -> str:
|
||||
"""生成一个随机 UUID（文本形式）。"""
|
||||
return str(uuid.uuid4())
|
||||
```
|
||||
|
||||
不推荐：
|
||||
|
||||
```python
|
||||
def get_uuid():
|
||||
return uuid.uuid4()
|
||||
```
|
||||
|
||||
如果代码主要服务中文风格训练或中文使用者，优先使用中文命名；如果必须调用第三方库或系统 API，保留原始英文 API 名称，只在自定义封装层使用中文命名。
|
||||
|
||||
## 命名规范
|
||||
|
||||
### 函数命名
|
||||
|
||||
函数名应表达一个明确动作，通常采用“动词 + 对象”结构。
|
||||
|
||||
推荐形式：
|
||||
|
||||
- `取UUID`
|
||||
- `取时间戳`
|
||||
- `生成随机字符串`
|
||||
- `读取JSON文件`
|
||||
- `写入文本文件`
|
||||
- `计算MD5`
|
||||
- `文本_取左边`
|
||||
- `文本_取右边`
|
||||
- `文本_取中间`
|
||||
- `文件_是否存在`
|
||||
- `路径_拼接`
|
||||
- `异常_转中文提示`
|
||||
|
||||
常用动词约定：
|
||||
|
||||
- `取`：获取已有值或即时计算值，如 `取时间戳`
|
||||
- `生成`：创建新值，如 `生成随机字符串`
|
||||
- `读取`：从文件、网络、配置中取数据，如 `读取JSON文件`
|
||||
- `写入`：把数据保存到外部位置，如 `写入文本文件`
|
||||
- `转换` / `到`：类型转换，如 `文本到字节集`
|
||||
- `判断` / `是否`：返回布尔值，如 `文件_是否存在`
|
||||
- `计算`：摘要、统计、数值结果，如 `计算SHA256`
|
||||
- `删除`：移除内容，如 `文本_删左边`
|
||||
- `查找` / `寻找`：定位内容，如 `寻找文本`
|
||||
|
||||
### 变量命名
|
||||
|
||||
变量名应使用中文名词或名词短语，表达数据含义。
|
||||
|
||||
推荐：
|
||||
|
||||
```python
|
||||
文件路径 = "config.json"
|
||||
文本内容 = "你好世界"
|
||||
哈希对象 = hashlib.md5()
|
||||
当前时间 = datetime.datetime.now()
|
||||
随机文本 = 生成随机字符串(16)
|
||||
```
|
||||
|
||||
避免：
|
||||
|
||||
```python
|
||||
a = "config.json"
|
||||
txt = "你好世界"
|
||||
hash_obj = hashlib.md5()
|
||||
```
|
||||
|
||||
允许在非常局部的循环中使用短变量，但更推荐中文语义变量：
|
||||
|
||||
```python
|
||||
for 序号, 项目 in enumerate(项目列表, start=1):
|
||||
print(序号, 项目)
|
||||
```
|
||||
|
||||
### 类命名
|
||||
|
||||
类名使用中文名词，表达对象或工具集合。
|
||||
|
||||
推荐：
|
||||
|
||||
- `文本工具`
|
||||
- `文件工具`
|
||||
- `配置读取器`
|
||||
- `异常处理器`
|
||||
- `日期时间工具`
|
||||
|
||||
类中方法仍使用动词结构：
|
||||
|
||||
```python
|
||||
class 文本工具:
|
||||
def 取左边(self, 文本: str, 长度: int) -> str:
|
||||
return 文本[:长度]
|
||||
```
|
||||
|
||||
### 常量命名
|
||||
|
||||
常量使用清晰中文名，优先保持统一。
|
||||
|
||||
```python
|
||||
默认编码 = "utf-8"
|
||||
最大重试次数 = 3
|
||||
请求超时时间 = 10
|
||||
```
|
||||
|
||||
如果项目已有英文大写常量风格，可以保留：
|
||||
|
||||
```python
|
||||
DEFAULT_ENCODING = "utf-8"
|
||||
```
|
||||
|
||||
## 模块组织
|
||||
|
||||
一个文件应围绕一个主题组织。
|
||||
|
||||
推荐模块主题：
|
||||
|
||||
- 文本操作
|
||||
- 文件操作
|
||||
- 路径操作
|
||||
- 编码解码
|
||||
- JSON 操作
|
||||
- 时间日期
|
||||
- 哈希摘要
|
||||
- 随机数据
|
||||
- 异常处理
|
||||
- 网络请求
|
||||
- 配置读取
|
||||
|
||||
文件内部推荐顺序：
|
||||
|
||||
1. 标准库导入
|
||||
2. 第三方库导入
|
||||
3. 常量定义
|
||||
4. 工具函数
|
||||
5. 类定义
|
||||
6. `if __name__ == "__main__":` 示例或测试入口
|
||||
|
||||
示例：
|
||||
|
||||
```python
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
默认编码 = "utf-8"
|
||||
|
||||
|
||||
def 读取JSON文件(文件路径: str):
|
||||
"""读取 JSON 文件并返回解析后的对象。"""
|
||||
with open(文件路径, "r", encoding=默认编码) as 文件对象:
|
||||
return json.load(文件对象)
|
||||
|
||||
|
||||
def 写入JSON文件(文件路径: str, 数据) -> None:
|
||||
"""将对象写入 JSON 文件。"""
|
||||
Path(文件路径).parent.mkdir(parents=True, exist_ok=True)
|
||||
with open(文件路径, "w", encoding=默认编码) as 文件对象:
|
||||
json.dump(数据, 文件对象, ensure_ascii=False, indent=4)
|
||||
```
|
||||
|
||||
## 函数设计规范
|
||||
|
||||
函数应短小、明确、可复用。
|
||||
|
||||
要求：
|
||||
|
||||
- 一个函数只做一件事
|
||||
- 函数名能说明用途
|
||||
- 参数名使用中文，必要时加类型注解
|
||||
- 返回值类型尽量稳定
|
||||
- 不在工具函数里随意 `print`，除非函数职责就是输出
|
||||
- 不在函数里吞掉异常后返回含糊结果，除非函数名明确表达“安全”或“尝试”
|
||||
|
||||
推荐：
|
||||
|
||||
```python
|
||||
def 文本_取左边(文本: str, 长度: int) -> str:
|
||||
"""从左侧取指定长度的文本。"""
|
||||
if 长度 <= 0:
|
||||
return ""
|
||||
return 文本[:长度]
|
||||
```
|
||||
|
||||
不推荐：
|
||||
|
||||
```python
|
||||
def 处理(a, b):
|
||||
print(a[:b])
|
||||
```
|
||||
|
||||
## 注释和文档字符串
|
||||
|
||||
注释使用中文，解释“为什么这样做”或“边界条件”，不要重复代码本身。
|
||||
|
||||
推荐 docstring：
|
||||
|
||||
```python
|
||||
import hashlib
|
||||
|
||||
|
||||
def 计算MD5(文本内容: str) -> str:
|
||||
"""计算文本内容的 MD5 十六进制摘要。"""
|
||||
哈希对象 = hashlib.md5()
|
||||
哈希对象.update(文本内容.encode("utf-8"))
|
||||
return 哈希对象.hexdigest()
|
||||
```
|
||||
|
||||
复杂函数可以写参数说明：
|
||||
|
||||
```python
|
||||
def 生成随机字符串(长度: int, 包含数字: bool = True) -> str:
|
||||
"""
|
||||
生成指定长度的随机字符串。
|
||||
|
||||
参数:
|
||||
长度: 生成字符串的字符数量。
|
||||
包含数字: 是否允许结果中出现数字。
|
||||
"""
|
||||
```
|
||||
|
||||
避免无意义注释：
|
||||
|
||||
```python
|
||||
# 返回结果
|
||||
return 结果
|
||||
```
|
||||
|
||||
## 异常处理规范
|
||||
|
||||
默认让异常自然抛出，除非有明确的中文化、重试、默认值需求。
|
||||
|
||||
推荐显式异常：
|
||||
|
||||
```python
|
||||
def 读取文本文件(文件路径: str, 编码: str = "utf-8") -> str:
|
||||
"""读取文本文件内容。"""
|
||||
with open(文件路径, "r", encoding=编码) as 文件对象:
|
||||
return 文件对象.read()
|
||||
```
|
||||
|
||||
需要安全返回时，函数名要说明行为：
|
||||
|
||||
```python
|
||||
def 尝试读取文本文件(文件路径: str, 默认值: str = "") -> str:
|
||||
"""读取文本文件，失败时返回默认值。"""
|
||||
try:
|
||||
with open(文件路径, "r", encoding="utf-8") as 文件对象:
|
||||
return 文件对象.read()
|
||||
except OSError:
|
||||
return 默认值
|
||||
```
|
||||
|
||||
异常中文化函数应单独封装：
|
||||
|
||||
```python
|
||||
def 异常_转中文提示(异常对象: Exception) -> str:
|
||||
"""把常见 Python 异常转换为中文提示。"""
|
||||
异常类型 = type(异常对象).__name__
|
||||
原始信息 = str(异常对象)
|
||||
return f"{异常类型}：{原始信息}"
|
||||
```
|
||||
|
||||
## PEP8 格式规范
|
||||
|
||||
易语言风格只改变命名表达，不改变 Python 的格式底线。代码必须遵守 PEP8。
|
||||
|
||||
要求：
|
||||
|
||||
- 使用 4 个空格缩进
|
||||
- 顶层函数、类之间空 2 行
|
||||
- 类方法之间空 1 行
|
||||
- import 放在文件顶部
|
||||
- 标准库、第三方库、本地库分组导入
|
||||
- 行宽尽量控制在 88 到 100 个字符
|
||||
- 运算符两侧保留空格
|
||||
- 逗号后保留一个空格
|
||||
- 函数默认参数写作 `参数: 类型 = 默认值`
|
||||
- 文件末尾保留一个换行
|
||||
- 优先使用 `ruff format` 或 `black` 格式化
|
||||
|
||||
推荐：
|
||||
|
||||
```python
|
||||
import hashlib
|
||||
|
||||
|
||||
def 计算SHA256(文本内容: str) -> str:
|
||||
"""计算文本内容的 SHA256 摘要。"""
|
||||
哈希对象 = hashlib.sha256()
|
||||
哈希对象.update(文本内容.encode("utf-8"))
|
||||
return 哈希对象.hexdigest()
|
||||
```
|
||||
|
||||
不推荐：
|
||||
|
||||
```python
|
||||
import hashlib
|
||||
|
||||
def 计算SHA256(文本内容):
|
||||
哈希对象=hashlib.sha256();哈希对象.update(文本内容.encode('utf-8'));return 哈希对象.hexdigest()
|
||||
```
|
||||
|
||||
## 常用代码模板
|
||||
|
||||
### UUID
|
||||
|
||||
```python
|
||||
import uuid
|
||||
|
||||
|
||||
def 取UUID() -> str:
|
||||
"""生成随机 UUID 字符串。"""
|
||||
return str(uuid.uuid4())
|
||||
```
|
||||
|
||||
### 时间戳
|
||||
|
||||
```python
|
||||
import time
|
||||
|
||||
|
||||
def 取时间戳(毫秒: bool = False) -> int:
|
||||
"""获取当前时间戳。"""
|
||||
当前时间 = time.time()
|
||||
if 毫秒:
|
||||
return int(当前时间 * 1000)
|
||||
return int(当前时间)
|
||||
```
|
||||
|
||||
### 文本截取
|
||||
|
||||
```python
|
||||
def 文本_取中间(文本: str, 左标记: str, 右标记: str) -> str:
|
||||
"""提取两个标记之间的文本。"""
|
||||
左位置 = 文本.find(左标记)
|
||||
if 左位置 == -1:
|
||||
return ""
|
||||
|
||||
开始位置 = 左位置 + len(左标记)
|
||||
右位置 = 文本.find(右标记, 开始位置)
|
||||
if 右位置 == -1:
|
||||
return ""
|
||||
|
||||
return 文本[开始位置:右位置]
|
||||
```
|
||||
|
||||
### JSON 文件
|
||||
|
||||
```python
|
||||
import json
|
||||
|
||||
|
||||
def 读取JSON文件(文件路径: str):
|
||||
"""读取 JSON 文件并返回 Python 对象。"""
|
||||
with open(文件路径, "r", encoding="utf-8") as 文件对象:
|
||||
return json.load(文件对象)
|
||||
|
||||
|
||||
def 写入JSON文件(文件路径: str, 数据) -> None:
|
||||
"""把 Python 对象写入 JSON 文件。"""
|
||||
with open(文件路径, "w", encoding="utf-8") as 文件对象:
|
||||
json.dump(数据, 文件对象, ensure_ascii=False, indent=4)
|
||||
```
|
||||
|
||||
## 禁止事项
|
||||
|
||||
- 不要为了中文化牺牲 Python 语法正确性
|
||||
- 不要使用拼音代替中文命名
|
||||
- 不要把多个无关能力塞进一个函数
|
||||
- 不要在工具函数中随意打印调试信息
|
||||
- 不要保留明显错误的示例代码
|
||||
- 不要生成无法通过 `ast.parse` 的代码
|
||||
- 不要把第三方项目名写进通用风格规范
|
||||
- 不要使用 `from xxx import *` 作为通用模板
|
||||
|
||||
## 质量检查清单
|
||||
|
||||
提交或生成代码前检查：
|
||||
|
||||
- 函数名是否中文且能表达用途
|
||||
- 变量名是否清楚表达数据含义
|
||||
- 函数是否只做一件事
|
||||
- 是否使用标准库优先实现
|
||||
- 是否有必要的中文 docstring
|
||||
- 是否遵守 PEP8 缩进和空行
|
||||
- 是否通过格式化工具
|
||||
- 是否通过 Python 语法检查
|
||||
- 是否去除了无意义打印和临时代码
|
||||
- 是否没有依赖特定项目内部路径
|
||||
|
||||
## 风格一句话
|
||||
|
||||
用中文命名表达意图，用 Python 语法保证正确，用 PEP8 格式保证可维护。
|
||||
Reference in New Issue
Block a user