User Defined Warnings

pcapkit.utilities.warnings holds refined built-in warnings.

Removed in version 1.5.0: pcapkit.utilities.warnings.DEVMODE, which 1.4.x imported from pcapkit.utilities.logging; read pcapkit.utilities.logging.DEVMODE instead.

Reporting a Warning

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

1. the pcapkit logger (logger), at logging.WARNING level, unconditionally – so a consumer watching the pcapkit logger sees every complaint whatever the warning filters say;

2. 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).

Neither flag changes how many records there are: PCAPKIT_DEVMODE changes where the log records go, and PCAPKIT_VERBOSE how much detail they carry. Constructing a warning class reports nothing and has no side effects.

A next layer is parsed on trial, and replaced with Raw when its header was not captured or its parse raises. The trial’s warnings are held back by hold_warnings: a replaced layer’s are dropped on each channel, since they describe a layer the result does not have, and a kept layer’s are reported as above when the trial ends (#1580, #2308, #2516).

pcapkit.utilities.warnings.warn(message, category, stacklevel=None)

Wrapper function of warnings.warn().

The warning is reported once on the logger logger, then once through warnings.warn(). The logger call does not consult warnings.filters, so a log-based consumer sees the complaint even when the application has filtered the category out; the warnings.warn() call is filtered normally, so the application keeps full control of that channel – including turning the warning into an error with -W error.

Parameters:

• message (str | Warning) – Warning message.

• category (Type[Warning]) – Warning category.

• stacklevel (int | None) – Warning stack level, relative to the caller of this function – 1 blames the line that called warn(), 2 its caller, and so on, exactly as the argument of the same name reads on warnings.warn() itself. Defaults to stacklevel(), i.e. the innermost frame outside pcapkit.

Return type:

None

See also

pcapkit.utilities.warnings for the emission model in full, and for how to silence either channel.

Note

Inside a hold_warnings block the warning is held back instead, with the frame it is attributed to, and reported from there only if the block keeps it.

Changed in version 1.5.0: A warning is reported exactly once on each channel, in development mode as outside it (#363), and the warnings channel answers to the application’s filters alone (#364).

class pcapkit.utilities.warnings.hold_warnings(hold=True)

Bases: object

Hold back the warnings a parse reports until it is known to be kept.

Parameters:

hold (bool) – Hold the warnings reported inside the block. When false, they are reported at once instead, even inside an enclosing block that holds.

Every warn() call inside the block is held, with the frame it is attributed to. On leaving the block they are reported in order, with the same message and category and attributed to the same frame on both channels, unless discard was set, in which case they are dropped, whether the block ends or is left by an Exception. A block left by any other BaseException – KeyboardInterrupt, SystemExit, GeneratorExit – drops them whatever discard says, so that a filter turning them into errors cannot replace it.

The line named is the frame’s line when the block is left. For the frame stacklevel() names – the caller of pcapkit, still inside that call – it is the line named when held.

Blocks nest, and each reports what it keeps when it is left, never handing it to an enclosing block. Under a filter turning warnings into errors, the error is then raised where the block that kept them is left – the end of the trial parse, inside the guard it was raised in when nothing was held.

Protocol._parse_next_layer uses this for the trial parse it replaces with Raw when the header was not captured, or that beholder() replaces when it raises: the warnings describe a layer the result does not have (#1580, #2308).

Note

Nothing here touches warnings.filters or a module’s __warningregistry__; warnings.catch_warnings would, which is what made unrelated warnings re-fire up to v1.4.1 (see BaseWarning).

A block left while one opened inside it is still open – a generator suspended inside its own block – stays in place for that one, which steps over it when it is left. While it is suspended, though, the generator’s block holds its caller’s warnings too: a context variable follows the thread, not the frame.

discard

Drop the held warnings on leaving the block, rather than report them.

holding

Whether warnings reported inside the block are held.

Silencing pcapkit Warnings

Filter them like any other library’s, by BaseWarning for all of them, or by 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, before site has added site-packages to sys.path, so no installed package’s category can be named there. Use a standard category on the command line, or a filter in code as above.

That governs the warnings channel. The pcapkit logger is configured through logging:

import logging

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

Changed in version 1.5.0: pcapkit warnings reach the warnings channel by default, and the first snippet above restores the 1.4.x quiet. In 1.4.x, constructing a BaseWarning installed an ignore filter for its own class, so a caller could not re-enable them. The filter went at the front of the process-global warnings.filters, so it also overrode the host application’s own configuration for those categories and made unrelated warnings re-fire (#364).

exception pcapkit.utilities.warnings.BaseWarning

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.

Changed in version 1.5.0: The constructor has no side effects (#364). In 1.4.x it 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. Filtering is the application’s business, and is done through the standard warnings machinery.

Parameters:

*args – Arbitrary positional arguments.

ImportWarning Category

exception pcapkit.utilities.warnings.FormatWarning

Bases: BaseWarning, ImportWarning

Warning on unknown format(s).

exception pcapkit.utilities.warnings.EngineWarning

Bases: BaseWarning, ImportWarning

Unsupported extraction engine.

exception pcapkit.utilities.warnings.InvalidVendorWarning

Bases: BaseWarning, ImportWarning

Invalid updater given to the vendor CLI.

RuntimeWarning Category

exception pcapkit.utilities.warnings.FileWarning

Bases: BaseWarning, RuntimeWarning

Warning on file(s).

exception pcapkit.utilities.warnings.LayerWarning

Bases: BaseWarning, RuntimeWarning

Unrecognised layer.

exception pcapkit.utilities.warnings.ProtocolWarning

Bases: BaseWarning, RuntimeWarning

Unrecognised protocol.

exception pcapkit.utilities.warnings.ChecksumWarning

Bases: ProtocolWarning

Checksum mismatch.

Reported when parsing verifies a checksum and finds it wrong, so that a filter can silence it without silencing other protocol warnings.

Added in version 1.6.0.

exception pcapkit.utilities.warnings.AttributeWarning

Bases: BaseWarning, RuntimeWarning

Unsupported attribute.

exception pcapkit.utilities.warnings.DevModeWarning

Bases: BaseWarning, RuntimeWarning

Run in development mode.

exception pcapkit.utilities.warnings.VendorRequestWarning

Bases: BaseWarning, RuntimeWarning

Vendor request connection failed.

exception pcapkit.utilities.warnings.VendorRuntimeWarning

Bases: BaseWarning, RuntimeWarning

Vendor failed during runtime.

exception pcapkit.utilities.warnings.UnknownFieldWarning

Bases: BaseWarning, RuntimeWarning

Unknown field.

exception pcapkit.utilities.warnings.RegistryWarning

Bases: BaseWarning, RuntimeWarning

Registry warning.

exception pcapkit.utilities.warnings.SchemaWarning

Bases: BaseWarning, RuntimeWarning

Schema warning.

exception pcapkit.utilities.warnings.InfoWarning

Bases: BaseWarning, RuntimeWarning

Info class warning.

exception pcapkit.utilities.warnings.SeekWarning

Bases: BaseWarning, RuntimeWarning

Seek operation warning.

exception pcapkit.utilities.warnings.ExtractionWarning

Bases: BaseWarning, RuntimeWarning

Extraction warning.

exception pcapkit.utilities.warnings.ConfigWarning

Bases: BaseWarning, RuntimeWarning

Configuration warning.

Reported for an environment variable that is invalid, and so falls back to its default, or that lifts a limit past its default: by the readers of pcapkit.utilities.config, and by this module for the flags pcapkit.utilities.logging reads.

Added in version 1.5.0.

ResourceWarning Category

exception pcapkit.utilities.warnings.DPKTWarning

Bases: BaseWarning, ResourceWarning

Warnings on DPKT usage.

exception pcapkit.utilities.warnings.ScapyWarning

Bases: BaseWarning, ResourceWarning

Warnings on Scapy usage.

exception pcapkit.utilities.warnings.PySharkWarning

Bases: BaseWarning, ResourceWarning

Warnings on PyShark usage.

exception pcapkit.utilities.warnings.EmojiWarning

Bases: BaseWarning, ResourceWarning

Warnings on Emoji usage.

exception pcapkit.utilities.warnings.VendorWarning

Bases: BaseWarning, ResourceWarning

Warnings on vendor usage.

DeprecationWarning Category

exception pcapkit.utilities.warnings.DeprecatedFormatWarning

Bases: BaseWarning, DeprecationWarning

Warning on deprecated formats.