# 免责声明：
    本文内容主要是肥清大神的视频以及自己收集学习内容的整理笔记，目是主要是为了让象博主这样的老白能更好的学习编号，如有侵权，请联系博主进行删除。

1. 注释

# 注释<Comments>: 用来向用户提示或解释某些代码的作用和功能
    * 可以出现在代码中的任何位置
    * Python 解释器在执行代码时会忽略
# 在调试<Debug>程序时可以用来临时移除无用的代码
# 提高程序的可读性
# 一般情况下，合理的代码注释应该占源代码的 1/3 左右
    * 注释不一定要有
	* 只有必要时才写注释

1.1. 格式

# 以 # 开头 

1.2. 要求

# # 与注释之间用一个空格间隔
# 最多72 ~ 80 个字符/行
    * URL 除外
# 最好是一个完整的句子
# 变更代码时要注意更新注释

1.3. 种类

1.3.1. 内联注释

# 内联注释<Inline Comment>: 
    * 通常用于描述一行代码的目的/解析性的描述/提示/警告
    * 确保做开发时候的一些隐藏的功能/逻辑
    * 与在代码在一行
    * # 代码间隔两个空格

1.3.1.1. 约定

# PEP8 约定对内联注释的规定: 
    * 仅在必要时使用内联注释，否则避免
    * 它们应该与它们引用的代码位于同一行的末尾
    * 为了便于阅读，代码和注释之间应该至少有两个或多个空格
    * 与块注释类似，内联注释以<#>开头，然后是一个空格
    * 避免使用内联注释过度解释明显的逻辑

1.3.1.2. 实例

count = 100  # This is the number for caculating the books

1.3.2. 块注释

# 块注释<Block comments>: 
    * 通常是多行
    * 在代码之前
        * 为读者提供了现在代码片段的目的
        * 讲清楚 'What
    * 解析一些功能性的/细节性的内容
	    * 为什么用这个标题
        * 功能块架构的描述
        * 数据库的功能描述

1.3.2.1. 约定

# PEP8 约定了块注释的以下准则: 
    * 注释的缩进应该与它的代码块的缩进级别相匹配
    * 每个注释行都应以<#>开头，后跟一个空格，然后再开始文本
    * 多个段落应该用一个以<#>开头的空白注释行分隔，而不仅仅是一个空白行

1.3.2.2. 实例

# Add comment for your codes
# Block comment tutorial

from typing import Iterator

def read_lines_from_file(path: str) -> Iterator[str]:
    # Read every line from the given file,
    # it just handles the rows which is not blank,
    # it should ignore the newline character
    # 
    # By the way, it should not check the ecistence of the given file
    # let the invoker to handle the raises if it does not exists that file
    # 
    # the file readline document below
    # see: https://jupter-docker-stacks.readthedocs.io/en/lotest/using/selecting.html
	
	with open(path, 'r') as file:
        while line:= file.readline():
                line = line.strip()
                if line:
                    yield line
                    
file_path = 'demo.txt'
for line in read_lines_from_file(file_path):
    print(line)

2. DocString

# 文档字符串<DocStrings>是一种 Python 格式的字符串，用于解释文档程序，解释对应的功能如何使用或者操作帮助程序文档更加简单易懂
    * PEP 257 很清楚的解释了文档字符串的协议和用法
    * Python 中的动态类型特性使得文档字符串的使用变得非常重要
    * 可以使用 __doc__ 属性调用函数中的文档字符串

2.1. 格式

# 用一对三个连续的单引号<'''>或三个连续的双引号<""">来定义文档字符串

2.2. 位置

# 在 Python Class/模块/方法的首行

2.3. 实例

def difference(a: set, b: set) -> list:
    """
    :param a: 求差前一个集合
    :param b: 求差后一个集合
    :return:
    """
    pass

print(difference.__doc__)

    :param a: 求差前一个集合
    :param b: 求差后一个集合
    :return:

3. 注解

# 注解<annotations>: 启用 Python 中的类型提示功能, 向应用程序用户提供参数及其关联的数据类型
    * 在 PEP 3107 中在 Python 中引入的
    * 允许指定预期变量的类型
    * 允许指定任何有助于更好地了解数据所代表内容的元数据
    * 只是一种类型提示, 对运行实际上是没有影响
    * 在 Python 3.5+ 中，对类型和注解进行了相应的更新

3.1. 注解类型

3.1.1. 内置类

# Python 3.9 之后的版本在内置的容器类支持定义内部元素的具体类型

# None: 空值或不存在的值
# str: 字符串
# bytes: 字节
# bytearray: 字节数组
# int: 整型
# float: 浮点型
# bool: 布尔
# list: 列表
# tuple: 元组
# dict: 字典
# set: 集合
# frozenset: 不可变集合
# type1 | type2 | type3...: typing.Union[] 简化形式
    * 建议采用此模式

3.1.2. typing 模块

# typing.Any: 任意类型
# typing.AnyStr: 用于可接受 str 或 bytes 参数但不允许两者混用的函数
# typing.Union[X[, Y, ...]]: 联合类型
# typing.Optional[X]: 可选参数
    * Python 3.10 引入
