luci package

Submodules

luci.cli module

Console script for luci.

class luci.cli.LuciCommand(**kwargs)

Bases: click.core.MultiCommand

Class to create and wrap around any Lucifier, with added features to generate a command-line interface for each of them..

This class extends click.MultiCommand. It uses a special Lucifier, CliLucifier to hold the Lucifier, investigate it’s metadata and create the cli in a way click understands.

get_command(ctx, name)

Returns the process() function of a wrapped Lucifier object.

list_commands(ctx)

Lists all registered Lucifiers.

stevedore is used to load the registered plugins. In order to register a plugin, you need to create a class that extends Lucifier, and you needs to specify it like below in a packages’ setup.py:

entry_points={
    'luci.lucifiers': [
        'metadata=luci.lucifiers:MetadataLucifier'
    ]
}

luci.cli_lucifier module

class luci.cli_lucifier.CliLucifier(ctx=None, dictlet=None, **kwargs)

Bases: luci.lucify.Lucifier

Lucifier to create a command-line interface with options and argument(s).

This Lucifier is a special case, as it take a class that extend Lucifier as an ‘input-dictlet’.

Parameters:ctx (dict) – the context passed from the parent MultiCommand

LUCI_CLI = {'__lucify__': {'doc': {'short help': 'creating a command-line interface', 'epilog': "the 'cli' lucifier is part of the luci package"}, 'lucifiers': {'cli': {'reader': {'config': {'class': {'keys': {'__luci__': '__luci__'}}}, 'name': 'class'}}}}}

get_default_metadata()

If a child Lucifier overwrites this method, the returned metadata is used as a base dict (instead of an empty one).

This is useful to set things like default readers/finders, or add default cli options to the child dictlet.

Returns:(optional) initial metadata for this type of Lucifier Return type:dict

get_dictlet(dictlet_path)

process_dictlet(metadata, dictlet_details=None)

Assembles the click.Multicommand that represents a lucifier.

This uses the name of the stevedore extension that was selected as command-name, and the default values that were also used for this ‘parent’ CliLucifier as initial metadata. The ‘child’ lucifier will be assembled in the LucifierCommand constructor.

Returns:the command Return type:function

class luci.cli_lucifier.LucifierCommand(name, lucifier_defaults, dictlet=None, **kwargs)

Bases: click.core.MultiCommand

Class to assemble and hold a Lucifier object, and create a dictlet-cli-command according to user input.

Internally, this uses stevedore to load the lucifier extension that matches the selected command name.

Parameters:

• name – the name (alias) of the selected command
• lucifier_defaults (dict) – the default metadata dict with which to initialize the Lucifier

get_command(ctx, name)

Returns a command function that is enriched with the metadata of the specified dictlet.

If the command_cache for this object was created, it is used to retrieve the result, otherwise the get_command_direct() method is used.

Parameters:

• ctx (click.Context) – the context
• name (str) – the name/path of/to the dictlet

Returns:

the function callback for click to use to create a (sub-)command-line interface

Return type:

function

get_command_cache(ctx)

Creates the command cache that contains all auto-detectable dictlets.

Non-auto-detectable dictlets can still be loaded if the user specifies their exact path/name.

Parameters:ctx (click.Context) – the context

get_command_direct(ctx, name, no_cache=False)

Parameters:

• ctx (click.Context) – the context
• name (str) – the name/path of/to the dictlet
• no_cache (bool) – whether to involve cache or not (depending on the use-case, one might be faster than the other)

Returns:

the function callback for click to use to create a (sub-)command-line interface

Return type:

function

list_commands(ctx)

Lists all auto-detectable dictlets.

Parameters:ctx (click.Context) – the context Returns:a listof dictlet-names/paths Return type:list

luci.defaults module

luci.docs module

luci.docs.get_lucifier(command_name)

Utility method to generate a LucifierCommand instance for the automated docs generation with Sphinx.

luci.exceptions module

exception luci.exceptions.DictletParseException(message, dictlet_name)

Bases: exceptions.Exception

exception luci.exceptions.NoSuchDictletException(dictlet_name)

Bases: exceptions.Exception

luci.finders module

class luci.finders.DictletFinder

Bases: object

Abstract base class for an object that can find and load dictlets.

