`sqlfluff.core.config`: Configuration & `FluffConfig`¶

When using the Python API, there are additional options for configuration beyond those specified in the Setting Configuration section of the main docs. Internally, SQLFluff uses a consistent FluffConfig class which is then made accessible to different parts of the tool during linting and fixing.

As described in the Nesting section of the configuration docs, multiple nested documentation files can be used in a project and the result is a combined config object which contains the resulting union of those files. Under the hood, this is stored in a dict object, and it’s possible get and set individual values, using get() & set_value(), but also get entire portions of that config dict using get_section().

Methods for creating config mappings¶

When instantiating a FluffConfig object, there are a few options to set specific config values (such as dialect or rules), but to access the full available set of features it’s best to pass in a dict of the values you want to set.

This config dict is a nested object, where the colon (:) characters from the .sqlfluff config files, delimit the keys. For example, take the following config file:

[sqlfluff:rules:capitalisation.keywords]
capitalisation_policy = lower

This would be represented in the config dict as below. See that the nested structure has been created by splitting the keys on the colon (:) characters:

configs = {
    "rules":{
        "capitalisation.keywords": {
            "capitalisation_policy": "lower"
        }
    }
}

The following methods are provided to allow conversion of a selection of file formats into a consistent mapping object for instantiating a FluffConfig object.

load_config_string(config_string: str, configs: ConfigMappingType | None = None, working_path: str | None = None) → ConfigMappingType¶

Load a config from a string in ini format.

Parameters:

config_string (str) – The raw config file as a string. The content is assumed to be in the the .ini format of a .sqlfluff file (i.e. not in .toml format).
configs (ConfigMappingType, optional) – A base set of configs to merge the loaded configs onto. If not provided, the result will contain only the values loaded from the string.
working_path (str, optional) – The working path to use for the resolution of any paths specified in the config. If not provided then os.getcwd() is used as a default.

Returns:

A nested dictionary of config values.

Return type:

ConfigMappingType

load_config_file(file_dir: str, file_name: str, configs: ConfigMappingType | None = None) → ConfigMappingType¶

Load a config file from the filesystem.

Parameters:

file_dir (str) – The path to the location of file to be loaded. This should be a reference to the directory only and not include the filename itself. Any paths in the loaded file are resolved relative to this location.
file_name (str) – The filename of the file to be loaded. If the filename is pyproject.toml then the file is loaded in toml format, but otherwise is assumed to be in ini format (as per .sqlfluff).
configs (ConfigMappingType, optional) – A base set of configs to merge the loaded configs onto. If not provided, the result will contain only the values loaded from the string.

Returns:

A nested dictionary of config values.

Return type:

ConfigMappingType

load_config_resource(package: str, file_name: str) → ConfigMappingType¶

Load a config resource from a python package.

Parameters:

package (str) – The name of the python package to load the resource from.
file_name (str) – The filename of the file to be loaded. If the filename is pyproject.toml then the file is loaded in toml format, but otherwise is assumed to be in ini format (as per .sqlfluff).

Returns:

A nested dictionary of config values.

Return type:

ConfigMappingType

This is primarily used when loading configuration bundled with a SQLFluff plugin, or to load the default config for SQLFluff itself. By loading config from the package directly we avoid some of the path resolution which otherwise occurs. This is also more compatible with mypyc because it avoids the use of the __file__ attribute to find the default config.

Any paths found in the loaded config are resolved relative to os.getcwd().

For more information about resource loading, see the docs for importlib: https://docs.python.org/3/library/importlib.resources.html

load_config_at_path(path: str) → ConfigMappingType¶

Load config files at a given path.

Parameters:: path (str) – The directory to search for config files.
Returns:: A nested dictionary of config values.
Return type:: ConfigMappingType

This function will search for all valid config files at the given path, load any found and combine them into a config mapping. If multiple valid files are found, they are resolved in priority order, where pyproject.toml is given the highest precedence, followed by .sqlfluff, pep8.ini, tox.ini and finally setup.cfg.

By accepting only a path string, we enable efficient caching of results, such that configuration can be reused between files without reloading the information from disk.

