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={})[source]

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)[source]

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)[source]

Set every given settings as object attributes.

Parameters:settings (dict) – Dictionnary of settings.
update(settings)[source]

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.

Base backend inherit from SettingsPostProcessor to be able to use it in its clean() method.

class boussole.conf.post_processor.SettingsPostProcessor[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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 available backends are JSON and YAML.

class boussole.conf.base_backend.SettingsBackendBase(basedir=None)[source]

Bases: boussole.conf.post_processor.SettingsPostProcessor

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. Value is settings.txt.

_kind_name

Backend format name. Value is txt.

_file_extension

Default filename extension. Value is txt.

check_filepath(path, filename)[source]

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)[source]

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
dump(content, filepath)[source]

Dump settings content to filepath.

Base method do nothing because dumping is dependent from backend.

Parameters:
  • content (str) – Settings content.
  • filepath (str) – Settings file location.
Returns:

Dictionnary containing parsed setting options.
Return type:

dict
load(filepath=None)[source]

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 options.
Return type:boussole.conf.model.Settings
open(filepath)[source]

Open settings backend to return its content

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

Load and parse opened settings content.

Base method do nothing because parsing is dependent from backend.

Parameters:
  • filepath (str) – Settings file location.
  • content (str) – Settings content from opened file, depends from backend.
Returns:

Dictionnary containing parsed setting options.
Return type:

dict
parse_filepath(filepath=None)[source]

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)[source]

Bases: boussole.conf.base_backend.SettingsBackendBase

JSON backend for settings

_default_filename

Filename for settings file to load. Value is settings.json.

_kind_name

Backend format name. Value is json.

_file_extension

Default filename extension. Value is json.

dump(content, filepath, indent=4)[source]

Dump settings content to filepath.

Parameters:
  • content (str) – Settings content.
  • filepath (str) – Settings file location.
parse(filepath, content)[source]

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

YAML settings backend

class boussole.conf.yaml_backend.SettingsBackendYaml(basedir=None)[source]

Bases: boussole.conf.base_backend.SettingsBackendBase

YAML backend for settings

Use PyYaml for parsing and pyaml for dumping.

_default_filename

Filename for settings file to load. Value is settings.yml.

_kind_name

Backend format name. Value is yaml.

_file_extension

Default filename extension. Value is yml.

dump(content, filepath, indent=4)[source]

Dump settings content to filepath.

Parameters:
  • content (str) – Settings content.
  • filepath (str) – Settings file location.
parse(filepath, content)[source]

Parse opened settings content using YAML 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 YAML object.
Returns:

Dictionnary containing parsed setting elements.
Return type:

dict

Backend discover

class boussole.conf.discovery.Discover(backends=[])[source]

Should be able to find a settings file without any specific backend given, just a directory path (the base dir) is required.

So:

  • If a file name is explicitely given, use it to find backend;

  • If no file name is given but a backend is, use its default file name;

  • If file name nor backend is given, start full discover process:

    • Get all backend default settings file name;
    • Search for any of these available settings file names;
    • If no available settings file name if finded, discovering fail;
    • If one file name is given assume backend from file name;

backends (list): List of backend engines to get available backend engines.

get_engine(filepath, kind=None)[source]

From given filepath try to discover which backend format to use.

Discovering is pretty naive as it find format from file extension.

Parameters:

filepath (str) – Settings filepath or filename.
Keyword Arguments:
 

kind (str) – A format name to enforce a specific backend. Can be any value from attribute _kind_name of available backend engines.
Raises:
Returns:

Backend engine class.
Return type:

object
guess_filename(basedir, kind=None)[source]

Try to find existing settings filename from base directory using default filename from available engines.

First finded filename from available engines win. So registred engines order matter.

Parameters:basedir (string) – Directory path where to search for.
Keyword Arguments:
 kind (string) – Backend engine kind name to search for default settings filename. If not given, search will be made for default settings filename from all available backend engines.
Returns:Absolute filepath and backend engine class.
Return type:tuple
scan_backends(backends)[source]

From given backends create and return engine, filename and extension indexes.

Parameters:backends (list) – List of backend engines to scan. Order does matter since resulted indexes are stored in an OrderedDict. So discovering will stop its job if it meets the first item.
Returns:Engine, filename and extension indexes where:
  • Engines are indexed on their kind name with their backend object as value;
  • Filenames are indexed on their filename with engine kind name as value;
  • Extensions are indexed on their extension with engine kind name as value;
Return type:tuple
search(filepath=None, basedir=None, kind=None)[source]

Search for a settings file.

Keyword Arguments:
 
  • filepath (string) – Path to a config file, either absolute or relative. If absolute set its directory as basedir (omitting given basedir argument). If relative join it to basedir.
  • basedir (string) – Directory path where to search for.
  • kind (string) – Backend engine kind name (value of attribute _kind_name) to help discovering with empty or relative filepath. Also if explicit absolute filepath is given, this will enforce the backend engine (such as yaml kind will be forced for a foo.json file).
Returns:

Absolute filepath and backend engine class.
Return type:

tuple