# `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, require_dialect: bool = True) → 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.

      - 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_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, require_dialect: bool = True) → 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.

      - require_dialect (bool, optional, default is True) – When True an error will be raise if the dialect config value is unset.

    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.