---
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v6.0.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-added-large-files
- id: mixed-line-ending
args: [--fix=lf]
- repo: https://github.com/lyz-code/yamlfix
rev: 1.19.1
hooks:
- id: yamlfix
- repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
rev: v2.16.0
hooks:
- id: pretty-format-toml
args: [--autofix]
- repo: https://github.com/psf/black
rev: 26.1.0
hooks:
- id: black
language_version: python3.14
args: [--line-length=88]
- repo: https://github.com/pycqa/isort
rev: 7.0.0
hooks:
- id: isort
args: [--profile, black, --line-length=88]
- repo: https://github.com/pycqa/flake8
rev: 7.3.0
hooks:
- id: flake8
args: [--max-line-length=88, '--ignore=E203, E501, W503']创建 PyEC 项目
约 1283 字大约 4 分钟
2025-12-08
这一章的内容有点多,如果从未写过编程的项目,有些概念可能从来没有见过。不过不用担心,可以先按照命令一个一个执行,回过头来再看细节。
uv 是一个比较新的 Python 项目管理工具,它可以帮助我们快速地创建和管理 Python 项目。执行下面的命令,我们就可以得到一个新的pyec目录。
$ uv init --name pyec --package pyec可以用cd pyec将当前的目录切换到项目目录。此外,这个项目会用到一下 Python 的包来帮助我们进行开发:
ipython:一个交互式的 Python 解释器,它可以帮助我们快速地测试代码。pdbpp:一个改进版的 Python 调试器,它可以帮助我们在调试时更方便地查看变量的值。pre-commit:一个 Git 钩子工具,它可以帮助我们在提交代码前自动运行一些检查和格式化工具。pytest:一个测试框架,它可以帮助我们编写和运行测试用例。
使用以下命令来安装这些包:
$ uv add ipython pdbpp pre-commit pytest --group devPre-commit 是一个 Git 钩子工具,它可以帮助我们在提交代码前自动运行一些检查和格式化工具。我们先要创建一个.pre-commit-config.yaml文件,用于配置 Pre-commit 要运行的检查和格式化项目。内容如下:
为了让 Pre-commit 生效,首先要激活 Python 的虚拟环境。然后调用环境中的pre-commit。
$ source .venv/bin/activate # activate virtual environment
$ pre-commit install
$ pre-commit install-hooks
$ pre-commit run --all-files # run pre-commit on all files现在让我们看看项目目录的结构。这里省略了一些和项目关系不大的文件和目录。
├── .git
│ └── ...
├── .gitignore
├── .pre-commit-config.yaml
├── pyproject.toml
├── .python-version
├── README.md
└── src
└── pyec
└── __init__.pyGit 是一个版本控制工具,它可以帮助我们管理项目的代码。.git/目录包含了项目全部的版本控制信息,包括代码的历史记录、分支、标签等。我们刻意省略了目录中的具体内容,因为 Git 会自己管理里面的数据。在这个项目中我们最常用的功能只是为代码的改动保存历史记录,也就是看看我们到底改了什么。与之相关的命令有:
git add .:将所有文件添加到暂存区git diff:查看当前目录和暂存区的差异git commit -m "<message>":提交暂存区的文件到仓库,并且添加一条提交信息
.gitignore文件用于指定哪些文件或目录应该被 Git 忽略。它通常包含了一些临时文件、缓存文件、日志文件等。它告诉 Git 不要将这些文件添加到版本控制中。以下是它的内容。以#开头的行是注释,以/开头的行表示目录,其余表示文件。包含*和[]的行表示文件名的模式匹配。譬如*.py[oc],表示所有以.pyo或.pyc结尾的名字。
# Python-generated files
__pycache__/
*.py[oc]
build/
dist/
wheels/
*.egg-info
# Virtual environments
.venv
uv.lock再来看.python-version 文件,其中包含了项目的 Python 版本信息。
3.14README.md文件是项目的说明文档,它通常包含了项目的背景、功能、安装方法、使用方法等信息。目前它是空的。让我们添加一些内容。
# PyEC
A not so easy calculatorpyproject.toml文件是项目的配置文件,它包含了项目的元数据、依赖、脚本等信息。我们来观察一下它的内容。
[build-system]
build-backend = "uv_build"
requires = ["uv_build>=0.10.1,<0.11.0"]
[project]
authors = [
{name = "jiefeic", email = "jiefei.chen@gmail.com"}
]
dependencies = [
"ipython>=9.10.0",
"pdbpp>=0.12.0.post1",
"pre-commit>=4.5.1",
"pytest>=9.0.2"
]
description = "A not so easy calculator"
name = "pyec"
readme = "README.md"
requires-python = ">=3.14"
version = "0.1.0"
[project.scripts]
pyec = "pyec:main"这个文件中的每个[]称为一个 section。它们的位置是可以互换的,不影响结果。在[project]这个 section 当中,有个 description 是项目的一句话介绍。我们把它的内容改了。此外 dependecies 记录了项目依赖于其他 Python 包,也就是我们刚刚使用uv add安装的那些包。剩下比较重要的一个设置是[project.scripts]。它的意思是会创建一个名叫pyec的可执行脚本,它会调用pyec:main这个函数。
pyec = "pyec:main"现在,只剩下src/pyec/__init__.py文件。它里面只有一个main()函数,调用它就会打印出Hello from pyec!。
def main() -> None:
print("Hello from pyec!")我们项目的创建就完成了。只是修改了两处项目介绍性的文字。现在,让我们来试一下
$ uv run pyec
Hello from pyec!在这个过程中,uv 会做几件事情
- 创建一个
.venv/虚拟环境,如果不存在的话 - 安装项目依赖 dependencies 中指定的包
- 安装项目到虚拟环境中(会创建
pyec可执行脚本) - 运行
.venv/bin/pyec的命令 pyec的内容就是调用__init__.py文件中的main()函数。
这样,我们就完成了项目创建。现在,我们用git命令将已经有的代码提交。
$ git add .
$ git commit -m "init git repo"