step.logic.run_if_env

Environment-gated step execution.

A run_if_env(step, var, ...) call runs the wrapped step only when an environment variable matches (or does not match) an expected value. This is the generic building block behind the convenience guards run_unless_no_calibrate, run_unless_no_checkpoints, run_if_debug and run_if_dev, which map onto the LIBSTP_* flags set by raccoon run (--no-calibrate, --no-checkpoints, --debug, --dev).

The environment is read at execution time, not when the step tree is built, so it reflects the flags the run was actually launched with.

Classes

RunIfEnv

Run a wrapped step only when an environment variable gate passes.

Functions

run_if_env(→ RunIfEnv)

Run a step only when an environment variable matches a value.

run_unless_no_calibrate(→ RunIfEnv)

Run a step unless calibration was skipped (--no-calibrate).

run_unless_no_checkpoints(→ RunIfEnv)

Run a step unless checkpoint waits were disabled (--no-checkpoints).

run_if_debug(→ RunIfEnv)

Run a step only in debug mode (--debug).

run_if_dev(→ RunIfEnv)

Run a step only in dev mode (--dev).

Module Contents

class step.logic.run_if_env.RunIfEnv(step: step.StepProtocol, var: str, equals: str | None = '1', *, negate: bool = False)

Bases: step.Step

Run a wrapped step only when an environment variable gate passes.

The gate is os.environ.get(var) == equals (so equals=None means “the variable is unset”), optionally inverted by negate. When the gate passes the wrapped step runs normally; otherwise it is skipped and a log line is emitted.

collected_resources() → frozenset[str]

Return all resources this step and its children require.

Used by validate_no_overlap for static conflict detection at construction time. Leaf steps don’t need to override this — the default delegates to required_resources. Composite steps override to union their children’s collected resources.

step.logic.run_if_env.run_if_env(step: step.StepProtocol, var: str, equals: str | None = '1', negate: bool = False) → RunIfEnv

Run a step only when an environment variable matches a value.

Evaluates os.environ.get(var) == equals at execution time and runs step when the result is truthy (or falsy, if negate is set). Use equals=None to gate on the variable being unset. The environment is read when the step runs, so it reflects the LIBSTP_* flags raccoon run was launched with.

This is the generic primitive; for the common flags prefer the named guards run_unless_no_calibrate, run_unless_no_checkpoints, run_if_debug and run_if_dev.

Parameters:

  • step – The step to execute when the gate is open.

  • var – Name of the environment variable to inspect.

  • equals – Expected value. The gate matches when the variable equals this string. Pass None to match when the variable is unset. Defaults to "1".

  • negate – Invert the gate — run step when the variable does not match equals. Defaults to False.

Returns:

A RunIfEnv step wrapping step.

Example:

from raccoon.step.logic import run_if_env
from raccoon.step.motion import drive_forward

# Only drive when MY_FLAG is set to "1"
run_if_env(drive_forward(20), "MY_FLAG")

# Only run when DEMO_MODE is unset
run_if_env(drive_forward(20), "DEMO_MODE", equals=None)
step.logic.run_if_env.run_unless_no_calibrate(step: step.StepProtocol) → RunIfEnv

Run a step unless calibration was skipped (--no-calibrate).

Runs step only when LIBSTP_NO_CALIBRATE is not set to "1" — i.e. when raccoon run was launched without --no-calibrate. Use this to wrap interactive calibration that should be bypassed on fast iteration runs.

Parameters:

step – The calibration step to run when calibration is enabled.

Returns:

A RunIfEnv step wrapping step.

Example:

from raccoon.step.logic import run_unless_no_calibrate

run_unless_no_calibrate(calibrate_line_sensor())
step.logic.run_if_env.run_unless_no_checkpoints(step: step.StepProtocol) → RunIfEnv

Run a step unless checkpoint waits were disabled (--no-checkpoints).

Runs step only when LIBSTP_NO_CHECKPOINTS is not set to "1" — i.e. when raccoon run was launched without --no-checkpoints.

Parameters:

step – The step to run when checkpoint timing is active.

Returns:

A RunIfEnv step wrapping step.

Example:

from raccoon.step.logic import run_unless_no_checkpoints

run_unless_no_checkpoints(wait_for_checkpoint("phase-2"))
step.logic.run_if_env.run_if_debug(step: step.StepProtocol) → RunIfEnv

Run a step only in debug mode (--debug).

Runs step only when LIBSTP_DEBUG is set to "1" — i.e. when raccoon run was launched with --debug. Use this to gate diagnostics, extra logging, or interactive pauses that should not affect normal competition runs.

Parameters:

step – The step to run when debug mode is active.

Returns:

A RunIfEnv step wrapping step.

Example:

from raccoon.step.logic import run_if_debug

run_if_debug(wait_for_button("Inspect arm position"))
step.logic.run_if_env.run_if_dev(step: step.StepProtocol) → RunIfEnv

Run a step only in dev mode (--dev).

Runs step only when LIBSTP_DEV_MODE is set to "1" — i.e. when raccoon run was launched with --dev.

Parameters:

step – The step to run when dev mode is active.

Returns:

A RunIfEnv step wrapping step.

Example:

from raccoon.step.logic import run_if_dev

run_if_dev(drive_forward(5))  # short dev-only sanity hop