Configuration & FluffConfig

This section is for plugin and rule authors who use the Python API. For everyday configuration options see the Configuration docs.

Internally, SQLFluff merges all discovered config files into a single FluffConfig object which is threaded through the linting pipeline. The sqlfluff.core.config.loader module exposes functions to build the nested dict that FluffConfig consumes.

The nested dict mirrors .sqlfluff key paths split on :. For example:

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

becomes:

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

Source: sqlfluff/core/config/

Loader functions

load_config_string

load_config_string(
    config_string,
    configs=None,
    working_path=None
)

Load a config from a string in ini format.

Parameters:

Parameter	Type	Default	Description
config_string	str		The raw config file as a string. The content is assumed to be in the .ini format of a .sqlfluff file (i.e. not in .toml format).
configs	Optional[ConfigMappingType]	None	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	Optional[str]	None	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:

ConfigMappingType: A nested dictionary of config values.

load_config_file

load_config_file(
    file_dir,
    file_name,
    configs=None
)

Load a config file from the filesystem.

Parameters:

Parameter	Type	Default	Description
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	Optional[ConfigMappingType]	None	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:

ConfigMappingType: A nested dictionary of config values.

load_config_resource

load_config_resource(
    package,
    file_name
)

Load a config resource from a python package.

Parameters:

Parameter	Type	Default	Description
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:

ConfigMappingType: A nested dictionary of config values.

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_up_to_path

load_config_up_to_path(
    path,
    extra_config_path=None,
    ignore_local_config=False
)

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

Parameters:

Parameter	Type	Default	Description
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	Optional[str]	None	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	False	If set to True, this skips loading configuration from the user home directory (~) or appdir path.

Returns:

ConfigMappingType: A nested dictionary of config values.

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.

FluffConfig

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:

Parameter	Type	Default	Description
configs	Optional[ConfigMappingType]	None	A nested dict of config values from which to construct the config.
extra_config_path	Optional[str]	None	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	False	If set to True, this skips loading configuration from the user home directory (~) or appdir path.
overrides	Optional[ConfigMappingType]	None	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	Optional[pluggy.PluginManager]	None	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.
require_dialect	bool	True

Methods

copy

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:

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

diff_to

diff_to(
    other
)

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:

Parameter	Type	Default	Description
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:

dict: A filtered dict of items in this config that are not in the other or are different to the other.

from_kwargs

from_kwargs(
    dialect=None,
    rules=None,
    exclude_rules=None,
    require_dialect=True
) → FluffConfig

Instantiate a config from a subset of common options.

Parameters:

Parameter	Type	Default	Description
dialect	str | None	None	The name of the dialect to use.
rules	list[str] | None	None	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[str] | None	None	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	True	When True an error will be raise if the dialect config value is unset.

Returns:

FluffConfig — FluffConfig: The loaded config object.

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.

from_path

from_path(
    path,
    extra_config_path=None,
    ignore_local_config=False,
    overrides=None,
    plugin_manager=None,
    require_dialect=True
)

Loads a config object given a particular path.

Parameters:

Parameter	Type	Default	Description
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	Optional[str]	None	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	False	If set to True, this skips loading configuration from the user home directory (~) or appdir path.
overrides	Optional[ConfigMappingType]	None	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	Optional[pluggy.PluginManager]	None	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.
require_dialect	bool	True	When True an error will be raise if the dialect config value is unset.

Returns:

FluffConfig: The loaded config object.

from_root

from_root(
    extra_config_path=None,
    ignore_local_config=False,
    overrides=None,
    require_dialect=True
)

Loads a config object based on the root directory.

Parameters:

Parameter	Type	Default	Description
extra_config_path	Optional[str]	None	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	False	If set to True, this skips loading configuration from the user home directory (~) or appdir path.
overrides	Optional[ConfigMappingType]	None	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	True	When True an error will be raise if the dialect config value is unset.

Returns:

FluffConfig: The loaded config object.

from_string

from_string(
    config_string,
    overrides=None
)

Loads a config object from a single config string.

Parameters:

Parameter	Type	Default	Description
config_string	str		The config string, assumed to be in ini format (like a .sqlfluff file).
overrides	Optional[ConfigMappingType]	None	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:

FluffConfig: The loaded config object.

from_strings

from_strings(
    config_strings,
    overrides=None
)

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

Parameters:

Parameter	Type	Default	Description
config_strings	str
overrides	Optional[ConfigMappingType]	None	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:

FluffConfig: The loaded config object.

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

get(
    val,
    section="core",
    default=None
) → Any

Get a particular value from the config.

Parameters:

Parameter	Type	Default	Description
val	str		The name of the config value to get.
section	str | collections.abc.Iterable[str]	"core"	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	Any	None	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'

Returns:

Any — See return type.

get_section

get_section(
    section
) → 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:

Parameter	Type	Default	Description
section	str | collections.abc.Iterable[str]		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.

Returns:

Any — See return type.

get_templater

get_templater(
    kwargs
)

Instantiate the configured templater.

Parameters:

Parameter	Type	Default	Description
kwargs	Any

get_templater_class

get_templater_class()

Get the configured templater class.

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

iter_vals(
    cfg=None
)

Return an iterable of tuples representing keys.

Parameters:

Parameter	Type	Default	Description
cfg	Optional[ConfigMappingType]	None	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

make_child_from_path(
    path,
    require_dialect=True
) → FluffConfig

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

Parameters:

Parameter	Type	Default	Description
path	str		The path to load the new config object from, inheriting the content of the calling FluffConfig as base values.
require_dialect	bool	True	When True an error will be raise if the dialect config value is unset.

Returns:

FluffConfig — FluffConfig: A new config object which copies the current config object, but overriding any values set by config values loaded from the given path.

process_inline_config

process_inline_config(
    config_line,
    fname
) → None

Process an inline config command and update self.

Parameters:

Parameter	Type	Default	Description
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'

Returns:

None — See return type.

process_raw_file_for_config

process_raw_file_for_config(
    raw_str,
    fname
) → None

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

Parameters:

Parameter	Type	Default	Description
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'

Returns:

None — See return type.

set_value

set_value(
    config_path,
    val
) → None

Set a value at a given path.

Parameters:

Parameter	Type	Default	Description
config_path	collections.abc.Iterable[str]		An iterable of strings. Each should be a one of the elements which is colon delimited in a standard config file.
val	Any		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

Returns:

None — See return type.

verify_dialect_specified

verify_dialect_specified() → None

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

Returns:

None — See return type.

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.