PySide6.QtCore.QLoggingCategory

class QLoggingCategory

QLoggingCategory 类表示日志记录基础设施中的一个类别或“区域”。更多…

概要

方法

静态函数

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

QLoggingCategory 表示运行时由字符串标识的特定日志记录类别。可以配置类别以启用或禁用每种消息类型的日志记录。致命消息是例外，它们总是启用的。

要检查消息类型是否启用，请使用以下方法之一：isDebugEnabled()、isInfoEnabled()、isWarningEnabled()和isCriticalEnabled()。

所有对象都应由一个公共注册表进行配置，如配置类别中所述。不同的对象也可以表示相同的类别。因此，不建议跨模块边界导出对象、直接操作对象或从QLoggingCategory继承。

创建类别对象

Q_DECLARE_LOGGING_CATEGORY() 和 Q_LOGGING_CATEGORY() 宏方便地声明和创建 QLoggingCategory 对象：

# in a header
Q_DECLARE_LOGGING_CATEGORY(driverUsb)
# in one source file
Q_LOGGING_CATEGORY(driverUsb, "driver.usb")

还有Q_DECLARE_EXPORTED_LOGGING_CATEGORY()宏，以便在库边界之间使用日志记录类别。

类别名称是自由文本；要使用Logging Rules配置类别，它们的名称应遵循以下约定：

  • 仅使用字母和数字。

  • 使用点来进一步将类别结构化为常见领域。

  • 避免使用以下类别名称：debug, info, warning, 和 critical。

  • 带有qt前缀的类别名称仅保留给Qt模块使用。

QLoggingCategory 对象由 Q_LOGGING_CATEGORY() 隐式定义，在首次使用时以线程安全的方式创建。

检查类别配置

QLoggingCategory 提供了 isDebugEnabled()、isInfoEnabled()、isWarningEnabled()、isCriticalEnabled()，以及 isEnabled() 来检查是否应记录给定消息类型的消息。

qCDebug()、qCWarning() 和 qCCritical() 宏在未启用相应消息类型的类别时，会阻止参数的评估，因此不需要显式检查：

# usbEntries() will only be called if driverUsb category is enabled
qCDebug(driverUsb) << "devices: " << usbEntries()

默认类别配置

QLoggingCategory 构造函数和 Q_LOGGING_CATEGORY() 宏都接受一个可选的 QtMsgType 参数，该参数会禁用所有严重程度较低的消息类型。也就是说，使用以下方式声明的类别：

Q_LOGGING_CATEGORY(driverUsbEvents, "driver.usb.events", QtWarningMsg)

记录类型为QtWarningMsg、QtCriticalMsg、QtFatalMsg的消息，但忽略类型为QtDebugMsg和QtInfoMsg的消息。

如果没有传递参数，所有消息都会被记录。只有以qt开头的Qt内部类别会有所不同：对于这些类别，默认情况下只会记录类型为QtInfoMsg、QtWarningMsg、QtCriticalMsg和QFatalMsg的消息。

注意

日志类别不受您的C++构建配置影响。也就是说，无论代码是否使用调试符号（'调试构建'）、优化（'发布构建'）或其他组合进行编译，消息的打印都不会改变。

配置类别

您可以通过设置日志记录规则或安装自定义过滤器来覆盖类别的默认配置。

日志记录规则

日志记录规则允许您以灵活的方式启用或禁用类别的日志记录。规则以文本形式指定，其中每一行必须遵循以下格式：

<category>[.<type>] = True|False

是类别的名称，可能包含 * 作为第一个或最后一个字符的通配符；或者在两个位置都包含。可选的 必须是 debug、info、warning 或 critical。不符合此方案的行将被忽略。

规则按文本顺序从第一个到最后一个进行评估。也就是说，如果有两个规则适用于一个类别/类型，则应用后面的规则。

可以通过setFilterRules()设置规则：

QLoggingCategory.setFilterRules("*.debug=False\n"
                                 "driver.usb.debug=True")

日志规则会自动从日志配置文件的[Rules]部分加载。这些配置文件在QtProject配置目录中查找，或者通过QT_LOGGING_CONF环境变量显式设置：

[Rules]
*.debug=False
driver.usb.debug=True

