# py-structure

**Repository Path**: allocator-normal/py-structure

## Basic Information

- **Project Name**: py-structure
- **Description**: python标准项目结构
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-07-02
- **Last Updated**: 2025-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# py-structure
规范的python项目组织结构,包含测试,打包等平时没有注意太多的部分

## 项目结构
python项目配置文件, 统一管理项目的依赖,构建,发布元数据以及运行入口. 官方guide: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/


## 运行环境配置

统一用环境变量, vscode的launch.json中配置本地debug的环境变量

## debug以及运行时启动方式

debug 在 vscode launch.json 配置两个launcher, 一个是运行整个app 本质上是fastapi dev xxx/main/py 这种debug方式可以热加载,代码修改马上就能看到
第二种是单个文件debug, 相当于直接运行单个文件测试
```json
{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "py-structure-all",
            "type": "debugpy",
            "request": "launch",
            "module": "fastapi",
            "cwd": "${workspaceFolder}",
            "console": "integratedTerminal",
            "args": [
                "dev",
                "py_structuure/main.py",
                "--host", "0.0.0.0",
                "--port", "8082"
            ],
            "env": {
                "OPENAI_BASE_URL": "https://api.deepseek.com",
                "OPENAI_API_KEY": "xxxx"
            }
        },
        {
            "name": "py-structure-single",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "env": {
                "OPENAI_BASE_URL": "https://api.deepseek.com",
                "OPENAI_API_KEY": "xxxx"
            }
        }
    ]
}
```

实际环境中运行时启动方式为:

这里fastapi run注意是将package看作路劲
```bash
fastapi run py_structure/main.py
```
或者使用uvicorn启动

uvicorn 启动是将package看作package

```bash
uvicorn py_structure.main:app
```

## 依赖管理(基于pyproject.toml)

主依赖的dev optional依赖都要安装

```bash
pip install -e .[dev]
```

同时项目也要维护requirements.txt文件, requirements.txt 是从toml的dependencies导出,为依赖版本锁定文件,把它视作只读文件,只能由toml中依赖导出,不允许主动修改.
依赖的修改只允许发生在pyproject.toml文件中,requirements.txt 只允许用如下的指令导出

导出主要依赖
```bash
pip-compile -o requirements.txt --no-header --no-annotate
```

导出主要依赖和optional dev依赖

```bash
pip-compile --extra dev -o requirements-dev.txt --no-header --no-annotate
```

pip-compile在pip-tools包中,它已经被添加到toml的optional dev依赖里面 上一步安装所有依赖后就可以使用这个指令

最佳做法是 requirements.txt 不允许修改,但是需要提交到github维护,每一次更新了toml的依赖需要重新生成以及提交到github.


## docker镜像构建

dockerfile中安装依赖使用上一步 pip-compile生成的requirements.txt(主要依赖包),文件里面记录的是纯粹的项目依赖包,docker镜像构建只需要这些依赖包

pip install -e . 除了依赖之外本项目也会添加包链接到当前项目目录, 这在构建镜像过程中不需要,构建镜像只需要纯粹的项目依赖包即可,所以才选择requirements.txt安装主依赖

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

## 项目测试
使用pytest lib 作为项目测试的首选lib 官方guide: https://docs.pytest.org/en/stable


## 打包发布

首先安装build包(可以放toml的optional dependencies里面)

```bash
python install build
```

然后执行

```bash
python -m build
```
会在dist 目录中打包成 xx.whl

```bash
dist/
├── py_structure-0.1.0-py3-none-any.whl
├── py_structure-0.1.0.tar.gz
```

安装whl包

```bash
pip install py_structure-0.1.0-py3-none-any.whl
```

上传到pypi让所有开发者都能使用

首先注册 PyPI 账号：https://pypi.org/account/register/

安装发布工具(可以放toml的optional dependencies里面)：

```bash
pip install twine
```

上传包,注意whl和tar包最好都上传

```bash
twine upload dist/*
```