User Defined Warnings¶

pcapkit.utilities.warnings refined built-in warnings.

How a Warning Is Reported¶

Every warning pcapkit reports goes through warn(), which reports it exactly once on each of two channels:

the logger logger, at logging.WARNING level, unconditionally – so a consumer watching the pcapkit logger sees every complaint whatever the warning filters say;
the standard warnings machinery, via warnings.warn(), subject to the filters – so warnings.filterwarnings(), warnings.catch_warnings(), pytest’s filterwarnings, -W and PYTHONWARNINGS govern pcapkit warnings exactly as they govern any other library’s (with one wrinkle in naming a category on the command line, noted below).

The counts are the same in development mode as outside it: PCAPKIT_DEVMODE and PCAPKIT_VERBOSE change how much detail the log record carries, never how many records there are. Constructing a warning class is not an act of reporting one – it emits nothing and has no side effects.

Silencing pcapkit Warnings¶

Filter them like any other library’s, at the level of granularity you want – BaseWarning for all of them, or a single category:

import warnings

from pcapkit.utilities.warnings import BaseWarning, SchemaWarning

warnings.filterwarnings('ignore', category=BaseWarning)    # all of them
warnings.filterwarnings('error', category=SchemaWarning)   # or turn one into an error

From the command line, name one of the standard categories these are mixed with. UserWarning covers all of them, and RuntimeWarning, ImportWarning, ResourceWarning and DeprecationWarning each select a family:

python -W ignore::UserWarning ...      # every pcapkit warning, and everyone else's
python -W error::RuntimeWarning ...    # the RuntimeWarning family, as errors

Note

-W and PYTHONWARNINGS cannot name a pcapkit category directly: -W ignore::pcapkit.utilities.warnings.BaseWarning is rejected with Invalid -W option ignored: invalid module name. CPython imports the category while parsing the option, and that happens before site has added site-packages to sys.path, so no installed package’s own category can be named there – this is not specific to pcapkit. Use a standard category on the command line, or install a precise filter in code as above.

All of that governs the warnings channel. The pcapkit logger is configured separately, through the logging module:

import logging

logging.getLogger('pcapkit').setLevel(logging.ERROR)   # drop WARNING records

Attention

Up to and including v1.4.1, BaseWarning installed an ignore filter for its own class as a side effect of being constructed, so pcapkit warnings were invisible on the warnings channel by default and a caller could not re-enable them. They are now delivered, which means a consumer who was relying on that silence will start seeing them; the first snippet above restores the old quiet. Since the filter was installed at the front of the process-global warnings.filters, it also overrode the host application’s own configuration for those categories and made unrelated warnings re-fire, so it is not something that can be kept.

exception pcapkit.utilities.warnings.BaseWarning[source]¶

Bases: UserWarning

Base warning class of all kinds.

Constructing one of these is deliberately free of side effects: it emits nothing and mutates no process-global state. Reporting a warning is the job of warn(), which is called once per complaint; a warning object may be built without ever being reported, and the two must not be confused.

Note

Up to and including v1.4.1, this constructor called warnings.simplefilter('ignore', type(self)) outside development mode, which inserted an entry at the front of the process-global warnings.filters – overriding whatever the host application, -W or the test runner had configured, and invalidating every module’s __warningregistry__ so that unrelated warnings re-fired. It also logged the warning a second time under DEVMODE. Both are gone; filtering is the application’s business, and is done through the standard warnings machinery.