创建 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 dev

Pre-commit 是一个 Git 钩子工具，它可以帮助我们在提交代码前自动运行一些检查和格式化工具。我们先要创建一个.pre-commit-config.yaml文件，用于配置 Pre-commit 要运行的检查和格式化项目。内容如下：

.pre-commit-config.yaml

---
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']

为了让 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__.py

Git 是一个版本控制工具，它可以帮助我们管理项目的代码。.git/目录包含了项目全部的版本控制信息，包括代码的历史记录、分支、标签等。我们刻意省略了目录中的具体内容，因为 Git 会自己管理里面的数据。在这个项目中我们最常用的功能只是为代码的改动保存历史记录，也就是看看我们到底改了什么。与之相关的命令有：

git add .：将所有文件添加到暂存区
git diff：查看当前目录和暂存区的差异
git commit -m "<message>"：提交暂存区的文件到仓库，并且添加一条提交信息

.gitignore文件用于指定哪些文件或目录应该被 Git 忽略。它通常包含了一些临时文件、缓存文件、日志文件等。它告诉 Git 不要将这些文件添加到版本控制中。以下是它的内容。以#开头的行是注释，以/开头的行表示目录，其余表示文件。包含*和[]的行表示文件名的模式匹配。譬如*.py[oc]，表示所有以.pyo或.pyc结尾的名字。

.gitignore

# Python-generated files
__pycache__/
*.py[oc]
build/
dist/
wheels/
*.egg-info

# Virtual environments
.venv

uv.lock

再来看.python-version 文件，其中包含了项目的 Python 版本信息。

.python-version

3.14

README.md文件是项目的说明文档，它通常包含了项目的背景、功能、安装方法、使用方法等信息。目前它是空的。让我们添加一些内容。

README.md

# PyEC

A not so easy calculator

pyproject.toml文件是项目的配置文件，它包含了项目的元数据、依赖、脚本等信息。我们来观察一下它的内容。

pyproject.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!。

src/pyec/__init__.py

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"