FluentCorpus#

class scikitplot.corpus.FluentCorpus(plan=None)[source]#

Immutable fluent builder over a CorpusPlan.

Notes

Every method returns a new instance, so a partially-configured builder is safely reusable as a template:

base = FluentCorpus().reader(r)
strict, lenient = base.storage(a), base.storage(b)

Examples

>>> a = FluentCorpus().embedder("E").storage("S")
>>> b = FluentCorpus().storage("S").embedder("E")
>>> a.plan() == b.plan()
True

Parameters:: plan (CorpusPlan | None)

build()[source]#

Validate and return the plan, raising on any problem.

Raises:

ValueError: Naming every validation problem found.

Return type:

Notes

Developer. build() remains the validated-plan boundary for backward compatibility. Runtime component construction is explicit via materialize, so a caller can still inspect, compare and serialise a plan without constructing operational state.

chunker(value, *, conflict='error')[source]#

Configure the chunker.

Parameters:

valueAny: Configuration fragment or component for the chunker domain.
conflict{{‘error’, ‘replace’}}, optional: What to do if the chunker is already configured. Default 'error': silently discarding the previous value would be a configuration that looks applied but was overwritten.

Returns:

FluentCorpus: A new builder; the original is unchanged.

Raises:

ConfigConflictError: If the chunker is already configured and conflict is 'error'.

Parameters:

value (Any)
conflict (str)

Return type:

config(domain, value, *, conflict='error')[source]#

Set one configuration domain by name.

Parameters:

domain (str)
value (Any)
conflict (str)

Return type:

configure(config=None, *, conflict='error', **fragments)[source]#

Set several domains atomically using the normal conflict contract.

Domains are applied in canonical CONFIG_DOMAINS order, never in mapping insertion order; fluent configuration therefore remains declarative and order-independent.

Parameters:

config (Mapping[str, Any] | None)
conflict (str)
fragments (Any)

Return type:

diff(other)[source]#

Describe domain/stage differences without constructing components.

Parameters:: other (FluentCorpus | CorpusPlan)
Return type:: dict[str, Any]

embedder(value, *, conflict='error')[source]#

Configure the embedder.

Parameters:

valueAny: Configuration fragment or component for the embedder domain.
conflict{{‘error’, ‘replace’}}, optional: What to do if the embedder is already configured. Default 'error': silently discarding the previous value would be a configuration that looks applied but was overwritten.

Returns:

FluentCorpus: A new builder; the original is unchanged.

Raises:

ConfigConflictError: If the embedder is already configured and conflict is 'error'.

Parameters:

value (Any)
conflict (str)

Return type:

enricher(value, *, conflict='error')[source]#

Configure the enricher.

Parameters:

valueAny: Configuration fragment or component for the enricher domain.
conflict{{‘error’, ‘replace’}}, optional: What to do if the enricher is already configured. Default 'error': silently discarding the previous value would be a configuration that looks applied but was overwritten.

Returns:

FluentCorpus: A new builder; the original is unchanged.

Raises:

ConfigConflictError: If the enricher is already configured and conflict is 'error'.

Parameters:

value (Any)
conflict (str)

Return type:

explain()[source]#

Return a JSON-compatible explanation of configuration and validity.

Return type:: dict[str, Any]

export(value, *, conflict='error')[source]#

Configure the export.

Parameters:

valueAny: Configuration fragment or component for the export domain.
conflict{{‘error’, ‘replace’}}, optional: What to do if the export is already configured. Default 'error': silently discarding the previous value would be a configuration that looks applied but was overwritten.

Returns:

FluentCorpus: A new builder; the original is unchanged.

Raises:

ConfigConflictError: If the export is already configured and conflict is 'error'.

Parameters:

value (Any)
conflict (str)

Return type:

classmethod from_config(config=None, *, stages=None, **fragments)[source]#

Generate a fluent plan from a user mapping plus keyword fragments.

This is the data-driven counterpart to chained setters. It is useful for configuration files, notebooks and generated experiment matrices while preserving the same canonical conflict/validation rules.

Parameters:

