Job

abc

Abstract base class for flepimop2 job runners.

JobABC

Bases: ModuleBase

Abstract base class for flepimop2 job runners.

status(handle)

Query the status of a previously submitted job.

Runs _status_validate first; if issues are found they are raised as a Flepimop2ValidationError. Otherwise delegates to _status.

Parameters:

Name	Type	Description	Default
handle	JobHandle	The handle returned when the job was submitted.	required

Returns:

Type	Description
JobStatusResult	A JobStatusResult describing the job's current state.

Raises:

Type	Description
Flepimop2ValidationError	If _status_validate returns issues.

Source code in src/flepimop2/job/abc/__init__.py

def status(self, handle: JobHandle) -> JobStatusResult:
    """Query the status of a previously submitted job.

    Runs `_status_validate` first; if issues are found they are raised as
    a `Flepimop2ValidationError`. Otherwise delegates to `_status`.

    Args:
        handle: The handle returned when the job was submitted.

    Returns:
        A `JobStatusResult` describing the job's current state.

    Raises:
        Flepimop2ValidationError: If `_status_validate` returns issues.
    """
    if (issues := self._status_validate()) is not None and issues:
        raise Flepimop2ValidationError(issues)
    return self._status(handle)

submit(command, *, dry_run=False)

Submit command for execution on this job backend.

Runs _submit_validate first; if issues are found they are raised as a Flepimop2ValidationError. The dry_run flag is forwarded to _submit so that backends can perform all of the work leading up to a submission (rendering batch scripts, staging files, resolving resources, ...) and then stop just before the submission itself, returning a JobDryRun that describes what would have been submitted.

Parameters:

Name	Type	Description	Default
command	CliCommand	The CLI command instance to submit.	required
dry_run	bool	If True, perform preflight work but do not actually submit.	False

Returns:

Type	Description
JobHandle | JobDryRun	A JobHandle for the submitted work unit, or a JobDryRun
JobHandle | JobDryRun	describing the skipped submission when dry_run=True.

Raises:

Type	Description
Flepimop2ValidationError	If _submit_validate returns issues.

Source code in src/flepimop2/job/abc/__init__.py

def submit(
    self, command: "CliCommand", *, dry_run: bool = False
) -> JobHandle | JobDryRun:
    """Submit `command` for execution on this job backend.

    Runs `_submit_validate` first; if issues are found they are raised as
    a `Flepimop2ValidationError`. The `dry_run` flag is forwarded to
    `_submit` so that backends can perform all of the work leading up to a
    submission (rendering batch scripts, staging files, resolving
    resources, ...) and then stop just before the submission itself,
    returning a `JobDryRun` that describes what would have been submitted.

    Args:
        command: The CLI command instance to submit.
        dry_run: If `True`, perform preflight work but do not actually
            submit.

    Returns:
        A `JobHandle` for the submitted work unit, or a `JobDryRun`
        describing the skipped submission when `dry_run=True`.

    Raises:
        Flepimop2ValidationError: If `_submit_validate` returns issues.
    """
    if (issues := self._submit_validate()) is not None and issues:
        raise Flepimop2ValidationError(issues)
    return self._submit(command, dry_run=dry_run)

JobDryRun

Bases: BaseModel

A description of the submission a dry run skipped.

Returned by JobABC.submit (in place of a JobHandle) when dry_run is requested, so the caller can report exactly what would have been submitted without actually submitting it.

Attributes:

Name	Type	Description
command	str	The command the backend would have run, rendered for display (e.g. flepimop2 simulate ... for the shell backend, or sbatch ... for a Slurm backend).
details	dict[str, str]	Optional backend-specific specifics about the skipped submission (working directory, partition, generated script path, ...).

JobHandle

Bases: BaseModel

A reference to a submitted job.

Modeled with pydantic so handles can be serialized to and parsed from JSON (with validation) for persistent caching.

Attributes:

Name	Type	Description
job_id	str	Opaque token identifying the job on the backend (PID, Slurm id, ARN, ...).
backend	str	The job module name that produced this handle.
submitted_at	datetime	When the job was submitted.
metadata	dict[str, Any]	Optional backend-specific metadata (partition, queue, ...).

__str__()

Return a short, single-line representation suitable for stdout.

Source code in src/flepimop2/job/abc/__init__.py

def __str__(self) -> str:
    """Return a short, single-line representation suitable for stdout."""
    ts = self.submitted_at.strftime("%Y-%m-%dT%H:%M:%S")
    return f"{self.backend}-{self.job_id} submitted_at={ts}"

JobStatus

Bases: StrEnum

The lifecycle state of a submitted job.

Attributes:

Name	Type	Description
PENDING		The job has been accepted but has not started running.
RUNNING		The job is currently executing.
SUCCESSFUL		The job finished and is believed to have succeeded.
FAILED		The job finished and is believed to have failed.
FINISHED_UNKNOWN		The job finished but its success or failure could not be determined (e.g. a detached subprocess whose exit code can no longer be recovered).

is_finished property

Whether this status represents a terminal (finished) state.

JobStatusResult

Bases: JobHandle

The status of a submitted job.

A JobHandle enriched with the job's current lifecycle status and an optional, backend-specific detail payload.

Attributes:

Name	Type	Description
status	JobStatus	The current lifecycle state of the job.
detail	dict[str, Any]	Optional backend-specific status details (exit code, queue position, node assignment, ...).

__str__()

Return a short, single-line representation suitable for stdout.

Source code in src/flepimop2/job/abc/__init__.py

def __str__(self) -> str:
    """Return a short, single-line representation suitable for stdout."""
    return f"{super().__str__()} status={self.status.value}"

build(config)

Build a JobABC from a configuration dictionary.

Parameters:

Name	Type	Description	Default
config	dict[str, Any] | ModuleBase | str	Configuration dictionary. The dict should contain a 'module' key, which will be used to lookup the job module path. The module will have "flepimop2.job." prepended.	required

Returns:

Type	Description
JobABC	The constructed job object.

Source code in src/flepimop2/job/abc/__init__.py

def build(config: dict[str, Any] | ModuleBase | str) -> JobABC:
    """Build a `JobABC` from a configuration dictionary.

    Args:
        config: Configuration dictionary. The dict should contain a
            'module' key, which will be used to lookup the job module path.
            The module will have "flepimop2.job." prepended.

    Returns:
        The constructed job object.
    """
    return _build(config, "job", JobABC)  # type: ignore[type-abstract]

shell

Shell job runner for flepimop2. For development and testing only.

ShellJob

Bases: JobABC

Run a command locally via subprocess. For dev/testing — not production.

Attributes:

Name	Type	Description
module	str	The fully-qualified module name, resolved from module="shell" to "flepimop2.job.shell".
cwd	Path | None	Optional working directory for the subprocess.
env	dict[str, str] | None	Optional environment variables for the subprocess. If None, the current process environment is inherited.
detach	bool	If True (the default), the subprocess runs detached in a new session and control returns immediately. If False, the call blocks until the subprocess exits (useful for tests).