0.0.9 (#20)

Co-authored-by: gyulaid <gyulaid@gyulai.cloud>
Reviewed-on: #20
Co-authored-by: Daniel Gyulai <gyulaid@gyulai.cloud>
Co-committed-by: Daniel Gyulai <gyulaid@gyulai.cloud>

alice-ci/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = alice-ci
-version = 0.0.7
+version = 0.0.9
 author = Daniel Gyulai
 description = Alice CI framework
 long_description = file: README.md

alice-ci/src/alice/__init__.py

@@ -1,5 +1,5 @@
 # flake8: noqa F401
-from alice.utils import ConfigParser
+from alice.configparser import ConfigParser
 from alice.exceptions import NonZeroRetcode
 from alice.runnerfactory import Factory
 from alice.runners.pythonrunner import PythonRunner

alice-ci/src/alice/cli.py

@@ -1,8 +1,7 @@
 import os
 import argparse
 
-from alice.utils import ConfigParser
+from alice.configparser import ConfigParser
-from alice.runnerfactory import Factory
 from alice.exceptions import ConfigException, NonZeroRetcode, RunnerError
 
 
@@ -19,21 +18,14 @@ def gen_env(param_list):
 
 def parse_jobs(args):
     try:
-        factory = Factory(args.verbose)
         if len(args.env) > 0:
             envs = gen_env(args.env)
             if args.verbose:
                 print(f"[Alice] Env vars from CLI: {envs}")
-        jobParser = ConfigParser(args.input, factory, gen_env(args.env), args.verbose)
+        jobParser = ConfigParser(args.input, gen_env(args.env), args.verbose)
 
-        print("[Alice] Begin pipeline steps")
         for step in args.steps:
-            if step in jobParser.jobs:
+            jobParser.execute(step)
-                status = jobParser.execute_job(step)
-                print(f"[Alice][Step] {step}: {status}")
-            else:
-                raise ConfigException(f"Step {step} not found in {args.input}")
-                exit(1)
     except ConfigException as e:
         print(f"Configuration error-> {e}")
         exit(1)
@@ -46,7 +38,7 @@ def parse_jobs(args):
 
 def main():
     parser = argparse.ArgumentParser(prog="alice")
-    parser.add_argument("steps", nargs='+')
+    parser.add_argument("steps", nargs='*', default=["default"])
     parser.add_argument("-i", "--input", default="alice-ci.yaml")
     parser.add_argument("-e", "--env", nargs='*', default=[])
     parser.add_argument("-a", "--addrunner", nargs='*', default=[])

alice-ci/src/alice/utils.py → alice-ci/src/alice/configparser.py

@@ -3,18 +3,17 @@ import subprocess
 import yaml
 
 from alice.exceptions import ConfigException
+from alice.runnerfactory import Factory
 
 
 class ConfigParser:
-    def __init__(self, file_path, factory, cli_env_vars, verbose=False) -> None:
+    def __init__(self, file_path, cli_env_vars, verbose=False) -> None:
         self.verbose = verbose
         with open(file_path) as f:
             self.config = yaml.safe_load(f)
-        self.factory = factory
+        self.factory = Factory(verbose, self.__gen_globals(cli_env_vars), self.config.get("runners", {}))
-        self.factory.set_globals(self.__gen_globals(cli_env_vars))
-        if "runners" in self.config:
-            self.factory.update_runners(self.config["runners"])
         self.jobs = self.__get_jobs()
+        self.pipelines = self.config.get("pipelines", {})
 
     # Initialize env and workdir if not present in global
     def __gen_globals(self, cli_vars):
@@ -74,8 +73,24 @@ class ConfigParser:
             raise ConfigException(f"Invalid 'changes' config: {changes}")
         return False
 
+    def execute(self, task_name):
+        if task_name in self.jobs:
+            self.execute_job(task_name)
+        elif task_name in self.pipelines:
+            print(f"[Alice][Pipeline] {task_name}: Start")
+            self.execute_pipeline(task_name)
+            print(f"[Alice][Pipeline] {task_name}: Success")
+        else:
+            raise ConfigException(f"No such job or pipeline: {task_name}")
+
+    def execute_pipeline(self, pipeline_name):
+        if pipeline_name in self.pipelines:
+            for job in self.pipelines[pipeline_name]:
+                self.execute_job(job)
+
     def execute_job(self, job_name):
         if job_name in self.jobs:
+            print(f"[Alice][Job] {job_name}: Start")
             job_spec = self.jobs[job_name]
             should_run = True
             if "changes" in job_spec:
@@ -83,6 +98,7 @@ class ConfigParser:
             if should_run:
                 runner = self.factory.get_runner(job_spec["type"])
                 runner.run(job_spec)
-                return "SUCCESS"
+                status = "SUCCESS"
             else:
-                return "SKIP, no change detected"
+                status = "SKIP, no change detected"
+            print(f"[Alice][Job] {job_name}: {status}")

alice-ci/src/alice/runnerfactory.py

@@ -1,35 +1,46 @@
+from os.path import join, abspath
+
 from alice.runners.pythonrunner import PythonRunner
+from alice.runners.pypirunner import PyPiRunner
 from alice.exceptions import ConfigException
 
 
 class Factory():
-    def __init__(self, verbose) -> None:
+    def __init__(self, verbose, globals, runner_configs) -> None:
         self.verbose = verbose
-        self.runnertypes = self.__load_runners()
+        self.globals = globals
         self.runner_configs = {}
+        self.runnertypes = {}
         self.runners = {}
-        self.globals = {}
+        self.__load_runners()
+        self.__gen_runner_configs(runner_configs)
 
     def __load_runners(self):
         # TODO: Runners can be imported via cli too
         # https://git.gyulai.cloud/gyulaid/alice/issues/4
         # module = __import__("module_file")
         # my_class = getattr(module, "class_name")
-        runners = {"python": PythonRunner}
+        self.runnertypes = {"python": PythonRunner,
+                            "pypi": PyPiRunner}
 
         if (self.verbose):
-            print(f"[Alice] Available runners: {'|'.join(runners.keys())}")
+            print(f"[Alice] Available runners: {'|'.join(self.runnertypes.keys())}")
-        return runners
-
-    def set_globals(self, globals):
-        self.globals = globals
 
-    def update_runners(self, config):
+    def __gen_runner_configs(self, config):
         for runnertype, runnerconfig in config.items():
             if runnertype != "global":
                 if (self.verbose):
-                    print(f"[Alice] Configuring runner: {runnertype}")
+                    print(f"[Alice] Global config found for runner {runnertype}")
-                self.get_runner(runnertype).update_config(runnerconfig)
+                config = self.globals.copy()
+                for key, value in runnerconfig.items():
+                    if key == "env":
+                        for env_var in value:
+                            config["env"][env_var["name"]] = env_var["value"]
+                    elif key == "workdir":
+                        config["workdir"] = abspath(join(config["workdir"], value))
+                    else:
+                        config[key] = value
+                self.runner_configs[runnertype] = config
 
     def get_runner(self, runnertype):
         if runnertype not in self.runners:
@@ -39,7 +50,9 @@ class Factory():
                 params = {
                     "verbose": self.verbose
                 }
-                self.runners[runnertype] = self.runnertypes[runnertype](params, self.globals)
+                # If there is a runner specific config, use that, else global
+                config = self.runner_configs.get(runnertype, self.globals.copy())
+                self.runners[runnertype] = self.runnertypes[runnertype](params, config)
             else:
                 raise ConfigException(f"Invalid runner type: {runnertype}")
         return self.runners[runnertype]

alice-ci/src/alice/runners/__init__.py

@@ -1,2 +1,3 @@
 # flake8: noqa F401
 from alice.runners.pythonrunner import PythonRunner
+from alice.runners.pypirunner import PyPiRunner

alice-ci/src/alice/runners/pypirunner.py

@@ -0,0 +1,175 @@
+import json
+import os
+import re
+import subprocess
+import sys
+from urllib import request, error
+from pkg_resources import parse_version
+from os import environ, path
+from alice.runners.pyutils import PackageManager, glob
+from alice.exceptions import ConfigException, RunnerError
+
+
+def grab_from(target):
+    if "from_env" in target:
+        return environ[target["from_env"]]
+    else:
+        raise ConfigException(f"Unsupported grabber: {target.keys()}")
+
+
+def get_uri(config, default):
+    url = config.get("repo", {}).get("uri", default)
+    if url is not None:
+        if not re.match('(?:http|ftp|https)://', url):
+            url = f"https://{url}"
+    return url
+
+
+def get_user(config, default):
+    if "repo" in config:
+        if "username" in config["repo"]:
+            data = config["repo"]["username"]
+            if isinstance(data, str):
+                return data
+            else:
+                return grab_from(data)
+    return default
+
+
+def get_pass(config, default):
+    if "repo" in config:
+        if "password" in config["repo"]:
+            data = config["repo"]["password"]
+            if isinstance(data, str):
+                return data
+            else:
+                return grab_from(data)
+    return default
+
+
+# Parses and stores the config from yaml
+class PypiConfig:
+    def __init__(self, config={}) -> None:
+        self.workdir = path.abspath(config.get("workdir", "."))
+        self.repo_uri = get_uri(config, None)
+        self.repo_user = get_user(config, None)
+        self.repo_pass = get_pass(config, None)
+        self.packages = set(config.get("packages", []))
+        self.upload = config.get("upload", False)
+        self.fail_if_exists = config.get("fail_if_exists", False)
+
+    # returns a PyPiConfig with merged values
+    def copy(self, job_config={}):
+        p = PypiConfig()
+        p.workdir = path.abspath(path.join(self.workdir, job_config.get("workdir", ".")))
+        p.repo_uri = get_uri(job_config, self.repo_uri)
+        p.repo_user = get_user(job_config, self.repo_user)
+        p.repo_pass = get_pass(job_config, self.repo_pass)
+        job_pkg_set = set(job_config["packages"])
+        job_pkg_set.update(self.packages)
+        p.packages = job_pkg_set
+        p.upload = job_config.get("upload", self.upload)
+        p.fail_if_exists = job_config.get("fail_if_exists", self.fail_if_exists)
+        return p
+
+
+# TODO: consider "--skip-existing" flag for twine
+class PyPiRunner():
+    def __init__(self, params, config) -> None:
+        self.verbose = params["verbose"]
+        if self.verbose:
+            print("[PyPiRunner] Initializing")
+        self.workdir = config["workdir"]
+        self.config = PypiConfig(config)
+
+    def __versions(self, repo, pkg_name):
+        if repo is not None:
+            url = f'{repo}/{pkg_name}/json'
+        else:
+            url = f"https://pypi.python.org/pypi/{pkg_name}/json"
+        try:
+            releases = json.loads(request.urlopen(url).read())['releases']
+        except error.URLError as e:
+            raise RunnerError(f"{url}: {e}")
+
+        return sorted(releases, key=parse_version, reverse=True)
+
+    def build(self, config, package):
+        # TODO: Actual build - silent, unless failure!
+        pkg_path = path.join(config.workdir, package)
+        if not path.isdir(pkg_path):
+            raise ConfigException(f"Path does not exists: {pkg_path}")
+        command = [sys.executable, "-m", "build", package]
+        with subprocess.Popen(command, cwd=config.workdir, stdout=subprocess.PIPE, stderr=subprocess.PIPE) as p:
+            p.wait()
+            if p.returncode != 0:
+                print("STDOUT:")
+                sys.stdout.buffer.write(p.stdout.read())
+                print("STDERR:")
+                sys.stdout.buffer.write(p.stderr.read())
+                raise RunnerError(f"[PyPiRunner] Failed to build {package}")
+
+    def find_unuploaded(self, repo, file_list, pkg_name):
+        versions = self.__versions(repo, pkg_name)
+        unuploaded = []
+        for file in file_list:
+            # flake8: noqa W605
+            re_groups = re.findall("(\d*\.\d*\.\d*)", file)
+            if len(re_groups) < 1:
+                raise RunnerError(f"Unable to determine version of file {file}")
+            file_version = re_groups[0]
+            if file_version not in versions:
+                unuploaded.append(file)
+            else:
+                print(f"[PyPiRunner] File already uploaded: {os.path.basename(file)}")
+        return unuploaded
+
+
+    def upload(self, config, package):
+        command = [sys.executable, "-m", "twine", "upload"]
+        if self.verbose:
+            command.append("--verbose")
+        if config.repo_uri is not None:
+            command.append("--repository-url")
+            command.append(config.repo_uri)
+        if config.repo_user is not None:
+            command.append("-u")
+            command.append(config.repo_user)
+        if config.repo_pass is not None:
+            command.append("-p")
+            command.append(config.repo_pass)
+        
+        dist_path = os.path.abspath(os.path.join(config.workdir, package, "dist"))
+        files = glob(os.path.join(dist_path, "*"), config.workdir)
+        for file in files:
+            print(f"[PyPiRunner] Found: {file}")
+
+        to_upload = self.find_unuploaded(config.repo_uri, files, package)
+        if len(to_upload) == 0:
+            return
+        command += to_upload
+        with subprocess.Popen(command, cwd=config.workdir, stdout=subprocess.PIPE, stderr=subprocess.PIPE) as p:
+            p.wait()
+            if p.returncode != 0:
+                print("STDOUT:")
+                sys.stdout.buffer.write(p.stdout.read())
+                print("STDERR:")
+                sys.stdout.buffer.write(p.stderr.read())
+                raise RunnerError(f"[PyPiRunner] Failed to upload {package} ({p.returncode})")
+
+    def run(self, job_spec):
+        job_config = self.config.copy(job_spec)
+
+        PackageManager.getInstance().ensure("build")
+        for package in job_config.packages:
+            print(f"[PyPiRunner] Building {package}")
+            #self.build(job_config, package)
+            print(f"[PyPiRunner] Package {package} built")
+
+        if job_config.upload:
+            PackageManager.getInstance().ensure("twine")
+            for package in job_config.packages:
+                print(f"[PyPiRunner] Uploading {package}")
+                self.upload(job_config, package)
+        else:
+            print(f"[PyPiRunner] Upload disabled, skiping")

alice-ci/src/alice/runners/pythonrunner.py

@@ -4,17 +4,18 @@ import sys
 import shlex
 
 from alice.exceptions import NonZeroRetcode, RunnerError, ConfigException
+from alice.runners.pyutils import glob_command
 
 
-class PythonRunner():
+# TODO: Handle config like PyPiConfig
-    def __init__(self, params, user_defaults) -> None:
+class PythonRunner:
+    def __init__(self, params, config) -> None:
         self.verbose = params["verbose"]
         if self.verbose:
             print("[PythonRunner] Initializing")
-        self.workdir = user_defaults["workdir"]
+        self.workdir = config["workdir"]
         self.virtual_dir = os.path.abspath(os.path.join(self.workdir, "venv"))
-        self.config = user_defaults
+        self.config = config
-
         self.__init_venv()
 
     def __init_venv(self):
@@ -37,50 +38,18 @@ class PythonRunner():
         else:
             if self.verbose:
                 print(f"[PythonRunner] Found virtualenv at {self.virtual_dir}")
-
+        dependencies = self.config.get("dependencies", [])
-    # Stores common defaults for all jobs - all types!
+        if len(dependencies) > 0:
-    # Also - dependency install by config is only allowed in this step
+            if self.verbose:
-    def update_config(self, config):
+                print(f"[PythonRunner] Ensuring dependencies:  {', '.join(dependencies)}")
-        if "dependencies" in config:
+            command = [self.vpython, "-m", "pip", "install"] + dependencies
-            for dependency in config["dependencies"]:
+            with subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE) as p:
-                # TODO: Check what happens with fixed version
+                p.wait()
-                command = [self.vpython, "-m", "pip", "install", dependency, "--upgrade"]
+                if p.returncode != 0:
-                with subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE) as p:
+                    sys.stdout.buffer.write(p.stderr.read())
-                    p.wait()
+                    raise(RunnerError(f"[PythonRunner] Could not install dependencies: {dependencies} ({p.returncode})"))
-                    if p.returncode != 0:
+            if self.verbose:
-                        sys.stdout.buffer.write(p.stderr.read())
+                print("[PythonRunner] Installation done")
-                        raise(RunnerError(f"[PythonRunner] Could not install dependency: {dependency} ({p.returncode})"))
-        if "env" in config:
-            for env_var in config["env"]:
-                self.config["env"][env_var["name"]] = env_var["value"]
-        if "workdir" in config and config["workdir"] is not None:
-            self.workdir = os.path.join(self.workdir, config["workdir"])
-
-    def __ghetto_glob(self, command, workdir):
-        if self.verbose:
-            print(f"[PythonRunner][Globbing] Starting command: {' '.join(command)}")
-        new_command = []
-        for item in command:
-            if "*" in item:
-                if self.verbose:
-                    print(f"[PythonRunner][Globbing] Found item: [{item}]")
-                dir = os.path.abspath(os.path.join(workdir, os.path.dirname(item)))
-                base_name = os.path.basename(item)
-                if os.path.isdir(dir):
-                    item_parts = base_name.split("*")
-                    for file in os.listdir(dir):
-                        # TODO: Fix ordering! A*B = B*A = AB*
-                        if item_parts[0] in file and item_parts[1] in file:
-                            new_item = os.path.join(dir, file)
-                            if self.verbose:
-                                print(f"[PythonRunner][Globbing] Substitute: {new_item}")
-                            new_command.append(new_item)
-                else:
-                    if self.verbose:
-                        print(f"[PythonRunner][Globbing] Dir not exists: {dir}")
-            else:
-                new_command.append(item)
-        return new_command
 
     # Executes the given job in the one and only venv
     # parameter shall be the raw jobscpec
