Configuration¶

snippet-fmt is configured using the pyproject.toml file in the root of your project (alongside setup.py, tox.ini etc.). The file uses the TOML syntax, with the configuration in the [tool.snippet-fmt] table.

The table can contain two keys: languages and directives

Alternatively, the -c / --config-file option can be used to point to a different TOML file. The layout is the same except the table [snippet-fmt] rather than [tool.snippet.fmt].

languages¶

This is a table of tables giving languages to check and reformat.

These correspond to the value after .. code-block::, preserving case.

For example, the following codeblock has a value of 'TOML':

.. code-block:: TOML

    key = "value"

Each language has a corresponding check / reformat function, which is determined from the lowercased form of the language name. This allows certain code blocks in a language to be excluded from formatting by using a different case, such as using TOML for most code blocks and toml for ones which shouldn’t be reformatted.

The currently supported languages (matched case insensitively) are:

JSON
INI
TOML
Python / Python3

Each sub table contains options specific to that language (and capitalisation). The exact options vary, but each has a reformat option which defaults to False. If set to True the code snippets in that language will be reformatted, otherwise they will only be syntax checked.

By default all languages are enabled for checks only.

directives¶

The directive types to reformat, such as 'code-block' for .. code-block::.

The values are case sensitive.

Defaults to ['code', 'code-block', 'sourcecode'].

Supported Languages¶

The following languages are supported by snippet-fmt:

Python / Python3¶

Reformatting Python files with formate.

Options

python.reformat¶: Type: Boolean

Default: False

If set to true the code blocks matching this language and capitalisation will be reformatted, otherwise they will only be syntax checked.

python.config-file¶: Type: String

Default: formate.toml

The TOML file containing the configuration for formate.

JSON¶

Syntax checking and reformatting of JSON files, using Python’s json module.

Options

json.reformat¶: Type: Boolean

Default: False

If set to true the code blocks matching this language and capitalisation will be reformatted, otherwise they will only be syntax checked.

json.ensure_ascii¶: Type: Boolean

Default: false

If true, the output is guaranteed to have all incoming non-ASCII characters escaped. If false (the default), these characters will be output as-is.

json.allow_nan¶: Type: Boolean

Default: true

If true (the default), then NaN, Infinity, and -Infinity will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise an error will be raised when attepting to reformat files containing such floats.

Note

JSON snippets containing NaN etc. when this option is false and reformat is also false will pass, as this check only takes place durinh reformatting.

json.sort_keys¶: Type: Boolean

Default: false

If true then the keys will be sorted alphabetically.

json.indent¶: Type: Integer or string

If indent is a non-negative integer or string, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0, negative, or “” will only insert newlines. If not specified a compact representation will be used. Using a positive integer indent indents that many spaces per level. If indent is a string (such as “t”), that string is used to indent each level.

json.separators¶: Type: Array of string

A 2-element array of [item_separator, key_separator]. The default is (', ', ': ') if indent is unspecified and (',', ': ') otherwise. To get the most compact JSON representation, you should specify (',', ':') to eliminate whitespace.

TOML¶

Syntax checking and reformatting of TOML files using the toml library.

Note

This only supports TOML version 0.5.0.

Options

toml.reformat¶: Type: Boolean

Default: False

If set to true the code blocks matching this language and capitalisation will be reformatted, otherwise they will only be syntax checked.

INI¶

Syntax checking and reformatting of INI files, using Python’s configparser module.

Options

ini.reformat¶: Type: Boolean

Default: False

If set to true the code blocks matching this language and capitalisation will be reformatted, otherwise they will only be syntax checked.

Example¶

[tool.snippet-fmt]
directives = [ "code", "code-block", "sourcecode",]

[tool.snippet-fmt.languages.python]
reformat = true
config-file = "pyproject.toml"

[tool.snippet-fmt.languages.TOML]
reformat = true

[tool.snippet-fmt.languages.toml]

[tool.snippet-fmt.languages.ini]

This will:

look at .. code::, .. code-block:: and .. sourcecode:: directives for python, TOML, toml, and ini.
Code blocks marked python and TOML will be reformatted.
Code blocks marked toml and ini will only be checked for valid syntax.
formate is configured to take its configuration from pyproject.toml.