2.2.3.24. pycsamt.api.view.progress#

Progress helpers used by public pyCSAMT APIs.

pycsamt.utils.progress implements the dependency-light progress engine (ProgressBar, verbosity normalization). This module layers package-wide policy on top of it — a configurable singleton (PYCSAMT_PROGRESS), following the same configure()/context()/reset() shape as pycsamt.api.pipe.PYCSAMT_PIPE and pycsamt.api.view.PYCSAMT_API_VIEW — plus thin backward-compatible wrappers (iter_progress(), progress_enabled()) used elsewhere in the API layer.

Examples

Silence every progress bar package-wide (e.g. for CI or batch jobs):

from pycsamt.api.view import configure_progress
configure_progress(force_verbose=0)

Prefer plain log lines (no carriage-return redraw) in a non-tty run:

from pycsamt.api.view import configure_progress
configure_progress(default_verbose="log")

Functions

`configure_progress`(**kw)	Configure `PYCSAMT_PROGRESS` with keyword arguments.
`get_progress_bar`([total, desc, unit, ...])	Build a `ProgressBar` honouring `PYCSAMT_PROGRESS` (style, throttle, forced verbosity).
`iter_progress`(iterable, *[, enabled, desc, ...])	Yield items, optionally wrapped by a `ProgressBar`.
`progress_enabled`([value])	Return whether progress should be displayed.
`reset_progress`()	Reset `PYCSAMT_PROGRESS` to package defaults.

Classes

`ProgressAPIConfig`()	Package-wide policy for `ProgressBar`.
`ProgressConfig`([enabled, desc, leave, unit, ...])	Configuration for terminal progress display.

class pycsamt.api.view.progress.ProgressAPIConfig[source]

Bases: object

Package-wide policy for ProgressBar.

Variables:

default_verbose – Verbosity used when a call site’s own verbose argument is None. Does not override an explicit verbose=True/False passed by the caller — use force_verbose for that.
force_verbose – When set (0, 1, or 2), overrides every call site’s verbose argument, explicit or not. None (default) leaves callers in control.
style – Bar glyph set — "ascii" (default, safe on legacy Windows console code pages) or "unicode".
min_interval – Minimum seconds between bar redraws.
log_every – Default line-throttle for log-mode (verbose level 2) progress. None auto-computes ~10 lines per run.

configure(**kw)[source]

Set one or more configuration attributes by keyword.

Parameters:: kw (Any)
Return type:: None

context(**kw)[source]

Temporarily override progress config, then restore it.

Parameters:: kw (Any)
Return type:: Generator[ProgressAPIConfig, None, None]

reset()[source]

Reset to package defaults.

Return type:: None

resolve(verbose=None)[source]

Resolve a call site’s verbose argument to 0/1/2.

Parameters:: verbose (bool | int | str | None)
Return type:: int

summary()[source]

Return a human-readable configuration summary.

Return type:: str

class pycsamt.api.view.progress.ProgressConfig(enabled='auto', desc=None, leave=False, unit='it', total=None)[source]

Bases: object

Configuration for terminal progress display.

Parameters:

enabled (bool | str)
desc (str | None)
leave (bool)
unit (str)
total (int | None)

enabled: bool | str = 'auto'

desc: str | None = None

leave: bool = False

unit: str = 'it'

total: int | None = None

pycsamt.api.view.progress.configure_progress(**kw)[source]

Configure PYCSAMT_PROGRESS with keyword arguments.

Parameters:: kw (Any)
Return type:: None

pycsamt.api.view.progress.get_progress_bar(total=None, *, desc=None, unit='it', verbose=None, leave=False, log_every=None)[source]

Build a ProgressBar honouring PYCSAMT_PROGRESS (style, throttle, forced verbosity).

This is the recommended entry point for AI-inversion agents, dataset generation, and realization loops — it lets a user silence or reshape progress output package-wide via configure_progress() without touching every function’s verbose default.

Parameters:

total (int | None)
desc (str | None)
unit (str)
verbose (bool | int | str | None)
leave (bool)
log_every (int | None)

Return type:

ProgressBar

pycsamt.api.view.progress.iter_progress(iterable, *, enabled='auto', desc=None, leave=False, unit='it', total=None)[source]

Yield items, optionally wrapped by a ProgressBar.

Parameters:

iterable (Iterable[T])
enabled (bool | str)
desc (str | None)
leave (bool)
unit (str)
total (int | None)

Return type:

Iterator[T]

pycsamt.api.view.progress.progress_enabled(value='auto')[source]

Return whether progress should be displayed.

Parameters:: value (bool | str)
Return type:: bool

pycsamt.api.view.progress.reset_progress()[source]

Reset PYCSAMT_PROGRESS to package defaults.

Return type:: None