@@ -100,7 +69,7 @@ class PythonRunner():
                     print(f"[PythonRunner] Raw command: {command}")
                 # TODO: only split if command is not an array
                 if "*" in command:
-                    run_command = self.__ghetto_glob(shlex.split(command), pwd)
+                    run_command = glob_command(shlex.split(command), pwd, self.verbose)
                 else:
                     run_command = shlex.split(command)
                 if self.verbose:

alice-ci/src/alice/runners/pyutils.py

@@ -0,0 +1,115 @@
+import os
+import subprocess
+import sys
+from pkg_resources import parse_version
+import re
+
+from alice.exceptions import RunnerError, ConfigException
+
+
+class PackageManager:
+    __instance = None
+
+    @staticmethod
+    def getInstance():
+        """ Static access method. """
+        if PackageManager.__instance is None:
+            PackageManager()
+        return PackageManager.__instance
+
+    def __init__(self):
+        """ Virtually private constructor. """
+        if PackageManager.__instance is not None:
+            raise Exception("This class is a singleton!")
+        else:
+            PackageManager.__instance = self
+        self.package_list = self.__get_packages()
+
+    def __get_packages(self):
+        packages = {}
+        with subprocess.Popen([sys.executable, "-m", "pip", "freeze"],
+                              stdout=subprocess.PIPE, stderr=subprocess.PIPE) as p:
+            p.wait()
+            installed = list(map(lambda x: x.decode("UTF-8").split("=="), filter(lambda x: b'==' in x, p.stdout.read().splitlines())))
+        for name, version in installed:
+            packages[name] = parse_version(version)
+        return packages
+
+    def ensure_more(self, package_list, executable=sys.executable):
+        to_install = list(filter(lambda x: not self.__has_package(x), package_list))
+        if len(to_install) > 0:
+            command = [executable, "-m", "pip", "install"] + to_install
+            with subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE) as p:
+                p.wait()
+                if p.returncode != 0:
+                    sys.stdout.buffer.write(p.stderr.read())
+                    raise(RunnerError(f"[PackageManager] Could not install dependencies ({p.returncode})"))
+            self.package_list = self.__get_packages()
+
+    # Assumption: there are more hits in the long run, than misses
+    def ensure(self, package_string, executable=sys.executable):
+        if not self.__has_package(package_string):
+            command = [executable, "-m", "pip", "install", package_string]
+            with subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE) as p:
+                p.wait()
+                if p.returncode != 0:
+                    sys.stdout.buffer.write(p.stderr.read())
+                    raise(RunnerError(f"[PackageManager] Could not install dependencies ({p.returncode})"))
+            self.package_list = self.__get_packages()
+
+    def __has_package(self, package_string):
+        package_data = re.split("==|>|>=|<|<=", package_string)
+        # check in cache
+        if package_data[0] in self.package_list:
+            # check if version is needed
+            if len(package_data) == 2:
+                required_version = parse_version(package_data[1])
+                installed_version = self.package_list[package_data[0]]
+                comparator = package_string.replace(package_data[0], "").replace(package_data[1], "")
+                if comparator == "==":
+                    return required_version == installed_version
+                elif comparator == ">":
+                    return installed_version > required_version
+                elif comparator == ">=":
+                    return installed_version >= required_version
+                elif comparator == "<":
+                    return installed_version < required_version
+                elif comparator == "<=":
+                    return installed_version <= required_version
+                else:
+                    raise ConfigException(f"Illegal comparator found: {comparator}")
+            else:
+                return True
+        return False
+
+
+def glob(item, workdir, verbose=False):
+    new_command = []
+    if "*" in item:
+        if verbose:
+            print(f"[Globbing] Found item: [{item}]")
+        dir = os.path.abspath(os.path.join(workdir, os.path.dirname(item)))
+        base_name = os.path.basename(item)
+        if os.path.isdir(dir):
+            item_parts = base_name.split("*")
+            for file in os.listdir(dir):
+                # TODO: Fix ordering! A*B = B*A = AB*
+                if item_parts[0] in file and item_parts[1] in file:
+                    new_item = os.path.join(dir, file)
+                    if verbose:
+                        print(f"[Globbing] Substitute: {new_item}")
+                    new_command.append(new_item)
+        else:
+            raise ConfigException(f"[Globbing] Dir not exists: {dir}")
+        return new_command
+    else:
+        return [item]
+
+
+def glob_command(command, workdir, verbose=False):
+    if verbose:
+        print(f"[Globbing] Starting command: {' '.join(command)}")
+    new_command = []
+    for item in command:
+        new_command += glob(item, workdir, verbose)
+    return new_command

