coalib.settings package¶
Submodules¶
coalib.settings.ConfigurationGathering module¶
-
coalib.settings.ConfigurationGathering.
find_user_config
(file_path, max_trials=10)¶ Uses the filepath to find the most suitable user config file for the file by going down one directory at a time and finding config files there.
Parameters: - file_path – The path of the file whose user config needs to be found
- max_trials – The maximum number of directories to go down to.
Returns: The config file’s path
-
coalib.settings.ConfigurationGathering.
gather_configuration
(acquire_settings, log_printer, autoapply=None, arg_list=None)¶ Loads all configuration files, retrieves bears and all needed settings, saves back if needed and warns about non-existent targets.
This function:
- Reads and merges all settings in sections from
- Default config
- User config
- Configuration file
- CLI
- Collects all the bears
- Fills up all needed settings
- Writes back the new sections to the configuration file if needed
- Gives all information back to caller
Parameters: - acquire_settings – The method to use for requesting settings. It will get a parameter which is a dictionary with the settings name as key and a list containing a description in [0] and the names of the bears who need this setting in all following indexes.
- log_printer – The log printer to use for logging. The log level will be adjusted to the one given by the section.
- autoapply – Set whether to autoapply patches. This is overridable via any configuration file/CLI.
- arg_list – CLI args to use
Returns: A tuple with the following contents:
- A dictionary with the sections
- Dictionary of list of local bears for each section
- Dictionary of list of global bears for each section
- The targets list
- Reads and merges all settings in sections from
-
coalib.settings.ConfigurationGathering.
get_config_directory
(section)¶
-
coalib.settings.ConfigurationGathering.
load_config_file
(filename, log_printer, silent=False)¶ Loads sections from a config file. Prints an appropriate warning if it doesn’t exist and returns a section dict containing an empty default section in that case.
It assumes that the cli_sections are available.
Parameters: - filename – The file to load settings from.
- log_printer – The log printer to log the warning/error to (in case).
- silent – Whether or not to warn the user/exit if the file doesn’t exist.
Raises: SystemExit – Exits when given filename is invalid and is not the default coafile. Only raised when silent is False.
-
coalib.settings.ConfigurationGathering.
load_configuration
(arg_list, log_printer)¶ Parses the CLI args and loads the config file accordingly, taking default_coafile and the users .coarc into account.
Parameters: - arg_list – The list of command line arguments.
- log_printer – The LogPrinter object for logging.
Returns: A tuple holding (log_printer: LogPrinter, sections: dict(str, Section), targets: list(str)). (Types indicated after colon.)
-
coalib.settings.ConfigurationGathering.
merge_section_dicts
(lower, higher)¶ Merges the section dictionaries. The values of higher will take precedence over the ones of lower. Lower will hold the modified dict in the end.
Parameters: - lower – A section.
- higher – A section which values will take precedence over the ones from the other.
Returns: The merged dict.
-
coalib.settings.ConfigurationGathering.
save_sections
(sections)¶ Saves the given sections if they are to be saved.
Parameters: sections – A section dict.
-
coalib.settings.ConfigurationGathering.
warn_nonexistent_targets
(targets, sections, log_printer)¶ Prints out a warning on the given log printer for all targets that are not existent within the given sections.
Parameters: - targets – The targets to check.
- sections – The sections to search. (Dict.)
- log_printer – The log printer to warn to.
coalib.settings.DocumentationComment module¶
coalib.settings.FunctionMetadata module¶
-
class
coalib.settings.FunctionMetadata.
FunctionMetadata
(name, desc='', retval_desc='', non_optional_params=None, optional_params=None, omit=frozenset())¶ Bases:
object
-
create_params_from_section
(section)¶ Create a params dictionary for this function that holds all values the function needs plus optional ones that are available.
Parameters: section – The section to retrieve the values from. Returns: The params dictionary.
-
classmethod
from_function
(func, omit=frozenset())¶ Creates a FunctionMetadata object from a function. Please note that any variable argument lists are not supported. If you do not want the first (usual named ‘self’) argument to appear please pass the method of an actual INSTANCE of a class; passing the method of the class isn’t enough. Alternatively you can add “self” to the omit set.
Parameters: - func – The function. If __metadata__ of the unbound function is present it will be copied and used, otherwise it will be generated.
- omit – A set of parameter names that are to be ignored.
Returns: The FunctionMetadata object corresponding to the given function.
-
non_optional_params
¶ Retrieves a dict containing the name of non optional parameters as the key and a tuple of a description and the python annotation. Values that are present in self.omit will be omitted.
-
optional_params
¶ Retrieves a dict containing the name of optional parameters as the key and a tuple of a description, the python annotation and the default value. Values that are present in self.omit will be omitted.
-
str_nodesc
= 'No description given.'¶
-
str_optional
= "Optional, defaults to '{}'."¶
-
coalib.settings.Section module¶
-
class
coalib.settings.Section.
Section
(name, defaults=None)¶ Bases:
object
This class holds a set of settings.
-
add_or_create_setting
(setting, custom_key=None, allow_appending=True)¶ Adds the value of the setting to an existing setting if there is already a setting with the key. Otherwise creates a new setting.
-
append
(setting, custom_key=None)¶
-
bear_dirs
()¶
-
copy
()¶ Returns: a deep copy of this object
-
delete_setting
(key)¶ Delete a setting :param key: The key of the setting to be deleted
-
get
(key, default='', ignore_defaults=False)¶ Retrieves the item without raising an exception. If the item is not available an appropriate Setting will be generated from your provided default value.
Parameters: - key – The key of the setting to return.
- default – The default value
- ignore_defaults – Whether or not to ignore the default section.
Returns: The setting.
-
is_enabled
(targets)¶ Checks if this section is enabled or, if targets is not empty, if it is included in the targets list.
Parameters: targets – List of target section names, all lower case. Returns: True or False
-
update
(other_section, ignore_defaults=False)¶ Incorporates all keys and values from the other section into this one. Values from the other section override the ones from this one.
Default values from the other section override the default values from this only.
Parameters: - other_section – Another Section
- ignore_defaults – If set to true, do not take default values from other
Returns: self
-
update_setting
(key, new_key=None, new_value=None)¶ Updates a setting with new values. :param key: The old key string. :param new_key: The new key string. :param new_value: The new value for the setting
-
-
coalib.settings.Section.
append_to_sections
(sections, key, value, origin, section_name=None, from_cli=False)¶ Appends the given data as a Setting to a Section with the given name. If the Section does not exist before it will be created empty.
Parameters: - sections – The sections dictionary to add to.
- key – The key of the setting to add.
- value – The value of the setting to add.
- origin – The origin value of the setting to add.
- section_name – The name of the section to add to.
- from_cli – Whether or not this data comes from the CLI.
coalib.settings.SectionFilling module¶
-
coalib.settings.SectionFilling.
fill_section
(section, acquire_settings, log_printer, bears)¶ Retrieves needed settings from given bears and asks the user for missing values.
If a setting is requested by several bears, the help text from the latest bear will be taken.
Parameters: - section – A section containing available settings. Settings will be added if some are missing.
- acquire_settings – The method to use for requesting settings. It will get a parameter which is a dictionary with the settings name as key and a list containing a description in [0] and the names of the bears who need this setting in all following indexes.
- log_printer – The log printer for logging.
- bears – All bear classes or instances.
Returns: The new section.
-
coalib.settings.SectionFilling.
fill_settings
(sections, acquire_settings, log_printer)¶ Retrieves all bears and requests missing settings via the given acquire_settings method.
Parameters: - sections – The sections to fill up, modified in place.
- acquire_settings – The method to use for requesting settings. It will get a parameter which is a dictionary with the settings name as key and a list containing a description in [0] and the names of the bears who need this setting in all following indexes.
- log_printer – The log printer to use for logging.
Returns: A tuple containing (local_bears, global_bears), each of them being a dictionary with the section name as key and as value the bears as a list.
coalib.settings.Setting module¶
-
class
coalib.settings.Setting.
Setting
(key, value, origin='', strip_whitespaces=True, list_delimiters=(', ', ';'), from_cli=False, remove_empty_iter_elements=True)¶ Bases:
coalib.misc.StringConverter.StringConverter
A Setting consists mainly of a key and a value. It mainly offers many conversions into common data types.
-
key
¶
-
-
coalib.settings.Setting.
path
(obj, *args, **kwargs)¶
-
coalib.settings.Setting.
path_list
(obj, *args, **kwargs)¶
-
coalib.settings.Setting.
typed_dict
(key_type, value_type, default)¶ Creates a function that converts a setting into a dict with the given types.
Parameters: - key_type – The type conversion function for the keys.
- value_type – The type conversion function for the values.
- default – The default value to use if no one is given by the user.
Returns: A conversion function.
-
coalib.settings.Setting.
typed_list
(conversion_func)¶ Creates a function that converts a setting into a list of elements each converted with the given conversion function.
Parameters: conversion_func – The conversion function that converts a string into your desired list item object. Returns: A conversion function.
-
coalib.settings.Setting.
typed_ordered_dict
(key_type, value_type, default)¶ Creates a function that converts a setting into an ordered dict with the given types.
Parameters: - key_type – The type conversion function for the keys.
- value_type – The type conversion function for the values.
- default – The default value to use if no one is given by the user.
Returns: A conversion function.
-
coalib.settings.Setting.
url
(obj, *args, **kwargs)¶