# study_python

**Repository Path**: python_94/study_python

## Basic Information

- **Project Name**: study_python
- **Description**: python学习
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-26
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Python 项目开发环境指南

本文档旨在帮助团队成员快速搭建一致的项目开发环境，避免因环境差异导致的问题。

## 1. 环境管理工具：pyenv

本项目使用 `pyenv` 来管理多个 Python 解释器版本。  
pyenv：用于管理多个 Python 版本的工具，它允许你在同一台机器上轻松安装、切换和管理不同的 Python 版本

### 安装 pyenv (Windows)

1. 访问 `pyenv-win` 项目主页：[https://github.com/pyenv-win/pyenv-win](https://github.com/pyenv-win/pyenv-win)
2. 按照说明进行安装（通常涉及克隆仓库或使用安装程序，并设置环境变量）。
3. 安装 pyenv 教程参考：
    * 软件地址：https://pyenv-win.github.io/pyenv-win/
    * 软件安装步骤：https://www.jb51.net/python/3372140qk.htm 、https://blog.csdn.net/taogumo/article/details/148562192
    * https://juejin.cn/post/7520958078973509641

### 常用 pyenv 命令

| 命令                          | 说明                                            | 示例                      |
|:----------------------------|:----------------------------------------------|:------------------------|
| `pyenv versions`            | 列出所有已安装的 Python 版本                            | `pyenv versions`        |
| `pyenv install <version>`   | 安装指定版本的 Python                                | `pyenv install 3.10.11` |
| `pyenv uninstall <version>` | 卸载指定版本的 Python                                | `pyenv uninstall 3.7.4` |
| `pyenv global <version>`    | 设置全局默认的 Python 版本                             | `pyenv global 3.10.11`  |
| `pyenv local <version>`     | 在当前目录设置本地 Python 版本（会创建 `.python-version` 文件） | `pyenv local 3.13.5`    |

## 2. pip 包管理工具

pip是Python的包管理工具，通过pip可以查找、安装、卸载、更新Python的三方库或工具，macOS和Linux系统应该使用pip3
pip是Python解释器自带的（安装Python解释器时，默认情况下已经勾选了安装pip），不同版本可能会有点区别，可以在命令提示符或终端中通过pip
--version来确定是否已经拥有了pip

在默认情况下，pip会访问`https://pypi.org/simple/` 来获得三方库相关的数据，但是国内访问这个网站的速度并不是十分理想，因此国内用户可以使用豆瓣网提供的镜像来替代这个默认的下载源，操作如下所示。

```shell
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
```

验证配置：执行 pip config list命令，如果看到输出了你刚刚设置的 index-url，就说明配置已经成功生效了

pip常用命令：

* 安装与管理：
    * pip install <包名>              安装最新的第三方的包
    * pip install <包名>==<版本号>     安装指定版本的包
    * pip install --upgrade <包名>    将已安装的包升级到最新版本
    * pip uninstall <包名>            卸载指定的包
* 查看与检查：
    * pip search <包名>    根据名字查找需要的三方库
    * pip list 列出当前环境下所有已安装的包
    * pip show <包名>      显示某个已安装包的详细信息（如版本、位置等）
    * pip check 检查已安装的包之间是否存在依赖冲突
* 项目依赖管理：
    * pip freeze > requirements.txt 将当前环境的包列表导出到文件，用于备份或共享项目环境
    * pip install -r requirements.txt 根据文件列表批量安装包，用于快速重现项目环境
* 配置与优化：
    * pip config set global.index-url <镜像源地址>   永久设置国内镜像源，大幅提升下载速度

## 3. 项目配置文件说明

### `.python-version` 文件

* **来源**：由 `pyenv local <version>` 命令自动生成。
* **作用**：告诉 `pyenv` 和其他工具（如 PyCharm）在该目录及其子目录下应使用哪个 Python 版本。
  **请确保团队成员都安装了该文件指定的版本**

### `requirements.txt` 文件

* **来源**：**命令生成**
  。在项目虚拟环境（venv）激活的前提【在虚拟环境中安装完项目所需的所有依赖后】下，运行 `pip freeze > requirements.txt` 命令。
* **作用**：**冻结**项目依赖的所有第三方库及其**精确版本**。团队成员可通过 `pip install -r requirements.txt`
  一键安装所有依赖，确保环境一致。**此文件需加入版本控制。**

### `pyproject.toml` 文件

* **来源**：通常由现代 Python 包管理工具（如 `Black`, `Ruff`, `Poetry`, `Flit`）**手动创建和维护**，或由项目初始化时生成。
* **作用**：一个更现代的项目配置文件，用于声明项目元信息、构建系统要求以及（可选的）项目依赖。它比 `setup.py`
  更通用。依赖可以是模糊的范围（如 `requests >=2.25`），由工具来解析和锁定具体版本。

#### 安装 Black、Ruff

Black：强制统一的代码格式化工具，无配置选项，直接按 PEP 8 规范自动重写代码（如调整缩进、换行、引号等）。

Ruff：基于 Rust 的超高速 Linter + 格式化工具，10-100 倍于传统工具（Flake8/Black/isort），支持 800+ 规则，可自动修复未使用导入等问题

```shell
PS F:\JetBrains\PyCharm 2024.1.7\py_project\pythonProject> pip install black ruff
Collecting black
  Downloading black-25.1.0-cp313-cp313-win_amd64.whl.metadata (81 kB)
Requirement already satisfied: click>=8.0.0 in f:\python313\lib\site-packages (from black) (8.2.1)
Collecting mypy-extensions>=0.4.3 (from black)
  Downloading mypy_extensions-1.1.0-py3-none-any.whl.metadata (1.1 kB)
Collecting packaging>=22.0 (from black)
  Downloading packaging-25.0-py3-none-any.whl.metadata (3.3 kB)
Collecting pathspec>=0.9.0 (from black)
  Downloading pathspec-0.12.1-py3-none-any.whl.metadata (21 kB)
Collecting platformdirs>=2 (from black)
  Downloading platformdirs-4.3.8-py3-none-any.whl.metadata (12 kB)
Requirement already satisfied: colorama in f:\python313\lib\site-packages (from click>=8.0.0->black) (0.4.6)
Downloading black-25.1.0-cp313-cp313-win_amd64.whl (1.4 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.4/1.4 MB 2.8 MB/s eta 0:00:00
Downloading mypy_extensions-1.1.0-py3-none-any.whl (5.0 kB)
Downloading packaging-25.0-py3-none-any.whl (66 kB)
Downloading pathspec-0.12.1-py3-none-any.whl (31 kB)
Downloading platformdirs-4.3.8-py3-none-any.whl (18 kB)
Installing collected packages: platformdirs, pathspec, packaging, mypy-extensions, black
Successfully installed black-25.1.0 mypy-extensions-1.1.0 packaging-25.0 pathspec-0.12.1 platformdirs-4.3.8    
```

#### 验证 Black、Ruff 是否安装成功

检查 black 是否安装成功以及安装地址

```shell
PS F:\JetBrains\PyCharm 2024.1.7\py_project\pythonProject> black --version
black, 25.1.0 (compiled: yes)
Python (CPython) 3.13.5
PS F:\JetBrains\PyCharm 2024.1.7\py_project\pythonProject> python -m pip show blask | Select-String "Location"

Location: F:\Python313\Lib\site-packages
```

检查 ruff 是否安装成功以及安装地址

```shell
PS F:\JetBrains\PyCharm 2024.1.7\py_project\pythonProject> ruff --version
ruff 0.12.4
PS F:\JetBrains\PyCharm 2024.1.7\py_project\pythonProject>  python -m pip show ruff | Select-String "Location"     

Location: F:\Python313\Lib\site-packages
```

### `pyproject.toml` vs `requirements.txt`

* **`pyproject.toml`**：用于**声明**依赖和项目配置，是面向包管理工具的。
* **`requirements.txt`**：用于**精确复制**一个完整的环境，是面向部署和协作的。两者可以共存。

## 4. 关于 `environment` 目录

项目中出现的 `environment/` 目录**并非 Python 标准或通用约定**，其含义完全由项目开发者定义。

常见的用途可能包括：

1. **存放环境配置文件**：例如 `.env` 文件（用于 `python-dotenv` 包），将敏感信息（如数据库链接、API密钥）与代码分离。
   **注意：务必将这些配置文件添加到 `.gitignore` 中，并提供一个示例模板文件（如 `env.template`）供团队成员参考。**
2. **存放环境设置脚本**：例如用于不同操作系统（Windows/macOS/Linux）的脚本，用于自动设置环境变量、启动服务等。
3. **存放容器化相关配置**：如果项目使用 Docker，有时会在此目录存放与开发环境相关的 Docker Compose 配置文件。

**具体到本项目，请咨询项目创建者或查看该目录内的文件内容以确定其具体用途。**

## 5. 其他开发拿到项目后，初始化项目环境步骤

1. **安装 Python**: 确保已安装 `.python-version` 文件指定的 Python 版本：

```bach
pyenv install <版本号>
```

2. **创建虚拟环境**: 建议使用 PyCharm 自动创建，或在项目根目录手动创建：

```bach
python -m venv .venv
```

3. **激活虚拟环境**:

* **Windows (PowerShell)**: `.\.venv\Scripts\Activate.ps1`
* **Windows (CMD)**: `.\.venv\Scripts\activate.bat`
* **Windows (CMD)**: `.\venv\Scripts\activate.bat`
* **macOS/Linux**: `source .venv/bin/activate`

注释：虚拟环境激活后，命令行提示符前通常会显示 (.venv)，这是判断是否激活成功的最直观标志

4. **安装依赖**: 在激活虚拟环境后，安装项目所需依赖。

```bash
pip install -r requirements.txt
```