python类元编程示例-使用类型注解来检查转换属性值的类框架

用三种方式实现使用类型注解来检查转换属性值的类框架

1 __init_subclass__方式

1.1 代码实现

from collections.abc import Callable  # <1>
from typing import Any, NoReturn, get_type_hints
from typing import Dict, Type

class Field:
    def __init__(self, name: str, constructor: Callable) -> None:  # <2>
        if not callable(constructor) or constructor is type(None):  # <3>
            raise TypeError(f'{name!r} type hint must be callable')
        self.name = name
        self.constructor = constructor

    def __set__(self, instance: Any, value: Any) -> None:
        if value is ...:  # <4>
            value = self.constructor()
        else:
            try:
                value = self.constructor(value)  # <5>
            except (TypeError, ValueError) as e:  # <6>
                type_name = self.constructor.__name__
                msg = f'{value!r} is not compatible with {self.name}:{type_name}'
                raise TypeError(msg) from e
        instance.__dict__[self.name] = value  # <7>

class Checked:
    @classmethod
    def _fields(cls) -> Dict[str, type]:  # <1>
        return get_type_hints(cls)

    def __init_subclass__(subclass) -> None:  # <2>
        super().__init_subclass__()           # <3>
        for name, constructor in subclass._fields().items():   # <4>
            setattr(subclass, name, Field(name, constructor))  # <5>

    def __init__(self, **kwargs: Any) -> None:
        for name in self._fields():             # <6>
            value = kwargs.pop(name, ...)       # <7>
            setattr(self, name, value)          # <8>
        if kwargs:                              # <9>
            self.__flag_unknown_attrs(*kwargs)  # <10>

 
    def __setattr__(self, name: str, value: Any) -> None:  # <1>
        if name in self._fields():              # <2>
            cls = self.__class__
            descriptor = getattr(cls, name)
            descriptor.__set__(self, value)     # <3>
        else:                                   # <4>
            self.__flag_unknown_attrs(name)

    def __flag_unknown_attrs(self, *names: str) -> NoReturn:  # <5>
        plural = 's' if len(names) > 1 else ''
        extra = ', '.join(f'{name!r}' for name in names)
        cls_name = repr(self.__class__.__name__)
        raise AttributeError(f'{cls_name} object has no attribute{plural} {extra}')

    def _asdict(self) -> Dict[str, Any]:  # <6>
        return {
            name: getattr(self, name)
            for name, attr in self.__class__.__dict__.items()
            if isinstance(attr, Field)
        }

    def __repr__(self) -> str:  # <7>
        kwargs = ', '.join(
            f'{key}={value!r}' for key, value in self._asdict().items()
        )
        return f'{self.__class__.__name__}({kwargs})'

#!/usr/bin/env python3

from checkedlib import Checked

class Movie(Checked):
    title: str
    year: int
    box_office: float


if __name__ == '__main__':
    movie = Movie(title='The Godfather', year=1972, box_office=137)
    print(movie.title)
    print(movie)
    try:
        # remove the "type: ignore" comment to see Mypy error
        movie.year = 'MCMLXXII'  # type: ignore
    except TypeError as e:
        print(e)
    try:
        blockbuster = Movie(title='Avatar', year=2009, box_office='billions')
    except TypeError as e:
        print(e)

checked_demo.py执行结果

The Godfather
Movie(title='The Godfather', year=1972, box_office=137.0)
'MCMLXXII' is not compatible with year:int
'billions' is not compatible with box_office:float

A Checked subclass definition requires that keyword arguments are
used to create an instance, and provides a nice __repr__::

>>> class Movie(Checked):  # <1>
...     title: str  # <2>
...     year: int
...     box_office: float
...
>>> movie = Movie(title='The Godfather', year=1972, box_office=137)  # <3>
>>> movie.title
'The Godfather'
>>> movie  # <4>
Movie(title='The Godfather', year=1972, box_office=137.0)

The type of arguments is runtime checked during instantiation and when an attribute is set::

>>> blockbuster = Movie(title='Avatar', year=2009, box_office='billions')
Traceback (most recent call last):
  ...
TypeError: 'billions' is not compatible with box_office:float
>>> movie.year = 'MCMLXXII'
Traceback (most recent call last):
  ...
