Skip to content

stepup.core.exceptions

Exceptions used in StepUp.

AmendWhileHoldingError

Bases: GraphError

amend(inp=...) was called while the calling step has an open hold() block.

Source code in stepup/core/exceptions.py 
72
73
class AmendWhileHoldingError(GraphError):
    """`amend(inp=...)` was called while the calling step has an open `hold()` block."""

CgroupError

Bases: RuntimeError

Cgroup v2 accounting is unavailable or unusable for this process.

Source code in stepup/core/exceptions.py 
140
141
class CgroupError(RuntimeError):
    """Cgroup v2 accounting is unavailable or unusable for this process."""

ConfigError

Bases: UsageError, ValueError

A configuration file or environment variable holds something StepUp cannot use.

ValueError is kept in the bases because most of the underlying problems (bad TOML syntax, a value of the wrong type, a value outside the allowed choices) surface as a ValueError before being wrapped in this class.

The raise site says nothing a user could act on: the message names the config file or environment variable to fix.

Source code in stepup/core/exceptions.py 
43
44
45
46
47
48
49
50
51
52
class ConfigError(UsageError, ValueError):
    """A configuration file or environment variable holds something StepUp cannot use.

    `ValueError` is kept in the bases because most of the underlying problems
    (bad TOML syntax, a value of the wrong type, a value outside the allowed choices)
    surface as a `ValueError` before being wrapped in this class.

    The raise site says nothing a user could act on:
    the message names the config file or environment variable to fix.
    """

ConsistencyError

Bases: RuntimeError

An invariant of the workflow graph is violated.

Deliberately not a UsageError: no plan can put the graph in such a state through the public API, so this always points at a bug in StepUp (or at a database corrupted by something outside it), and the full traceback is what a bug report needs.

Source code in stepup/core/exceptions.py 
111
112
113
114
115
116
117
118
119
class ConsistencyError(RuntimeError):
    """An invariant of the workflow graph is violated.

    Deliberately not a `UsageError`:
    no plan can put the graph in such a state through the public API,
    so this always points at a bug in StepUp
    (or at a database corrupted by something outside it),
    and the full traceback is what a bug report needs.
    """

CyclicError

Bases: GraphError

Adding a new relation would introduce a cyclic dependency.

Source code in stepup/core/exceptions.py 
76
77
class CyclicError(GraphError):
    """Adding a new relation would introduce a cyclic dependency."""

EnvVarError

Bases: StepUpError

An environment variable referenced in a path or string could not be resolved.

Source code in stepup/core/exceptions.py 
102
103
class EnvVarError(StepUpError):
    """An environment variable referenced in a path or string could not be resolved."""

GraphError

Bases: UsageError

A change to the graph could not be made as it would introduce an inconsistency.

Source code in stepup/core/exceptions.py 
68
69
class GraphError(UsageError):
    """A change to the graph could not be made as it would introduce an inconsistency."""

HashCancelledError

Bases: HashError

Raised when a hash computation was aborted because its cancel_event was set.

Source code in stepup/core/exceptions.py 
152
153
class HashCancelledError(HashError):
    """Raised when a hash computation was aborted because its `cancel_event` was set."""

HashError

Bases: Exception

Base class for errors raised while computing a file hash.

Source code in stepup/core/exceptions.py 
148
149
class HashError(Exception):
    """Base class for errors raised while computing a file hash."""

HashFailedError

Bases: HashError

Raised when a file cannot be hashed.

Source code in stepup/core/exceptions.py 
156
157
class HashFailedError(HashError):
    """Raised when a file cannot be hashed."""

InputNotFoundError

Bases: Exception

Raised when dynamic inputs are not available yet.

Source code in stepup/core/exceptions.py 
136
137
class InputNotFoundError(Exception):
    """Raised when dynamic inputs are not available yet."""

PathError

Bases: StepUpError

A path argument is invalid.

Raised when a path does not exist, has the wrong type (e.g. a directory where a file is required), or violates the leading ./ / trailing / affix contract.

Source code in stepup/core/exceptions.py 
93
94
95
96
97
98
99
class PathError(StepUpError):
    """A path argument is invalid.

    Raised when a path does not exist, has the wrong type
    (e.g. a directory where a file is required),
    or violates the leading `./` / trailing `/` affix contract.
    """

RPCClientUnusableError

Bases: ConnectionResetError

An RPC client was used after it stopped being able to talk to the server.

The client was closed, or an interrupted exchange left it out of step with the server. Neither is a reset by the peer, which is what makes this worth telling apart, but ConnectionResetError is kept in the bases so that code catching a lost connection keeps catching this too.

Source code in stepup/core/exceptions.py 
126
127
128
129
130
131
132
133
class RPCClientUnusableError(ConnectionResetError):
    """An RPC client was used after it stopped being able to talk to the server.

    The client was closed, or an interrupted exchange left it out of step with the server.
    Neither is a reset by the peer, which is what makes this worth telling apart,
    but `ConnectionResetError` is kept in the bases
    so that code catching a lost connection keeps catching this too.
    """

RPCError

Bases: Exception

A remote procedure call could not be interpreted correctly.

Source code in stepup/core/exceptions.py 
122
123
class RPCError(Exception):
    """A remote procedure call could not be interpreted correctly."""

RunError

Bases: RuntimeError

An error raised by the run module while executing a command.

Source code in stepup/core/exceptions.py 
144
145
class RunError(RuntimeError):
    """An error raised by the `run` module while executing a command."""

StepUpError

Bases: UsageError, ValueError

Invalid argument passed to a StepUp user- or extension-facing API function.

ValueError is kept in the bases so that existing except ValueError code keeps catching these errors.

Source code in stepup/core/exceptions.py 
85
86
87
88
89
90
class StepUpError(UsageError, ValueError):
    """Invalid argument passed to a StepUp user- or extension-facing API function.

    `ValueError` is kept in the bases so that existing `except ValueError` code
    keeps catching these errors.
    """

ToolError

Bases: UsageError

An error raised by a stepup subcommand, i.e. by a tool.

This is what a tool raises for a situation that the user is expected to run into, such as a command that needs a workflow database in a directory that has none.

Source code in stepup/core/exceptions.py 
55
56
57
58
59
60
class ToolError(UsageError):
    """An error raised by a `stepup` subcommand, i.e. by a tool.

    This is what a tool raises for a situation that the user is expected to run into,
    such as a command that needs a workflow database in a directory that has none.
    """

UsageError

Bases: Exception

Base class for errors that the user can fix by changing their own code.

These are reported as a short message without a traceback, unless STEPUP_DEBUG is set: a step or a stepup subcommand that raises one ends with return code 1, and the director sends one to the client without a director-side traceback. Any other exception keeps the full traceback, because it indicates a bug in StepUp rather than in the user’s plan.

Source code in stepup/core/exceptions.py 
32
33
34
35
36
37
38
39
40
class UsageError(Exception):
    """Base class for errors that the user can fix by changing their own code.

    These are reported as a short message without a traceback, unless `STEPUP_DEBUG` is set:
    a step or a `stepup` subcommand that raises one ends with return code `1`,
    and the director sends one to the client without a director-side traceback.
    Any other exception keeps the full traceback,
    because it indicates a bug in StepUp rather than in the user's plan.
    """