API Reference

Public Interface

f2format.convert(code, filename=None, *, source_version=None, linesep=None, indentation=None, pep8=None)[source]

Convert the given Python source code string.

Parameters
  • code (Union[str, bytes]) – the source code to be converted

  • filename (Optional[str]) – an optional source file name to provide a context in case of error

  • source_version (Optional[str]) –

  • linesep (Optional[Literal[ , , ]]) –

  • indentation (Optional[Union[str, int]]) –

  • pep8 (Optional[bool]) –

Keyword Arguments

source_version (Optional[str]) – parse the code as this Python version (uses the latest version by default)

Environment Variables
  • F2FORMAT_SOURCE_VERSION – same as the source_version argument and the --source-version option

    in CLI

  • F2FORMAT_LINESEP – same as the linesep argument and the --linesep option in CLI

  • F2FORMAT_INDENTATION – same as the indentation argument and the --indentation option in CLI

  • F2FORMAT_PEP8 – same as the pep8 argument and the --no-pep8 option in CLI (logical negation)

Returns

converted source code

Return type

str

f2format.f2format(filename, *, source_version=None, linesep=None, indentation=None, pep8=None, quiet=None, dry_run=False)[source]

Convert the given Python source code file. The file will be overwritten.

Parameters
  • filename (str) – the file to convert

  • source_version (Optional[str]) –

  • linesep (Optional[Literal[ , , ]]) –

  • indentation (Optional[Union[str, int]]) –

  • pep8 (Optional[bool]) –

  • quiet (Optional[bool]) –

  • dry_run (bool) –

Keyword Arguments
  • source_version (Optional[str]) – parse the code as this Python version (uses the latest version by default)

  • linesep (Optional[str]) – line separator of code (LF, CRLF, CR) (auto detect by default)

  • indentation (Optional[Union[int, str]]) – code indentation style, specify an integer for the number of spaces, or 't'/'tab' for tabs (auto detect by default)

  • pep8 (Optional[bool]) – whether to make code insertion PEP 8 compliant

  • quiet (Optional[bool]) – whether to run in quiet mode

  • dry_run (bool) – if True, only print the name of the file to convert but do not perform any conversion

Environment Variables
  • F2FORMAT_SOURCE_VERSION – same as the source-version argument and the --source-version option

    in CLI

  • F2FORMAT_LINESEP – same as the linesep argument and the --linesep option in CLI

  • F2FORMAT_INDENTATION – same as the indentation argument and the --indentation option in CLI

  • F2FORMAT_PEP8 – same as the pep8 argument and the --no-pep8 option in CLI (logical negation)

  • F2FORMAT_QUIET – same as the quiet argument and the --quiet option in CLI

Return type

None

f2format.main(argv=None)[source]

Entry point for f2format.

Parameters

argv (Optional[List[str]]) – CLI arguments

Environment Variables
  • F2FORMAT_QUIET – same as the --quiet option in CLI

  • F2FORMAT_CONCURRENCY – same as the --concurrency option in CLI

  • F2FORMAT_DO_ARCHIVE – same as the --no-archive option in CLI (logical negation)

  • F2FORMAT_ARCHIVE_PATH – same as the --archive-path option in CLI

  • F2FORMAT_SOURCE_VERSION – same as the --source-version option in CLI

  • F2FORMAT_LINESEP – same as the --linesep option in CLI

  • F2FORMAT_INDENTATION – same as the --indentation option in CLI

  • F2FORMAT_PEP8 – same as the --no-pep8 option in CLI (logical negation)

Return type

int

Conversion Implementation

The main logic of the f2format conversion is to extract the expressions part from formatted string literals and rewrite the original f-string using str.format syntax.

For conversion algorithms and details, please refer to Algorithms.

Data Structures

During conversion, we utilised bpc_utils.Config to store and deliver the configurations over the conversion Context instances, which should be as following:

class f2format.Config[source]

Configuration object shared over the conversion process of a single source file.

indentation: str

Indentation sequence.

linesep: Literal['\n', '\r\n', '\r']

Line separator.

pep8: bool

PEP 8 compliant conversion flag.

filename: Optional[str]

An optional source file name to provide a context in case of error.

source_version: Optional[str]

Parse the code as this Python version (uses the latest version by default).

Conversion Contexts

class f2format.Context(node, config, *, indent_level=0, raw=False)[source]

Bases: bpc_utils.context.BaseContext

General conversion context.

Parameters
Keyword Arguments

raw (bool) – raw processing flag

Return type

None

Important

raw should be True only if the node is in the clause of another context, where the converted wrapper functions should be inserted.

For the Context class of f2format module, it will process nodes with following methods:

Initialize BaseContext.

Parameters
  • node (NodeOrLeaf) – parso AST

  • config (Config) – conversion configurations

  • indent_level (int) – current indentation level

  • raw (bool) – raw processing flag

Return type

None

_concat()[source]

Concatenate final string.

This method tries to concatenate final result based on the very location where starts to contain formatted string literals, i.e. between the converted code as self._prefix and self._suffix.

Return type

None

_process_fstring(node)[source]

Process formatted strings (f_string).

Parameters

node (parso.python.tree.PythonNode) – formatted strings node

Return type

None

_process_strings(node)[source]

Process concatenable strings (stringliteral).

Parameters

node (parso.python.tree.PythonNode) – concatentable strings node

Return type

None

As in Python, adjacent string literals can be concatenated in certain cases, as described in the documentation. Such concatenable strings may contain formatted string literals (f-string) within its scope.

Return type

None

Parameters

node (parso.python.tree.PythonNode) –

classmethod has_debug_fstring(node)[source]

Check if node has debug formatted string literals.

Parameters

node (parso.tree.NodeOrLeaf) – parso AST

Returns

if node has debug formatted string literals

Return type

bool

classmethod has_expr(node)[source]

Check if node has formatted string literals.

Parameters

node (parso.tree.NodeOrLeaf) – parso AST

Returns

if node has formatted string literals

Return type

bool

classmethod has_f2format(node)

Check if node has formatted string literals.

Parameters

node (parso.tree.NodeOrLeaf) – parso AST

Returns

if node has formatted string literals

Return type

bool

classmethod has_fstring(node)[source]

Check if node has actual formatted string literals.

Parameters

node (parso.tree.NodeOrLeaf) – parso AST

Returns

if node has actual formatted string literals

(with expressions in the literals)

Return type

bool

static is_debug_fstring(node)[source]

Check if node is debug formatted string literal expression (f_expression).

Parameters

node (parso.python.tree.PythonNode) – formatted literal expression node

Returns

if node is debug formatted string literals

Return type

bool

_abc_impl = <_abc_data object>
class f2format.StringContext