The task of a DictletFinder is to find all available dictlets for the current environment. A sub-class of this should implement the find_available_dictlets() and/or, if applicable, overwrite the get_dictlet_details() methods.

If it’s not possible to get a list of all available dictlets, it’s advisable to return an empty dict for the find_available_dictlets() method and implement get_dictlet_details().

get_all_dictlet_names()

Returns a list of all available dictlet names.

Returns:all dictlet names Return type:list

get_all_dictlets()

Returns all available dictlets.

Returns:a dictionary with the dictlet name as key, and it’s url as value Return type:dict

get_dictlet(name)

Loads the dictlet with the specified name/path.

Parameters:name (str) – the name (or path) of the dictlet Returns:details for this dictlet, None if not found Return type:dict

get_dictlet_details(name)

Returns the details of the dictlet with the specified name.

The returned details should contain at least a ‘type’ key, indicating the type of the dictlet (e.g. ‘file’, ‘class’). Which and whether other keys are necessary depends on that type.

Parameters:name – the name or url of a dictlet Returns:details about this dictlet Return type:dict

init_dictlet_cache(name=None)

Fills the cache, either with all dictlets, or only the one whose name was specified.

Parameters:name (str) – if specified, only the dictlet with that name is loaded, otherwise all available Returns:a dictionary with either one (requested) dictlet and it’s details, or all of them Return type:dict

class luci.finders.FolderFinder(**kwargs)

Bases: luci.finders.DictletFinder

Simple finder for folders.

get_all_dictlet_names()

Returns a list of all available dictlet names.

Returns:all dictlet names Return type:list

get_dictlet(name)

Loads the dictlet with the specified name/path.

Parameters:name (str) – the name (or path) of the dictlet Returns:details for this dictlet, None if not found Return type:dict

class luci.finders.FolderOrFileFinder(**kwargs)

Bases: luci.finders.DictletFinder

Simple finder for folders.

get_all_dictlet_names()

Returns a list of all available dictlet names.

Returns:all dictlet names Return type:list

get_dictlet(name)

Loads the dictlet with the specified name/path.

Parameters:name (str) – the name (or path) of the dictlet Returns:details for this dictlet, None if not found Return type:dict

class luci.finders.LucifierFinder

Bases: luci.finders.DictletFinder

Finds all lucifiers.

This lucifier is mainly used to create a command-line interface using the luci.cli_lucifer.CliLucifier class.

get_all_dictlet_names()

Returns a list of all available dictlet names.

Returns:all dictlet names Return type:list

get_dictlet(name)

Loads (stevedore-registered) available lucifier class in this Python environment. :returns: lucifier details :rtype: dict

class luci.finders.PathDictletFinder(paths=None, max_folders=2)

Bases: luci.finders.DictletFinder

Can find dictlets using a list of paths.

Parameters:

• paths (list) – a list of paths where to look for dictlets
• max_folders (int) – how many child-folder levels to look for dictlets, this is restricted by default because for performance reasons

CONTENT_MARKER_REGEX = <_sre.SRE_Pattern object>

find_available_dictlets(paths=None)

Finds all available dictlets under the specified paths.

Parameters:paths (list) – the paths to look in. If not specified, the objects default paths will be used Returns:all dictlets and their details Return type:dict

find_available_dictlets_path(base_path, relative_path='', current_result=None, current_level=0)

Checks a path for valid dictlet files.

Parameters:

• base_bath (str) – the base path (corresponding to one of the object initial paths)
• relative_path (str) – relative path (from the base_path) to the folder/file in question
• current_result (dict) – used for recursive call of this method
• current_level (int) – used for recursive call of this method

Returns:

a list of available dictlets (so far)

Return type:

dict

get_all_dictlet_names()

Returns a list of all available dictlet names.

Returns:all dictlet names Return type:list

get_dictlet(name)

Loads the dictlet with the specified name/path.

Parameters:name (str) – the name (or path) of the dictlet Returns:details for this dictlet, None if not found Return type:dict

luci.finders.check_dictlet_content(file_path, regex)

Checks whether a dictlet file matches the specified regular expression.

Parameters:

• file_path (str) – the path to the dictlet
• regex (str, _sre.SRE_Pattern) – the regular expression

