API reference

doormat's public API is four names: load(), which reads and scans a file, and the frozen dataclasses it returns. Everything else in the package is internal.

doormat.load

load(
    filepath: str | Path,
    *,
    max_uncompressed_bytes: int
    | None = DEFAULT_MAX_UNCOMPRESSED_BYTES,
) -> GridDoc

Load a spreadsheet file and run the credential detection engine.

Supports .xlsx, .xlsm, .xls, .csv, .tsv, and .ods formats. Opens the file, extracts all cells, sends them through the Rust detection pipeline, and returns the results as a GridDoc.

A sheet that cannot be parsed does not stop the scan: it is recorded in GridDoc.errors and the remaining sheets are scanned. Problems with the file as a whole (missing, wrong format, zip bomb, unreadable workbook structure) raise.

Parameters:

Name	Type	Description	Default
filepath	str | Path	Path to a spreadsheet file. Accepts both str and pathlib.Path. Supported extensions: .xlsx, .xlsm, .xls, .csv, .tsv, .ods.	required
max_uncompressed_bytes	int | None	For zip-based formats (.xlsx, .xlsm, .ods), refuse files that would decompress to more than this many bytes. Defaults to 512 MiB; None removes the size limit. Parts with a zip-bomb compression ratio are refused regardless.	DEFAULT_MAX_UNCOMPRESSED_BYTES

Returns:

Type	Description
GridDoc	A GridDoc containing all detected relationships and file metadata.

Raises:

Type	Description
FileNotFoundError	If the file does not exist.
ValueError	If the file extension is unsupported, the file content does not match the expected format, or a zip-based file looks like a zip bomb (see max_uncompressed_bytes).
ImportError	If an optional dependency is missing for the requested format (.xls requires xlrd, .ods requires odfpy).

Example::

import doormat

doc = doormat.load("workbook.xlsx")
for cred in doc.credentials(min_confidence=120):
    print(f"{cred.key} = {cred.value}")

doormat.GridDoc dataclass

Result of processing a spreadsheet file through the doormat engine.

Attributes:

Name	Type	Description
filepath	Path	Path to the source spreadsheet file.
sheet_count	int	Number of sheets read (1 for CSV and TSV). Sheets that could not be read are not counted; they are listed in errors.
cell_count	int	Total number of non-empty cells across the sheets read.
errors	tuple[SheetError, ...]	One entry per sheet that could not be read. Its findings are missing, so a scan that must be exhaustive should check complete.

complete property

complete: bool

True if every sheet in the file was read.

relationships

relationships() -> list[Relationship]

Return all inferred key-value relationships.

Returns:

Type	Description
list[Relationship]	A list of all Relationship objects detected in the workbook,
list[Relationship]	regardless of confidence score.

credentials

credentials(
    min_confidence: float = 0.0,
) -> list[Relationship]

Return relationships at or above a minimum confidence threshold.

Parameters:

Name	Type	Description	Default
min_confidence	float	Minimum confidence score to include. Defaults to 0.0 (all relationships). Use 120.0 for typical credential filtering.	0.0

Returns:

Type	Description
list[Relationship]	A filtered list of Relationship objects with confidence
list[Relationship]	= min_confidence.

doormat.Relationship dataclass

A credential found in a spreadsheet, with where it was found.

Attributes:

Name	Type	Description
key	str	The header or label text (e.g., "Password").
value	str	The detected credential value.
confidence	float	Heuristic confidence score. Values above 120 typically indicate real credentials; above 200 indicates high-confidence inline or formula-embedded detections.
reason	str	Semicolon-separated breakdown of scoring factors (e.g., "distance=100;upper;lower;digit;special;length>=8").
sheet	str	Name of the sheet holding the value. For CSV and TSV files this is the file name without its extension.
row	int	1-based row of the cell holding the value.
col	int	1-based column of the cell holding the value.
header_row	int	1-based row of the label the value was paired with. Equal to row for inline, formula and comment detections.
header_col	int	1-based column of the label the value was paired with.
hidden	bool	True if the sheet is hidden in the workbook.

coordinate property

coordinate: str

Spreadsheet reference of the value cell, e.g. "B3".

header_coordinate property

header_coordinate: str

Spreadsheet reference of the label cell, e.g. "A3".

doormat.SheetError dataclass

A sheet that could not be read. The other sheets were still scanned.

Attributes:

Name	Type	Description
sheet	str	Name of the sheet, as stored in the file.
kind	str	Name of the exception that stopped it, e.g. "TypeError".
message	str	The exception's message. Parsers sometimes quote the content they failed on, so treat it like file content: repr() omits it.