ksconf package

Submodules

ksconf.archive module

ksconf.archive.GenArchFile

alias of ksconf.archive.GenericArchiveEntry

ksconf.archive.extract_archive(archive_name, extract_filter=None)
ksconf.archive.gaf_filter_name_like(pattern)
ksconf.archive.gen_arch_file_remapper(iterable, mapping)
ksconf.archive.sanity_checker(iterable)

ksconf.consts module

class ksconf.consts.SmartEnum

Bases: enum.Enum

An enumeration.

CREATE = 'created'
NOCHANGE = 'unchanged'
UPDATE = 'updated'

ksconf.filter module

class ksconf.filter.FilteredList(flags=0, default=True)

Bases: object

IGNORECASE = 1
INVERT = 2
VERBOSE = 4
feed(item, filter=None)
feedall(iterable, filter=None)
has_rules
match(item)
match_path(path)
match_stanza(stanza)

Same as match(), but handle GLOBAL_STANZA gracefully.

reset_counters()
class ksconf.filter.FilteredListRegex(flags=0, default=True)

Bases: ksconf.filter.FilteredList

Regular Expression support

calc_regex_flags()
reset_counters()
class ksconf.filter.FilteredListSplunkGlob(flags=0, default=True)

Bases: ksconf.filter.FilteredListRegex

Classic wildcard support (‘*’ and ?’) plus ‘…’ or ‘**’ for multiple-path components with some (non-advertised) pass-through regex behavior

class ksconf.filter.FilteredListString(flags=0, default=True)

Bases: ksconf.filter.FilteredList

Handle simple string comparisons

reset_counters()
class ksconf.filter.FilteredListWildcard(flags=0, default=True)

Bases: ksconf.filter.FilteredListRegex

Wildcard support (handling ‘*’ and ?’) Technically fnmatch also supports [] and [!] character ranges, but we don’t advertise that

ksconf.filter.create_filtered_list(match_mode, flags=0, default=True)

ksconf.layer module

class ksconf.layer.DirectLayerRoot(config=None)

Bases: ksconf.layer.LayerRootBase

A very simple direct LayerRoot implementation that relies on all layer paths to be explicitly given without any automatic detection mechanisms. You can think of this as the legacy implementation.

add_layer(path)
order_layers()
class ksconf.layer.DotDLayerRoot(config=None)

Bases: ksconf.layer.LayerRootBase

class Layer(name, root, physical, logical, config, file_cls, prune_points=None)

Bases: ksconf.layer.Layer

prune_points
walk()
apply_filter(layer_filter)

Apply a destructive filter to all layers. layer_filter(layer) will be called one for each layer, if the filter returns True than the layer is kept. Root layers are always kept.

layer_regex = re.compile('(?P<layer>\\d\\d-[\\w_.-]+)')
list_layers()
mount_regex = re.compile('(?P<realname>[\\w_.-]+)\\.d$')
order_layers()
set_root(root, follow_symlinks=None)

Set a root path, and auto discover all ‘.d’ directories.

Note: We currently only support ‘.d/<layer>’ directories, a file like default.d/10-props.conf won’t be handled here.

class ksconf.layer.LayerConfig

Bases: object

exception ksconf.layer.LayerException

Bases: Exception

class ksconf.layer.LayerFilter

Bases: object

add_rule(action, pattern)
evaluate(layer: LayerRootBase.Layer) → bool
class ksconf.layer.LayerRootBase(config=None)

Bases: object

All ‘path’s here are relative to the ROOT.

class File(layer, relative_path, stat=None)

Bases: os.PathLike

layer
logical_path
mtime
physical_path
relative_path
size
stat
class Layer(name: str, root: str, physical: str, logical: str, config: ksconf.layer.LayerConfig, file_cls: Type[CT_co])

Bases: object

Basic layer Container: Connects logical and physical paths.

config
get_file(path)

Return file object (by logical path), if it exists in this layer.

list_files()
logical_path
name
physical_path
root
walk()
add_layer(layer, do_sort=True)
apply_filter(layer_filter)

Apply a destructive filter to all layers. layer_filter(layer) will be called one for each layer, if the filter returns True than the layer is kept. Root layers are always kept.

get_file(path)

return all layers associated with the given relative path.

get_path_layers(path)
list_files()

Return a list of logical paths.

list_layer_names()
list_layers()
order_layers()
exception ksconf.layer.LayerUsageException

Bases: ksconf.layer.LayerException

ksconf.layer.path_in_layer(layer, path, sep='/')