Returns:

whether there was a match or not

Return type:

bool

luci.finders.create_dictlet_finder(dictlet_finder_name, dictlet_finder_config=None)

Create a dictlet reader with the provided config.

Parameters:

• dictlet_finder_name (str) – the registered name (in setup.py entry point)
• dictlet_finder_config (dict) – optional configuration for the finder object

Returns:

the finder object

Return type:

DictletFinder

luci.lucifiers module

class luci.lucifiers.CatLucifier(**kwargs)

Bases: luci.lucify.Lucifier

Very simple lucifier, outputs the part of the dictlet that is not processed by luci.

DEFAULT_READER = 'skip'

LUCI_CAT = {'__lucify__': {'doc': {'short help': 'creating a command-line interface', 'epilog': "the 'cli' lucifier is part of the luci package", 'short_help': 'output of the dictlet (minus the luci parts)'}, 'register': {'content_filtered': '__cat__.data', 'metadata': '__cat__.metadata'}, 'vars': {'__cat__.display_luci_contents': {'default': False, 'doc': {'help': 'print the whole dictlet, including luci metadata'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'is_flag': True, 'param_decls': ['--luci-content', '-l']}}}, '__cat__.pager': {'default': False, 'doc': {'help': 'whether to use a pager for display'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'param_decls': ['--pager', '-p'], 'type': <type 'bool'>, 'is_flag': True}}}}, 'lucifiers': {'cli': {'reader': {'config': {'class': {'keys': {'__luci__': '__luci__'}}}, 'name': 'class'}}}}}

get_default_metadata()

If a child Lucifier overwrites this method, the returned metadata is used as a base dict (instead of an empty one).

This is useful to set things like default readers/finders, or add default cli options to the child dictlet.

Returns:(optional) initial metadata for this type of Lucifier Return type:dict

process_dictlet(metadata, dictlet_details)

The main method implemented by a lucifier, it executes the task it is written for, using the metadata accrued as configuration.

Depending on the lucifier, this may return a string, an object, or nothing (and just prints out text to stdout).

Parameters:

• metadata – the metadata to process
• dictlet_details – metadata about the dictlet itself

Returns:

the new (processed) metadata

Return type:

object

class luci.lucifiers.DebugLucifier(**kwargs)

Bases: luci.lucify.Lucifier

Lucifier to be used when debugging dictlets.

It let’s you print debug information of both metadata and content of a dictlet to stdout.

LUCI_DEBUG = {'__lucify__': {'doc': {'short help': 'creating a command-line interface', 'epilog': "the 'cli' lucifier is part of the luci package", 'short_help': 'displays relevant parsing information for dictlets'}, 'register': {'content': '__debug__.content.content', 'all': '__debug__.content.all', 'content_filtered': '__debug__.content.filtered', 'metadata': '__debug__.content.metadata'}, 'vars': OrderedDict([('__dictlet__.debug.all_lines', {'default': False, 'doc': {'help': "display all line-related information ('content', 'content_filtered', 'metadata')"}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'is_flag': True, 'param_decls': ['--all-lines', '-l']}}}), ('__dictlet__.debug.lines_content_all', {'default': False, 'doc': {'help': 'display all lines of a template'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'is_flag': True, 'param_decls': ['--lines-all', '-la']}}}), ('__dictlet__.debug.metadata_user', {'default': False, 'doc': {'help': 'display user-input arguments'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'is_flag': True, 'param_decls': ['--metadata-user', '-mu']}}}), ('__dictlet__.debug.lines_metadata', {'default': False, 'doc': {'help': 'display all lines of a template that were processed by luci'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'is_flag': True, 'param_decls': ['--lines-metadata', '-lm']}}}), ('__dictlet__.debug.all', {'default': False, 'doc': {'help': 'display all available information'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'is_flag': True, 'param_decls': ['--all', '-a']}}}), ('__dictlet__.debug.all_metadata', {'default': False, 'doc': {'help': 'display all available metadata information'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'is_flag': True, 'param_decls': ['--all-metadata', '-ma']}}}), ('__dictlet__.debug.metadata_defaults', {'default': False, 'doc': {'help': 'display default vars'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'is_flag': True, 'param_decls': ['--metadata-defaults', '-md']}}}), ('__dictlet__.debug.lines_content', {'default': False, 'doc': {'help': 'display all lines of a template that were skipped by luci processing and will be used as content'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'is_flag': True, 'param_decls': ['--lines-content', '-lc']}}}), ('__dictlet__.debug.metadata_dictlet', {'default': False, 'doc': {'help': 'display processed dictlet metadata'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'is_flag': True, 'param_decls': ['--metadata-dictlet', '-mt']}}}), ('__dictlet__.debug.metadata_luci', {'default': False, 'doc': {'help': 'display luci-related metadata'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'is_flag': True, 'param_decls': ['--metadata-luci', '-ml']}}}), ('__dictlet__.output_type', {'doc': {'help': 'the output type'}, 'required': False, 'type': <type 'str'>, 'click': {'option': {'param_decls': ['--format', '-f'], 'type': Choice(['yaml', 'json', 'raw'])}}}), ('__dictlet__.debug.metadata', {'default': False, 'doc': {'help': 'display the merged metadata)'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'is_flag': True, 'param_decls': ['--metadata', '-m']}}}), ('__dictlet__.pager', {'default': False, 'doc': {'help': 'whether to use a pager for display'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'param_decls': ['--pager', '-p'], 'type': <type 'bool'>, 'is_flag': True}}}), ('__dictlet__.debug.lines_content_filtered', {'default': False, 'doc': {'help': 'display all lines of a template that were skipped by luci processing and are pre-filtered'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'is_flag': True, 'param_decls': ['--lines-filtered', '-lf']}}})]), 'lucifiers': {'cli': {'reader': {'config': {'class': {'keys': {'__luci__': '__luci__'}}}, 'name': 'class'}}}}}

