qgis_deployment_toolbelt.jobs.generic_job module

Base of QDT jobs.

Author: Julien Moura (https://github.com/guts)

class qgis_deployment_toolbelt.jobs.generic_job.GenericJob

Bases: ABC

Abstract base for QDT jobs.

It provides the shared context (QDT working folders, QGIS profiles folder, operating system configuration, rules context) and helpers to list profiles and validate options. A concrete job must define:

  • ID, the identifier used in the uses key of a scenario step;

  • OPTIONS_SCHEMA, the options accepted in the with key, checked by validate_options();

  • run(), called by the deployment command once the job is instantiated.

ID and OPTIONS_SCHEMA are declared as abstract properties so that a plain class attribute in the subclass implements them.

Example

class JobExample(GenericJob):
    ID: str = "example-job"
    OPTIONS_SCHEMA: dict = {}

    def __init__(self, options: dict) -> None:
        super().__init__()
        self.options: dict = self.validate_options(options)

    def run(self) -> None: ...
ENSURE_QGIS_PROFILES_FOLDER: bool = True
abstract property ID: str

Job identifier, used in the uses key of a scenario step.

abstract property OPTIONS_SCHEMA: dict[str, dict[str, Any]]

Options accepted in the with key of a scenario step.

PROFILES_FOLDER_CACHE: dict[Path, tuple[QdtProfile, ...] | None] = {}
RULES_FILTER_CACHE: dict[tuple[Path, ...], tuple[list[QdtProfile], list[QdtProfile]]] = {}
__init__() → None

Object instanciation.

_abc_impl = <_abc._abc_data object>
_ensure_folder_exists(folder_path: Path, log_label: str | None = None) → None

Create folder and its parents when it does not exist yet.

Parameters:

  • folder_path (Path) – pat to directory to create if absent.

  • log_label (str | None, optional) – human-readable name used in the log message. Defaults to None

classmethod clear_profiles_cache(folder_path: Path | None = None) → None

Invalidate the profiles-folder scan cache to make subsequent jobs re-scan the directory instead of returning cached data.

Parameters:

folder_path (Path | None, optional) – specific cached folder to clear. If None, the entire cache is cleared. Defaults to None.

filter_profiles_folder(start_parent_folder: Path, cached: bool = True, quiet: bool = False) → tuple[QdtProfile, ...] | None

Parse a folder structure to filter on QGIS profiles folders.

Parameters:

  • start_parent_folder (Path) – root directory to scan for profile.json files.

  • cached (bool, optional) – return the previously computed result when available. Defaults to True.

  • quiet (bool, optional) – if True, log the “no profile found” case as debug instead of error. Set this when an empty folder is an expected outcome rather than a failure condition for the calling job. Defaults to False.

Returns:

tuple of profiles objects matching criteria or

None if no profile folder found

Return type:

tuple[QdtProfile, …] | None

filter_profiles_on_qdt_version(tup_qdt_profiles: tuple[QdtProfile, ...]) → tuple[list[QdtProfile], list[QdtProfile]]

Evaluate profiles against their optional qdtMinVersion attribute.

Parameters:

tup_qdt_profiles (tuple[QdtProfile, ...]) – input tuple of QDT profiles

Returns:

tuple of profiles that are compatible with the running QDT version and those which are not

Return type:

tuple[list[QdtProfile], list[QdtProfile]]

filter_profiles_on_rules(tup_qdt_profiles: tuple[QdtProfile, ...], cached: bool = True) → tuple[list[QdtProfile], list[QdtProfile]]

Evaluate profile regarding to its deployment rules. Results are stored in the class RULES_FILTER_CACHE attribute.

Parameters:

  • tup_qdt_profiles (tuple[QdtProfile, ...]) – input tuple of QDT profiles

  • cached (bool, optional) – using previously computed value if not None. Defaults to True.

Returns:

tuple of profiles that matched and those which did not match their deployment rules

Return type:

tuple[QdtProfile], list[QdtProfile]]

get_matching_profile_from_name(li_profiles: list[QdtProfile], profile_name: str) → QdtProfile | None

Get a profile from list of profiles using a profile’s name to match.

Parameters:

  • li_profiles (list[QdtProfile]) – list of profile to look into

  • profile_name (str) – profile name

Returns:

matching profile object

Return type:

QdtProfile

list_downloaded_profiles(quiet: bool = False) → tuple[QdtProfile, ...] | None
List downloaded QGIS profiles, i.e. a profile’s folder located into the QDT

working folder. Typically: ~/.cache/qgis-deployment-toolbelt/repositories/geotribu or %USERPROFILE%/.cache/qgis-deployment-toolbelt/repositories/geotribu).

Parameters:

quiet (bool, optional) – if True, log the “no profile found” case as debug instead of error. Useful for lookups where an empty result is an expected outcome, not a failure. Defaults to False.

Returns:

tuple of profiles objects or None if no profile

folder listed

Return type:

tuple[QdtProfile, …] | None

list_installed_profiles(quiet: bool = False) → tuple[QdtProfile, ...] | None
List installed QGIS profiles, i.e. a profile’s folder located into the QGIS

profiles path and so accessible to the end-user through the QGIS interface. Typically: ~/.local/share/QGIS/QGIS4/profiles/geotribu or %APPDATA%/QGIS/QGIS3/profiles/geotribu).

Parameters:

quiet (bool, optional) – if True, log the “no profile found” case as debug instead of error. Useful for lookups where an empty result is an expected outcome, not a failure. Defaults to False.

Returns:

tuple of profiles objects or None if no profile is

installed in the QGIS profiles folder

Return type:

tuple[QdtProfile, …] | None

property os_config: OSConfiguration

Get current operating system configuration.

Returns:

object with settings regarding operating system and QGIS

Return type:

OSConfiguration

abstractmethod run() → CleanupReport | None

Execute the job logic. Must be implemented by every concrete job.

validate_options(options: dict[str, Any]) → dict[str, Any]

Validate job options against OPTIONS_SCHEMA.

Parameters:

options (dict[str, Any]) – options to validate

Raises:
Returns:

unchanged when all checks pass

Return type:

dict[str, Any]