Check to see if path exist within layer. Returns either None, or the path without the shared prefix with layer.

ksconf.package module

class ksconf.package.AppPackager(src_path, app_name, output)

Bases: object

block_local(report=True)
blocklist(patterns)
check()

Run safety checks prior to building archive:

  1. Set app name based on app.conf [package] id, if set. Otherwise confirm that the package id and top-level folder names align.
  2. Check for files or directories starting with ., makes AppInspect very grumpy!
cleanup()
combine(src, filters, layer_method='dir.d', allow_symlink=False)
expand_new_only(value)

Expand a variable but return False if no substitution occurred

Parameters:value (str) – String that main contain {{variable}} substitution.
Returns:Expanded value if variables were expanded, else False
Return type:str
expand_var(value)

Expand a variable, if present

Parameters:value (str) – String that main contain {{variable}} substitution.
Returns:Expanded value
Return type:str
make_archive(filename)

Create a compressed tarball of the build directory.

merge_local()

Find everything in local, if it has a corresponding file in default, merge.

update_app_conf(version: str = None, build: str = None)

Update version and/or build in apps.conf

class ksconf.package.AppVarMagic(src_dir, build_dir, meta=None)

Bases: object

A lazy loading dict-like object to fetch things like app version and such on demand.

expand(value)

A simple Jinja2 like {{VAR}} substitution mechanism.

get_app_id()

Splunk app package id from app.conf

get_build()

Splunk app build fetched from app.conf

get_git_head()

Git HEAD rev abbreviated

get_git_last_rev()

Git abbreviated rev of the last change of the app. This may not be the same as HEAD.

get_git_tag()

Git version tag using the git describe --tags command

get_layers_hash()

Build a unique hash representing the combination of ksconf layers used.

get_layers_list()

List of ksconf layers used.

get_version()

Splunk app version fetched from app.conf

git_single_line(*args)
list_vars()

Return a list of (variable, description) available in this class.

exception ksconf.package.AppVarMagicException

Bases: KeyError

exception ksconf.package.PackagingException

Bases: Exception

ksconf.package.find_conf_in_layers(app_dir, conf, *layers)
ksconf.package.get_merged_conf(app_dir, conf, *layers)
ksconf.package.normalize_directory_mtime(path)

Walk a tree and update the directory modification times to match the newest time of the children. This results in a more predictable behavior over multiple executions.

ksconf.setup_entrypoints module

Defines all command prompt entry points for CLI actions

This is a silly hack allows for fallback mechanism when
  1. running unit tests (can happen before install)
  2. if entrypoints or pkg_resources are not available at run time (Splunk’s embedded python)
class ksconf.setup_entrypoints.Ep(name, module_name, object_name)

Bases: tuple

module_name

Alias for field number 1

name

Alias for field number 0

object_name

Alias for field number 2

class ksconf.setup_entrypoints.LocalEntryPoint(data)

Bases: object

Bare minimum stand-in for entrypoints.EntryPoint

load()
ksconf.setup_entrypoints.debug()
ksconf.setup_entrypoints.get_entrypoints_fallback(group)
ksconf.setup_entrypoints.get_entrypoints_setup()

ksconf.xmlformat module

class ksconf.xmlformat.FileReadlinesCache

Bases: object

Silly class as a hacky workaround for CDATA detection…

static convert_filename(filename)
readlines(filename)
class ksconf.xmlformat.SplunkSimpleXmlFormatter

Bases: object

static cdata_tags(elem: Any, tags: List[str])

Expand text to CDATA, if it isn’t already.

classmethod expand_tags(elem: Any, tags: set)

Keep <elem></elem> instead of shortening to <elem/>

classmethod format_json(elem: Any, indent=2)

Format JSON data within a Dashboard Studio dashboard. This is still pretty limited (for example, long searches still show up on a single line), but this give you at least a fighting change to figure out what’s different.

classmethod format_xml(src, dest, default_indent=2)
static guess_indent(elem: Any, default=2)
classmethod indent_tree(elem: Any, level=0, indent=2)
keep_tags = {'default', 'earliest', 'fieldset', 'label', 'latest', 'option', 'search', 'set'}

Module contents

ksconf - Ksconf Splunk CONFig tool

Design goals:

  • Multi-purpose go-to .conf tool.
  • Dependability
  • Simplicity
  • No eternal dependencies (single source file, if possible; or packable as single file.)
  • Stable CLI
  • Good scripting interface for deployment scripts and/or git hooks
exception ksconf.KsconfPluginWarning

Bases: Warning