get_default_metadata()

If a child Lucifier overwrites this method, the returned metadata is used as a base dict (instead of an empty one).

This is useful to set things like default readers/finders, or add default cli options to the child dictlet.

Returns:(optional) initial metadata for this type of Lucifier Return type:dict

process_control_options(dictlet_properties)

Just a utility method to set the output options specified in the user input.

process_dictlet(metadata, dictlet_details)

The main method implemented by a lucifier, it executes the task it is written for, using the metadata accrued as configuration.

Depending on the lucifier, this may return a string, an object, or nothing (and just prints out text to stdout).

Parameters:

• metadata – the metadata to process
• dictlet_details – metadata about the dictlet itself

Returns:

the new (processed) metadata

Return type:

object

class luci.lucifiers.DownloadLucifier(**kwargs)

Bases: luci.lucify.Lucifier

Lucifier that can update a template by downloading and replacing it on filesystem.

The dictlet needs to contain a metadata key ‘url’ with a child key ‘default’ and the remote url to download as value. It can also, optionally, contain a child key ‘version’ and a templated string like ‘https://dl.com/dictlet-{{ version }}.yml’ as value. The latter will be used if the ‘–version’ option is specified (as described below).

This lucifier adds a few command-line options to the dictlet-part of the command (not the lucifier part, as is normal – mostly because I like it better that way in this case):

• target (‘–target’, ‘-t’): a target file
• replace (‘–replace’, ‘-r’): whether to replace an existing file
• version (‘–version): whether to download a specific version of the file

By default, this lucifier will print out the content of the remote file. If the ‘–replace’ option is specified, the template itself will be replaced with the remote file. If the ‘–target’ option is specified, the remote file will be downloaded to it’s value instead.

LUCI_DOWNLOAD = {'__lucify__': {'doc': {'short help': 'creating a command-line interface', 'epilog': "the 'cli' lucifier is part of the luci package", 'short_help': 're-download/update a dictlet'}, 'cli': {'default_dictlet_vars': {'__download__.replace': {'doc': {'help': "if set, the target file will be overwritten (if '-t' is not specified, the original dictlet will be overwritten)"}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'param_decls': ['--replace', '-r'], 'is_flag': True}}}, '__download__.version': {'default': 'default', 'doc': {'help': 'the version of the dictlet to download (optional)'}, 'required': False, 'alias': 'version', 'type': <type 'str'>, 'click': {'option': {'metavar': 'VERSION'}}}, '__download__.target': {'doc': {'help': 'if specified, the url content will be saved into the specified file, otherwise the dictlet itself will be replaced'}, 'required': False, 'type': <type 'str'>, 'click': {'option': {'param_decls': ['--target', '-t'], 'type': <type 'str'>, 'metavar': 'PATH'}}}}}, 'vars': {'__user__.pager': {'default': False, 'doc': {'help': 'whether to use a pager for display'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'param_decls': ['--pager', '-p'], 'type': <type 'bool'>, 'is_flag': True}}}}, 'lucifiers': {'download': {'reader': {'config': {'metadata_key': 'url'}, 'name': 'yaml'}}, 'cli': {'reader': {'config': {'class': {'keys': {'__luci__': '__luci__'}}}, 'name': 'class'}}}}}

