Python 特殊属性 __qualname__ 限定名

在 Python 中，definition.__qualname__ 是一个特殊属性，用于获取函数或方法的限定名称（qualified name）。限定名称包括了函数或方法所在的类的名称，对于嵌套函数或方法，也包括了其父函数或方法的名称。类、函数、方法、描述器或生成器实例的 qualified name。在 3.3 版本加入。

限定名称

一个以点号分隔的名称，显示从模块的全局作用域到该模块中定义的某个类、函数或方法的“路径”，相关定义见 PEP 3155（https://peps.python.org/pep-3155/）。对于最高层级的函数和类，限定名称与对象名称一致:

class C:
    class D:
        def meth(self):
            pass

C.__qualname__
# 'C'
C.D.__qualname__
# 'C.D'
C.D.meth.__qualname__
# 'C.D.meth'

当被用于引用模块时，完整限定名称 意为标示该模块的以点号分隔的整个路径，其中包含其所有的父包，例如 email.mime.text:

import email.mime.text
email.mime.text.__name__
# 'email.mime.text'

在 Python 中，限定名称（qualified name）是指一个对象的完全限定名称，包括了对象所在的模块、类、父类等信息。在限定名称中，各个部分之间使用点号 . 进行分隔。

对于函数、方法、类等对象，其限定名称的构成方式如下：

• 对于函数或方法：限定名称由其所在的模块名（如果有）、类名（如果是类方法或静态方法）、函数或方法的名称组成。
• 对于类：限定名称由其所在的模块名（如果有）、类的名称组成。

限定名称对于定位和识别对象在程序中的位置非常有用，特别是在模块、类、函数等的嵌套结构中。通过限定名称，可以清晰地指明对象在代码中的位置，方便理解和调试。

举个例子，假设有一个模块 my_module.py，其中定义了一个类 MyClass，以及类中的一个方法 my_method。那么该方法的限定名称就是 my_module.MyClass.my_method。

举例

对于普通函数：

def my_function():
    pass

print(my_function.__qualname__)
# 输出 my_function

对于类方法：

class MyClass:
    def my_method(self):
        pass

print(MyClass.my_method.__qualname__)
# 输出 MyClass.my_method

对于嵌套函数：

def outer_function():
    def inner_function():
        pass
    return inner_function

print(outer_function().__qualname__)
# 输出 outer_function.<locals>.inner_function

__qualname__ 属性通常用于获取函数或方法的限定名称，它对于函数或方法的定位和调试非常有用，特别是在嵌套结构中。

用途

限定名称在 Python 中有几种使用场景和作用：

• 定位对象位置： 通过限定名称，可以清晰地指明对象在代码中的位置，包括所在的模块、类、父类等信息。这有助于开发人员理解代码结构和定位特定对象在代码中的位置。
• 元编程： 在元编程中，限定名称可以用于动态地构造或操作对象。例如，可以根据限定名称动态导入模块、获取类的属性或方法、动态调用函数等操作。
• 调试和日志记录： 在调试和日志记录过程中，限定名称可以提供有用的信息，帮助开发人员快速定位和诊断问题。
• 文档生成： 在自动生成文档或文档字符串时，限定名称可以作为对象的标识符，提供对象在代码中的完整位置信息。

限定名称提供了对象在代码中的完整位置信息，有助于开发人员理解代码结构、实现元编程操作、调试和日志记录等。

参考

• https://docs.python.org/zh-cn/3/library/stdtypes.html#definition.__qualname__

更新时间：2024-04-01 17:18:16 标签：python 属性 特殊属性 限定名