lucidity_files package

Submodules

lucidity_files.file_utils module

Module for the file system utilities.

lucidity_files.file_utils.currentOs()[source]

Returns the name of the current os.

Returns:: The name of the current os.
Return type:: str

lucidity_files.file_utils.isSamePath(path_a, path_b, platform=None)[source]

Returns whether or not a 2 paths are the same.

Parameters:

path_a (str) – A full path to compare.
path_b (str) – The other full path to compare.
platform (str, optional) – The platform to target. Defaults to current platform.

Returns:

Whether or not the paths are the same.

Return type:

bool

lucidity_files.file_utils.toAbsolutePath(path, base, platform=None)[source]

Expand a relative path to a full path.

Parameters:

path (str) – Relative path to convert.
base (str) – Full path to base path to resolve the relative path from.
platform (str, optional) – The platform to target. Defaults to current platform.

Returns:

The full path.

Return type:

str

lucidity_files.file_utils.toCleanPath(path, platform=None)[source]

Convert the path to a clean path that we can use safely.

Parameters:

path (str) – Full path to clean.
platform (str, optional) – The platform to target the clean. Defaults to current platform.

Returns:

The clean path.

Return type:

str

lucidity_files.file_utils.toComparePath(path, platform=None)[source]

Convert a path to a comparable version of the same path.

Parameters:

path (str) – Full path to the path to convert.
platform (str, optional) – The platform to target. Defaults to current platform.

Returns:

A path that points to the same place but can be string compared.

Return type:

str

lucidity_files.file_utils.toLucidityPath(path)[source]

Converts the path to what lucidity expects (forward bars).

Parameters:: path (str) – Full path to convert.
Returns:: The converted path.
Return type:: str

lucidity_files.lucidity_files module

Module for the main class.

class lucidity_files.lucidity_files.TemplateFile(l_template, default_values=None, roots=None)[source]

Bases: object

Class that wraps lucidity template adding the ability for listing files and partial templates.

DEFAULT_VALUES_KEY = 'default_values'

MAX_FILES_COUNT = 999999

ROOT_KEY = 'roots'

__init__(l_template, default_values=None, roots=None)[source]

Parameters:

l_template (lucidity.Template) – the template to wrap
default_values (dict) – the default values for some key in lucidity template. This overrides values added to the template
roots (dict) – the root values for the templates. This overrides values added to the template

_getGlobPath(fields, skip_keys=None)[source]

Builds a glob path to use with python’s glob function.

Parameters:

fields (dict) – the fields to define. Undefined fields will become an * .
skip_keys (list) – the keys to ignore from the fields dict.

Returns:

a path to use with glob.

Return type:

str

_getOrderedKeyTokens(pattern, no_dups=True)[source]

return keys found in a pattern in order.

Parameters:

pattern (str) – the lucidity pattern.
no_dups (bool) – whether or not to remove the duplicates keeping the first appearance for each key.

Returns:

the keys in order.

Return type:

list[str]

_getPartialPattern(split_key)[source]

return a partial pattern splitting by a key and up to the path separator

Parameters:: split_key (str) – the key to do the split at (inclusive).
Returns:: the lucidity template pattern or None if it could not be made.
Return type:: str or None

_replaceKeysOnPath(path, key_dict)[source]

Replaces keys in a template path with their corresponding values.

Parameters:

path (str) – path to replace roots on.
key_dict (dict) – the dict of keys to find and values to put in replacement.

Returns:

the path with the roots replaced.

Return type:

str

Notes

TODO: this dont depend on self, could be extracted

_resolveParam(key, override, default)[source]

Helper to resolve parameters.

Parameters:

key (str) – key to resolve
override (obj) – the overriding value, can be None in case it’s not overridden.
default (obj) – the value to use in case it’s not defined on the template or the override.

Returns:

the resolved value.

Return type:

obj

checkData(data)[source]

Check if data is consistent with this template.

Parameters:: data (dict) – the data to check.
Returns:: True if check is passed, False otherwise.
Return type:: bool

checkPath(path)[source]

Check if path is consistent with this template.

Parameters:: path (str) – the path to check.
Returns:: True if check is passed, False otherwise.
Return type:: bool

classmethod create(name, pattern, default_placeholder_expression='[\\w_.\\-]+', template_resolver=None, default_values=None, roots=None)[source]

Creates a TemplateFile object initialized.

Parameters:

name (str) – Name of the template.
pattern (str) – File pattern to use with lucidity.
default_placeholder_expression (str, optional) – Pseudo regex used in the pattern fields. Defaults to ‘[w_.-]+’.
template_resolver (lucidity.Resolver, optional) – A resolver for the inner templates. Defaults to None.
default_values (dict, optional) – A mapping between values and their defaults. Defaults to None.
roots (dict, optional) – A mapping between root names and root paths. Defaults to None.

Returns:

The initialized template file.

Return type:

TemplateFile

format(data)[source]

wraps lucidity format function.

