python3.8 typing 使用规范

参考来源：https://docs.python.org/zh-cn/3.8/library/typing.html

• 入参出参规则一致
• 简单变量直接返回，例如：str int float bool
• 若返回代码中或第三方包的类/实例，则使用导入类

class A:
    pass

def test() -> A:
    a = A()
    return a

• 若代码中对象(变量/类/方法)不可变更/继承，则必须尽量（最好、必须）使用Final声明，详情使用方法参阅https://blog.csdn.net/youzi_yun/article/details/108983855, 来自官方文档：https://www.python.org/dev/peps/pep-0591/
• 常用类型：

内置：str int float bool list dict tuple set
from typing import List, Dict, Tuple, Set, Union, Optional, Any, Final

• python3.8支持从typing导入的类型如下：

##  常用的
'Dict',  # Dict[str, int], 必须写明key、value的类型，尽量保证value类型一致，如果不一致，则直接返回dict 或 Dict[str, Any] 或 注明可能的类型，比如：Dict[str, Union[str, int]]
'Set', # Set[int], 变量必须是同一类型，如果不一致，则直接返回set 或 Set[Any] 或 注明可能的类型，比如：Set[Union[str, int]]
'List',  # List[int], 变量必须是同一类型，如果不一致，则直接返回list 或 List[Any]或注明可能的类型，比如：List[Union[str, int]]
'Tuple',  # Tuple[int, str] 代表返回(1, '1'), 如果有多个同类型返回值，可写为Tuple[str, ...], 若返回数量类型都很多，可直接返回tuple 或 Tuple[Any] 或 注明可能的类型，比如：Tuple[Union[str, int], ...]
'FrozenSet',  # 冻结的集合，冻结后集合不能再添加或删除任何元素。FrozenSet[int] 变量必须是同一类型，如果不一致，则直接返回frozenset 或 FrozenSet[Any] 或 注明可能的类型，比如：FrozenSet[Union[str, int]]

## 特殊类型
'Any',  # Any 是一种特殊的类型。静态类型检查器将所有类型视为与 Any 兼容，反之亦然， Any 也与所有类型相兼容。
'Callable',  # 期望特定签名的回调函数的框架可以将类型标注为 Callable[[Arg1Type, Arg2Type], ReturnType]。
    def feeder(get_next_item: Callable[[int], str]) -> None:
        pass
'ClassVar',  # 用于标记类变量的特殊类型构造。
    class Starship:
        stats: ClassVar[Dict[str, int]] = {} # class variable
        damage: int = 10  # instance variable
    
'Final',  # 最终限定符，声明不应重写的方法；声明一个类不应该被子类化；声明不应重新分配变量或属性。
    类型检查器禁止对象在子类中被覆盖。
    Final只能用作赋值或变量注释中的最外面的类型。在其他任何位置使用它都是错误的
    Final不能在函数参数的注释中使用
    eg:
    MAX_SIZE: Final = 9000
    MAX_SIZE += 1  # Error reported by type checker
'ForwardRef',  # 用于字符串正向引用的内部类型表示的类。例如，List["SomeClass"]被隐式转换为 List[ForwardRef("SomeClass")]。此类不应由用户实例。
'Generic',  # 泛型类：用户定义的类
'Literal',  # 不能被子类化，检查固定值或几个固定值之一，可用于类型检查。
    eg:
    def validate_simple(data: Any) -> Literal[True]:  # always returns True
        ...

    MODE = Literal['r', 'rb', 'w', 'wb']
    def open_helper(file: str, mode: MODE) -> str:
        ...
'Optional',  # Optional[X]等价于Union[X, None]
'Protocol',  # 协议类的基类
'Tuple',  # Tuple[int, str] 代表返回(1, '1'), 如果有多个同类型返回值，可写为Tuple[str, ...], 若返回数量类型都很多，可直接返回tuple或Tuple[Any]或 注明可能的类型，比如：Tuple[Union[str, int], ...]
'Type',
'TypeVar',  # 类型变量
'Union',  # 联合类型 Union[X, Y] 意味着：要么是X，要么是Y

## 来自collections
'ChainMap',  # collections.ChainMap
'Counter',  # collections.Counter
'Deque',  # collections.deque
'DefaultDict', #  collections.defaultdict DefaultDict[str, int] 必须写明key、value的类型，尽量保证value类型一致，如果不一致，则直接返回DefaultDict 或 DefaultDict[str, Any] 或 注明可能的类型，比如：DefaultDict[str, Union[str, int]]
'OrderedDict',  # collections.OrderedDict  OrderedDict[str, int]  # 必须写明key、value的类型，尽量保证value类型一致，如果不一致，则直接返回OrderedDict 或 OrderedDict[str, Any] 或 注明可能的类型，比如：OrderedDict[str, Union[str, int]]
'Generator',  # collections.abc.Generator
'NamedTuple',  # Not really a type.
'TypedDict',  # Not really a type.

## ABCs (来自 collections.abc).
'AbstractSet',  # collections.abc.Set.
'ByteString',
'Container',
'ContextManager',
'Hashable',
'ItemsView',
'Iterable',
'Iterator',
'KeysView',
'Mapping',
'MappingView',
'MutableMapping',
'MutableSequence',
'MutableSet',
'Sequence',  # 鸭子类型，可以看做是任何带有.__len__()和.__getitem__()实现的对象
'Sized',
'ValuesView',
'Awaitable',
'AsyncIterator',
'AsyncIterable',
'Coroutine',
'Collection',
'AsyncGenerator',
'AsyncContextManager',
'Reversible',
'SupportsAbs',
'SupportsBytes',
'SupportsComplex',
'SupportsFloat',
'SupportsIndex',
'SupportsInt',
'SupportsRound',

# One-off things.
'AnyStr',
'cast',
'final',
'get_args',
'get_origin',
'get_type_hints',
'NewType',  # 使用 NewType() 辅助函数创建不同的类型 UserId = NewType('UserId', int) 
'no_type_check',
'no_type_check_decorator',
'NoReturn',  # 注释那些从未期望正常返回的函数，比如方法中都是raise
'overload',
'runtime_checkable',
'Text',
'TYPE_CHECKING',

• 若需要获得向前引用， 可使用from future import annotations

from __future__ import annotations


class Deck:
    @classmethod
    def create(cls, shuffle: bool = False) -> Deck:
        pass

• 通常不应注释self或cls参数
• 注释*args和**kwargs，应该注释每个可能的关键字参数的类型

def test(*args: str, **kwargs: Union[str, int]):
    pass

test('', a=1, b='')