ksconf.builder package

Submodules

ksconf.builder.cache module

class ksconf.builder.cache.CachedRun(root)

Bases: object

STATE_DISABLED = 'disabled'

STATE_EXISTS = 'exists'

STATE_NEW = 'new'

STATE_TAINT = 'taint'

cache_dir

cached_inputs

cached_outputs

config_file

disable()

dump()

exists

inputs_identical(inputs)

is_disabled

is_expired

is_new

load()

rename(dest)

root

set_cache_info(type, data)

set_settings(cache_settings)

taint()

class ksconf.builder.cache.FileSet

Bases: object

A collection of fingerprinted files.

Currently the fingerprint is only a SHA256 hash.

Two constructore are provided for building an instance from either file that live on the filesystem, via from_filesystem() or from a persisted cached record aviable from the from_cache(). The filesystem version actively reads all inputs files at object creation time, so this can be costly, especially if repeated.

add_file(root, relative_path)

Add a simple relative path to a file to the FileSet.

add_glob(root, pattern)

Recursively add all files matching glob pattern.

copy_all(src_dir, dest_dir)

Copy a the given set of files from one location to another.

files

files_meta

classmethod from_cache(data)

classmethod from_filesystem(root, files)

static get_fingerprint(path)

ksconf.builder.core module

Cache build requirements:

• Caching mechanism should inspet ‘inputs’ (collect file hashes) to determine if any content has changed. If input varies, then command should be re-run.
• Command (decorated function) should be generally unaware of all other details of build process, and it should ONLY be able to see files listed in “inputs”
• Allow caching to be fully disabled (run in-place with no dir proxying) for CI/CD
• Cache should have allow a timeout parameter

decorator used to implement caching:

• decorator args:

  • inputs: list or glob

  • outputs (do we need this, can we just detect this??)

    Default to “.” (everything)

  • timeout=0 Seconds before cache should be considered stale

  • name=None If not given, default to the short name of the function.

    (Cache “slot”), must be filesystem safe]

class ksconf.builder.core.BuildManager

Bases: object

Management of individual build steps

cache(inputs, outputs, timeout=None, name=None, cache_invalidation=None)

function decorator

XXX: Clearly document what things are good cache candidates and which are not.

Example:

• No extra argument to the function (at least currently)
• Changes to inputs files are not supported
• Deleting files aren’t supported
• Can only operate in a single directory given a limited set of inputs
• Cannot read from the source directory, and agrees not to write to dist (In other words, limit all activities to build_path for deterministic behavior)

disable_cache()

get_build_step(output=None)

get_cache_info(name)

set_folders(source_path, build_path, dist_path=None)

taint_cache()

ksconf.builder.steps module

ksconf.builder.steps: Collection of reusable build steps for reuse in your build script.

ksconf.builder.steps.clean_build(step)

Ensure a clean build folder for consistent build results.

ksconf.builder.steps.copy_files(step, patterns)

Copy source files into the build folder that match given glob patterns

ksconf.builder.steps.pip_install(step, requirements_file='requirements.txt', dest='lib', python_path=None, isolated=True, dependencies=True, handle_dist_info='remove', remove_console_scripts=True)

Module contents

exception ksconf.builder.BuildCacheException

Bases: Exception

exception ksconf.builder.BuildExternalException

Bases: Exception

class ksconf.builder.BuildStep(build, source=None, dist=None, output=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

Bases: object

alternate_path(path)

Construct a new BuildStep instance with only ‘build_path’ altered.

build_path

config

dist_path

get_logger(prefix=None)

is_quiet

is_verbose()

run(*args)

Execute an OS-level command regarding the build process. The process will run withing the working directory of the build folder.

source_path

verbosity

ksconf.builder.default_cli(build_manager, build_funct, argparse_parents=())

This is the function you stick in the: if __name__ == '__main__' section of your code :-)

Pass in a BuildManager instance, and a callback function. The callback function must accept (steps, args). If you have need for custom arguments, you can add them to your own ArgumentParser instance and pass them to the argparse_parents keyword argument, and then handle additional ‘args’ passed into the callback function.