# typing.ClassVar: 用于标注类变量 
# typing.LiteralString: 只包括字符串字面值
    * Python 3.11 添加
# typing.Self: 通常用于类中返回 self 的方法的返回值
    * 通常不用于注解形参
    * Python 3.11 添加

3.1.3. collections 模块

# collections.deque: 双端队列
# collections.defaultdict: 默认值字典
# collections.Counter: 计数器
# collections.ChainMap: 链映射

3.1.4. collections.abc 模块

# collections.abc.Generator: 生成器
# collections.abc.Iterable: 迭代对象
# collections.abc.Iterator: 迭代器
# collections.abc.Sequence: 只读序列
# collections.abc.MutableSequence: 可变序列
# collections.abc.Callable: 可调用对象
    * 通常用于注解函数类型
# collections.abc.Set: 只读集合 
# collections.abc.MutableSet: 可变集合
# collections.abc.Mapping: 映射类型
    * 键值对的类型
# collections.abc.MutableMapping: 可变映射
# collections.abc.MappingView: 映射视图
# collections.abc.KeysView: 映射键的视图
# collections.abc.ItemsView: 映射项目的视图
# collections.abc.ValuesView: 映射值的视图
# collections.abc.Awaitable: 可等待对象
# collections.abc.Coroutine: 协程对象
# collections.abc.AsyncIterable: 异步迭代对象
# collections.abc.AsyncIterator: 异步迭代器
# collections.abc.AsyncGenerator: 异步生成器
# collections.abc.Buffer: 缓冲区类型
    * bytes | bytearray | memoryview 字节序列的并集
	* Python 3.12 引入

3.1.5. contextlib 模块

# contextlib.AbstractContextManager: 
# contextlib.AbstractAsyncContextManager: 

3.1.6. re 模块

# re.Pattern:  
# re.Match: 

3.2. 格式

3.2.1. 变量

# 变量名: 注解类型[ = 默认值]
    * 要求: 
        * 变量名和冒号无空格
        * 冒号和注解类型间有一个空格
        * 默认值的 = 前后各有一个空格

3.2.2. 形参

# 形参名: 注解类型[ = 默认值]
    * 要求: 
        * 形参名和冒号无空格
        * 冒号和注解类型间有一个空格
        * 默认值的 = 前后各有一个空格

3.2.3. 返回值

# -> 注解类型: 
    * 要求: 
        * -> 前后各有一个空格
        * 注解类型和冒号之间无空格

3.3. __ annotations __

# 引入注解会自动添加的一个特殊属性<__annotations__>
    * 功能: 提供了一个 API 以字典形式访问已定义注解的名称-值对
    * 调用方式: 
        * function_name.__annotations__
        * class_name.__annotations__
    * 特性: 
        * 只能捕获被标注的参数
    * 实例: 
 # -*- coding: UTF-8 -*-


def foo(a: int, b: str, c=None) -> int:
    pass

print(foo.__annotations__)  # {'a': <class 'int'>, 'b': <class 'str'>, 'return': <class 'int'>}

3.4. 检查

3.4.1. Pylint

# 静态分析工具
# 主要用于检验编码风格是否符合 PEP-8 规范

3.4.1.1. 安装

3.4.1.1.1. Windows

# pip install pylint
    * 直接在 cmd 下使用
    * 若 pip 不可用, 安装最新版 Python，或者找到 pip 的安装脚本先装 pip
# 安装位置: Python 安装目录下的 /Scripts/ 下
    * 此路径自动添加到环境变量 PATH

3.4.1.1.2. Linux

# $ sudo pip install pylint 
    * 直接在 Terminal 中使用
# 安装位置: /usr/bin/pylint

3.4.1.2. 配置

# 以 PyCharm 2024.1.1 为例: 

# File > Settings... > Tools > External Tools

# Program: 指向 pylint 的实际目录
    * 此处以 Windows 为例
        * "C:\Programs\Python\Python312\Scripts\pylint.exe"
# Parameters: --output-format=parseable --disable=R --disable=C0102,C0103,C0111,C0301,C0302,C0303,C0304,C0305,W0120,W0123,W0401,W0603,W0612,W0614,W0621,W0622,W0703,E1003,E1101 $FilePath$
    * 根据情况选择 pylint 输出信息显示格式和要 disable 的项目
    * 为了防止 Pylint 打印找不到 配置文件的 warning
        * 可以在当前工程目录下新建一个空的文件，取名为 .pylintrc
        * 在上述参数中加入选项 --rcfile=path/to/.pylintrc 即可
# Working directory: $FileDir$

3.4.1.3. 评估代码质量

# 写完一个脚本后, 直接右键单击
# 选择 External Tools > Pylint
# 运行可得到当前代码质量和改进建议

3.4.2. MyPy

# 静态类型检查工具
# 

3.4.2.1. 安装

# pip install mypy

3.4.2.2. 配置

# 以 PyCharm 2024.1.1 为例: 

# File > Settings... > Tools > External Tools

# Program: 指向 mypy 的实际目录
    * 此处以 Windows 为例
        * "C:\Programs\Python\Python312\Scripts\mypy.exe"
