Core

S = TypeVar('S', bound=Enum)

ScanEngine

Bases: ABC, Generic[S]

Abstract base class for scanning engines.

This ABC defines the interface for any scanning engine that can identify patterns within a byte buffer and associate them with specific states. Implementations should provide methods for compiling patterns and streaming matches.

Type variables

S: An Enum type representing the possible states a file can be in.

compile(patterns)

Compile regex patterns to speed up searching.

This method prepares the scanning engine to efficiently search for the provided patterns. The exact compilation mechanism will depend on the concrete implementation of the ScanEngine.

PARAMETER	DESCRIPTION
patterns	A dictionary where keys are state Enum members and values are lists of byte patterns (e.g., regex strings) that the engine should compile and look for. TYPE: dict[S, list[bytes]]

stream(buf)

Stream (match_start, match_end, pattern, target_state) triples.

This method should iterate through the provided byte buffer and yield tuples for each match found. Each tuple should contain:

- The inclusive starting byte offset of the match.
- The exclusive ending byte offset of the match.
- The actual byte pattern that was matched.
- The target state associated with the matched pattern.

PARAMETER	DESCRIPTION
buf	The byte buffer to be scanned. TYPE: bytes

YIELDS	DESCRIPTION
int	A tuple containing the start position, end position, matched
int	pattern, and the target state for each detected pattern.