new-python-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python 项目初始化

Python Project Initialization

流程概述

Process Overview

确认项目信息 - 与用户交互确认项目名称和 Python 版本
初始化项目 - 使用 uv init 创建项目，启用 git 版本控制
配置代码规范检查 - 使用 pre-commit 管理并初始化代码规范检查 hooks，并应用相应的规范配置
配置测试框架 - 添加 pytest、pytest-cov 开发依赖
配置版本管理工具 - 配置 .gitignore 优化VCS管理，配置版本元信息，配置 bumpversion 进行语义化版本管理
添加常用开发工具 - 添加 ipython 用于本地调试
安装并验证 - 安装所有依赖并验证配置
更新README - 创建并更新README文件，添加项目使用说明
完成初始提交

Confirm Project Information - Interact with users to confirm project name and Python version
Initialize Project - Use uv init to create the project and enable git version control
Configure Code Style Checking - Use pre-commit to manage and initialize code style checking hooks, and apply corresponding specification configurations
Configure Testing Framework - Add pytest and pytest-cov as development dependencies
Configure Version Management Tools - Optimize VCS management by configuring .gitignore, set up version metadata, and configure bumpversion for semantic versioning
Add Common Development Tools - Add ipython for local debugging
Install and Verify - Install all dependencies and verify configurations
Update README - Create and update the README file with project usage instructions
Complete Initial Commit

Step 1: 确认项目信息

Step 1: Confirm Project Information

与用户确认以下信息：

项目名称 project_name: 默认使用当前目录名称
项目描述 project_description: 简短的项目描述信息，用于快速理解项目功能和定位
Python 版本 python_version: 推荐使用官方支持的版本（3.10及以上）

Confirm the following information with users:

Project Name (project_name): Defaults to the current directory name
Project Description (project_description): A short project description to quickly understand the project's function and positioning
Python Version (python_version): Recommended to use officially supported versions (3.10 and above)

Step 2: 初始化项目

Step 2: Initialize Project

使用 uv 初始化项目，启用 git 版本控制：

bash

uv init \
    # 项目名称
    --name=<project_name> \
    # 项目描述
    --description="<project_description>" \
    # 初始化 src/<project_name> 包目录
    --package \
    # 初始化 git
    --vcs=git \
    # Python 最低支持版本
    --python=<python_version>

Use uv to initialize the project and enable git version control:

bash

uv init \
    # Project name
    --name=<project_name> \
    # Project description
    --description="<project_description>" \
    # Initialize src/<project_name> package directory
    --package \
    # Initialize git
    --vcs=git \
    # Minimum supported Python version
    --python=<python_version>

Step 3: 配置代码规范检查

Step 3: Configure Code Style Checking

添加 pre-commit 及代码格式化工具：

bash

uv add --dev pre-commit black flake8 flake8-import-order ruff

将 assets/pre-commit-config.yaml 内容写入项目根目录的

.pre-commit-config.yaml

文件

将 assets/flake8.j2 模板应用到项目根目录的

.flake8

文件，替换变量

{{ project_name }}

为项目名称

安装 pre-commit hooks：

bash

uv run pre-commit install

Add pre-commit and code formatting tools:

bash

uv add --dev pre-commit black flake8 flake8-import-order ruff

Write the content of assets/pre-commit-config.yaml to the

.pre-commit-config.yaml

file in the project root directory

Apply the template assets/flake8.j2 to the

.flake8

file in the project root directory, replacing the variable

{{ project_name }}

with the project name

Install pre-commit hooks:

bash

uv run pre-commit install

Step 4: 配置测试框架

Step 4: Configure Testing Framework

添加 pytest 和 pytest-cov 开发依赖：

bash

uv add --dev pytest pytest-cov

创建 tests 目录和初始测试文件：

bash

mkdir -p tests
touch tests/__init__.py

在

pyproject.toml

中添加 pytest 配置：

