snippet_fmt

Format and validate code snippets in reStructuredText files.

Classes:

CodeBlockError(offset, exc)	Represents an exception raised when parsing and reformatting a code block.
RSTReformatter(filename, config)	Reformat code snippets in a reStructuredText file.

Functions:

reformat_file(filename, config[, colour])

Reformat the given reStructuredText file, and show the diff if changes were made.

namedtuple CodeBlockError(offset, exc)

Bases: NamedTuple

Represents an exception raised when parsing and reformatting a code block.

Fields

0.  offset (int) – The character offset where the exception was raised.

1.  exc (Exception) – The exception itself.

__repr__()

Return a nicely formatted representation string

class RSTReformatter(filename, config)

Bases: object

Reformat code snippets in a reStructuredText file.

Parameters

• filename (Union[str, Path, PathLike]) – The filename to reformat.

• config (SnippetFmtConfigDict) – The snippet_fmt configuration, parsed from a TOML file (or similar).

Attributes:

config	The formate configuration, parsed from a TOML file (or similar).
file_to_format	The filename being reformatted, as a POSIX-style path.
filename	The filename being reformatted.

Methods:

get_diff()	Returns the diff between the original and reformatted file content.
load_extra_formatters()	Load custom formatters defined via entry points.
process_match(match)	Process a re.Match for a single code block.
run()	Run the reformatter.
to_file()	Write the reformatted source to the original file.
to_string()	Return the reformatted file as a string.

config

Type:    SnippetFmtConfigDict

The formate configuration, parsed from a TOML file (or similar).

file_to_format

Type:    PathPlus

The filename being reformatted, as a POSIX-style path.

filename

Type:    str

The filename being reformatted.

get_diff()

Returns the diff between the original and reformatted file content.

Return type

str

load_extra_formatters()

Load custom formatters defined via entry points.

process_match(match)

Process a re.Match for a single code block.

Parameters

match (Match[str])

Return type

str

run()

Run the reformatter.

Return type

bool

Returns

Whether the file was changed.

to_file()

Write the reformatted source to the original file.

to_string()

Return the reformatted file as a string.

Return type

str

reformat_file(filename, config, colour=None)

Reformat the given reStructuredText file, and show the diff if changes were made.

Parameters

• filename (Union[str, Path, PathLike]) – The filename to reformat.

• config (SnippetFmtConfigDict) – The snippet-fmt configuration, parsed from a TOML file (or similar).

• colour (Optional[bool]) – Whether to force coloured output on (True) or off (False). Default None.

Return type

int