ksconf.builder package¶
Submodules¶
ksconf.builder.cache module¶
-
class
ksconf.builder.cache.
CachedRun
(root: pathlib.Path)¶ 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: ksconf.builder.cache.FileSet) → bool¶
-
is_disabled
¶
-
is_expired
¶
-
is_new
¶
-
load
()¶
-
rename
(dest)¶
-
root
¶
-
set_cache_info
(type: str, data: ksconf.builder.cache.FileSet)¶
-
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 thefrom_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
New in version v0.8.0.
-
cache
(inputs: List[str], outputs: int, timeout: int = None, name: str = None, cache_invalidation: Union[dict, list, str] = None) → None¶ function decorator for caching build steps Wrapped function must accept BuildStep instance as first parameters
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)¶
-
is_folders_set
()¶
-
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: ksconf.builder.BuildStep) → None¶ Ensure a clean build folder for consistent build results.
-
ksconf.builder.steps.
copy_files
(step: ksconf.builder.BuildStep, patterns: List[str], target: str = None) → None¶ Copy source files into the build folder that match given glob patterns
-
ksconf.builder.steps.
pip_install
(step: ksconf.builder.BuildStep, requirements_file: str = 'requirements.txt', dest: str = 'lib', python_path: str = None, isolated: bool = True, dependencies: bool = True, handle_dist_info: str = 'remove', remove_console_scripts: bool = True) → None¶
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: str = None) → Callable¶
-
is_quiet
¶
-
is_verbose
()¶
-
run
(executable, *args, **kw_only)¶ Execute an OS-level command regarding the build process. The process will run withing the working directory of the build folder.
Parameters: - executable (str) – Executable to launch for a build step.
- args (str) – Additional argument(s) for the new process.
- cwd (str) – Optional kw arg to change the working directory. This defaults to the build folder.
-
source_path
¶
-
verbosity
¶
-
-
ksconf.builder.
default_cli
(build_manager: ksconf.builder.core.BuildManager, build_funct: Callable, argparse_parents: List[argparse.ArgumentParser] = ())¶ 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.