TypeError: 'MCMLXXII' is not compatible with year:int

Attributes not passed as arguments to the constructor are initialized with default values::

>>> Movie(title='Life of Brian')
Movie(title='Life of Brian', year=0, box_office=0.0)

Providing extra arguments to the constructor is not allowed::

>>> blockbuster = Movie(title='Avatar', year=2009, box_office=2000,
...                     director='James Cameron')
Traceback (most recent call last):
  ...
AttributeError: 'Movie' object has no attribute 'director'

Creating new attributes at runtime is restricted as well::

>>> movie.director = 'Francis Ford Coppola'
Traceback (most recent call last):
  ...
AttributeError: 'Movie' object has no attribute 'director'

The _asdict instance method creates a dict from the attributes
of a Movie object::

>>> movie._asdict()
{'title': 'The Godfather', 'year': 1972, 'box_office': 137.0}

2 代码解释

在这个例子中，__init_subclass__ 和 __init__ 的调用顺序和作用域不同，它们各自处理类和实例级别的逻辑。

调用顺序

• __init_subclass__ 是在子类定义时自动调用的。这发生在任何实例被创建之前，仅在类定义期间触发一次。因此，当定义一个继承了 Checked 类的新类时，__init_subclass__ 将被调用来为这个新类设置 Field 描述符。
• __init__ 是在创建类的一个实例时调用的。每次通过类（例如 Checked 的子类）创建一个新对象时，都会调用 __init__ 方法。

不同的作用

• __init_subclass__ 在 Checked 类中用来自动为每个子类基于类型注解创建并设置 Field 实例。这些 Field 实例被设置为类属性，用来管理对应的实例属性。

• __init__ 的作用是初始化具体的实例。尽管 __init_subclass__ 已经设置了 Field 描述符，但是描述符需要在实例化时对具体的属性值进行管理和转换。__init__ 中的 setattr(self, name, value) 调用是用来初始化这些实例属性的值，并且触发 Field 描述符的 __set__ 方法，该方法负责使用提供的构造函数验证和转换这些值。尽管 __init_subclass__ 已经把注解自动创建并分配为 Field 实例，但这些 Field 实例实际上是作为类属性存在的。它们不直接持有数据，而是定义了如何通过其 __set__ 和 __get__ 方法处理数据。当你在 __init__ 方法中使用 setattr 时，实际上是触发了这些 Field 描述符的 __set__ 方法，它们负责根据构造函数规则来验证和转换赋予实例属性的值。这样，每个实例都可以持有独立的、已经经过验证和转换的数据。

• __init_subclass__ 设置了如何管理和验证属性（即通过 Field 描述符），但并未处理具体的属性值。

• __init__ 负责实际设置这些属性的初始值，并触发描述符来处理验证和转换的逻辑。

在调用 __init_subclass__ 之后类的结构会发生一些变化

在这个例子中，使用了 __init_subclass__ 方法和 Checked 类的框架，当 Movie 类被定义继承自 Checked 类时，__init_subclass__ 会自动被调用。这是在类级别发生的，即在任何 Movie 实例被创建之前。

当 Movie 类定义完成并触发 __init_subclass__ 方法时，这里发生的主要变化如下：

1. 自动属性创建：

   • 对于 Movie 类中定义的每个类型注解（title: str, year: int, box_office: float），__init_subclass__ 会从这些注解中获取信息，并为每个属性创建一个 Field 实例。

2. Field 实例作为类属性：

   • 这些 Field 实例不直接存储任何数据，而是作为描述符存在。描述符主要负责拦截对这些属性的访问和修改操作。
   • 对于每个属性，Field 描述符会设置如何创建（调用相应的类型构造器，如 str(), int(), float()），验证和存储其值。

__init_subclass__ 方法中的核心操作包括：

• 遍历从 get_type_hints 获取到的类型注解。
• 为每个属性（如 title, year, box_office）创建一个 Field 描述符，并将其作为类属性设置到 Movie 类上。

这样设置后的 Movie 类的结构将包含以下元素：

• title 属性关联到一个 Field 描述符，该描述符使用 str 作为构造函数。
• year 属性关联到一个 Field 描述符，该描述符使用 int 作为构造函数。
• box_office 属性关联到一个 Field 描述符，该描述符使用 float 作为构造函数。

