kempnerpulse.config

Cross-cutting tier — parsed configuration.

Turns command-line arguments into a single frozen Config value that the lifecycle, reader, translate, compute, and present layers all read from. This module owns parsing and validation only: it builds the argument parser, resolves the weight preset, applies the backend-aware --poll default, and reports poll-validation problems as data. It never prints, never exits, and never installs signal handlers — those are the lifecycle’s responsibility.

Runtime dependencies are the standard library only.

Functions

build_config([argv])	Parse argv (or sys.argv) into a frozen Config.
build_parser()	Construct the KempnerPulse command-line parser.
parse_weights(raw)	Validate a --weights string into a normalized 4-tuple.
validate_poll(config)	Validate config.poll_seconds against the backend, returning data only.

Classes

Config	Fully-resolved run configuration, frozen for the process lifetime.
PollValidation	Outcome of poll validation, returned as data for the lifecycle to act on.

class kempnerpulse.config.Config

Bases: object

Fully-resolved run configuration, frozen for the process lifetime.

Field semantics:

• gpu_ids is the explicit --gpus selection (already a tuple of string ids), or None when the flag was not supplied. Environment / accessibility resolution is the selection layer’s job, not config’s.

• weights is normalized to sum to 1; preset_name is the matching preset name ("ai" / "hpc" / "mem") or "custom".

• export_spec is None (no export), "default" (--export with no argument), "all", or a comma-separated column list.

• focus_gpu is the id to start focused on, or None.

backend: BackendKind

poll_seconds: float

source: str

gpu_ids: Tuple[str, ...] | None

show_all: bool

weights: Tuple[float, float, float, float]

preset_name: str

export_spec: str | None

once: bool

focus_gpu: str | None

history_length: int

__init__(backend, poll_seconds, source, gpu_ids, show_all, weights, preset_name, export_spec, once, focus_gpu, history_length)

Parameters:

• backend (BackendKind)

• poll_seconds (float)

• source (str)

• gpu_ids (Tuple[str, ...] | None)

• show_all (bool)

• weights (Tuple[float, float, float, float])

• preset_name (str)

• export_spec (str | None)

• once (bool)

• focus_gpu (str | None)

• history_length (int)

Return type:

None

kempnerpulse.config.parse_weights(raw)

Validate a --weights string into a normalized 4-tuple.

Requires exactly four comma-separated numeric values in SM,TENSOR,DRAM,GR order summing to a positive value; the tuple is normalized to sum to 1. Raises argparse.ArgumentTypeError on any malformed input so argparse reports it cleanly.

Parameters:

raw (str)

Return type:

Tuple[float, float, float, float]

kempnerpulse.config.build_parser()

Construct the KempnerPulse command-line parser.

Returned standalone so callers (and tests) can introspect or reuse it without triggering a parse. Defaults mirror the legacy CLI surface; the weight presets and custom-weight default are sourced from the compute layer’s PRESETS so the two never drift.

Return type:

ArgumentParser

kempnerpulse.config.build_config(argv=None)

Parse argv (or sys.argv) into a frozen Config.

Resolves the backend enum, applies the backend-aware --poll default when unset, names the weight preset, and floors the history length. Poll values are not validated here — call validate_poll() on the returned config.

Parameters:

argv (list[str] | None)

Return type:

Config

class kempnerpulse.config.PollValidation

Bases: object

Outcome of poll validation, returned as data for the lifecycle to act on.

error is a user-facing message when the configured poll is invalid (the lifecycle should print it and exit non-zero), else None. When the dcgm backend is asked for a sub-floor interval, clamped is True and note carries an advisory the lifecycle may print to stderr; effective_poll_seconds is the interval that will actually be used.

error: str | None

clamped: bool

note: str | None

effective_poll_seconds: float

__init__(error, clamped, note, effective_poll_seconds)

Parameters:

• error (str | None)

• clamped (bool)

• note (str | None)

• effective_poll_seconds (float)

Return type:

None

kempnerpulse.config.validate_poll(config)

Validate config.poll_seconds against the backend, returning data only.

Rules (ported from the legacy CLI):

• poll <= 0 is an error for any backend.

• prometheus requires poll >= 1.0 (the exporter’s scrape interval is the true ceiling; sub-second values just duplicate samples).

• dcgm allows a sub-100ms request but clamps it up to the 100ms profiling floor, reported via clamped / note rather than printed here.

No printing or exiting happens in this function; the lifecycle owns that.

Parameters:

config (Config)

Return type:

PollValidation