Project configuration

Boussole work on per project configurations stored in a settings file for each project.

Backends behavior is to search for a settings file in the given directory, read it, possibly patch its values and hen return a boussole.conf.model.Settings object.

Almost all paths in settings will be expanded to absolute paths if they are not allready so:

• If the path start with a home directory character, the home directory is used to expand the path;
• If the path is relative, expand it to absolute using directory from settings file location;

Also note, that SASS files from libraries directories are never compiled.

Settings model

This define the model object containing settings that will be passed to interfaces.

class boussole.conf.model.Settings(initial={})

Settings model object

Class init method fills object attributes from default settings (DEFAULT_SETTINGS) then update it with initial settings if given.

Settings are available as object attributes, there is also a private _settings attribute containing a dict of all stored settings. You are strongly advised to never directly manipulate the _settings attribute. Instead, allways use the update() method.

Note

If you intend to manually open and fill a Settings instance, remember to allways use absolute paths in your settings. Relative path will cause issues in resolving that lead to wrong compilations.

Keyword Arguments:  initial (dict) – A dictionnary of settings for initial values.

clean(settings)

Filter given settings to keep only key names available in DEFAULT_SETTINGS.

Parameters:settings (dict) – Loaded settings. Returns:Settings object filtered. Return type:dict

set_settings(settings)

Set every given settings as object attributes.

Parameters:settings (dict) – Dictionnary of settings.

update(settings)

Update object attributes from given settings

Parameters:settings (dict) – Dictionnary of elements to update settings. Returns:Dictionnary of all current saved settings. Return type:dict

Backend values patchs

Patchs are used to modify given settings items like expanding paths. Backends inherit from SettingsPatcher to be able to use it in their clean() method.

Todo:

• Should be named postprocess.SettingsPostProcessor because it contains patchs but will contain some validations soon.
• Add validation that source_dir is not also set as a library dir (would cause some issues in resolving);

class boussole.conf.patcher.SettingsPatcher

Mixin object for all available patch methods to use in SETTINGS_MANIFEST.

_patch_expand_path(settings, name, value)

Patch a path to expand home directory and make absolute path.

Parameters:

• settings (dict) – Initial settings unpatched.
• name (str) – Setting name.
• value (str) – Path to patch.

Returns:

Patched path to an absolute path.

Return type:

str

_patch_expand_paths(settings, name, value)

Apply patch SettingsPatcher._patch_expand_path for each element in list.

Parameters:

• settings (dict) – Initial settings unpatched.
• name (str) – Setting name.
• value (list) – List of paths to patch.

Returns:

Patched path list to an absolute path.

Return type:

list

patch(settings)

Perform patchs on settings according to their rules in SETTINGS_MANIFEST.

Patchs are implemented in their own method that all have the same signature:

• Get arguments: initial settings, item name and item value;
• Return item value possibly patched;

Parameters:settings (dict) – Loaded settings. Returns:Settings object patched. Return type:dict

Base settings backend

Backends are responsible to find settings file, parse it, load its values then return a Settings object.

Backends inherit from boussole.conf.patcher so they can patch each loaded settings values following the settings manifest rules.

Actually the only backend available is JSON.

class boussole.conf.base_backend.SettingsBackendBase(basedir=None)

Base project settings backend

Parameters:basedir (str) –

Directory path where to search for settings filepath.

Default is empty, meaning it will resolve path from current directory. Don’t use an empty basedir attribute to load settings from non-absolute filepath.

Given value will fill intial value for projectdir attribute.

_default_filename

Filename for settings file to load. Default to settings.txt but every backend should set their own filename.

check_filepath(path, filename)

Check and return the final filepath to settings

Parameters:

• path (str) – Directory path where to search for settings file.
• filename (str) – Filename to use to search for settings file.

Raises:

boussole.exceptions.SettingsBackendError – If determined filepath does not exists or is a directory.

Returns:

Settings file path, joining given path and filename.

Return type:

string

clean(settings)

Clean given settings for backend needs.

Default backend only apply available patchs.

Parameters:dict – Loaded settings. Returns:Settings object cleaned. Return type:dict

load(filepath=None)

Load settings file from given path and optionnal filepath.

During path resolving, the projectdir is updated to the file path directory.

Keyword Arguments:  filepath (str) – Filepath to the settings file. Returns:Settings object with loaded elements. Return type:boussole.conf.model.Settings

open(filepath)

Open settings backend to return its content

Parameters:filepath (str) – Settings object, depends from backend Returns:File content. Return type:string

parse(filepath, content)

Parse opened settings content

Base method do nothing because parsing is dependent from backend.

Parameters:

• filepath (str) – Settings object, depends from backend
• content (str) – Settings content from opened file, depends from backend.

Returns:

Dictionnary containing parsed setting elements.

Return type:

dict

parse_filepath(filepath=None)

Parse given filepath to split possible path directory from filename.

• If path directory is empty, will use basedir attribute as base filepath;
• If path directory is absolute, ignore basedir attribute;
• If path directory is relative, join it to basedir attribute;

Keyword Arguments:  

filepath (str) – Filepath to use to search for settings file. Will use value from _default_filename class attribute if empty.

If filepath contain a directory path, it will be splitted from filename and used as base directory (and update object basedir attribute).

Returns:

Separated path directory and filename.

Return type:

tuple

JSON settings backend

class boussole.conf.json_backend.SettingsBackendJson(basedir=None)

JSON backend for settings

parse(filepath, content)

Parse opened settings content using JSON parser.

Parameters:

• filepath (str) – Settings object, depends from backend
• content (str) – Settings content from opened file, depends from backend.

Raises:

boussole.exceptions.SettingsBackendError – If parser can not decode a valid JSON object.

Returns:

Dictionnary containing parsed setting elements.

Return type:

dict