Parameters:: data (dict) – the dict with the keys to find in template and the values to replace the keys found.
Returns:: the builded path.
Return type:: str

Raises: lucidity.FormatError if path cant be formatted.

getDefaultKeys()[source]

Get the keys that have a default value.

Parameters:: None.
Returns:: the unordered list of keys.
Return type:: list

getKeys(ordered=False, no_dups=True)[source]

Get the keys as defined in lucidity template but without roots.

Parameters:

ordered (bool) – whether or not to order the keys.
no_dups (bool) – whether or not to remove the duplicates keeping the first appearance for each key. Only valid for ordered.

Returns:

the unordered list of keys.

Return type:

list

getPartialTemplateFile(split_key)[source]

Returns a TemplateFile object with a partial pattern.

Parameters:: split_key (str) – the key to do the split at (inclusive).
Returns:: the TemplateFile with the partial pattern or None if it could not be made.
Return type:: TemplateFile or None

Examples

Get paths from partial template and get data too:

partial_template_file = self.getPartialTemplateFile('entity')
paths = partial_template_file.getPaths()
datas = [template_file.parse(p) for p in paths]

getPaths(fields=None, skip_keys=None, strict_check=True, max_count=None)[source]

Returns the found paths that matched this template.

Parameters:

fields (dict) – the fields to define. Undefined fields will become an wildcard.
skip_keys (list) – the keys to ignore from the fields dict.
strict_check (bool) – whether or not to strictly check that the paths found can be parsed (takes more time).
max_count (int) – maximum files to return.

Returns:

the list of paths found that matched the template and the fields.

Return type:

list[str]

getRawKeys()[source]

Get the keys as defined in lucidity template.

Parameters:: None.
Returns:: the unordered list of keys.
Return type:: list

getRootKeys()[source]

Get the keys that are root.

Parameters:: None.
Returns:: the unordered list of keys.
Return type:: list

property lucidity_name: returns lucidity template name

parse(path, return_roots=True)[source]

Wraps lucidity parse function.

Parameters:

path (str) – the path to parse
return_roots (bool) – whether or not to return the roots in the result

Returns:

the key values pairs

Return type:

dict

Raises: lucidity.ParseError if path cant be parsed.

roundTripCheckData(data)[source]

Check if data is consistent with this template by converting back and forth.

Parameters:: data (dict) – the data to check.
Returns:: True if check is passed, False otherwise.
Return type:: bool

Notes

TODO: move to tests!

roundTripCheckPath(path, platform=None)[source]

Check if path is consistent with this template by converting back and forth.

Parameters:

path (str) – the path to check.
platform (str) – the name of the platform as defined in file_utils.

Returns:

True if check is passed, False otherwise.

Return type:

bool

Notes

TODO: move to tests!

Module contents

TODO: not sure if match multiple makes sense

class lucidity_files.TemplateFile(l_template, default_values=None, roots=None)[source]

Bases: object

Class that wraps lucidity template adding the ability for listing files and partial templates.

DEFAULT_VALUES_KEY = 'default_values'

MAX_FILES_COUNT = 999999

ROOT_KEY = 'roots'

__init__(l_template, default_values=None, roots=None)[source]

Parameters:

l_template (lucidity.Template) – the template to wrap
default_values (dict) – the default values for some key in lucidity template. This overrides values added to the template
roots (dict) – the root values for the templates. This overrides values added to the template

_getGlobPath(fields, skip_keys=None)[source]

Builds a glob path to use with python’s glob function.

Parameters:

fields (dict) – the fields to define. Undefined fields will become an * .
skip_keys (list) – the keys to ignore from the fields dict.

Returns:

a path to use with glob.

Return type:

str

_getOrderedKeyTokens(pattern, no_dups=True)[source]

return keys found in a pattern in order.

Parameters:

pattern (str) – the lucidity pattern.
no_dups (bool) – whether or not to remove the duplicates keeping the first appearance for each key.

Returns:

the keys in order.

Return type:

list[str]

_getPartialPattern(split_key)[source]

return a partial pattern splitting by a key and up to the path separator

Parameters:: split_key (str) – the key to do the split at (inclusive).
Returns:: the lucidity template pattern or None if it could not be made.
Return type:: str or None

_replaceKeysOnPath(path, key_dict)[source]

Replaces keys in a template path with their corresponding values.

Parameters:

path (str) – path to replace roots on.
key_dict (dict) – the dict of keys to find and values to put in replacement.

Returns:

the path with the roots replaced.

Return type:

str

Notes

TODO: this dont depend on self, could be extracted

_resolveParam(key, override, default)[source]

Helper to resolve parameters.

Parameters:

key (str) – key to resolve
override (obj) – the overriding value, can be None in case it’s not overridden.
default (obj) – the value to use in case it’s not defined on the template or the override.

Returns:

the resolved value.

Return type:

obj

checkData(data)[source]

Check if data is consistent with this template.

Parameters:: data (dict) – the data to check.
Returns:: True if check is passed, False otherwise.
Return type:: bool

checkPath(path)[source]