ci-examples/full.yaml

@@ -7,7 +7,7 @@ runners:
         value: B
       - name: C
         value: C
-    workdir: packages
+    workdir: .
   python:
     env:
       - name: A
@@ -22,12 +22,33 @@ jobs:
       branch: origin/master
       paths:
         - "docs"
+        - "alice-ci"
     env:
       - name: B
         value: E
     commands:
-      - "-c \"import os; print(os.environ)\""
+      - "-c \"from os import environ; assert environ['A'] == 'D'; assert environ['B'] == 'E'; assert environ['C'] == 'C'; print('Assertions passed')\""
   - name: lint
-    workdir: alice-ci
+    type: python
+    workdir: alice-ci/src
     commands:
-      - "-m flake8 --ignore E501"
+      - "-m flake8 --ignore E501"
+  - name: pkg
+    type: pypi
+    workdir: .
+    upload: false
+    fail_if_exists: false # TODO: currently unused
+    repo:
+      uri: example.com
+      username:
+        from_env: PYPIUSER
+      password:
+        from_env: PYPIPASS
+    packages:
+     - alice-ci
+pipelines:
+  default:
+    - lint
+    - env
+    - pkg
+    

docs/runners.md

@@ -16,17 +16,18 @@ TODO
 
 Each runner has to support the following functions:
 
