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 then 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

Model is only about data model, there is no other validation that available ‘fields’ from DEFAULT_SETTINGS.

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.

You may also apply post processor validation to ensure your datas.

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

Settings backend post processing

Post processing methods are used to modify or validate given settings items.

Backends inherit from SettingsPostProcessor to be able to use it in their clean() method.

class boussole.conf.post_processor.SettingsPostProcessor

Mixin object for all available post processing methods to use in settings manifest (default manifest comes from SETTINGS_MANIFEST).

_patch_expand_path(settings, name, value)

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

Parameters:

• settings (dict) – Current settings.
• 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 SettingsPostProcessor._patch_expand_path to each element in list.

Parameters:

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

Returns:

Patched path list to an absolute path.

Return type:

list

_validate_path(settings, name, value)

Validate path exists

Parameters:

• settings (dict) – Current settings.
• name (str) – Setting name.
• value (str) – Path to validate.

Raises:

boussole.exceptions.SettingsInvalidError – If path does not exists.

Returns:

Validated path.

Return type:

str

_validate_paths(settings, name, value)

Apply SettingsPostProcessor._validate_path to each element in list.

Parameters:

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

Raises:

boussole.exceptions.SettingsInvalidError – Once a path does not exists.

Returns:

Validated paths.

Return type:

list

_validate_required(settings, name, value)

Validate a required setting (value can not be empty)

Parameters:

• settings (dict) – Current settings.
• name (str) – Setting name.
• value (str) – Required value to validate.

Raises:

boussole.exceptions.SettingsInvalidError – If value is empty.

Returns:

Validated value.

Return type:

str

post_process(settings)

Perform post processing methods on settings according to their definition in manifest.

Post process methods are implemented in their own method that have the same signature:

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

Parameters:settings (dict) – Loaded settings. Returns:Settings object possibly modified (depending from applied post processing). 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.post_processor so they can post process 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 post processor methods.

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