step.logic.run_if_env
=====================

.. py:module:: step.logic.run_if_env

.. autoapi-nested-parse::

   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
-------

.. autoapisummary::

   step.logic.run_if_env.RunIfEnv


Functions
---------

.. autoapisummary::

   step.logic.run_if_env.run_if_env
   step.logic.run_if_env.run_unless_no_calibrate
   step.logic.run_if_env.run_unless_no_checkpoints
   step.logic.run_if_env.run_if_debug
   step.logic.run_if_env.run_if_dev


Module Contents
---------------

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

   Bases: :py:obj:`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.


   .. py:method:: 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.



.. py:function:: 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``.

   :param step: The step to execute when the gate is open.
   :param var: Name of the environment variable to inspect.
   :param equals: Expected value. The gate matches when the variable equals
                  this string. Pass ``None`` to match when the variable is
                  unset. Defaults to ``"1"``.
   :param 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)


.. py:function:: 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.

   :param 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())


.. py:function:: 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``.

   :param 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"))


.. py:function:: 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.

   :param 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"))


.. py:function:: 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``.

   :param 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