日志记录规则也可以在QT_LOGGING_RULES环境变量中指定；多个规则也可以用分号分隔：

QT_LOGGING_RULES=*.debug=False;driver.usb.debug=True

由setFilterRules()设置的规则优先于QtProject配置目录中指定的规则。反过来，这些规则可以被QT_LOGGING_CONF指定的配置文件中的规则覆盖，也可以被QT_LOGGING_RULES设置的规则覆盖。

评估顺序如下：

  1. [ DataPath ]/qtlogging.ini

  2. QtProject/qtlogging.ini

  3. setFilterRules()

  4. QT_LOGGING_CONF

  5. QT_LOGGING_RULES

QtProject/qtlogging.ini 文件会在由 GenericConfigLocation 返回的所有目录中查找。

设置QT_LOGGING_DEBUG环境变量以找出您的日志规则是从哪里加载的。

安装自定义过滤器

作为文本规则的低级替代方案，您也可以通过installFilter()实现自定义过滤器。在这种情况下，所有过滤规则都将被忽略。

打印类别

使用 %{category} 占位符在默认消息处理程序中打印类别：

qSetMessagePattern("%{category} %{message}")
__init__(category[, severityLevel=QtDebugMsg])
Parameters:

  • category – str

  • severityLevel – QtMsgType

使用提供的category名称构造一个QLoggingCategory对象，并启用所有类型至少为enableForLevel的消息，默认情况下为QtDebugMsg（启用所有类别）。

如果 category 是 None，则使用类别名称 "default"。

注意

category 必须在此对象的生命周期内保持有效。通常使用字符串字面量来实现这一点。

categoryName()
Return type:

字符串

返回类别的名称。

static defaultCategory()
Return type:

QLoggingCategory

返回指向全局类别"default"的指针，该类别由qDebug()、qInfo()、qWarning()、qCritical()或qFatal()使用。

注意

在静态对象的销毁过程中，返回的指针可能为空。此外，不要delete这个指针，因为类别的所有权并未转移。

isCriticalEnabled()
Return type:

布尔

如果应该显示此类别的重要消息，则返回true；否则返回false。

注意

qCCritical() 宏在执行任何代码之前已经进行了此检查。然而，调用此方法可能有助于避免仅为调试输出生成昂贵的数据。

isDebugEnabled()
Return type:

布尔

如果应显示此类别的调试消息，则返回true；否则返回false。

注意

qCDebug() 宏在运行任何代码之前已经进行了此检查。然而，调用此方法可能有助于避免仅为调试输出生成昂贵的数据。

isEnabled(type)
Parameters:

类型 – QtMsgType

Return type:

布尔

如果应该显示类别为msgtype的消息，则返回true；否则返回false。

isInfoEnabled()
Return type:

布尔

如果应显示此类别的信息消息，则返回true；否则返回false。

注意

qCInfo() 宏在执行任何代码之前已经进行了此检查。然而，调用此方法可能有助于避免仅为调试输出生成数据的昂贵操作。

isWarningEnabled()
Return type:

布尔

如果应显示此类别的警告消息，则返回true；否则返回false。

注意

qCWarning() 宏在执行任何代码之前已经进行了此检查。然而，调用此方法可能有助于避免仅为调试输出生成昂贵的数据。

__call__()
Return type:

QLoggingCategory

返回对象本身。这允许同时使用：一个QLoggingCategory变量，以及一个返回QLoggingCategory的工厂方法，可以在qCDebug()、qCWarning()、qCCritical()或qCFatal()宏中使用。

setEnabled(type, enable)
Parameters:

将类别的消息类型 type 更改为 enable。

此方法仅用于从通过installFilter()安装的过滤器内部使用。有关如何全局配置类别的概述，请参见Configuring Categories。

注意

QtFatalMsg 无法更改；它将始终保持 true。

另请参阅

isEnabled()

static setFilterRules(rules)
Parameters:

规则 – str

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

配置应通过一组rules启用的类别和消息类型。

示例：

QLoggingCategory.setFilterRules("driver.usb.debug=True")

注意

如果安装了自定义类别过滤器installFilter()，或者用户定义了QT_LOGGING_CONF或QT_LOGGING_RULES环境变量，则可能会忽略这些规则。