-### __init__(params, user_defaults)
+### __init__(params, config)
 
 * params: dict of runtime variables for the program itself.
-* user_defaults: raw data from the CI file's global dict, augmented with an "env" dict, which contains environment variables from the host sytem, the CLI params and the pipeline global config, and the "workdir" value, which is the absolute path of the directory that the runner shall recognize as the current working directory.
+* config: Runner config data, aplies to all jobs
 
 #### Params
 
 Currently the only param used is the dict is "verbose", whichis a boolean. The intended purpose is to show debug output if set to True.
 
-#### Workdir
+#### config
-workdir can be assigned at CI yaml level as global
+
+Dict. Has two fix keys, `env` and `workdir`. Env is the environment variables of the host, expanded by CLI parameters, expanded by global config values from yaml. A key defined in the yaml overwrites the value copied from the host. Workdir is similar, can be assigned at CI yaml level as global, but runners may overwrite it.
 Order:
     By default: os.cwd()
     if overwritten in global
@@ -34,11 +35,15 @@ Order:
     if owerwritten in runner config
     if overwritten in job
 
-Runner shall receive the current working directory, unless stated otherwise in global config
+Runner shall receive the current working directory, unless stated otherwise in global config.
 
-### update_config(config)
+The expected behaviour of "overwriting" the workdir is adding the new directory name to the existing path. For example:
+ * cwd = /root
+ * global defines workdir as "projects"
+ * runner config defines workdir as "python"
+ * job defines workdir as "alice"
 
-The function takes the raw data from the parsed yaml under runners.(runnername). Handling its own config is the sole responsibility of the runner. This function may be called at any point of the running lifecycle, so the runner has to support changing its own configuration.
+ In the case above, the actual working directory of the running job shall be `/root/projects/python/alice`.
 
 ### run(job_spec)