类的行为

当创建 Movie 的实例并尝试设置这些属性时：

• 访问或修改这些属性将触发对应的 Field 描述符的 __set__ 或 __get__ 方法。
• 如果尝试设置的值类型不正确，Field 的 __set__ 方法将尝试转换值到声明的类型（如将字符串转换为整数）。如果转换失败，将抛出 TypeError。

2 类装饰器方式

2.1 代码实现

from collections.abc import Callable  # <1>
from typing import Any, NoReturn, get_type_hints
from typing import Dict, Type
class Field:
    def __init__(self, name: str, constructor: Callable) -> None:  # <2>
        if not callable(constructor) or constructor is type(None):
            raise TypeError(f'{name!r} type hint must be callable')
        self.name = name
        self.constructor = constructor

    def __set__(self, instance: Any, value: Any) -> None:  # <3>
        if value is ...:  # <4>
            value = self.constructor()
        else:
            try:
                value = self.constructor(value)  # <5>
            except (TypeError, ValueError) as e:
                type_name = self.constructor.__name__
                msg = (
                    f'{value!r} is not compatible with {self.name}:{type_name}'
                )
                raise TypeError(msg) from e
        instance.__dict__[self.name] = value  # <6>


# tag::CHECKED_DECORATOR[]
def checked(cls: type) -> type:  # <1>
    for name, constructor in _fields(cls).items():    # <2>
        setattr(cls, name, Field(name, constructor))  # <3>

    cls._fields = classmethod(_fields)  # type: ignore  # <4>

    instance_methods = (  # <5>
        __init__,
        __repr__,
        __setattr__,
        _asdict,
        __flag_unknown_attrs,
    )
    for method in instance_methods:  # <6>
        setattr(cls, method.__name__, method)

    return cls  # <7>

def _fields(cls: type) -> Dict[str, type]:
    return get_type_hints(cls)

def __init__(self: Any, **kwargs: Any) -> None:
    for name in self._fields():
        value = kwargs.pop(name, ...)
        setattr(self, name, value)
    if kwargs:
        self.__flag_unknown_attrs(*kwargs)

def __setattr__(self: Any, name: str, value: Any) -> None:
    if name in self._fields():
        cls = self.__class__
        descriptor = getattr(cls, name)
        descriptor.__set__(self, value)
    else:
        self.__flag_unknown_attrs(name)

def __flag_unknown_attrs(self: Any, *names: str) -> NoReturn:
    plural = 's' if len(names) > 1 else ''
    extra = ', '.join(f'{name!r}' for name in names)
    cls_name = repr(self.__class__.__name__)
    raise AttributeError(f'{cls_name} has no attribute{plural} {extra}')

def _asdict(self: Any) -> Dict[str, Any]:
    return {
        name: getattr(self, name)
        for name, attr in self.__class__.__dict__.items()
        if isinstance(attr, Field)
    }

def __repr__(self: Any) -> str:
    kwargs = ', '.join(
        f'{key}={value!r}' for key, value in self._asdict().items()
    )
    return f'{self.__class__.__name__}({kwargs})'

2.2 代码解释

这段代码实现了一个装饰器 checked，它为 Python 类添加强类型检查和自动属性管理的功能。该装饰器使用了 Python 的描述符协议和类型注解来自动验证和初始化类属性。下面逐部分解析代码的功能和工作方式：

Field 类

• 目的：Field 类用作属性描述符，主要负责设置和检索类实例的属性值，并确保值符合指定的类型。
• 构造方法 (__init__): 接收一个属性名和一个构造函数（类型）。如果构造函数不是可调用的或者是 None 类型，则抛出 TypeError。
• 设置方法 (__set__): 负责接收和处理对属性的赋值操作。如果值是 ...（省略符号），则使用构造函数（无参数）创建默认值。如果提供了值，则尝试使用构造函数将值转换为适当的类型。如果转换失败，会抛出 TypeError。
• 当从实例访问这个属性（如 instance.title）时，由于缺少 get 方法，Python 的解释器会直接从实例的 dict 字典中查找该属性的值，而不是调用描述符的 get 方法。描述符的 set 方法直接操作了托管实例的 dict 字典，将值存储在由 self.name 指定的键下。这意味着，尽管 Field 对象被设置为类的属性，它并没有拦截获取属性值的操作，而是允许直接从实例的字典中获取这些值。