load_config_up_to_path(path: str, extra_config_path: str | None = None, ignore_local_config: bool = False) → ConfigMappingType¶

Loads a selection of config files from both the path and its parent paths.

Parameters:

path (str) – The directory which is the target of the search. Config files in subdirectories will not be loaded by this method, but valid config files between this path and the current working path will.
extra_config_path (str, optional) – An additional path to load config from. This path is not used in iterating through intermediate paths, and is loaded last (taking the highest precedence in combining the loaded configs).
ignore_local_config (bool, optional, defaults to False) – If set to True, this skips loading configuration from the user home directory (~) or appdir path.

Returns:

A nested dictionary of config values.

Return type:

ConfigMappingType

We layer each of the configs on top of each other, starting with any home or user configs (e.g. in appdir or home (~)), then any local project configuration and then any explicitly specified config paths.

The `FluffConfig` object¶

class FluffConfig(configs: ConfigMappingType | None = None, extra_config_path: str | None = None, ignore_local_config: bool = False, overrides: ConfigMappingType | None = None, plugin_manager: pluggy.PluginManager | None = None, require_dialect: bool = True)¶

The persistent object for internal methods to access configuration.

This class is designed to be instantiated once for each file and then be reused by each part of the process. For multiple files in the same path, a parent object will be created for the each path and then variants of it are created for each file. The object itself contains the references to any long lived objects which might be used by multiple parts of the codebase such as the dialect and the templater (both of which can be resource intensive to load & instantiate), which allows (for example), multiple files to reuse the same instance of the relevant dialect.

It is also designed to pickle well for use in parallel operations.

Parameters:

configs (ConfigMappingType, optional) – A nested dict of config values from which to construct the config.
extra_config_path (str, optional) – An optional additional path to load config files from. These are loaded last if found and take precedence over any pre-existing config values. Note that when provided directly to the class, this path is not loaded for the class in question (it’s assumed that has already been done, and the results are incorporated in the configs argument), but it is passed onward to child config instances, which will use it.
ignore_local_config (bool, optional, defaults to False) – If set to True, this skips loading configuration from the user home directory (~) or appdir path.
overrides (ConfigMappingType, optional) – A additional set of configs to merge into the core section of the config object at the end. These values take precedence over all other provided values and are inherited by child configs. For example, override values provided in the CLI use this method to apply to all files in a linting operation. Note that this mapping dict only applies to the core section and so cannot be used for all values.
plugin_manager (PluginManager, optional) – Optional pre-loaded config manager. Generally users should not need to provide this, as the class will fetch it’s own if not provided. This argument is used when creating new class instances to avoid reloading the manager.

Note

Methods for accessing internal properties on the config are not particularly standardised as the project currently assumes that few other tools are using this interface directly. If you or your project would like more formally supported methods for access to the config object, raise an issue on GitHub with the kind of things you’d like to achieve.

copy() → FluffConfig¶

Create a copy of this FluffConfig.

Copies created using this method can safely be modified without those changes propagating back up to the object which was originally copied.

Returns:: A shallow copy of this config object but with a deep copy of the internal _configs dict.
Return type:: FluffConfig

diff_to(other: FluffConfig) → ConfigMappingType¶

Compare this config to another.

This is primarily used in the CLI logs to indicate to the user what values have been changed for each file compared to the root config for the project.

Parameters:: other (FluffConfig) – Another config object to compare against. We will return keys from this object that are not in other or are different to those in other.
Returns:: A filtered dict of items in this config that are not in the other or are different to the other.
Return type:: dict

classmethod from_kwargs(dialect: str | None = None, rules: List[str] | None = None, exclude_rules: List[str] | None = None, require_dialect: bool = True) → FluffConfig¶

Instantiate a config from a subset of common options.

Parameters:

dialect (str, optional) – The name of the dialect to use.
rules (list of str, optional) – A list of rules to include. Rule specifiers can be codes, names, groups or aliases. If not set, defaults to all rules.
exclude_rules (list of str, optional) – A list of rules to exclude. Rule specifiers can be codes, names, groups or aliases. If not set, does not exclude any rules.
require_dialect (bool, optional, default is True) – When True an error will be raise if the dialect config value is unset.

