diff options
| author | Frederick Muriuki Muriithi <fredmanglis@gmail.com> | 2026-11-11 19:04:07 +0000 |
|---|---|---|
| committer | Frederick Muriuki Muriithi <fredmanglis@gmail.com> | 2026-11-11 14:06:44 -0600 |
| commit | 98f2e739ef4724bdd3043fad8277c4444986326b (patch) | |
| tree | 03717920a3f17d010846971cadbbbde4e0e235ba /gn_libs/jobs | |
| parent | 9a30e5112f252d7aa5a09fd718733a35c7869b4e (diff) | |
| download | gn-libs-main.tar.gz | |
Change `initialise_job` to accept metadata as keyword arguments, with
`expiry_seconds` as a keyword-only reserved argument. Document the
`external_id` value, and the `workflow_claim` metadata convention for
idempotent stage transitions.
Call sites that pass `extra_meta={...}` must unpack the dict instead.
Co-authored-by: pi coding agent <pi@pi.dev>
Diffstat (limited to 'gn_libs/jobs')
| -rw-r--r-- | gn_libs/jobs/jobs.py | 62 |
1 files changed, 48 insertions, 14 deletions
diff --git a/gn_libs/jobs/jobs.py b/gn_libs/jobs/jobs.py index f45819c..03b9b44 100644 --- a/gn_libs/jobs/jobs.py +++ b/gn_libs/jobs/jobs.py @@ -7,7 +7,7 @@ import logging import subprocess from pathlib import Path from functools import partial -from typing import Mapping, Union, Optional +from typing import Any, Mapping, Union, Optional from datetime import datetime, timezone, timedelta from gn_libs.sqlite3 import DbCursor, DbConnection, cursor as _cursor @@ -160,23 +160,57 @@ def initialise_job(# pylint: disable=[too-many-arguments, too-many-positional-ar job_id: uuid.UUID, command: list, job_type: str, - extra_meta: Optional[dict] = None, + *, expiry_seconds: int = _DEFAULT_EXPIRY_SECONDS_, - external_id: Optional[Union[str, uuid.UUID]] = None + **extra_meta ) -> dict: - """Initialise the job and put the details in a SQLite3 database.""" - if extra_meta is None: - extra_meta = {} + r"""Initialise the job and put the details in a SQLite3 database. + + Metadata is passed as keyword arguments. ``expiry_seconds`` is a + reserved operational argument and is handled explicitly rather + than as user metadata. + + The ``**extra_meta`` takes any type for the values; in practice, + however, those values should be easy to marshall/unmarshall + to/from the ``str`` type. + + The following special metadata value items need attention: + + - An ``external_id`` metadata value, when it exists, should be a + ``str``, ``uuid.UUID`` or ``None`` value. Any other value will + raise an exception. + - A ``workflow_claim`` metadata value of the form + ``<workflow>:<root-id>:<stage>`` can be used, together with a + unique index on the metadata value, to make stage transitions + idempotent. + + :param conn: A connection to the jobs database. + :type conn: gn_libs.sqlite3.DbConnection + :param job_id: The identifier for this job. + :type job_id: uuid.UUID + :param command: The command this job will run. + :type command: Sequence[str] + :param expiry_seconds: How long to keep the job around for from creation + :type expiry_seconds: int + :param \*\*extra_meta: extra metadata fields for the job. + :type \*\*extra_meta: Any + """ + + def __process_external_id__(_id: Any) -> dict[str, str]: + if _id is None: + return {} - def __process_external_id__(_id: Optional[Union[str, uuid.UUID]]) -> str: if isinstance(_id, uuid.UUID): - return str(_id) + return {"external_id": str(_id)} - if _id is not None and bool(_id.strip()): - return str(_id.strip()) - return "" + if isinstance(_id, str): + stripped = _id.strip() + return {"external_id": stripped} if bool(stripped) else {} - _ext_id = __process_external_id__(external_id) + raise ValueError( + "`external_id` MUST be a string or uuid.UUID value when provided") + + _ext_id = __process_external_id__(extra_meta.pop("external_id", None)) _job = { "job_id": job_id, "command": shlex.join(command), @@ -186,10 +220,10 @@ def initialise_job(# pylint: disable=[too-many-arguments, too-many-positional-ar "percent": 0, "job-type": job_type, **extra_meta, - **({"external_id": _ext_id} if bool(_ext_id) else {}) + **_ext_id } } - return __save_job__(conn, _job, expiry_seconds, _ext_id) + return __save_job__(conn, _job, expiry_seconds, _ext_id.get("external_id", "")) def output_file(jobid: uuid.UUID, outdir: Path, stream: str) -> Path: |