checked 装饰器

• 功能：通过自动应用类型注解和属性管理，使类成为"检查型"类。
• 实现：
  • 自动属性管理：遍历类的类型注解，并为每个注解创建一个 Field 描述符，负责管理相应的属性。
  • 添加方法：将一系列方法（如 __init__, __repr__, __setattr__, _asdict, __flag_unknown_attrs）添加到被装饰的类中，以支持初始化、属性设置、字典转换和错误管理等功能。

实现的方法

• _fields：返回一个字典，包含类的所有类型注解。用于在类中创建 Field 描述符。
• __init__：负责初始化新创建的实例。从 kwargs 中提取每个字段的值，如果未提供，则使用省略符号触发默认构造。
• __setattr__：当尝试设置属性时，首先检查该属性是否由 Field 描述符管理。如果是，则使用描述符的 __set__ 方法来设置值，否则抛出属性错误。
• __flag_unknown_attrs：在尝试设置未知属性或当 __init__ 方法中存在额外的 kwargs 时被调用，抛出 AttributeError。
• _asdict：返回一个字典，包含由 Field 描述符管理的所有属性及其值。
• __repr__：生成类实例的字符串表示，展示所有通过 Field 管理的属性和它们的值。

使用 checked 装饰器处理子类后类的结构会发生的变化

属性管理
checked 装饰器会遍历子类中通过类型注解定义的属性，并为每个属性创建并分配一个 Field 描述符实例。这些 Field 描述符被设置为类属性，用于管理相应的实例属性。这意味着：

对于每个定义的属性，都会有一个 Field 实例与之关联，负责接收和处理对该属性的所有访问和修改请求。
这些 Field 描述符将确保属性值在设置时被正确地转换和验证，按照定义的类型进行。

方法增强
checked 装饰器还会将几个关键的方法添加到子类中：

init：用于正确地初始化新对象的实例属性，接受关键字参数，每个参数对应一个属性。如果属性未在初始化时提供，将使用其类型的默认构造函数来生成值。
setattr：重写此方法以确保对属性的设置通过 Field 描述符进行，从而利用 Field 的类型检查和转换功能。
repr：提供了一种格式化的方式来描述类实例，显示所有通过 Field 管理的属性和它们的值。
_asdict：允许将对象的属性转换成字典形式，便于查看和使用。
__flag_unknown_attrs：当尝试访问或设置不存在的属性时，此方法将被调用，抛出 AttributeError。

3 元类方式

3.1 代码实现

from collections.abc import Callable
from typing import Any, NoReturn, get_type_hints
from typing import Dict, Type

class Field:
    def __init__(self, name: str, constructor: Callable) -> None:
        if not callable(constructor) or constructor is type(None):
            raise TypeError(f'{name!r} type hint must be callable')
        self.name = name
        self.storage_name = '_' + name  # <1>
        self.constructor = constructor

    def __get__(self, instance, owner=None):
        if instance is None:  # <2>
            return self
        return getattr(instance, self.storage_name)  # <3>

    def __set__(self, instance: Any, value: Any) -> None:
        if value is ...:
            value = self.constructor()
        else:
            try:
                value = self.constructor(value)
            except (TypeError, ValueError) as e:
                type_name = self.constructor.__name__
                msg = f'{value!r} is not compatible with {self.name}:{type_name}'
                raise TypeError(msg) from e
        setattr(instance, self.storage_name, value)  # <4>

class CheckedMeta(type):

    def __new__(meta_cls, cls_name, bases, cls_dict):  # <1>
        if '__slots__' not in cls_dict:  # <2>
            slots = []
            type_hints = cls_dict.get('__annotations__', {})  # <3>
            for name, constructor in type_hints.items():   # <4>
                field = Field(name, constructor)  # <5>
                cls_dict[name] = field  # <6>
                slots.append(field.storage_name)  # <7>

            cls_dict['__slots__'] = slots  # <8>

        return super().__new__(
                meta_cls, cls_name, bases, cls_dict)  # <9>

