`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.
`DocstringReformatter`(token, filename, config)	Reformat code snippets in a docstring from a Python file.
`PyReformatter`(filename, config)	Reformat code snippets in docstrings in a Python file.
`RSTReformatter`(filename, config)	Reformat code snippets in a reStructuredText file.
`Reformatter`(source, filename, config)	Base class for reformatters.

Functions:

`reformat_docstrings`(filename, config[, colour])	Reformat docstrings in the given Python file, and show the diff if changes were made.
`reformat_file`(filename, config[, colour])	Reformat the given reStructuredText file, and show the diff if changes were made.

namedtuple CodeBlockError(offset, exc)[source]¶

Bases: NamedTuple

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

Fields

offset (int) – The character offset where the exception was raised.
exc (Exception) – The exception itself.

__repr__()¶: Return a nicely formatted representation string

class Reformatter(source, filename, config)[source]¶

Bases: object

Base class for reformatters.

Parameters

source (str) – The file content.
filename (str) – The file being formatted, for display in error messages.
config (SnippetFmtConfigDict) – The snippet_fmt configuration, parsed from a TOML file (or similar).

New in version 0.2.0.

Methods:

`compile_regex`()	Compile the regular expression for finding directives.
`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.
`report_error`(error)	Print the error message.
`run`()	Run the reformatter.
`to_string`()	Return the reformatted file as a string.

Attributes:

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

compile_regex()[source]¶

Compile the regular expression for finding directives.

New in version 0.2.0.

Return type: Pattern

config¶

Type: SnippetFmtConfigDict

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

filename¶

Type: str

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

get_diff()[source]¶

Returns the diff between the original and reformatted file content.

Return type: str

load_extra_formatters()[source]¶: Load custom formatters defined via entry points.

process_match(match)[source]¶

Process a re.Match for a single code block.

Parameters: match (Match[str])
Return type: str

report_error(error)[source]¶

Print the error message.

Parameters: error (CodeBlockError)

New in version 0.2.0.

run()[source]¶

Run the reformatter.

Return type: bool
Returns: Whether the file was changed.

to_string()[source]¶

Return the reformatted file as a string.

Return type: str

class RSTReformatter(filename, config)[source]¶

Bases: Reformatter

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:

file_to_format

The filename being reformatted.

Methods:

to_file()

Write the reformatted source to the original file.

file_to_format¶

Type: PathPlus

The filename being reformatted.

to_file()[source]¶: Write the reformatted source to the original file.

class DocstringReformatter(token, filename, config)[source]¶

Bases: Reformatter

Reformat code snippets in a docstring from a Python file.

Parameters

token (Token) – The docstring token to format.
filename (Union[str, Path, PathLike]) – The filename being reformated.
config (SnippetFmtConfigDict) – The snippet_fmt configuration, parsed from a TOML file (or similar).

New in version 0.2.0.

Methods:

`get_diff`()	Returns the diff between the original and reformatted file content.
`report_error`(error)	Print the error message.
`run`()	Run the reformatter.
`to_string`()	Return the reformatted file as a string.
`to_token`()	Return the docstring as a token for `tokenize_rt`.

Attributes:

`indent`	The docstring’s indentation.
`prefix_char`	Letters before the string e.g.
`quote_char`	Quotes used for the docstring, e.g.
`token`	The docstring token being reformatted.

get_diff()[source]¶

Returns the diff between the original and reformatted file content.

Return type: str

indent¶

Type: str

The docstring’s indentation.

prefix_char¶

Type: str

Letters before the string e.g. f, u, r, fr

quote_char¶

Type: str

Quotes used for the docstring, e.g. ' or """

report_error(error)[source]¶

Print the error message.

Parameters: error (CodeBlockError)

run()[source]¶

Run the reformatter.

Return type: bool
Returns: Whether the file was changed.

to_string()[source]¶

Return the reformatted file as a string.

Return type: str

to_token()[source]¶

Return the docstring as a token for tokenize_rt.

Return type: Token

token¶

Type: Token

The docstring token being reformatted.

class PyReformatter(filename, config)[source]¶

Bases: RSTReformatter

Reformat code snippets in docstrings in a Python file.

Parameters

filename (Union[str, Path, PathLike]) – The filename to reformat.
config (SnippetFmtConfigDict) – The snippet_fmt configuration, parsed from a TOML file (or similar).

New in version 0.2.0.

run()[source]¶

Run the reformatter.

Return type: bool
Returns: Whether the file was changed.

reformat_file(filename, config, colour=None)[source]¶

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

reformat_docstrings(filename, config, colour=None)[source]¶

Reformat docstrings in the given Python 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).v. Default None.

Return type

int

New in version 0.2.0.

snippet_fmt¶

`snippet_fmt`¶