Registry Helpers

pcapkit.interface.registry holds the helpers the registrars use to compare registry entries and to put back the entry a registry shipped with, so that an override of a built-in can be undone (#1363, #1364). They back the registrars of Extractor – register_engine(), register_reassembly(), register_traceflow() and register_dumper() – and TraceFlow.register_dumper, which the functions in pcapkit.foundation.registry call in turn.

A registry entry is a class or a ModuleDescriptor naming one; an __output__ entry is a (dumper, ext) pair whose dumper is such an entry.

What a registrar does with the entry it is handed:

        flowchart TD
    CALL["a registrar is<br/>handed an entry"] --> SHIPPED{"same_entry: the entry<br/>the key shipped with?"}
    SHIPPED -->|yes| RESTORE["restore_shipped, or<br/>restore_shipped_dumper"]
    RESTORE --> HELD{"what is registered<br/>under the key?"}
    HELD -->|"the shipped class"| SILENT["silent; for a dumper,<br/>a new ext is stored"]
    HELD -->|"another class"| WARN1["RegistryWarning"]
    HELD -->|nothing| STORE1["store the shipped entry"]
    WARN1 --> STORE1
    SHIPPED -->|no| CHECK{"a class, and a subclass<br/>of the public base?"}
    CHECK -->|no| ERROR["RegistryError"]
    CHECK -->|yes| OTHER{"another class<br/>under the key?"}
    OTHER -->|yes| WARN2["RegistryWarning"]
    OTHER -->|no| STORE2["store the class"]
    WARN2 --> STORE2

    click SHIPPED "registry.html#pcapkit.interface.registry.same_entry"
    click RESTORE "registry.html#pcapkit.interface.registry.restore_shipped"
    

pcapkit.interface.registry.same_entry(entry, other)

Tell whether two registry entries name the same class.

An entry is a class or a ModuleDescriptor. Two descriptors are the same entry when they are equal, and a descriptor and a class are when the descriptor names that class. The class is looked up in sys.modules rather than imported: a class someone holds has its module loaded already, so a descriptor whose module is not loaded cannot name it, and an optional engine that is not installed is never imported to answer the question.

The comparison is symmetric, and two classes are the same entry only when they are the same object.

Parameters:

• entry (Any) – registry entry

• other (Any) – registry entry to compare against

Return type:

bool

Returns:

True if both name the same class.

pcapkit.interface.registry.restore_shipped(registry, key, shipped, kind)

Put the entry registry shipped with back under key.

The public registrars call this when handed the built-in that shipped under key, so an override can be undone (#1363). It stores the shipped object itself, a descriptor if a descriptor shipped, and it is a silent no-op when the incumbent already names the shipped class, as decided by same_entry().

Parameters:

• registry (dict[str, Any]) – registry to restore

• key (str) – registry key

• shipped (Any) – entry the registry shipped with under key

• kind (str) – entry kind, for the warning message

Warns:

RegistryWarning – If a different class is registered under key; it is overwritten.

pcapkit.interface.registry.restore_shipped_dumper(registry, format, shipped, ext)

Put the dumper registry shipped with back under format.

The __output__ counterpart of restore_shipped(): an entry is a (dumper, ext) pair, so the shipped pair itself is stored when ext matches it, and the shipped dumper with the new ext otherwise. A re-registration that only changes ext stays silent, as the dumper registrars document.

The incumbent is read with dict.get(), so an __output__ that is a collections.defaultdict gains no entry from the lookup.

Parameters:

• registry (dict[str, Any]) – __output__ registry to restore

• format (str) – format name

• shipped (tuple[Any, str | None]) – (dumper, ext) pair the registry shipped with under format

• ext (str) – file extension

Warns:

RegistryWarning – If a different dumper is registered for format; it is overwritten.