2.2.3.3. pycsamt.api.cli#

CLI configuration API for pyCSAMT.

Mirrors the configure_* / reset_* pattern used throughout pycsamt.api. Import from here to configure CLI defaults programmatically or from a script.

Example

from pycsamt.api.cli import configure_cli, reset_cli, PYCSAMT_CLI

# set session-wide defaults
configure_cli(log__level=1, output__format="json")

# inspect current settings
print(PYCSAMT_CLI)

# restore defaults
reset_cli()
class pycsamt.api.cli.BuildConfig(n_jobs=1, cache=True, cache_dir=None)

Bases: object

Build / processing execution settings.

Parameters:
n_jobs: int = 1
cache: bool = True
cache_dir: Path | None = None
class pycsamt.api.cli.LogConfig(level=0, color=True, file=None)

Bases: object

Logging / verbosity settings.

Parameters:
level: int = 0
color: bool = True
file: Path | None = None
class pycsamt.api.cli.OutputConfig(format='text', dir=<factory>, overwrite=False)

Bases: object

Output format and destination settings.

Parameters:
format: str = 'text'
dir: Path
overwrite: bool = False
class pycsamt.api.cli.PyCSAMTCLI

Bases: object

Package-wide CLI configuration container.

Access the singleton via PYCSAMT_CLI. Do not instantiate directly unless you need an independent copy.

configure(**kw)

Set attributes using section__attribute dotted paths.

Examples

>>> PYCSAMT_CLI.configure(log__level=1, output__format="json")
>>> PYCSAMT_CLI.configure(build__n_jobs=4)
Parameters:

kw (Any)

Return type:

None

context(**kw)

Temporarily override settings, then restore on exit.

Examples

>>> with PYCSAMT_CLI.context(log__level=2):
...     run_command()
Parameters:

kw (Any)

Return type:

Generator[PyCSAMTCLI, None, None]

reset()

Reset all settings to package defaults.

Return type:

None

load_env()

Override settings from environment variables.

2.2.3.3. Recognised variables#

PYCSAMT_VERBOSE integer 0-2 PYCSAMT_NO_COLOR any non-empty value disables colour PYCSAMT_OUTPUT text | json | csv PYCSAMT_OUTPUT_DIR path PYCSAMT_JOBS integer >= 1

Return type:

None

summary()

Return a human-readable summary of current settings.

Return type:

str

pycsamt.api.cli.configure_cli(**kw)

Configure PYCSAMT_CLI with dotted-path arguments.

Examples

>>> from pycsamt.api.cli import configure_cli
>>> configure_cli(log__level=1, output__format="json")
Parameters:

kw (Any)

Return type:

None

pycsamt.api.cli.reset_cli()

Reset PYCSAMT_CLI to package defaults.

Return type:

None

pycsamt.api.cli.common_options(f)

Attach verbose, no-color, format, and output-dir to a command.

pycsamt.api.cli.format_option(f)

Add the text, JSON, or CSV output-format option to a Click command.

Parameters:

f (FC)

Return type:

FC

pycsamt.api.cli.fresh_option(f)
Parameters:

f (FC)

Return type:

FC

pycsamt.api.cli.n_jobs_option(f)

Add the positive --jobs parallel-worker option to a Click command.

Parameters:

f (FC)

Return type:

FC

pycsamt.api.cli.no_cache_option(f)

Add the --no-cache processing option to a Click command.

Parameters:

f (FC)

Return type:

FC

pycsamt.api.cli.no_color_option(f)

Add the --no-color terminal-output option to a Click command.

Parameters:

f (FC)

Return type:

FC

pycsamt.api.cli.output_dir_option(f)

Add the writable --output-dir path option to a Click command.

Parameters:

f (FC)

Return type:

FC

pycsamt.api.cli.overwrite_option(f)

Add the --overwrite confirmation-bypass option to a Click command.

Parameters:

f (FC)

Return type:

FC

pycsamt.api.cli.survey_option(f)
Parameters:

f (FC)

Return type:

FC

pycsamt.api.cli.verbose_option(f)

Add the repeatable --verbose logging option to a Click command.

Parameters:

f (FC)

Return type:

FC

class pycsamt.api.cli.EDIDir

Bases: Path

A Click Path type for a directory that contains EDI files.

name: str = 'EDI_DIR'

the descriptive name of this type

convert(value, param, ctx)

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

  • value (Any) – The value to convert.

  • param (Parameter | None) – The parameter that is using this type to convert its value. May be None.

  • ctx (Context | None) – The current context that arrived at this value. May be None.

Return type:

Path

class pycsamt.api.cli.EDIPath

Bases: Path

A Click Path type that additionally requires a .edi extension.

name: str = 'EDI_FILE'

the descriptive name of this type

convert(value, param, ctx)

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

  • value (Any) – The value to convert.

  • param (Parameter | None) – The parameter that is using this type to convert its value. May be None.

  • ctx (Context | None) – The current context that arrived at this value. May be None.

Return type:

Path

class pycsamt.api.cli.FreqRange

Bases: ParamType

Parse a fmin:fmax frequency-range string into (float, float).

Examples

--freq 0.1:1000 → (0.1, 1000.0)

name: str = 'FREQ_RANGE'

the descriptive name of this type

convert(value, param, ctx)

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

  • value (Any) – The value to convert.

  • param (Parameter | None) – The parameter that is using this type to convert its value. May be None.

  • ctx (Context | None) – The current context that arrived at this value. May be None.

Return type:

tuple[float, float]

class pycsamt.api.cli.PipeStepList

Bases: ParamType

Parse a comma-separated list of pipeline step codes or names.

Each token is validated against the step registry, so the user gets an immediate error with a hint if they mistype a code.

Examples

--steps NR001,FREQ002,FREQ001,FREQ004,SS001

→ ['NR001', 'FREQ002', 'FREQ001', 'FREQ004', 'SS001']

--steps notch_powerline,drop_duplicates,align_grid

→ ['NR001', 'FREQ002', 'FREQ004']

name: str = 'STEP_LIST'

the descriptive name of this type

convert(value, param, ctx)

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

  • value (Any) – The value to convert.

  • param (Parameter | None) – The parameter that is using this type to convert its value. May be None.

  • ctx (Context | None) – The current context that arrived at this value. May be None.

Return type:

list[str]

class pycsamt.api.cli.StationList

Bases: ParamType

Parse a comma-separated list of station identifiers.

Examples

--stations S01,S02,S03 → ['S01', 'S02', 'S03']

name: str = 'STATION_LIST'

the descriptive name of this type

convert(value, param, ctx)

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

  • value (Any) – The value to convert.

  • param (Parameter | None) – The parameter that is using this type to convert its value. May be None.

  • ctx (Context | None) – The current context that arrived at this value. May be None.

Return type:

list[str]