config (Mapping[str, Any] | None)
stages (tuple[str, ...] | list[str] | None)
fragments (Any)

Return type:

index(value, *, conflict='error')[source]#

Configure the index.

Parameters:

valueAny: Configuration fragment or component for the index domain.
conflict{{‘error’, ‘replace’}}, optional: What to do if the index is already configured. Default 'error': silently discarding the previous value would be a configuration that looks applied but was overwritten.

Returns:

FluentCorpus: A new builder; the original is unchanged.

Raises:

ConfigConflictError: If the index is already configured and conflict is 'error'.

Parameters:

value (Any)
conflict (str)

Return type:

iter_variants(*, max_variants=256, **choices)[source]#

Lazily generate a deterministic bounded configuration grid.

The full Cartesian size is validated before the first value is yielded. This preserves the existing safety bound while letting callers stream variants into CI/tuning loops without materializing every FluentCorpus instance at once.

Parameters:

max_variants (int)
choices (Iterable[Any])

Return type:

Iterable[FluentCorpus]

materialize(*, policy=None, registry=None)[source]#

Validate this plan and construct a RuntimeCorpus.

Unlike the fluent setters, materialization is an operational boundary: it may construct storage/index/component objects, but it does not read the configured source. Source processing starts only when RuntimeCorpus.run or RuntimeCorpus.add is called.

Parameters:

policy (RuntimePolicy | str | Mapping[str, Any] | None)
registry (ComponentRegistry | None)

Return type:

normalizer(value, *, conflict='error')[source]#

Configure the normalizer.

Parameters:

valueAny: Configuration fragment or component for the normalizer domain.
conflict{{‘error’, ‘replace’}}, optional: What to do if the normalizer is already configured. Default 'error': silently discarding the previous value would be a configuration that looks applied but was overwritten.

Returns:

FluentCorpus: A new builder; the original is unchanged.

Raises:

ConfigConflictError: If the normalizer is already configured and conflict is 'error'.

Parameters:

value (Any)
conflict (str)

Return type:

plan()[source]#

Return the canonical plan this builder describes.

Return type:: CorpusPlan

reader(value, *, conflict='error')[source]#

Configure the reader.

Parameters:

valueAny: Configuration fragment or component for the reader domain.
conflict{{‘error’, ‘replace’}}, optional: What to do if the reader is already configured. Default 'error': silently discarding the previous value would be a configuration that looks applied but was overwritten.

Returns:

FluentCorpus: A new builder; the original is unchanged.

Raises:

ConfigConflictError: If the reader is already configured and conflict is 'error'.

Parameters:

value (Any)
conflict (str)

Return type:

replace_chunker(value)[source]#

Replace the chunker, whether or not one is already configured.

The explicit counterpart to the error-by-default rule: the intent to substitute is stated in the method name.

Returns:

FluentCorpus

Parameters:

value (Any)

Return type:

replace_embedder(value)[source]#

Replace the embedder, whether or not one is already configured.

The explicit counterpart to the error-by-default rule: the intent to substitute is stated in the method name.

Returns:

FluentCorpus

Parameters:

value (Any)

Return type:

replace_enricher(value)[source]#

Replace the enricher, whether or not one is already configured.

The explicit counterpart to the error-by-default rule: the intent to substitute is stated in the method name.

Returns:

FluentCorpus

Parameters:

value (Any)

Return type:

replace_export(value)[source]#

Replace the export, whether or not one is already configured.

The explicit counterpart to the error-by-default rule: the intent to substitute is stated in the method name.

Returns:

FluentCorpus

Parameters:

value (Any)

Return type:

replace_index(value)[source]#

Replace the index, whether or not one is already configured.

The explicit counterpart to the error-by-default rule: the intent to substitute is stated in the method name.

Returns:

FluentCorpus

Parameters:

value (Any)

Return type:

replace_normalizer(value)[source]#

Replace the normalizer, whether or not one is already configured.

The explicit counterpart to the error-by-default rule: the intent to substitute is stated in the method name.

Returns:

FluentCorpus

Parameters:

value (Any)

