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.
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
).- 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
- _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
- _patch_hash_suffix(settings, name, value)[source]¶
Coerce setting
HASH_SUFFIX
to the right value.- Parameters
settings (dict) – Current settings.
name (str) – Setting name.
value (str) – Required value to patch.
- Returns
It may be:
None if value is an empty string, None or False;
If value is
:blake2
, this will return a hash from black2b with a length of 20 characters (almost guaranteed to be unique);If value is
:blake2
, this will return a hash from uuid4 with a length of 32 characters (guaranteed to be unique);If True, assume it enables the default hash engine which is
:blake2
;A string if value is a string that do not match any hash engine name;
- Return type
object
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:
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
.
- 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
- 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
- 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
- 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
- clean(settings)[source]¶
Clean and patch given settings for backend needs.
Default backend only apply available post processor methods.
- Parameters
dict – Loaded settings.
- Returns
Settings object cleaned.
- Return type
dict
JSON settings backend¶
- class boussole.conf.json_backend.SettingsBackendJson(basedir=None)[source]¶
Bases:
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:
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]¶
Discovery is 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;
- 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
- 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
boussole.exceptions.SettingsDiscoveryError – If extension is unknowed or if given format name is unknowed.
- 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
- 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 afoo.json
file).
- Returns
Absolute filepath and backend engine class.
- Return type
tuple