tugboat package

tugboat, the main package of the Tugboat framework.

The Tugboat framework is a modular static analysis tool for software manifests. It is designed to examine software manifests and report issues detected by the analyzers.

This package exposes only the core components of the framework:

  • Diagnosis: The primary structure for a diagnosis.

  • Field: A special type to indicate a field in the manifest.

  • hookimpl: The hook implementation marker for the Tugboat framework.

Other components are available in the subpackages of the framework but are not automatically imported here; they are intended to be imported explicitly by the developers as needed.

class tugboat.Diagnosis

Bases: TypedDict

A diagnosis reported by the analyzer.

This class is a TypedDict that defines the structure of a diagnosis produced by the analyzer. It serves as the standard format for reporting issues detected during analysis.

All analyzers return diagnoses in this format to ensure consistency across different implementations.

code: str

A unique identifier representing the violated rule.

ctx: NotRequired[dict[str, Bundle]]

Additional context(s). The context is a dictionary that maps context names to their corresponding bundle.

fix: NotRequired[str | None]

Possible alternative value to fix the issue.

input: NotRequired[Any]

The input that caused the issue. Use Field to indicate a specific field rather than a value.

loc: Sequence[str | int]

The location of the issue occurrence within the manifest, specified in a path-like format.

The first element is the key of the manifest, and the rest are the keys of the nested dictionaries.

msg: str

The detailed message.

When multiple lines are used in the message, the framework will automatically dedent it. This allows the analyzer to use Python multiline strings without concern for indentation.

summary: NotRequired[str]

The summary. When not provided, the first sentence of the message will be used.

type: NotRequired[Literal['error', 'failure', 'warning']]

The diagnosis type. When not provided, it defaults to “failure”.

  • error indicates a critical issue that prevents the analyzer from running.

  • failure indicates an issue that the analyzer has detected.

  • warning indicates a potential issue that the analyzer has detected. This is not a critical issue, but it may require attention.

class tugboat.Field

Representing a field in a YAML document.

This class is tended to be used as Diagnosis.input to indicate that the diagnosis is related to a specific field in the YAML document.

tugboat.hookimpl: pluggy.HookimplMarker

The hook implementation marker for the Tugboat framework. Please see the pluggy documentation for more information.