【杂记】VS Code 设置 Python 文件模板

整理一个完整的 VS Code Python 文件模板设置教程：

VS Code 设置 Python 文件模板

方法一：用户代码片段（推荐）

1. 打开命令面板

   • Windows: Ctrl + Shift + P
   • Mac: Cmd + Shift + P
   • 输入 “Configure User Snippets”，选择 “Python”

2. 在打开的 python.json 文件中添加以下配置：

{
    "Python File Header": {
        "prefix": "header",
        "body": [
            "#!/usr/bin/env python",
            "# -*- coding: utf-8 -*-",
            "# @Time          : $CURRENT_YEAR/$CURRENT_MONTH/$CURRENT_DATE $CURRENT_HOUR:$CURRENT_MINUTE",
            "# @Author        : your_name",
            "# @Email         : your.email@example.com",
            "# @File          : $TM_FILENAME",
            "# @Description   : ${3:description}",
            "",
            "$0"
        ],
        "description": "Add Python file header"
    }
}

3. 使用方法
   • 新建 Python 文件
   • 输入 header 后按 Tab 键
   • 通过 Tab 键在不同字段间跳转填写

方法二：安装扩展

1. Python File Header 扩展

   • 打开 VS Code 扩展市场（Ctrl + Shift + X）
   • 搜索 “Python File Header”
   • 安装后可在设置中自定义模板格式

2. File Header Generator 扩展

   • 功能更丰富，支持多种语言
   • 可自定义快捷键
   • 支持更多变量和格式化选项

方法三：项目级模板设置

1. 创建模板文件

   • 在项目根目录创建 .vscode 文件夹
   • 创建 python.template 文件

2. 添加模板内容

#!/usr/bin/env python
# -*- coding: utf-8 -*-
# @Time          : ${CURRENT_YEAR}/${CURRENT_MONTH}/${CURRENT_DATE} ${CURRENT_HOUR}:${CURRENT_MINUTE}
# @Author        : ${USER}
# @Email         : your.email@example.com
# @File          : ${FILE_NAME}
# @Description   : 

VS Code 可用变量

常用的预定义变量：

• $CURRENT_YEAR: 当前年份
• $CURRENT_MONTH: 当前月份
• $CURRENT_DATE: 当前日期
• $CURRENT_HOUR: 当前小时
• $CURRENT_MINUTE: 当前分钟
• $TM_FILENAME: 当前文件名
• $TM_FILENAME_BASE: 不带扩展名的文件名
• $USER: 当前用户名

为现有项目添加文件头

对于已有的项目文件，可以使用 Python 脚本批量添加文件头：

#!/usr/bin/env python
# -*- coding: utf-8 -*-
from datetime import datetime
import os
import fileinput
import shutil
from pathlib import Path

def generate_header(filename):
    """生成文件头信息"""
    now = datetime.now()
    header = [
        "#!/usr/bin/env python",
        "# -*- coding: utf-8 -*-",
        f"# @Time          : {now.year}/{now.month}/{now.day} {now.hour}:{now.minute}",
        "# @Author        : jcfszxc",
        "# @Email         : jcfszxc.ai@gmail.com",
        f"# @File          : {filename}",
        "# @Description   : ",
        "\n"
    ]
    return "\n".join(header)

def add_header_to_file(file_path):
    """给单个文件添加头部信息"""
    # 创建临时文件
    temp_file = file_path.parent / (file_path.name + '.tmp')
    
    try:
        with open(file_path, 'r', encoding='utf-8') as original, \
             open(temp_file, 'w', encoding='utf-8') as temp:
            
            # 检查文件是否已经有header
            first_line = original.readline()
            original.seek(0)
            
            # 如果文件不是以shebang开头，则添加header
            if not first_line.startswith('#!/usr/bin/env python'):
                temp.write(generate_header(file_path.name))
            
            # 写入原文件内容
            for line in original:
                temp.write(line)
        
        # 替换原文件
        shutil.move(str(temp_file), str(file_path))
        print(f"成功添加header到: {file_path}")
        
    except Exception as e:
        print(f"处理文件 {file_path} 时出错: {str(e)}")
        if temp_file.exists():
            temp_file.unlink()

def process_directory(directory):
    """处理目录下所有的Python文件"""
    directory = Path(directory)
    
    # 遍历所有.py文件
    for py_file in directory.rglob('*.py'):
        # 跳过虚拟环境和隐藏目录
        if any(part.startswith('.') or part == 'venv' or part == 'env' \
            for part in py_file.parts):
            continue
        
        add_header_to_file(py_file)

if __name__ == '__main__':
    directory = input("请输入要处理的项目目录路径: ")
    process_directory(directory)
    print("处理完成!")

注意事项

1. 代码片段方法的优点：

   • 一次配置，永久生效
   • 跨项目通用
   • 支持 Tab 键导航
   • 可自定义变量

2. 最佳实践：

   • 保持团队统一的文件头格式
   • 定期更新文档信息
   • 确保描述信息的完整性
   • 考虑版权信息的添加

3. 常见问题：

   • 编码声明在 Python 3 中可选
   • shebang 行在 Windows 中可选
   • 注意时间格式的一致性