python 项目结构规范

最近，在做一些python项目，发现以前的习惯很不好，很多脚本写的很随意，导致后面看的时候自己都忘记当时的思路了。因此，特复习下之前看过的项目结构化规范，顺便就在此处留个记录吧。

1. python项目仓库的通用结构

python项目仓库通常如下图示

README.md
LICENSE
setup.py
requirements.txt
helloword/__init__.py
helloword/core.py
helloword/usages.py
docs/conf.py
docs/index.md
tests/test_basic.py
tests/test_advanced.py

1. README.md
   介绍整个python项目，例如描述项目具体是做啥，怎么安装及其使用等信息。
2. LICENSE
   指明许可说明和授权，可参考http://choosealicense.com/
3. setup.py
   用于打包和发布管理。
   requirements.txt
   指明整个项目的所有依赖包
4. helloword/
   这个仓库的核心代码，如果简单也可以直接写成helloword.py。任意包含 __init__.py 文件的目录都被认为是一个Python包
5. docs/
   Python项目的参考文档
6. tests/
   python包的集合和单元测试

2. Python模块

Python的模块可以简单理解为一个python文件。可以通过 import 语句导入。
一些规范：

1. 模块名称要短、使用小写，并避免使用特殊符号，比如点(.) 和问号(?)
2. 不推荐在模块名中使用下划线，而是使用子模块
3. from modu import * 的代码较难阅读而且依赖独立性不足，通常使用 from modu import fun 或者 import modu

3. python包

Python的包可以简单理解为一个包含 init.py 文件的目录。
一些规范：

1. 如果 包内的模块和子包没有代码共享的需求，使用空白的 init.py 文件是正常 甚至好的做法
2. 导入深层嵌套的包可用这个方便的语法：import very.deep.module as mod

4. 编码规范

1. 一行一个声明语句，避免将两句独立分割的代码写在同一行。
2. 函数的参数可以使用四种不同的方式传递给函数（必选参数，关键字参数，任意参数列表，任意关键字参数字典）。主要遵循：
   易读（名字和参数无需解释）
   易改（添加新的关键字参数不会破坏代码的其他部分）
3. 任何不开放给客户端代码使用的方法或属性，应该有一个下划线前缀。这将保证更好的职责划分以及更容易对已有代码进行修改。
4. 在函数体中避免使用返回多个有意义的值. 因为当一个函数在其正常运行过程中有多个主要出口点时，它会变得难以调试其返回结果，所以保持单个出口点可能会更好。
5. 在下列场景中，使用集合或者字典而不是列表，通常会更好：
   （因为查找集合是利用了Python 中的『集合是可哈希』的特性）
   集合体中包含大量的项；
   你将在集合体中重复地查找项；
   没有重复的项。

最后放一下《Python之禅》

# Python之禅 by Tim Peters

优美胜于丑陋（Python 以编写优美的代码为目标）
明了胜于晦涩（优美的代码应当是明了的，命名规范，风格相似）
简洁胜于复杂（优美的代码应当是简洁的，不要有复杂的内部实现）
复杂胜于凌乱（如果复杂不可避免，那代码间也不能有难懂的关系，要保持接口简洁）
扁平胜于嵌套（优美的代码应当是扁平的，不能有太多的嵌套）
间隔胜于紧凑（优美的代码有适当的间隔，不要奢望一行代码解决问题）
可读性很重要（优美的代码是具备高可读性的）
即便假借特例的实用性之名，也不可违背这些规则（这些规则至高无上）
不要包容所有错误，除非您确定需要这样做（精准地捕获异常，不写 `except:pass` 风格的代码）
当存在多种可能，不要尝试去猜测
而是尽量找一种，最好是唯一一种明显的解决方案（如果不确定，就用穷举法）
虽然这并不容易，因为您不是 Python 之父（这里的 Dutch 是指 Guido ）
做也许好过不做，但不假思索就动手还不如不做（动手之前要细思量）
如果您无法向人描述您的方案，那肯定不是一个好方案；反之亦然（方案测评标准）
命名空间是一种绝妙的理念，我们应当多加利用（倡导与号召）

参考资料：
https://pythonguidecn.readthedocs.io/zh/latest/
https://learnku.com/docs/python-guide/2018/