Returns:

The loaded config object.

Return type:

FluffConfig

This is a convenience method for the ways that the public classes like Linter(), Parser() and Lexer() allow a subset of attributes to be set directly rather than requiring a pre-made FluffConfig.

classmethod from_path(path: str, extra_config_path: str | None = None, ignore_local_config: bool = False, overrides: ConfigMappingType | None = None, plugin_manager: pluggy.PluginManager | None = None) → FluffConfig¶

Loads a config object given a particular path.

Parameters:

path (str) – The target path to load config files from. Files found between the working path and this path are also loaded and nested with files closest to this target path taking precedence.
extra_config_path (str, optional) – An optional additional path to load config files from. These are loaded last if found and take precedence over any pre-existing config values.
ignore_local_config (bool, optional, defaults to False) – If set to True, this skips loading configuration from the user home directory (~) or appdir path.
overrides (ConfigMappingType, optional) – A additional set of configs to merge into the core section of the config object at the end. These values take precedence over all other provided values and are inherited by child configs. Note that this mapping dict only applies to the core section and so cannot be used for all values.
plugin_manager (PluginManager, optional) – Optional pre-loaded config manager. Generally users should not need to provide this, as the class will fetch it’s own if not provided. This argument is used when creating new class instances to avoid reloading the manager.

Returns:

The loaded config object.

Return type:

FluffConfig

classmethod from_root(extra_config_path: str | None = None, ignore_local_config: bool = False, overrides: ConfigMappingType | None = None, require_dialect: bool = True) → FluffConfig¶

Loads a config object based on the root directory.

Parameters:

extra_config_path (str, optional) – An optional additional path to load config files from. These are loaded last if found and take precedence over any pre-existing config values.
ignore_local_config (bool, optional, defaults to False) – If set to True, this skips loading configuration from the user home directory (~) or appdir path.
overrides (ConfigMappingType, optional) – A additional set of configs to merge into the config object at the end. These values take precedence over all other provided values and are inherited by child configs. For example, override values provided in the CLI use this method to apply to all files in a linting operation.
require_dialect (bool, optional, default is True) – When True an error will be raise if the dialect config value is unset.

Returns:

The loaded config object.

Return type:

FluffConfig

classmethod from_string(config_string: str, overrides: ConfigMappingType | None = None) → FluffConfig¶

Loads a config object from a single config string.

Parameters:

config_string (str) – The config string, assumed to be in ini format (like a .sqlfluff file).
overrides (ConfigMappingType, optional) – A additional set of configs to merge into the config object at the end. These values take precedence over all other provided values and are inherited by child configs. For example, override values provided in the CLI use this method to apply to all files in a linting operation.

Returns:

The loaded config object.

Return type:

FluffConfig

classmethod from_strings(*config_strings: str, overrides: ConfigMappingType | None = None) → FluffConfig¶

Loads a config object given a series of nested config strings.

Parameters:

*config_strings (str) – An iterable of config strings, assumed to be in ini format (like a .sqlfluff file).
overrides (ConfigMappingType, optional) – A additional set of configs to merge into the config object at the end. These values take precedence over all other provided values and are inherited by child configs. For example, override values provided in the CLI use this method to apply to all files in a linting operation.

Returns:

The loaded config object.

Return type:

FluffConfig

Config strings are incorporated from first to last, treating the first element as the “root” config, and then later config strings will take precedence over any earlier values.

get(val: str, section: str | Iterable[str] = 'core', default: Any = None) → Any¶

Get a particular value from the config.

Parameters:

val (str) – The name of the config value to get.
section (str or iterable of str, optional) – The “path” to the config value. For values in the main [sqlfluff] section of the config, which are stored in the core section of the config this can be omitted.
default – The value to return if the config value was not found. If no default is provided, then a KeyError will be raised if no value was found.

The following examples show how to fetch various default values:

>>> FluffConfig(overrides={"dialect": "ansi"}).get("dialect")
'ansi'

>>> config = FluffConfig(overrides={"dialect": "ansi"})
>>> config.get("tab_space_size", section="indentation")
4