get_default_metadata()

If a child Lucifier overwrites this method, the returned metadata is used as a base dict (instead of an empty one).

This is useful to set things like default readers/finders, or add default cli options to the child dictlet.

Returns:(optional) initial metadata for this type of Lucifier Return type:dict

process_dictlet(metadata, dictlet_details)

The main method implemented by a lucifier, it executes the task it is written for, using the metadata accrued as configuration.

Depending on the lucifier, this may return a string, an object, or nothing (and just prints out text to stdout).

Parameters:

• metadata – the metadata to process
• dictlet_details – metadata about the dictlet itself

Returns:

the new (processed) metadata

Return type:

object

class luci.lucifiers.MetadataLucifier(**kwargs)

Bases: luci.lucify.Lucifier

Lucifier that extracts metadata out of a dictlet and prints it to stdout.

Parameters:

• luci_metadata (bool) – whether to also display ‘luci’-specific metadata
• output_type (str) – the format of the output. Available: ‘raw’, ‘json’, ‘yaml’
• pager (bool) – whether to use a pager or not

LUCI_METADATA = {'__lucify__': {'doc': {'short help': 'creating a command-line interface', 'epilog': "the 'cli' lucifier is part of the luci package", 'short_help': 'direct output of processed luci metadata'}, 'vars': {'__dictlet__.luci_metadata': {'default': False, 'doc': {'help': 'whether to print internal metadata (mostly useful for debugging purposes)'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'param_decls': ['--luci-metadata', '-l'], 'type': <type 'bool'>, 'is_flag': True}}}, '__dictlet__.output_type': {'doc': {'help': 'the output type'}, 'required': False, 'type': <type 'str'>, 'click': {'option': {'param_decls': ['--format', '-f'], 'type': Choice(['yaml', 'json', 'raw'])}}}, '__dictlet__.pager': {'default': False, 'doc': {'help': 'whether to use a pager for display'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'param_decls': ['--pager', '-p'], 'type': <type 'bool'>, 'is_flag': True}}}}, 'lucifiers': {'cli': {'reader': {'config': {'class': {'keys': {'__luci__': '__luci__'}}}, 'name': 'class'}}}}}

get_default_metadata()

If a child Lucifier overwrites this method, the returned metadata is used as a base dict (instead of an empty one).

This is useful to set things like default readers/finders, or add default cli options to the child dictlet.

Returns:(optional) initial metadata for this type of Lucifier Return type:dict

process_dictlet(metadata, dictlet_details)

The main method implemented by a lucifier, it executes the task it is written for, using the metadata accrued as configuration.

Depending on the lucifier, this may return a string, an object, or nothing (and just prints out text to stdout).

Parameters:

• metadata – the metadata to process
• dictlet_details – metadata about the dictlet itself

Returns:

the new (processed) metadata

Return type:

object

class luci.lucifiers.TemplateLucifier(output_type=None, pager=None, all=False, **kwargs)

Bases: luci.lucify.Lucifier

Lucifier that uses the dictlet metadata as variables to replace strings in the dictlet content.

