python软件开发目录设计规范

资料来源：https://book.apeland.cn/details/339/

软件开发目录

• 目录可参考：https://github.com/pallets/flask

Foo/
|-- bin/
|   |-- foo
|
|-- src/
|   |-- tests/
|   |   |-- __init__.py
|   |   |-- test_main.py
|   |
|   |-- __init__.py
|   |-- main.py
|
|-- docs/
|   |
|   |-- abc.rst
|
|-- conf.py
|-- setup.py
|-- requirements.txt
|-- README

• bin/: 存放项目的一些可执行文件，当然你可以起名script/之类的也行。

• src/: 存放项目的所有源代码。(1) 源代码中的所有模块、包都应该放在此目录。不要置于顶层目录。(2) 其子目录tests/存放单元测试代码； (3) 程序的入口最好命名为main.py。

• docs/: 存放一些文档。

• setup.py: 安装、部署、打包的脚本。

• requirements.txt: 存放软件依赖的外部Python包列表。

• README: 项目说明文件。

• conf.py:配置文件

README

这个我觉得是每个项目都应该有的一个文件，目的是能简要描述该项目的信息，让读者快速了解这个项目。

它需要说明以下几个事项:

• 软件定位，软件的基本功能。
• 运行代码的方法: 安装环境、启动命令等。
• 简要的使用说明。
• 代码目录结构说明，更详细点可以说明软件的基本原理。
• 常见问题说明。

requirements.txt

这个文件存在的目的是:

• 方便开发者维护软件的包依赖。将开发过程中新增的包添加进这个列表中，避免在 setup.py 安装依赖时漏掉软件包。
• 方便读者明确项目使用了哪些Python包。
• 如下所示

#
# This file is autogenerated by pip-compile
# To update, run:
#
#    pip-compile requirements/dev.in
#
alabaster==0.7.12         # via sphinx
appdirs==1.4.4            # via virtualenv
attrs==20.2.0             # via pytest
babel==2.8.0              # via sphinx
blinker==1.4              # via -r requirements/tests.in
certifi==2020.6.20        # via requests
cfgv==3.2.0               # via pre-commit
chardet==3.0.4            # via requests
click==7.1.2              # via pip-tools
distlib==0.3.1            # via virtualenv
docutils==0.16            # via sphinx
filelock==3.0.12          # via tox, virtualenv
greenlet==0.4.17          # via -r requirements/tests.in
identify==1.5.6           # via pre-commit
idna==2.10                # via requests
imagesize==1.2.0          # via sphinx
iniconfig==1.1.1          # via pytest
jinja2==2.11.2            # via sphinx
markupsafe==1.1.1         # via jinja2
nodeenv==1.5.0            # via pre-commit
packaging==20.4           # via -r requirements/docs.in, pallets-sphinx-themes, pytest, sphinx, tox
pallets-sphinx-themes==1.2.3  # via -r requirements/docs.in
pip-tools==5.3.1          # via -r requirements/dev.in
pluggy==0.13.1            # via pytest, tox
pre-commit==2.8.2         # via -r requirements/dev.in
py==1.9.0                 # via pytest, tox
pygments==2.7.2           # via sphinx, sphinx-tabs
pyparsing==2.4.7          # via packaging
pytest==6.1.2             # via -r requirements/tests.in
python-dotenv==0.15.0     # via -r requirements/tests.in
pytz==2020.1              # via babel
pyyaml==5.3.1             # via pre-commit
requests==2.24.0          # via sphinx
six==1.15.0               # via packaging, pip-tools, tox, virtualenv
snowballstemmer==2.0.0    # via sphinx
sphinx-issues==1.2.0      # via -r requirements/docs.in
sphinx-tabs==1.3.0        # via -r requirements/docs.in
sphinx==3.2.1             # via -r requirements/docs.in, pallets-sphinx-themes, sphinx-issues, sphinx-tabs, sphinxcontrib-log-cabinet
sphinxcontrib-applehelp==1.0.2  # via sphinx
sphinxcontrib-devhelp==1.0.2  # via sphinx
sphinxcontrib-htmlhelp==1.0.3  # via sphinx
sphinxcontrib-jsmath==1.0.1  # via sphinx
sphinxcontrib-log-cabinet==1.0.1  # via -r requirements/docs.in
sphinxcontrib-qthelp==1.0.3  # via sphinx
sphinxcontrib-serializinghtml==1.1.4  # via sphinx
toml==0.10.2              # via pre-commit, pytest, tox
tox==3.20.1               # via -r requirements/dev.in
urllib3==1.25.11          # via requests
virtualenv==20.1.0        # via pre-commit, tox

# The following packages are considered to be unsafe in a requirements file:
# pip
# setuptools

setup.py

• 一般来说，用setup.py来管理代码的打包、安装、部署问题。业界标准的写法是用Python流行的打包工具setuptools来管理这些事情
• 示例1

from setuptools import find_packages, setup

setup(
    name='pkDemo',
    version='0.1',
    install_requires=[
        "Werkzeug>=0.15",
        "Jinja2>=2.10.1",
        "itsdangerous>=0.24",
        "click>=5.1",
    ],
)

• 示例2

from setuptools import find_packages, setup

setup(
    name='pkDemo',
    version='0.1',
    packages=find_packages(),
)

conf.py

• 配置文件，可以.ini或者.yaml格式，看项目需要