>>> FluffConfig(overrides={"dialect": "ansi"}).get(
...     "capitalisation_policy",
...     section=["rules", "capitalisation.keywords"]
... )
'consistent'

get_section(section: str | Iterable[str]) → Any¶

Return a whole section of config as a dict.

If the element found at the address is a value and not a section, it is still returned and so this can be used as a more advanced from of the basic get method.

Parameters:: section – An iterable or string. If it’s a string we load that root section. If it’s an iterable of strings, then we treat it as a path within the dictionary structure.

get_templater(**kwargs: Any) → RawTemplater¶: Instantiate the configured templater.

get_templater_class() → Type['RawTemplater']¶: Get the configured templater class.

Note

This is mostly useful to call directly when rules want to determine the type of a templater without (in particular to work out if it’s a derivative of the jinja templater), without needing to instantiate a full templater. Instantiated templaters don’t pickle well, so aren’t automatically passed around between threads/processes.

iter_vals(cfg: ConfigMappingType | None = None) → Iterable[Tuple[int, str, ConfigValueOrListType]]¶

Return an iterable of tuples representing keys.

Parameters:: cfg (optional) – An optional config mapping to format instead. If not provided, we use the internal config object of the FluffConfig.

This is primarily to enable formatting of config objects in the CLI.

We show values before dicts, the tuple contains an indent value to know what level of the dict we’re in. Dict labels will be returned as a blank value before their content.

make_child_from_path(path: str) → FluffConfig¶

Make a child config at a path but pass on overrides and extra_config_path.

Parameters:: path (str) – The path to load the new config object from, inheriting the content of the calling FluffConfig as base values.
Returns:: A new config object which copies the current config object, but overriding any values set by config values loaded from the given path.
Return type:: FluffConfig

process_inline_config(config_line: str, fname: str) → None¶

Process an inline config command and update self.

Parameters:

config_line (str) – The inline config section to be processed. This should usually begin with -- sqlfluff:.
fname (str) – The name of the current file being processed. This is used purely for logging purposes in the case that an invalid config string is provided so that any error messages can reference the file with the issue.

>>> cfg = FluffConfig(overrides={"dialect": "ansi"})
>>> cfg.process_inline_config(
...     "-- sqlfluff:dialect:postgres",
...     "test.sql"
... )
>>> cfg.get("dialect")
'postgres'

process_raw_file_for_config(raw_str: str, fname: str) → None¶

Process a full raw file for inline config and update self.

Parameters:

raw_str (str) – The full SQL script to evaluate for inline configs.
fname (str) – The name of the current file being processed. This is used purely for logging purposes in the case that an invalid config string is provided so that any error messages can reference the file with the issue.

>>> cfg = FluffConfig(overrides={"dialect": "ansi"})
>>> cfg.process_raw_file_for_config(
...     "-- sqlfluff:dialect:postgres",
...     "test.sql"
... )
>>> cfg.get("dialect")
'postgres'

set_value(config_path: Iterable[str], val: Any) → None¶

Set a value at a given path.

Parameters:

config_path – An iterable of strings. Each should be a one of the elements which is colon delimited in a standard config file.
val – The value to set at the given path.

>>> cfg = FluffConfig(overrides={"dialect": "ansi"})
>>> cfg.set_value(["dialect"], "postgres")
>>> cfg.get("dialect")
'postgres'

>>> cfg = FluffConfig(overrides={"dialect": "ansi"})
>>> cfg.set_value(["indentation", "tab_space_size"], 2)
>>> cfg.get("tab_space_size", section="indentation")
2

verify_dialect_specified() → None¶

Check if the config specifies a dialect, raising an error if not.

Raises:: SQLFluffUserError – If dialect config value is unset. The content of the error contains user-facing instructions on what dialects are available and how to set the dialect.

`sqlfluff.core.config`: Configuration & `FluffConfig`¶

Methods for creating config mappings¶

The `FluffConfig` object¶

Navigation

Related Topics

sqlfluff.core.config: Configuration & FluffConfig¶

Methods for creating config mappings¶

The FluffConfig object¶

`sqlfluff.core.config`: Configuration & `FluffConfig`¶

The `FluffConfig` object¶