LUCI_TEMPLATE = {'__lucify__': {'doc': {'short help': 'creating a command-line interface', 'epilog': "the 'cli' lucifier is part of the luci package", 'short_help': 'use luci metadata for (jinja2) templating, in the same dictlet'}, 'register': {'content': '__template__.content.all', 'content_filtered': '__template__.content.filtered', 'metadata': '__template__.content.data'}, 'vars': {'__user__.pager': {'default': False, 'doc': {'help': 'whether to use a pager for display'}, 'required': False, 'type': <type 'bool'>, 'click': {'option': {'param_decls': ['--pager', '-p'], 'type': <type 'bool'>, 'is_flag': True}}}, '__user__.output_type': {'doc': {'help': 'the output type'}, 'required': False, 'type': <type 'str'>, 'click': {'option': {'param_decls': ['--format', '-f'], 'type': Choice(['yaml', 'json', 'raw'])}}}, '__user__.all': {'doc': {'help': 'whether to include parts that were being used by luci to extract metadata in the output'}, 'type': <type 'bool'>, 'click': {'option': {'is_flag': True, 'param_decls': ['--all', '-a']}}}}, 'lucifiers': {'cli': {'reader': {'config': {'class': {'keys': {'__luci__': '__luci__'}}}, 'name': 'class'}}}}}

get_default_metadata()

If a child Lucifier overwrites this method, the returned metadata is used as a base dict (instead of an empty one).

This is useful to set things like default readers/finders, or add default cli options to the child dictlet.

Returns:(optional) initial metadata for this type of Lucifier Return type:dict

process_dictlet(metadata, dictlet_details)

The main method implemented by a lucifier, it executes the task it is written for, using the metadata accrued as configuration.

Depending on the lucifier, this may return a string, an object, or nothing (and just prints out text to stdout).

Parameters:

• metadata – the metadata to process
• dictlet_details – metadata about the dictlet itself

Returns:

the new (processed) metadata

Return type:

object

luci.lucify module

class luci.lucify.Lucifier(name=None, init_metadata=None, **kwargs)

Bases: object

Abstract base class for an object that can execute a certain task using the added dictlet(s).

Parameters:

• name (str) – the name/alias of this lucifier
• init_metadata (dict) – (optional) metadata to be used as seed for this lucifiers internal metadata
• **kwargs (dict) – other arguments, most likely those will be ignored

add_metadata(metadata)

Add metadata to the currently existing.

This merges the new metadata on top of the old ones, so if keys exist in both, the new ones take precedence.

Parameters:metadata (dict) – the metadata to add

get_default_dictlet_finder()

get_default_dictlet_reader()

Returns the default dictlet reader for this lucifier.

get_default_finder_config()

Returns an object of the default dictlet finder for this lucifier.

Returns:the finder object configuration Return type:dict

get_default_metadata()

If a child Lucifier overwrites this method, the returned metadata is used as a base dict (instead of an empty one).

This is useful to set things like default readers/finders, or add default cli options to the child dictlet.

Returns:(optional) initial metadata for this type of Lucifier Return type:dict

get_default_reader_config()

Returns an object of the default dictlet reader for this lucifier.

Returns:the reader object configuration Return type:dict

get_key_path_value(key_path, default_value=None)

Utility method to retrieve a key-path from the (current) metadata of this lucifier.

A key-path is a character-delimited (mostly using ‘.’) string ala: key1.child_key.another_key

Parameters:

• key_path (str) – the path to the key we are interested in
• default_value (object) – the default value if the key is not found

Returns:

the value for the key-path

Return type:

object

get_metadata()

Returns the current metadata of this lucifier.

Returns:the metadata Return type:dict

static get_var_lookup_dict(vars_metadata)

Generates a reverse lookup dictionary out of vars metadata.

This enables the mapping of flags like “–help” to the var-name-keys in the vars metadata.

Parameters:vars_metadata (dict) – the vars metadata Returns:the lookup dict Return type:dict

overlay_dictlet(dictlet_name, dictlet_details=None, add_dictlet=True, add_metadata=False, dictlet_reader_name=None, dictlet_reader_config=None)

Overlays a dictlet on the current lucifier metadata.

If the ‘add_metadata’ arg is True, the dictlet and it’s newly created metadata will be stored in this object.

Parameters:

• dictlet_name (str) – an alias/name for the dictlet
• dictlet_details (dict) – the dictlet details
• add_dictlet (bool) – whether to add the resulted metadata to this lucifiers’ ‘base’-metadata
• add_metadata (bool) – whether to add the dictlet and it’s metadata to the lucifier permanently
• dictlet_reader_name (str) – the dictlet reader to use to extract metadata out of the dictlet
• dictlet_reader_config (str) – the config for the dictlet reader