class Checked(metaclass=CheckedMeta):
    __slots__ = ()  # skip CheckedMeta.__new__ processing

    @classmethod
    def _fields(cls) -> Dict[str, type]:
        return get_type_hints(cls)

    def __init__(self, **kwargs: Any) -> None:
        for name in self._fields():
            value = kwargs.pop(name, ...)
            setattr(self, name, value)
        if kwargs:
            self.__flag_unknown_attrs(*kwargs)

    def __flag_unknown_attrs(self, *names: str) -> NoReturn:
        plural = 's' if len(names) > 1 else ''
        extra = ', '.join(f'{name!r}' for name in names)
        cls_name = repr(self.__class__.__name__)
        raise AttributeError(f'{cls_name} object has no attribute{plural} {extra}')

    def _asdict(self) -> Dict[str, Any]:
        return {
            name: getattr(self, name)
            for name, attr in self.__class__.__dict__.items()
            if isinstance(attr, Field)
        }

    def __repr__(self) -> str:
        kwargs = ', '.join(
            f'{key}={value!r}' for key, value in self._asdict().items()
        )
        return f'{self.__class__.__name__}({kwargs})'

3.2 代码解释

这段代码定义了一个复杂的类装饰和类元编程机制，通过自定义描述符 Field 和元类 CheckedMeta 来自动化处理类属性的类型检查和初始化。这种机制可以用来创建严格类型化的数据结构，确保对象属性在设置时自动进行类型转换和验证。

Field 类

Field 用作属性描述符，负责管理属性的访问和设置。

• 初始化: 接收一个属性名称和一个构造函数。如果构造函数不是可调用的，则抛出异常。此外，它生成一个内部使用的存储属性名 (storage_name)，这通常是私有属性名。
• __get__ 方法: 用于获取属性值。如果 instance 为 None（通常在直接通过类访问属性时发生），返回描述符自身；否则从实例字典中返回相应的值。
• __set__ 方法: 设置属性值。如果值为特殊标记 ...，使用无参数的构造函数创建默认值；否则尝试使用构造函数转换提供的值。如果转换失败，抛出 TypeError。

CheckedMeta 元类

CheckedMeta 是一个元类，用于在创建类时自动处理属性的类型注解。

• __new__ 方法: 在创建类对象时被调用。
  • 检查是否已定义 __slots__，用于优化内存使用。
  • 从类定义中获取类型注解，并为每个注解创建一个 Field 描述符，将其添加到类字典中。
  • 为每个 Field 描述符生成的 storage_name 创建一个对应的槽。
  • 最后，使用修改后的类字典调用基类的 __new__ 方法创建类。

Checked 类

作为使用 CheckedMeta 元类的示例，这个类提供了以下功能：

• 初始化: 使用关键字参数初始化类的实例。通过 _fields 方法获取所有字段，并尝试从 kwargs 中提取对应的值进行设置。
• 属性设置 (__setattr__): 拦截所有属性赋值操作，确保通过 Field 描述符处理。
• 错误处理: 当尝试访问或设置未知属性时，__flag_unknown_attrs 方法会抛出 AttributeError。
• 字典转换 (_asdict): 提供一种将对象属性转换为字典的方法，便于外部访问和操作。
• 字符串表示 (__repr__): 生成对象的友好字符串表示，展示其所有属性和值。

使用 CheckedMeta 作为元类的子类结构

属性描述符 (Field 实例):

title 关联到一个 Field 实例，此实例用 str 作为构造函数进行类型检查和转换。
year 关联到一个 Field 实例，此实例用 int 作为构造函数进行类型检查和转换。
box_office 关联到一个 Field 实例，此实例用 float 作为构造函数进行类型检查和转换。

槽 (slots):

slots 包含 [‘_title’, ‘_year’, ‘_box_office’]，这些是实际存储属性值的内部属性名，避免了使用实例字典。

方法:

类继承自 Checked，因此拥有 init、setattr、_asdict、repr 和 __flag_unknown_attrs 等方法，这些方法提供了初始化、属性设置、错误处理、对象转字典和字符串表示的功能。

类属性与实例属性不能同名的原因

使用 __slots__ 在 Python 类中定义哪些属性名将作为实例属性存储，通常是为了节省内存和提高属性访问速度。当使用 __slots__ 时，Python 不再为每个实例创建一个 __dict__ 字典，而是为这些属性在内存中分配固定位置。

