perago.errors 源代码
[文档]
class TaskDefinitionError(ValueError):
"""
Raised when a task module violates the Perago task contract.
Task definition errors are detected while loading, checking, or extracting
a single-task module. They describe authoring-time contract problems such
as unsupported function signatures, invalid workspace checks, or controls
that cannot be represented in a Conductor TaskDef.
See Also
--------
task : Declare a task module contract.
load_module_task : Load and validate the task declared by a module.
build_taskdef : Convert a valid task definition to a Conductor TaskDef.
Examples
--------
>>> TaskDefinitionError("task module must define exactly one task")
TaskDefinitionError('task module must define exactly one task')
"""
[文档]
class RuntimeConfigError(ValueError):
"""
Raised when local runtime configuration is invalid.
Runtime config errors are produced from process environment variables,
``.env`` files, writable root probes, and supervisor settings. They are
local worker setup failures, not task input validation failures.
See Also
--------
load_runtime_config : Load local runtime configuration.
RuntimeConfig : Validated runtime configuration model.
worker_child_specs : Validate supervisor process count and worker ids.
Examples
--------
>>> RuntimeConfigError("CONDUCTOR_SERVER_URL is required for perago start")
RuntimeConfigError('CONDUCTOR_SERVER_URL is required for perago start')
"""
[文档]
class TaskExecutionError(RuntimeError):
"""
Base class for task-authored execution failures.
Task execution errors are raised from task bodies when the task did not
complete successfully. The reason must be a string because Perago writes it
to Conductor's ``reasonForIncompletion`` field.
Parameters
----------
reason : str
Short diagnostic reason reported to Conductor.
Attributes
----------
reason : str
The original task-authored diagnostic reason.
"""
reason: str
def __init__(self, reason: str) -> None:
if not isinstance(reason, str):
raise TypeError("reason must be str")
self.reason = reason
super().__init__(reason)
[文档]
class TaskFailed(TaskExecutionError):
"""
Raised when a task attempt should be reported as retryable ``FAILED``.
Use this for execution failures where retrying the same Conductor input may
succeed, such as transient upstream service errors.
Parameters
----------
reason : str
Short diagnostic reason reported to Conductor.
"""
[文档]
class TaskTerminalError(TaskExecutionError):
"""
Raised when a task attempt should be reported as terminal failure.
Use this for execution failures where retrying the same Conductor input has
no value. Perago maps it to ``FAILED_WITH_TERMINAL_ERROR``.
Parameters
----------
reason : str
Short diagnostic reason reported to Conductor.
"""
[文档]
class GuardrailViolation(RuntimeError):
"""
Raised when a workspace guardrail check fails.
This is the common base class for pre- and post-task workspace check
failures. The runtime maps subclasses by phase so pre-check failures become
terminal Conductor failures while post-check failures remain ordinary
failed attempts.
See Also
--------
PreGuardrailViolation : Raised for failed pre-task workspace checks.
PostGuardrailViolation : Raised for failed post-task workspace checks.
check_guardrails : Evaluate workspace checks against a local workspace.
Examples
--------
>>> GuardrailViolation("required file is missing")
GuardrailViolation('required file is missing')
"""
[文档]
class PreGuardrailViolation(GuardrailViolation):
"""
Raised when pre-task workspace checks fail.
A pre-check failure means the downloaded workspace does not satisfy the
task's required input shape. ``result_for_exception`` maps this subclass to
``FAILED_WITH_TERMINAL_ERROR`` because retrying the same invalid input
should not re-run the task body.
See Also
--------
GuardrailViolation : Base class for workspace check failures.
check_guardrails : Evaluate configured workspace checks.
result_for_exception : Convert this exception to a terminal failed result.
Examples
--------
>>> PreGuardrailViolation("raw/input.parquet is missing")
PreGuardrailViolation('raw/input.parquet is missing')
"""
[文档]
class PostGuardrailViolation(GuardrailViolation):
"""
Raised when post-task workspace checks fail.
A post-check failure means the task body completed but did not leave the
workspace in the declared output shape. The runtime reports it as ordinary
``FAILED`` and does not publish the attempted workspace.
See Also
--------
GuardrailViolation : Base class for workspace check failures.
check_guardrails : Evaluate configured workspace checks.
result_for_exception : Convert runtime exceptions to Conductor results.
Examples
--------
>>> PostGuardrailViolation("features/output.parquet is missing")
PostGuardrailViolation('features/output.parquet is missing')
"""
[文档]
class PublishFenceError(RuntimeError):
"""
Raised when a workspace branch cannot be safely advanced.
Publish fence errors are fail-closed publication failures. They indicate
that the target branch HEAD is neither the attempt input ref nor a commit
whose first parent is the input ref, so the current attempt must not publish
its staged workspace.
See Also
--------
LakeFSWorkspaceRuntime.publish_workspace : Apply the LakeFS HEAD-state
publication protocol.
failed_result : Build the ordinary failed Conductor result used for this
exception.
Examples
--------
>>> PublishFenceError("main cannot publish from input ref old")
PublishFenceError('main cannot publish from input ref old')
"""
[文档]
class StaleAttemptError(RuntimeError):
"""
Raised when a Conductor task snapshot no longer matches the attempt.
Stale attempt errors come from the attempt fence. They prevent a worker
from staging or publishing workspace changes after Conductor has moved the
task out of the same in-progress workflow, task id, or retry count.
See Also
--------
assert_current_attempt_snapshot : Check that a fresh snapshot still matches.
run_workspace_task_attempt : Calls the attempt fence around publication.
failed_result : Build the ordinary failed Conductor result used for this
exception.
Examples
--------
>>> StaleAttemptError("task-9b4c")
StaleAttemptError('task-9b4c')
"""