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 theupdate()
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
-
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
[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
- If path directory is empty, will use
-
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¶
-
boussole.conf.discover.
get_backend
(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 either json
oryaml
. Default toNone
.Raises: boussole.exceptions.SettingsBackendError
– If extension is unknowed or if given format name is unknowed.Returns: Backend object. Return type: object