Returns:

a copy of the (merged) metadata of this dictlet

Return type:

dict

print_metadata(output_type='raw', safe=True)

Utility method to pretty print (unordered) metadata of this lucifier.

Parameters:

• output_type (str) – how to format the output. Available: ‘raw’, ‘json’, ‘yaml’
• safe (bool) – whether to allow potentially available ‘unsafe’ dump methods (e.g. ‘yaml.dump’ instead of ‘yaml.safe_dump’)

process()

Processes all dictlets that were added to this Lucifier, one after the other.

static process_default_values(user_vars, vars_metadata)

Removes any keys from a dict where the user didn’t specify a value.

If this is not done, those keys stay with a ‘None’ value, which would shadow a ‘valid’ value that was provided at an earlier stage.

Parameters:

• user_vars (dict) – the user input dictionary
• vars_metadata (dict) – the vars metadata

Returns:

the cleaned dict

Return type:

dict

process_dictlet(metadata, dictlet_details=None)

The main method implemented by a lucifier, it executes the task it is written for, using the metadata accrued as configuration.

Depending on the lucifier, this may return a string, an object, or nothing (and just prints out text to stdout).

Parameters:

• metadata – the metadata to process
• dictlet_details – metadata about the dictlet itself

Returns:

the new (processed) metadata

Return type:

object

luci.param_types module

class luci.param_types.VarsFileType

Bases: click.types.ParamType

complete(ctx, incomplete)

convert(value, param, ctx)

Converts the value. This is not invoked for values that are None (the missing value).

name = 'vars_type'

luci.plugins module

luci.plugins.get_lucifier_extensions()

Loading all extensions.

luci.plugins.get_plugin_details()

Get plugin details.

luci.plugins.get_plugin_names()

Get all plugin names.

luci.plugins.load_dictlet_finder_extension(name, init_params=None)

Loading a dictlet finder extension.

Parameters:

• name (str) – the registered name of the extension
• init_params (dict) – the parameters to initialize the extension object

Returns:

the extension object

Return type:

DictletFinder

luci.plugins.load_dictlet_reader_extension(name, init_params=None)

Loading a processor extension.

Parameters:name (str) – the registered name of the extension Returns:the extension object Return type:DictletReader

luci.readers module

class luci.readers.ClassDictletReader(**kwargs)

Bases: luci.readers.DictletReader

Reader that reads class properties for Lucifier sub-classes.

get_content(dictlet_details, current_metadata)

process_content(content, current_metadata, luci_metadata, luci_metadata_key_name='__lucify__')

Processes a set of lines in a certain format.

Returns:the values of the processed dictlet Return type:dict

class luci.readers.DictletReader(**kwargs)

Bases: object

Abstract base class for a reader that can parse a dictlet of a certain format.

get_content(dictlet_path, current_metadata)

process_content(content, current_vars, luci_metadata, luci_metadata_key_name='__lucify__')

Processes a set of lines in a certain format.

Returns:the values of the processed dictlet Return type:dict

read_dictlet(dictlet_details, current_metadata, luci_metadata={})

class luci.readers.FilesInFolderReader(base_url_var_name='base_url', **kwargs)

Bases: luci.readers.DictletReader

DictletReader to find all files in a folder and use their paths and filenames for metadata.

get_content(dictlet_details, current_metadata)

Finds all files in this folder (recursively).

is_usable_file(path)

process_content(content, current_metadata, luci_metadata, luci_metadata_key_name=None)

Processes a set of lines in a certain format.

Returns:the values of the processed dictlet Return type:dict

class luci.readers.LucifyYamlDictionaryDictletReader(delimiter_profile={'block_end_string': '::%}', 'block_start_string': '{%::', 'variable_end_string': '::}}', 'variable_start_string': '{{::'}, **kwargs)

Bases: luci.readers.TextFileDictletReader

Reader for yaml-formatet dictlets.

Basically, yaml-structures that contain a dict as it’s root element. The yaml-structure can be contained in the files comments.

SHORT_HELP = 'reader for yaml formatted templates'

process_lines(content, current_vars)

