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() 宏，用于在库边界之间使用日志分类。

分类名称是自由文本；要使用 日志 规则 配置分类，它们的名称应遵循以下约定

  • 仅使用字母和数字。

  • 使用点进一步将分类结构化为通用区域。

  • 避免使用分类名称：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

<category> 是类别的名称，可能包含 * 作为通配符，用于第一个或最后一个字符；或者在两个位置。可选的 <type> 必须是 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

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

设置 QT_LOGGING_DEBUG 环境变量以查找日志规则从何处加载。

安装自定义过滤器#

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

打印类别#

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

qSetMessagePattern("%{category} %{message}")
__init__(category[, severityLevel=QtDebugMsg])#
参数：

  • category – str

  • severityLevel – QtMsgType

使用提供的 category 名称构建一个 QLoggingCategory 对象，并启用所有类型至少与 enableForLevel 相同或更详细的日志消息，默认为 QtDebugMsg（这会启用所有类别）。

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

注意

在对象的生存期内必须保持 category 的有效性。使用字符串常量是实现这一点的常规方式。

categoryName()#
返回类型：

str

返回类别名称。

static defaultCategory()#
返回类型：

QLoggingCategory

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

注意

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

isCriticalEnabled()#
返回类型：

bool

如果应为此类别显示关键消息，则返回 true；否则返回 false。

注意

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

isDebugEnabled()#
返回类型：

bool

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

注意

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

isEnabled(type)#
参数：

type – QtMsgType

返回类型：

bool

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

isInfoEnabled()#
返回类型：

bool

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

注意

qCInfo() 宏在执行任何代码之前已经做过此检查。但是，调用此方法可能有助于避免仅生成调试输出的昂贵数据生成。

isWarningEnabled()#
返回类型：

bool

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

注意

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

__call__()#
返回类型：

QLoggingCategory

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

setEnabled(type, enable)#
参数：

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

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

注意

QtFatalMsg 不能更改；它始终为 true。

另请参阅

isEnabled()

static setFilterRules(rules)#
参数：

rules – str

警告

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

通过对一组 rules 进行配置，配置应启用哪些类别和消息类型。

示例

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

注意

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