toml

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*", "*Test"]
python_functions = ["test_*"]
addopts = [
    "-v",
    "--cov=src/<project_name>",
    "--cov-report=term-missing",
    "--tb=short",
]

[tool.coverage.run]
source = ["src/<project_name>"]
branch = true
omit = ["tests/*"]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "raise NotImplementedError",
    "if __name__ == .__main__.:",
]

Add pytest and pytest-cov as development dependencies:

bash

uv add --dev pytest pytest-cov

Create tests directory and initial test files:

bash

mkdir -p tests
touch tests/__init__.py

Add pytest configuration to

pyproject.toml

toml

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*", "*Test"]
python_functions = ["test_*"]
addopts = [
    "-v",
    "--cov=src/<project_name>",
    "--cov-report=term-missing",
    "--tb=short",
]

[tool.coverage.run]
source = ["src/<project_name>"]
branch = true
omit = ["tests/*"]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "raise NotImplementedError",
    "if __name__ == .__main__.:",
]

Step 5: 配置版本管理工具

Step 5: Configure Version Management Tools

添加 .gitignore

bash

curl https://raw.githubusercontent.com/github/gitignore/refs/heads/main/Python.gitignore -o .gitignore

添加 bumpversion 依赖：

bash

uv add --dev bumpversion

配置版本元信息

新建

src/<project_name>/_version.py

文件用于保存项目版本元信息

python

__version__ = "0.1.0"

将版本信息导出到项目包命名空间，调整

src/<project_name>/__init__.py

python

"""<project_name> package."""

from ._version import __version__  # noqa: F401

添加测试用例用于验证版本元信息获取

python

from <project_name> import __version__

def test_version():
    assert __version__

将 assets/bumpversion.cfg.j2 模板应用到项目根目录的

.bumpversion.cfg

文件，替换变量

{{ project_name }}

为项目名称

Add .gitignore

bash

curl https://raw.githubusercontent.com/github/gitignore/refs/heads/main/Python.gitignore -o .gitignore

Add bumpversion dependency:

bash

uv add --dev bumpversion

Configure Version Metadata

Create a

src/<project_name>/_version.py

file to store project version metadata

python

__version__ = "0.1.0"

Export version information to the project package namespace, adjust

src/<project_name>/__init__.py

python

"""<project_name> package."""

from ._version import __version__  # noqa: F401

Add test case to verify version metadata retrieval

python

from <project_name> import __version__

def test_version():
    assert __version__

Apply the template assets/bumpversion.cfg.j2 to the

.bumpversion.cfg

file in the project root directory, replacing the variable

{{ project_name }}

with the project name

Step 6: 添加常用开发工具

Step 6: Add Common Development Tools

bash

uv add --dev ipython

bash

uv add --dev ipython

Step 7: 安装并验证

Step 7: Install and Verify

安装所有依赖：

bash

uv sync

验证配置：

bash

undefined

Install all dependencies:

bash

uv sync

Verify configurations:

bash

undefined

验证 pytest

Verify pytest

uv run pytest

验证 pre-commit

Verify pre-commit

uv run pre-commit run --all-files

验证 bumpversion

Verify bumpversion

uv run bumpversion --help

验证版本元信息

Verify version metadata

uv run python -c 'from <project_name> import version; print(version)'

undefined

uv run python -c 'from <project_name> import version; print(version)'

undefined

Step 8: 更新README

Step 8: Update README

使用模板 assets/README.md.j2 生成项目 README 文件，替换以下变量：

```
{{ project_name }}
```
- 项目名称
```
{{ project_description }}
```
- 项目描述

将生成的内容写入项目根目录的

README.md

文件。

Generate the project README file using the template assets/README.md.j2, replacing the following variables:

```
{{ project_name }}
```
- Project name
```
{{ project_description }}
```
- Project description

Write the generated content to the

README.md

file in the project root directory.

Step 9: 完成初始提交

Step 9: Complete Initial Commit

bash

git add .
git commit -m "Initial project setup"

bash

git add .
git commit -m "Initial project setup"