当使用描述符（如 Field 类实例）作为类属性，同时使用 __slots__ 指定实例属性时，需要注意的是：

1. 名称冲突：如果一个实例属性与一个类属性（描述符）同名，那么在访问这个属性时，描述符的逻辑将被触发，而不是直接访问实例属性。这是因为类属性（描述符）的访问级别比实例属性更高。

2. 描述符协议：描述符协议定义了如何通过描述符对象来控制属性的访问。在你的 Field 描述符的实现中，__get__ 和 __set__ 方法被用来管理访问和设置属性的行为。当你尝试访问一个属性，Python 首先检查该属性是否是一个描述符（即是否有 __get__ 或 __set__ 方法），如果是，则调用这些方法。

3. 存储位置：Field 描述符使用 storage_name （例如 '_title'）来在实例中存储数据，而不是直接使用 title。这是为了避免直接访问和修改这些属性，从而绕过描述符逻辑。

如何确保描述符的 __get__ 正确执行

为了确保 Field 描述符的 __get__ 方法能够正确执行，你应该这样访问属性：

• 当通过实例访问属性时（例如 movie_instance.title），将调用 Field 的 __get__ 方法，从实例中的 '_title' 位置取出值。
• 当直接通过类访问属性时（例如 Movie.title），__get__ 方法中的 instance is None 分支将被执行，这通常返回描述符自身或其他与类相关的信息。

4 元类的调用顺序

元类在 Python 中用于创建类，它们本身是类的类。

元类的关键方法

1. __prepare__:

   • 调用时机: 在类体被执行前调用。
   • 功能: 返回一个映射对象，用于在类定义时存储类属性和方法的定义。通常返回的是一个字典，但可以覆盖为其他类型的映射对象。
   • 参数: 接受将要创建的类的名称和它的基类。
   • 返回值: 用于类体执行的命名空间。

2. __new__:

   • 调用时机: 在类的实例（即类对象本身）被创建时调用。
   • 功能: 负责实际创建类对象。它可以修改类的定义，添加、修改或删除属性，或者根据需要完全改变类的创建过程。
   • 参数: 元类、类名、基类元组、类字典（由 __prepare__ 返回的映射对象），还可以接收额外的关键字参数（如果在类定义中提供）。
   • 返回值: 返回一个新的类对象。

3. __init__:

   • 调用时机: 在类对象创建后被调用，用于初始化新创建的类对象。
   • 功能: 初始化新创建的类对象。与 __new__ 不同，__init__ 不返回任何值，它仅用于初始化操作。
   • 参数: 类对象、类名、基类元组、字典。

4. __init_subclass__:

   • 调用时机: 这是一个类方法，当类被继承时自动调用。
   • 功能: 用于在创建子类时执行初始化或其他配置工作。
   • 参数: 子类和任何在子类定义时传递的关键字参数。
   • 返回值: 通常无返回值，用于设置子类或进行检查。

调用顺序示例

假设我们有一个元类 Meta 和使用这个元类的类 MyClass：

class Meta(type):
    def __prepare__(name, bases, **kwargs):
        print("Meta.__prepare__ called")
        return super().__prepare__(name, bases, **kwargs)

    def __new__(cls, name, bases, namespace, **kwargs):
        print("Meta.__new__ called")
        return super().__new__(cls, name, bases, namespace, **kwargs)

    def __init__(cls, name, bases, namespace, **kwargs):
        print("Meta.__init__ called")
        super().__init__(name, bases, namespace, **kwargs)

    def __init_subclass__(cls, **kwargs):
        print("Meta.__init_subclass__ called")
        super().__init_subclass__(**kwargs)

class MyClass(metaclass=Meta):
    pass

class MySubClass(MyClass):
    pass

调用顺序为：

1. Meta.__prepare__ 被调用来准备 MyClass 的命名空间。
2. 类体 MyClass 执行。
3. Meta.__new__ 被调用来创建 MyClass 类对象。
4. Meta.__init__ 被调用来初始化 MyClass 类对象。
5. Meta.__init_subclass__ 被调用（如果在 MyClass 中定义）。
6. 当 MySubClass 被定义时，上述步骤（1-4）重复执行，此外，MyClass.__init_subclass__ 也会被调用来处理子类的创建。

参考《流程的python》第24章