# Parameters: $FilePath$
# Working directory: $FileDir$

3.4.2.3. 评估代码质量

# 写完一个脚本后, 直接右键单击
# 选择 External Tools > MyPy
# 运行可得到当前代码质量和改进建议

3.4.3. Black

# 静态检验工具
# Python 官方出品
# 检查代码是否符合 PEP8 规范
# 格式化整个文件或指定目录
# 使用方式相对简单

3.4.3.1. 安装

# pip install black

3.4.3.2. 配置

# 以 PyCharm 2024.1.1 为例: 

# File > Settings... > Tools > External Tools

# Program: 指向 black 的实际目录
    * 此处以 Windows 为例
        * "C:\Programs\Python\Python312\Scripts\black.exe"
# Parameters: $FilePath$
# Working directory: $FileDir$

3.4.3.3. 评估代码质量

# 写完一个脚本后, 直接右键单击
# 选择 External Tools > black
# 运行可得到当前代码质量和改进建议

3.4.4. Flake8

# 静态检验工具

# 检查代码是否符合 PEP8 规范

3.4.4.1. 安装

# pip install flake8

3.4.4.2. 配置

# 以 PyCharm 2024.1.1 为例: 

# File > Settings... > Tools > External Tools

# Program: 指向 mypy 的实际目录
    * 此处以 Windows 为例
        * "C:\Programs\Python\Python312\Scripts\flake8.exe"
# Parameters: $FilePath$
# Working directory: $FileDir$

3.4.4.3. 评估代码质量

# 写完一个脚本后, 直接右键单击
# 选择 External Tools > Flake8
# 运行可得到当前代码质量和改进建议

3. 命名约定

# 常量: 全是大写字母
# 类名: 驼峰式
# 其余: 小写字母

4. 布局

4.1. 空行

# 尽可能多用缩进和分行

4.1.1. 间隔两个空行

# 类与类之间
# 类与顶级函数之间

4.1.2. 间隔一个空行

# 类内部的方法之间
# 方法内部流程的各个步骤之间

4.2. 每行最大字符长度和分行符

# 最大字符长度: 79字符/行
# 分行符: \
    * 在要换行的位置直接回车
    * 一般在二元运算符之前进行分行

4.3. 缩进

# 用 4 个连续的<空格>代表缩进
# 优先使用 空格
	* 确保在不同编辑器之间的一致性
# 不允许 Tabs 和 空格 混用

4.3.1. 分行后缩进

4.3.1.1. 括号与参数在同一行

# 分行后参数与上一行参数起点对齐
foo = long_funciton_name(var_one, var_two,
                         var_three, var_four)

4.3.1.2. 括号与参数不在同一行

# 分行后参数缩进多一级
	* 与函数语句体区分开
def long_funciton_name(
		var_one, var_two, var_three, 
    	var_four):
    print(var_one)

4.3.1.3. 悬挂缩进

# 语句中除第 1 行外的语句都缩进
foo = long_funciton_name(
    var_one, var_two,
	var_three, var_four)

4.3.2. 技巧

# 条件语句的缩进
if (this_is_one_thing
   		and that_is_another_thing):
    do_something()

4.4. 定位闭合括号

# 指右括号

# 与上一行的第 1 个非空白字符对齐
my_list = [
    1, 2, 3,
    4, 5, 6,
	]

# 与语句最初始的字符对齐
my_list = [
    1, 2, 3, 
    4, 5, 6,
]

4.5. 表达式/语句中的空格

# 直接在括号内书写, 括号与内容间无空格
spam(ham[1], {egg: 2})

# 逗号结尾的也不要加空格
foo = (0,)

# 冒号/逗号/分号用来分隔语义时前面也不要加空格
if x == 4: print(x, y); x, y = y, x

# 切片操作时, 冒号两侧的间距要相等
	* 冒号两侧无空格
ham[1:9], ham[1:9:3], ham[:9:3], ham[1::3], ham[1:9:]
    * 冒号两侧空格相等
ham[1 : 9], ham[1 : 9 : 3], [: 9 : 3], ham[1 :: 3], ham[1 : 9:]

# 函数与参数括号间无空格
span(1)

# 索引/切片/键名的括号与相应变量间无空格
dct['key']
lst[0]
lst[:-1]

# 赋值操作两边各留一个空格
x = 1
y = 2

# 二元运算符/比较运算符两侧各有一个空格
i = i + 1
submitte += 1

# 使用具有不同优先级的运算符, 只在具有最低优先级的运算符两边添加空格
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)

# 函数定义中参数与类型之前要留空格
def munge(input: AnyStr):

# 返回值的 -> 两侧要各留一个空格
def munge(input: AnyStr) -> str:

# 返回值类型与冒号之前不留空格
def func() -> str:
    
# 函数定义中的关键字参数和默认值之间不留空格
def compley(real, image=0.0):
    
# 函数定义中, 注解类型和默认值之间的等号两侧各留一个空格
def mnuge(input: AnyStr = None, sep: Any = None, limit=1000):
    
# 避免增加尾部空格