load_documents#

scikitplot.corpus.load_documents(path, format=None, *, trusted=False, expected_sha256=None)[source]#

Load CorpusDocument instances from a previously exported file.

Supported round-trip formats: ExportFormat.PICKLE, ExportFormat.JOBLIB. For all other formats, returns an empty list with a warning (full deserialization from CSV/JSON/Parquet is handled separately by the pipeline).

Parameters:
pathpathlib.Path

Path to the exported file.

formatExportFormat or None, optional

Format hint. When None, the format is inferred from the file extension (.pkl → PICKLE, .joblib → JOBLIB).

trustedbool

Whether the user has explicitly opted in to unsafe loading.

expected_sha256str or None, optional

When provided, the artifact’s SHA-256 is verified before deserialization; a mismatch raises ValueError before any pickle code runs (tamper/wrong-artifact detection). Default None.

Returns:
list of CorpusDocument
Raises:
ImportError

If joblib is not installed and the file is a joblib dump.

OSError

If the file cannot be read.

ValueError

If loading is not trusted for a pickle/joblib file, or if expected_sha256 does not match the artifact.

TypeError

If the deserialized object is not a list of CorpusDocument (a trusted-but-wrong artifact is rejected rather than returned).

Parameters:
Return type:

list[CorpusDocument]

Examples

Loading a pickle/joblib export requires an explicit trust decision, because deserialization can execute arbitrary code. By default it is refused:

>>> load_documents(Path("corpus.pkl"))
Traceback (most recent call last):
    ...
ValueError: Loading pickle files is disabled by default ...

Opt in only for a source you trust — and, when you have a known-good digest, pin it so a tampered artifact is rejected before it is deserialized:

>>> docs = load_documents(
...     Path("corpus.pkl"),
...     trusted=True,
...     expected_sha256="e3b0c44298fc1c149afbf4c8996fb924...",
... )
>>> len(docs)
312

Prefer a safe, code-execution-free format (Parquet or JSON) whenever you control the export.