Return type:

replace_reader(value)[source]#

Replace the reader, whether or not one is already configured.

The explicit counterpart to the error-by-default rule: the intent to substitute is stated in the method name.

Returns:

FluentCorpus

Parameters:

value (Any)

Return type:

replace_retrieval(value)[source]#

Replace the retrieval, whether or not one is already configured.

The explicit counterpart to the error-by-default rule: the intent to substitute is stated in the method name.

Returns:

FluentCorpus

Parameters:

value (Any)

Return type:

replace_source(value)[source]#

Replace the source, whether or not one is already configured.

The explicit counterpart to the error-by-default rule: the intent to substitute is stated in the method name.

Returns:

FluentCorpus

Parameters:

value (Any)

Return type:

replace_storage(value)[source]#

Replace the storage, whether or not one is already configured.

The explicit counterpart to the error-by-default rule: the intent to substitute is stated in the method name.

Returns:

FluentCorpus

Parameters:

value (Any)

Return type:

retrieval(value, *, conflict='error')[source]#

Configure the retrieval.

Parameters:

valueAny: Configuration fragment or component for the retrieval domain.
conflict{{‘error’, ‘replace’}}, optional: What to do if the retrieval is already configured. Default 'error': silently discarding the previous value would be a configuration that looks applied but was overwritten.

Returns:

FluentCorpus: A new builder; the original is unchanged.

Raises:

ConfigConflictError: If the retrieval is already configured and conflict is 'error'.

Parameters:

value (Any)
conflict (str)

Return type:

source(value, *, conflict='error')[source]#

Configure the source.

Parameters:

valueAny: Configuration fragment or component for the source domain.
conflict{{‘error’, ‘replace’}}, optional: What to do if the source is already configured. Default 'error': silently discarding the previous value would be a configuration that looks applied but was overwritten.

Returns:

FluentCorpus: A new builder; the original is unchanged.

Raises:

ConfigConflictError: If the source is already configured and conflict is 'error'.

Parameters:

value (Any)
conflict (str)

Return type:

stages(*stages)[source]#

Set an explicit pipeline stage order.

Notes

Developer. This is the only way to express execution order. Chained configuration calls deliberately do not, because a chain whose order silently changed the pipeline would be a second execution engine defined by call order.

Parameters:: stages (str)
Return type:: FluentCorpus

storage(value, *, conflict='error')[source]#

Configure the storage.

Parameters:

valueAny: Configuration fragment or component for the storage domain.
conflict{{‘error’, ‘replace’}}, optional: What to do if the storage is already configured. Default 'error': silently discarding the previous value would be a configuration that looks applied but was overwritten.

Returns:

FluentCorpus: A new builder; the original is unchanged.

Raises:

ConfigConflictError: If the storage is already configured and conflict is 'error'.

Parameters:

value (Any)
conflict (str)

Return type:

validate()[source]#

Return cross-fragment problems, empty when coherent.

Return type:: list[ErrorRecord]

variants(*, max_variants=256, **choices)[source]#

Materialize iter_variants as a convenience tuple.

Use iter_variants when the consumer itself is streaming or when constructing every variant object at once is unnecessary.

Parameters:

max_variants (int)
choices (Iterable[Any])

Return type:

tuple[FluentCorpus, …]

with_overrides(config=None, **fragments)[source]#

Return a copy with explicit multi-domain replacements.

Parameters:

config (Mapping[str, Any] | None)
fragments (Any)

Return type:

without(*domains)[source]#

Return a copy with selected configuration domains removed.

Parameters:: domains (str)
Return type:: FluentCorpus

Gallery examples#

Configure Corpus with FluentCorpus

Configure Corpus with FluentCorpus

Build and Search a Real Hamlet Corpus with FluentCorpus

Build and Search a Real Hamlet Corpus with FluentCorpus

Build and Search a Real Hamlet Corpus with FluentCorpus

Build and Search a Real Hamlet Corpus with FluentCorpus

Build and Search a Real Hamlet Corpus with FluentCorpus

Build and Search a Real Hamlet Corpus with FluentCorpus