Check if path is consistent with this template.

Parameters:: path (str) – the path to check.
Returns:: True if check is passed, False otherwise.
Return type:: bool

classmethod create(name, pattern, default_placeholder_expression='[\\w_.\\-]+', template_resolver=None, default_values=None, roots=None)[source]

Creates a TemplateFile object initialized.

Parameters:

name (str) – Name of the template.
pattern (str) – File pattern to use with lucidity.
default_placeholder_expression (str, optional) – Pseudo regex used in the pattern fields. Defaults to ‘[w_.-]+’.
template_resolver (lucidity.Resolver, optional) – A resolver for the inner templates. Defaults to None.
default_values (dict, optional) – A mapping between values and their defaults. Defaults to None.
roots (dict, optional) – A mapping between root names and root paths. Defaults to None.

Returns:

The initialized template file.

Return type:

TemplateFile

format(data)[source]

wraps lucidity format function.

Parameters:: data (dict) – the dict with the keys to find in template and the values to replace the keys found.
Returns:: the builded path.
Return type:: str

Raises: lucidity.FormatError if path cant be formatted.

getDefaultKeys()[source]

Get the keys that have a default value.

Parameters:: None.
Returns:: the unordered list of keys.
Return type:: list

getKeys(ordered=False, no_dups=True)[source]

Get the keys as defined in lucidity template but without roots.

Parameters:

ordered (bool) – whether or not to order the keys.
no_dups (bool) – whether or not to remove the duplicates keeping the first appearance for each key. Only valid for ordered.

Returns:

the unordered list of keys.

Return type:

list

getPartialTemplateFile(split_key)[source]

Returns a TemplateFile object with a partial pattern.

Parameters:: split_key (str) – the key to do the split at (inclusive).
Returns:: the TemplateFile with the partial pattern or None if it could not be made.
Return type:: TemplateFile or None

Examples

Get paths from partial template and get data too:

partial_template_file = self.getPartialTemplateFile('entity')
paths = partial_template_file.getPaths()
datas = [template_file.parse(p) for p in paths]

getPaths(fields=None, skip_keys=None, strict_check=True, max_count=None)[source]

Returns the found paths that matched this template.

Parameters:

fields (dict) – the fields to define. Undefined fields will become an wildcard.
skip_keys (list) – the keys to ignore from the fields dict.
strict_check (bool) – whether or not to strictly check that the paths found can be parsed (takes more time).
max_count (int) – maximum files to return.

Returns:

the list of paths found that matched the template and the fields.

Return type:

list[str]

getRawKeys()[source]

Get the keys as defined in lucidity template.

Parameters:: None.
Returns:: the unordered list of keys.
Return type:: list

getRootKeys()[source]

Get the keys that are root.

Parameters:: None.
Returns:: the unordered list of keys.
Return type:: list

property lucidity_name: returns lucidity template name

parse(path, return_roots=True)[source]

Wraps lucidity parse function.

Parameters:

path (str) – the path to parse
return_roots (bool) – whether or not to return the roots in the result

Returns:

the key values pairs

Return type:

dict

Raises: lucidity.ParseError if path cant be parsed.

roundTripCheckData(data)[source]

Check if data is consistent with this template by converting back and forth.

Parameters:: data (dict) – the data to check.
Returns:: True if check is passed, False otherwise.
Return type:: bool

Notes

TODO: move to tests!

roundTripCheckPath(path, platform=None)[source]

Check if path is consistent with this template by converting back and forth.

Parameters:

path (str) – the path to check.
platform (str) – the name of the platform as defined in file_utils.

Returns:

True if check is passed, False otherwise.

Return type:

bool

Notes

TODO: move to tests!

lucidity_files.discover_templates(paths=None, recursive=True, default_values=None, roots=None)[source]: Wraps lucidity to return TemplateFiles instead for lucidity templates

lucidity_files.format_(data, templates, match_multiple=False)[source]

Finds a template from templates that matches data and returns the builded path and the matching template. :param data: the data to construct a path :type data: dict :param templates: the list of template files to match against the path :type templates: list[TemplateFile] :param match_multiple: whether to return just the first or all that matches :type match_multiple: bool

Returns:: the list of the builded path and template
Return type:: list[tuple(path, TemplateFile)]

lucidity_files.get_template(name, templates)[source]

Finds a template by name from a provided list :param name: the name of the template :type name: str :param templates: the list of templates to look for the one with name :type templates: list[TemplateFile]

Raises:: Exception – if no template has the name (or no templates provided)

lucidity_files.parse(path, templates, match_multiple=False, return_roots=True)[source]

Finds a template from templates that matches path and returns the parsed values and the matching template. :param path: the path to match :type path: str :param templates: the list of template files to match against the path :type templates: list[TemplateFile] :param match_multiple: whether to return just the first or all that matches :type match_multiple: bool :param return_roots: whether or not to return the roots in the result :type return_roots: bool

Returns:: the list of the parsed data and template
Return type:: list[tuple(dict, TemplateFile)]