Jobs¶

jobs ¶

Modules:

Name	Description
`job`
`jobs`
`manager`
`sql`

Functions:

Name	Description
`get_parameters`	Get the job's input parameters.
`update_progress`	Update the job's progress (0-100) with an optional message.
`fail`	Mark the job as failed with an error message.
`complete`	Mark the job as completed with a result dictionary.
`get_context`	Get the context object from caller's globals (set by runpy.run_path).

Attributes:

Name	Type	Description
`T`

T `module-attribute` ¶

T = TypeVar('T')

get_parameters ¶

get_parameters() -> dict[str, Any]

Get the job's input parameters.

Source code in src/jobs/__init__.py

def get_parameters() -> dict[str, Any]:
    """Get the job's input parameters."""
    return _get_job().parameters

update_progress ¶

update_progress(
    progress: int, message: str | None = None
) -> None

Update the job's progress (0-100) with an optional message.

Source code in src/jobs/__init__.py

def update_progress(progress: int, message: str | None = None) -> None:
    """Update the job's progress (0-100) with an optional message."""
    _get_job().update_progress(progress, message)

fail ¶

fail(error: str) -> None

Mark the job as failed with an error message.

Source code in src/jobs/__init__.py

def fail(error: str) -> None:
    """Mark the job as failed with an error message."""
    _get_job().fail(error)

complete ¶

complete(result: dict[str, Any]) -> None

Mark the job as completed with a result dictionary.

Source code in src/jobs/__init__.py

def complete(result: dict[str, Any]) -> None:
    """Mark the job as completed with a result dictionary."""
    _get_job().complete(result)

get_context ¶

get_context(type: type[T]) -> T

get_context(type: None = None) -> Any

get_context(type: type[T] | None = None) -> T | Any

Get the context object from caller's globals (set by runpy.run_path).

If a type is provided, validates that the context is an instance of that type and returns it with the correct type annotation.

Source code in src/jobs/__init__.py

def get_context(type: type[T] | None = None) -> T | Any:
    """Get the context object from caller's globals (set by runpy.run_path).

    If a type is provided, validates that the context is an instance of that type
    and returns it with the correct type annotation.
    """
    frame = inspect.currentframe()
    try:
        caller = frame.f_back if frame else None
        while caller:
            context = caller.f_globals.get("__CONTEXT__")
            if context is not None:
                if type is not None:
                    # Compare by fully-qualified name instead of isinstance()
                    # to handle runpy.run_path() module namespace issues
                    expected = f"{type.__module__}.{type.__qualname__}"
                    actual = f"{context.__class__.__module__}.{context.__class__.__qualname__}"
                    if expected != actual:
                        raise TypeError(
                            f"Context is not an instance of {type.__name__}, got {context.__class__.__name__}"
                        )
                return context
            caller = caller.f_back
        raise RuntimeError("__CONTEXT__ not found in call stack. Are you running inside a job with context?")
    finally:
        del frame

jobs.job ¶

Classes:

Name	Description
`Job`

Attributes:

Name	Type	Description
`JobStatus`

JobStatus `module-attribute` ¶

JobStatus = Literal[
    "pending", "running", "completed", "failed", "cancelled"
]

Job ¶

Bases: ABC

Methods:

Name	Description
`update_progress`	Updates the job's progress.
`start`	Starts the job.
`cancel`	Cancels the job.
`complete`	Completes the job.
`fail`	Sets the job into failed state.
`restart`	Restarts the job.
`remove`	Remove the job from the repository.

Attributes:

Name	Type	Description
`id`	`str`	The unique id of the job.
`type`	`str`	A category of the job. To allow applications to distinguish between different process types.
`name`	`str`	A unique technical name for the job.
`title`	`str`	A human-readable title which might be shown to the end-user.
`file`	`Path`	A Python file which defines the actual job logic.
`parameters`	`dict[str, Any]`	Serialized set of input parameters for the job.
`created`	`datetime`	The datetime when the job has been created (UTC).
`started_at`	`datetime \| None`	The dateime when the job has been started.
`completed_at`	`datetime \| None`	The datetime when the job was last updated.
`updated_at`	`datetime`	The datetime when the job was last updated.
`no_progres_timeout_seconds`	`int`	The time in seconds the job should be considered as stale when no update has been recorded.
`retention_seconds`	`int`	Time in seconds the job should be kept in database after completion before automatic deletion.
`progress`	`int`	The progress as percent value (0 - 100).
`progress_message`	`str \| None`	A message (for users) which describes the current progress.
`status`	`JobStatus`	The status of the job.
`max_retries`	`int`	The number of maximum retries for the job.
`retries`	`int`	Number of current retry attempts.
`retry_timeout_seconds`	`int`	The retry timeout in seconds.
`result`	`dict[str, Any] \| None`	A serialized result of the job.
`error`	`str \| None`	If job has failed, this property will contain the error message.

id `abstractmethod` `property` ¶

id: str

The unique id of the job.

type `abstractmethod` `property` ¶

type: str

A category of the job. To allow applications to distinguish between different process types.

name `abstractmethod` `property` ¶

name: str

A unique technical name for the job.

title `abstractmethod` `property` ¶

title: str

A human-readable title which might be shown to the end-user.

file `abstractmethod` `property` ¶

file: Path

A Python file which defines the actual job logic.

parameters `abstractmethod` `property` ¶

parameters: dict[str, Any]

Serialized set of input parameters for the job.

created `abstractmethod` `property` ¶

created: datetime

The datetime when the job has been created (UTC).

started_at `abstractmethod` `property` ¶

started_at: datetime | None

The dateime when the job has been started.

completed_at `abstractmethod` `property` ¶

completed_at: datetime | None

The datetime when the job was last updated.

updated_at `abstractmethod` `property` ¶

updated_at: datetime

The datetime when the job was last updated.

no_progres_timeout_seconds `abstractmethod` `property` ¶

no_progres_timeout_seconds: int

The time in seconds the job should be considered as stale when no update has been recorded. When this timeout is reached, the job process will be killed and it will be restarted.

retention_seconds `abstractmethod` `property` ¶

retention_seconds: int

Time in seconds the job should be kept in database after completion before automatic deletion.

progress `abstractmethod` `property` ¶

progress: int

The progress as percent value (0 - 100).

progress_message `abstractmethod` `property` ¶

progress_message: str | None

A message (for users) which describes the current progress.

status `abstractmethod` `property` ¶

status: JobStatus

The status of the job.

max_retries `abstractmethod` `property` ¶

max_retries: int

The number of maximum retries for the job.

retries `abstractmethod` `property` ¶

retries: int

Number of current retry attempts.

retry_timeout_seconds `abstractmethod` `property` ¶

retry_timeout_seconds: int

The retry timeout in seconds.

result `abstractmethod` `property` ¶

result: dict[str, Any] | None

A serialized result of the job.

error `abstractmethod` `property` ¶

error: str | None

If job has failed, this property will contain the error message.