API Reference

Note

As of now, no assumptions should be made about APIs remaining stable

KSCONF is first and foremost a CLI tool, so backwards incompatible changes are more of a concern for CLI breakage than for API breakage. That being said, there are a number of helpful features in the core ksconf Python module. So if anyone is interested in using the API, please feel free to do so, but let us know how you are using it and we’ll find a way to keep the the important bits stable. We’d love to make it more clear what APIs are stable and which are likely to change.

As of right now, the general rule of thumb is this: Anything well-covered by the unit tests should be be fairly safe to build on top of, but again, ping us. Also, things used in the cdillc.splunk Ansible Collection should be fairly safe too. There’s a decent bit of back and forth between these two projects driving feature development.

KSCONF API

• ksconf
  • ksconf namespace
    • Subpackages
      • ksconf.app package
      • ksconf.builder package
      • ksconf.commands namespace
      • ksconf.conf package
      • ksconf.plugins namespace
      • ksconf.util package
      • ksconf.vc package
    • Submodules
    • ksconf.archive module
      • GenArchFile
      • extract_archive()
      • gaf_filter_name_like()
      • gen_arch_file_remapper()
      • sanity_checker()
    • ksconf.cli module
      • build_cli_parser()
      • check_py()
      • check_py_sane()
      • cli()
      • handle_cmd_failed()
    • ksconf.combine module
      • LayerCombiner
      • LayerCombinerException
      • handle_merge_conf_files()
      • handle_spec_concatenate()
      • register_handler()
    • ksconf.command module
      • ConfDirProxy
      • ConfFileProxy
      • ConfFileType
      • KsconfCmd
      • add_splunkd_access_args()
      • add_splunkd_namespace()
      • dedent()
      • get_all_ksconf_cmds()
      • get_entrypoints()
    • ksconf.compat module
      • Dict
      • List
      • Set
      • Tuple
      • cache()
    • ksconf.consts module
      • SmartEnum
      • is_debug()
    • ksconf.filter module
      • FilteredList
      • FilteredListRegex
      • FilteredListSplunkGlob
      • FilteredListString
      • FilteredListWildcard
      • create_filtered_list()
    • ksconf.hook module
      • BadPluginWarning
      • get_plugin_manager()
    • ksconf.hookspec module
      • KsconfHookSpecs
      • KsconfPluginWarning
    • ksconf.layer module
      • DirectLayerRoot
      • DotDLayerCollection
      • DotDLayerRoot
      • DotdLayer
      • FileFactory
      • Layer
      • LayerCollectionBase
      • LayerContext
      • LayerException
      • LayerFile
      • LayerFile_Jinja2
      • LayerFilter
      • LayerRenderedFile
      • LayerRootBase
      • LayerType
      • LayerUsageException
      • MultiDirLayerCollection
      • build_layer_collection()
      • register_file_handler()
    • ksconf.package module
      • AppPackager
      • AppVarMagic
      • AppVarMagicException
      • PackagingException
      • find_conf_in_layers()
      • get_merged_conf()
      • normalize_directory_mtime()
    • ksconf.setup_entrypoints module
      • Ep
      • LocalEntryPoint
      • debug()
      • get_entrypoints_fallback()
      • get_entrypoints_setup()
    • ksconf.types module
    • ksconf.version module
    • ksconf.xmlformat module
      • FileReadlinesCache
      • SplunkSimpleXmlFormatter
• Build example
  • Usage notes

Version information

For code bases using ksconf, sometimes behaviors have to vary based on ksconf version.

In general, the best approach is to either (1) specify a hard version requirement in a packaging, or (2) if you have to support a wider range of versions use the EAFP approach of asking for forgiveness rather than permission. In other words, simply try to import the module or call then method you need and if the modules doesn’t exist or the new method argument doesn’t exist yet, capture that in an exception.

Other times a direct version number is helpful to evaluate or simply report to the user. Here’s the approach works across the widest range of ksconf versions:

try:
    from ksconf.version import version, version_info
except ImportError:
    from ksconf._version import version
    # If you need version_info; if not drop this next line
    version_info = tuple(int(p) if p.isdecimal() else p for p in version.split("."))

Note

Historic version capture

In ksconf 0.12.0, the suggested method was to simply use:

from ksconf import __version__

This is simple and straight forward. However this no longer works as of version 0.13 and later due to migration to a namespace package and this is no longer viable. Therefore, we recommend approach detailed above.