class luci.readers.LupkgFolderReader(use_files=None, get_pkg_name_function=None, use_metadata_files=None, get_pkg_name_function_metadata=None, use_parent_metadata_files=None, parent_meta_file_name=None, include_relative_path_to_files=None, use_subfolders_as_tags=None, safe_load=True, reader_config_filename='.lupkg_repo', **kwargs)

Bases: luci.readers.DictletReader

Feature-ful folder reader used for lupkg.

This one reads folders containing either only files (in which case the file-name is used as pkg-name, only metadata-files, or a combination of both. If the latter. the file and (side-car) metadata file need to have the same file-name and can only differ in the extension.

TODO: list pkg name strategies

Parameters:

• use_files (bool) – whether to add non-metadata-files to the index
• is_file_function (func) – the function to be used to determine whether a file is to be added
• use_metadata_files (bool) – whether to add packages described in metadata files to the index
• is_metadata_file_function (func) – the function to be used to determine whether a metadata file is to be used
• use_parent_metadata_files (bool) – whether to inherit metadata by placing ‘non-package’ metadata files in the folder tree
• parent_meta_file_name (str) – the name of potential meta parent files
• include_relative_path_to_files (bool) – whether to include the relative paths to a file in the file url dict
• use_subfolders_as_tags (bool) – whether to automatically add subfolder names as tags to the metadata
• safe_load (bool) – whether to ‘safe’ load yaml
• reader_config_filename (str) – filename in root of folder to contain default reader settings

get_content(dictlet_details, current_metadata)

process_content(content, current_metadata, luci_metadata, luci_metadata_key_name=None)

Processes a set of lines in a certain format.

Returns:the values of the processed dictlet Return type:dict

class luci.readers.MetadataFolderReader(meta_file_name=None, merge_keys=False, use_relative_paths_as_keys=True, safe_load=True, **kwargs)

Bases: luci.readers.DictletReader

DictletReader to read all yaml files in a directory and collect all content in one dict.

Parameters:

• meta_file_name (str) – if the folder structure contains metadata files to augment final data (see above), specify their file-name here. If this is ‘None’, no metadata will be augmented
• merge_keys (bool) – whether to merge (True) or overwrite (False) values if the same key (aka filename in the default implementation) is already present.
• use_relative_paths_as_keys (bool) – whether to use relative (True) or absolute (False) paths to the yaml file for the metadata keys
• **kwargs (dict) – will be forwarded to the constructor of the underlying DictletReader parent class

get_content(dictlet_details, current_metadata)

Reads all yaml files under this folder (recursively).

is_usable_file(path)

Utility method determine whether a file contains metadata relevant for lupkg or not.

By default, this returns true if the filename in question ends with either “.yaml” or “.yml”, and does not start with a ‘.’.

Can be overwrittern by a child class.

process_content(content, current_metadata, luci_metadata, luci_metadata_key_name=None)

Processes a set of lines in a certain format.

Returns:the values of the processed dictlet Return type:dict

luci.readers.PICK_ALL_FILES_FUNCTION(path)

Default implementation of an ‘is_*_file’ method.

luci.readers.PICK_ALL_FILES_WITH_LUPKG_EXTENSION(path)

Filter that picks files that end with ‘.lupkg’.

class luci.readers.TextFileDictletReader(**kwargs)

Bases: luci.readers.DictletReader

Parent class for readers that read text files.

get_content(dictlet_details, current_metadata)

is_content_line(line, sensible=True)

static parse_lucify_line(line, luci_key_word='__lucify__')

process_content(content_orig, current_metadata, luci_metadata, luci_metadata_key_name='__lucify__')

Processes a set of lines in a certain format.

Returns:the values of the processed dictlet Return type:dict

process_lines(current_content, current_vars)

class luci.readers.YamlDictletReader(type='dict', **kwargs)

Bases: luci.readers.DictletReader

get_content(dictlet_details, current_metadata)

process_content(content, current_vars, luci_metadata, luci_metadata_key_name='__lucify__')

Processes a set of lines in a certain format.

Returns:the values of the processed dictlet Return type:dict

luci.readers.create_dictlet_reader(dictlet_reader_name, dictlet_reader_config=None)

Create a dictlet reader with the provided config.

Module contents

Top-level package for luci.

View page source