API Reference

Public Interface

walrus.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

Keyword Arguments

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

  • linesep (Optional[Linesep]) – 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

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

    in CLI

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

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

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

Returns

converted source code

Return type

str

walrus.walrus(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

Keyword Arguments

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

  • linesep (Optional[Linesep]) – 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
  • WALRUS_SOURCE_VERSION – same as the source-version argument and the --source-version option

    in CLI

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

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

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

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

Return type

None

walrus.main(argv=None)[source]

Entry point for walrus.

Parameters

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

Returns

program exit code

Return type

int

Environment Variables

  • WALRUS_QUIET – same as the --quiet option in CLI

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

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

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

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

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

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

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

Conversion Implementation

The main logic of the walrus conversion is to wrap assignment expressions as functions which manipulates variable namespaces to implement the assignment part and evaluates original code blocks to archive the expression part.

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 walrus.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).

Since conversion of assignment expressions in different statements has different processing logics and templates, we hereby describe two data structures representing such information.

The FunctionEntry represents an assignment expression at most circumstances. It will be provided to FUNC_TEMPLATE to render the wrapper function for the conversion.

class walrus.FunctionEntry
Bases

typing.TypedDict

name: str

Function name, as the original left-hand-side variable name from the assignment expression.

uuid: str

UUID text in the function name to avoid name collision with existing functions.

scope_keyword: Literal['global', 'nonlocal']

Scope manipulation keyword. If name is declared in global namespace, then it will be 'global', else 'nonlocal'.

Note

If the left-hand-side variable name is recorded in the global context (Context.global_stmt), then the converted function should use 'global' as its scope keyword.

The LambdaEntry represents an assignment expression declared in lambda statements. It will be provided to LAMBDA_FUNC_TEMPLATE to render the wrapper function for the conversion.

class walrus.LambdaEntry
Bases

typing.TypedDict

param: str

Concatenated parameter string for the wrapper function.

suite: str

Original lambda suite with assignment expressions converted.

uuid: str

UUID text in the function name to avoid name collision with existing functions.

Conversion Templates

For general conversion scenarios, the converted wrapper functions will be rendered based on the following templates.

walrus.NAME_TEMPLATE: List[str]
['if False:',
 '%(indentation)s%(name_list)s = NotImplemented']

Declares variables in the current scope for using global and/or nonlocal statements.

Variables

  • indentation – indentation sequence as defined in Config.indentation

  • name_list – equal (=) separated list of variable names

Important

This is a rather hack way to fool the Python interpreter that such variables had been declared in the current scope, whilst not actually declaring such variables at runtime.

walrus.CALL_TEMPLATE: str
'_walrus_wrapper_%(name)s_%(uuid)s(%(expr)s)'

Wrapper function call to replace the original assignment expression.

Variables

  • name – left-hand-side variable name

  • uuid – UUID text

  • expr – right-hand-side expression

walrus.FUNC_TEMPLATE: List[str]
['def _walrus_wrapper_%(name)s_%(uuid)s(expr):',
 '%(indentation)s"""Wrapper function for assignment expression."""',
 '%(indentation)s%(scope_keyword)s %(name)s',
 '%(indentation)s%(name)s = expr',
 '%(indentation)sreturn %(name)s']

Wrapper function call to replace the original assignment expression.

Variables

  • indentation – indentation sequence as defined in Config.indentation

  • **kwargs – function record as described in Function

For assignment expression in lambda expressions, the converted wrapper function will be rendered based on the following templates.

walrus.LAMBDA_CALL_TEMPLATE: str
'_walrus_wrapper_lambda_%(uuid)s'

Wrapper function call to replace the original assignment expression.

Variables

  • uuid – UUID text

walrus.LAMBDA_FUNC_TEMPLATE: List[str]
['def _walrus_wrapper_lambda_%(uuid)s(%(param)s):',
 '%(indentation)s"""Wrapper function for lambda definitions."""',
 '%(indentation)s%(suite)s']

Wrapper function call to replace the original assignment expression.

Variables

For assignment expression in class variables (ClassVar), the converted wrapper function will be rendered based on the following templates.

walrus.CLS_TEMPLATE: str
"(__import__('builtins').locals().__setitem__(%(name)r, %(expr)s), %(name)s)[1]"

One-liner to rewrite the original assignment expression for a regular class variable definition.

Variables

  • name – variable name

  • expr – original right-hand-side expression

Note

If a wrapper function and/or class involves manipulation over the global and nonlocal statements, then walrus will append a UUID exclusively.

Conversion Contexts

class walrus.Context(node, config, *, indent_level=0, scope_keyword=None, context=None, raw=False)[source]

Bases: bpc_utils.context.BaseContext

General conversion context.

Parameters
Keyword Arguments

  • indent_level (int) – current indentation level

  • scope_keyword (Optional[Literal['global', 'nonlocal']]) – scope keyword for wrapper function

  • context (Optional[List[str]]) – global context (namespace)

  • raw (bool) – raw processing flag

Important

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

Typically, only if node is an assignment expression (namedexpr_test) node, raw will be set as True, in consideration of nesting assignment expressions.

For the Context class of walrus 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

_concat()[source]

Concatenate final string.

This method tries to inserted the recorded wrapper functions and variables at the very location where starts to contain assignment expressions, i.e. between the converted code as self._prefix and self._suffix.

The inserted code include variable declaration rendered from NAME_TEMPLATE, wrapper function definitions rendered from FUNC_TEMPLATE and extracted lambda expressions rendered from LAMBDA_FUNC_TEMPLATE. If self._pep8 is True, it will insert the code in compliance with PEP 8.

Return type

None

_process_argument(node)[source]

Process function argument (argument).

Parameters

node (parso.python.tree.PythonNode) – argument node

This method processes arguments from function argument list.

Return type

None

_process_classdef(node)[source]

Process class definition (classdef).

Parameters

node (parso.python.tree.Class) – class node

This method converts the whole class suite context with _process_suite_node() through ClassContext respectively.

Return type

None

_process_for_stmt(node)[source]

Process for statement (for_stmt).

Parameters

node (parso.python.tree.ForStmt) – for node

This method processes the indented suite under the for and optional else statements.

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_funcdef(node)[source]

Process function definition (funcdef).

Parameters

node (parso.python.tree.Function) – function node

This method converts the function suite with _process_suite_node().

Return type

None

_process_global_stmt(node)[source]

Process function definition (global_stmt).

Parameters

node (parso.python.tree.GlobalStmt) – global statement node

This method records all variables declared in a global statement into self._context.

Return type

None

_process_if_stmt(node)[source]

Process if statement (if_stmt).

Parameters

node (parso.python.tree.IfStmt) – if node

This method processes each indented suite under the if, elif, and else statements.

Return type

None

_process_lambdef(node)[source]

Process lambda definition (lambdef).

Parameters

node (parso.python.tree.Lambda) – lambda node

This method first checks if node contains assignment expressions. If not, it will append the original source code directly to the buffer.

For lambda expressions with assignment expressions, this method will extract the parameter list and initialise a LambdaContext instance to convert the lambda suite. Such information will be recorded as LambdaEntry in self._lamb.

Note

For LambdaContext, scope_keyword should always be 'nonlocal'.

Then it will replace the original lambda expression with a wrapper function call rendered from LAMBDA_CALL_TEMPLATE.

Return type

None

_process_namedexpr_test(node)[source]

Process assignment expression (namedexpr_test).

Parameters

node (parso.python.tree.PythonNode) – assignment expression node

This method converts the assignment expression into wrapper function and extracts related records for inserting converted code.

  • The left-hand-side variable name will be recorded in self._vars.

  • The right-hand-side expression will be converted using another Context instance and replaced with a wrapper function call rendered from CALL_TEMPLATE; information described as FunctionEntry will be recorded into self._func.

Return type

None

_process_string_context(node)[source]

Process string contexts (stringliteral).

Parameters

node (parso.python.tree.PythonNode) – string literals node

This method first checks if node contains assignment expression. If not, it will not perform any processing, rather just append the original source code to context buffer. Later it will check if node contains debug f-string. If not, it will process the regular processing on each child of such node.

See also

The method calls f2format.Context.has_debug_fstring() to detect debug f-strings.

Otherwise, it will initialise a new StringContext instance to perform the conversion process on such node, which will first use f2format to convert those formatted string literals.

Important

When initialisation, raw parameter must be set to True; as the converted wrapper functions should be inserted in the outer context, rather than the new StringContext instance.

After conversion, the method will keep records of converted wrapper functions (Context.functions()), converted lambda expressions (Context.lambdef()) and left-hand-side variable names (Context.variables()) into current instance as well.

Return type

None

_process_strings(node)[source]

Process concatenable strings (stringliteral).

Parameters

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

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.

_documentation: https://docs.python.org/3/reference/lexical_analysis.html#string-literal-concatenation

Return type

None

_process_suite_node(node, func=False, raw=False, cls_ctx=None)[source]

Process indented suite (suite or others).

Parameters

  • node (parso.tree.NodeOrLeaf) – suite node

  • func (bool) – if node is suite from function definition

  • raw (bool) – raw processing flag

  • cls_ctx (Optional[str]) – class name if node is in class context

This method first checks if node contains assignment expression. If not, it will not perform any processing, rather just append the original source code to context buffer.

If node contains assignment expression, then it will initialise another Context instance to perform the conversion process on such node; whilst if cls_ctx is provided, then it will initialise a ClassContext instance instead.

Note

If func is True, when initiating the Context instance, scope_keyword will be set as 'nonlocal', as in the wrapper function it will refer the original left-hand-side variable from the outer function scope rather than global namespace.

The method will keep global statements (Context.global_stmt()) from the temporary Context (or ClassContext) instance in the current instance.

And if raw is set as True, the method will keep records of converted wrapper functions (Context.functions()), converted lambda expressions (Context.lambdef()) and left-hand-side variable names (Context.variables()) into current instance as well.

Important

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

Return type

None

_process_try_stmt(node)[source]

Process try statement (try_stmt).

Parameters

node (parso.python.tree.TryStmt) – try node

This method processes the indented suite under the try, except, else, and finally statements.

Return type

None

_process_while_stmt(node)[source]

Process while statement (while_stmt).

Parameters

node (parso.python.tree.WhileStmt) – while node

This method processes the indented suite under the while and optional else statements.

Return type

None

_process_with_stmt(node)[source]

Process with statement (with_stmt).

Parameters

node (parso.python.tree.WithStmt) – with node

This method processes the indented suite under the with statement.

Return type

None

classmethod determine_scope_keyword(node)[source]

Determine scope keyword based on node position.

Parameters

node (parso.tree.NodeOrLeaf) – parso AST

Returns

scope keyword

Return type

Literal[‘global’, ‘nonlocal’]

This method recursively perform the following checks on the parents of node:

classmethod has_expr(node)[source]

Check if node has assignment expression (namedexpr_test).

Parameters

node (parso.tree.NodeOrLeaf) – parso AST

Returns

if node has assignment expression

Return type

bool

classmethod has_walrus(node)

Check if node has assignment expression (namedexpr_test).

Parameters

node (parso.tree.NodeOrLeaf) – parso AST

Returns

if node has assignment expression

Return type

bool

static is_walrus(node)[source]

Check if node is assignment expression.

Parameters

node (parso.tree.NodeOrLeaf) – parso AST

Returns

if node is assignment expression

Return type

bool

_abc_impl = <_abc_data object>
_context: List[str]

Variable names in global statements.

Type

List[str]

_func: List[FunctionEntry]

Converted wrapper functions described as FunctionEntry.

Type

List[FunctionEntry]

_lamb: List[LambdaEntry]

Converted lambda expressions described as LambdaEntry.

Type

List[LambdaEntry]

_scope_keyword: ScopeKeyword

Literal[‘global’, ‘nonlocal’]: The global / nonlocal keyword.

_vars: List[str]

Original left-hand-side variable names in assignment expressions.

Type

List[str]

property functions

Assignment expression wrapper function records (self._func).

Return type

List[FunctionEntry]

property global_stmt

List of variables declared in the global statements.

If current root node (self._root) is a function definition (parso.python.tree.Function), then returns an empty list; else returns self._context.

Return type

List[str]

property lambdef

Lambda definitions (self._lamb).

Return type

List[LambdaEntry]

property variables

Assignment expression variable records (self._vars).

The variables are the left-hand-side variable name of the assignment expressions.

Return type

List[str]

class walrus.StringContext(node, config, *, indent_level=0, scope_keyword=None, context=None, raw=True)[source]

Bases: walrus.Context

String (f-string) conversion context.

This class is mainly used for converting formatted string literals.

Parameters
Keyword Arguments

  • indent_level (int) – current indentation level

  • scope_keyword (Literal['nonlocal']) – scope keyword for wrapper function

  • context (Optional[List[str]]) – global context (namespace)

  • raw (Literal[True]) – raw processing flag

Note

  • raw should always be True.

As the conversion in Context changes the original expression, which may change the content of debug f-string.

Initialize BaseContext.

Parameters

  • node (PythonNode) – parso AST

  • config (Config) – conversion configurations

  • indent_level (int) – current indentation level

  • raw (Literal[True]) – raw processing flag

_abc_impl = <_abc_data object>
_buffer: str

Final converted result.

_context: List[str]

Variable names in global statements.

Type

List[str]

_func: List[FunctionEntry]

Converted wrapper functions described as FunctionEntry.

Type

List[FunctionEntry]

_indent_level: Final[int]

Current indentation level.

_indentation: Final[str]

Indentation sequence.

_lamb: List[LambdaEntry]

Converted lambda expressions described as LambdaEntry.

Type

List[LambdaEntry]

_linesep: Final[Linesep]

Line seperator.

Type

Final[Linesep]

_node_before_expr: Optional[parso.tree.NodeOrLeaf]

Preceding node with the target expression, i.e. the insertion point.

_pep8: Final[bool]

PEP 8 compliant conversion flag.

_prefix: str

Code before insertion point.

_prefix_or_suffix: bool

Flag to indicate whether buffer is now self._prefix.

_root: Final[parso.tree.NodeOrLeaf]

Root node given by the node parameter.

_scope_keyword: ScopeKeyword

Literal[‘global’, ‘nonlocal’]: The global / nonlocal keyword.

_suffix: str

Code after insertion point.

_uuid_gen: Final[UUID4Generator]

UUID generator.

_vars: List[str]

Original left-hand-side variable names in assignment expressions.

Type

List[str]

config: Final[Config]

Internal configurations.

class walrus.LambdaContext(node, config, *, indent_level=0, scope_keyword=None, context=None, raw=False)[source]

Bases: walrus.Context

Lambda (suite) conversion context.

This class is mainly used for converting lambda expressions.

Parameters
Keyword Arguments

  • indent_level (int) – current indentation level

  • scope_keyword (Literal['nonlocal']) – scope keyword for wrapper function

  • context (Optional[List[str]]) – global context (namespace)

  • raw (Literal[False]) – raw processing flag

Note

  • scope_keyword should always be 'nonlocal'.

  • raw should always be False.

Initialize BaseContext.

Parameters

  • node (NodeOrLeaf) – parso AST

  • config (Config) – conversion configurations

  • indent_level (int) – current indentation level

  • raw (Literal[False]) – raw processing flag

_concat()[source]

Concatenate final string.

Since conversion of lambda expressions doesn’t involve inserting points, this method first simply adds wrapper code to the buffer (self._buffer); then it adds a return statement yielding the converted lambda suite stored in self._prefix and self._suffix.

The wrapper code include variable declaration rendered from NAME_TEMPLATE, wrapper function definitions rendered from FUNC_TEMPLATE and extracted lambda expressions rendered from LAMBDA_FUNC_TEMPLATE. If self._pep8 is True, it will insert the code in compliance with PEP 8.

Return type

None

_abc_impl = <_abc_data object>
_buffer: str

Final converted result.

_context: List[str]

Variable names in global statements.

Type

List[str]

_func: List[FunctionEntry]

Converted wrapper functions described as FunctionEntry.

Type

List[FunctionEntry]

_indent_level: Final[int]

Current indentation level.

_indentation: Final[str]

Indentation sequence.

_lamb: List[LambdaEntry]

Converted lambda expressions described as LambdaEntry.

Type

List[LambdaEntry]

_linesep: Final[Linesep]

Line seperator.

Type

Final[Linesep]

_node_before_expr: Optional[parso.tree.NodeOrLeaf]

Preceding node with the target expression, i.e. the insertion point.

_pep8: Final[bool]

PEP 8 compliant conversion flag.

_prefix: str

Code before insertion point.

_prefix_or_suffix: bool

Flag to indicate whether buffer is now self._prefix.

_root: Final[parso.tree.NodeOrLeaf]

Root node given by the node parameter.

_scope_keyword: ScopeKeyword

Literal[‘global’, ‘nonlocal’]: The global / nonlocal keyword.

_suffix: str

Code after insertion point.

_uuid_gen: Final[UUID4Generator]

UUID generator.

_vars: List[str]

Original left-hand-side variable names in assignment expressions.

Type

List[str]

config: Final[Config]

Internal configurations.

class walrus.ClassContext(node, config, *, cls_ctx, cls_var=None, indent_level=0, scope_keyword=None, context=None, raw=False, external=None)[source]

Bases: walrus.Context

Class (suite) conversion context.

This class is mainly used for converting :term:`class variable <class-variable>`.

Parameters
Keyword Arguments

  • cls_ctx (str) – class context name

  • cls_var (Dict[str, str]) – mapping for assignment variable and its UUID

  • indent_level (int) – current indentation level

  • scope_keyword (Optional[Literal['global', 'nonlocal']]) – scope keyword for wrapper function

  • context (Optional[List[str]]) – global context (namespace)

  • raw (Literal[False]) – raw context processing flag

  • external (Optional[Dict[str, Literal['global', 'nonlocal']]]) – mapping of class variable declared in global and/or nonlocal statements

Important

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

Typically, only if node is an assignment expression (namedexpr_test) node, raw will be set as True, in consideration of nesting assignment expressions.

Initialize BaseContext.

Parameters

  • node (Class) – parso AST

  • config (Config) – conversion configurations

  • indent_level (int) – current indentation level

  • raw (bool) – raw processing flag

_concat()[source]

Concatenate final string.

This method tries to inserted the recorded wrapper functions and variables at the very location where starts to contain assignment expressions, i.e. between the converted code as self._prefix and self._suffix.

For special class variable declared in global and/or nonlocal statements, when assigning to to such variables, i.e. they are on left-hand-side of assignment expressions, the expressions will be assigned with a wrapper function rendered from FUNC_TEMPLATE.

Return type

None

_process_defined_name(node)[source]

Process defined name (name).

Parameters

node (parso.python.tree.Name) – defined name node

This method processes name of defined class variable. The original variable name will be recorded in self._vars; its corresponding UUID will be recorded in self._cls_var; information described as FunctionEntry will be recorded into self._func.

Note

If the left-hand-side variable was declared in global and/or nonlocal, then it shall NOT be considered as class variable.

Return type

None

_process_expr_stmt(node)[source]

Process variable name (expr_stmt).

Parameters

node (parso.python.tree.ExprStmt) – expression statement

This method processes expression statements in the class context. It will search for left-hand-side variable names of defined class variables and call _process_defined_name() to process such nodes.

Return type

None

_process_global_stmt(node)[source]

Process function definition (global_stmt).

Parameters

node (parso.python.tree.GlobalStmt) – global statement node

This method records all variables declared in a global statement into self._context and self._ext_vars.

Return type

None

_process_namedexpr_test(node)[source]

Process assignment expression (namedexpr_test).

Parameters

node (parso.python.tree.PythonNode) – assignment expression node

This method converts the assignment expression into wrapper function and extracts related records for inserting converted code.

  • The left-hand-side variable name will be recorded in self._vars; and its corresponding UUID will be recorded in self._cls_var.

  • The right-hand-side expression will be converted using another ClassContext instance and replaced with a wrapper tuple with attribute setting from CLS_TEMPLATE; information described as FunctionEntry will be recorded into self._func.

Important

ClassContext will mangle left-hand-side variable name through self.mangle when converting.

For special class variable declared in global and/or nonlocal statements:

  • The left-hand-side variable name will NOT be considered as class variable, thus shall NOT be recorded.

  • The expression will be replaced with a wrapper function call rendered from CALL_TEMPLATE; information described as FunctionEntry will be recorded into self._ext_func instead.

Return type

None

_process_nonlocal_stmt(node)[source]

Process function definition (nonlocal_stmt).

Parameters

node (parso.python.tree.KeywordStatement) – nonlocal statement node

This method records all variables declared in a nonlocal statement into self._ext_vars.

Return type

None

_process_string_context(node)[source]

Process string contexts (stringliteral).

Parameters

node (parso.python.tree.PythonNode) – string literals node

This method first checks if node contains assignment expression. If not, it will not perform any processing, rather just append the original source code to context buffer.

If node contains assignment expression, then it will initialise a new ClassStringContext instance to perform the conversion process on such node, which will first use f2format to convert those formatted string literals.

Important

When initialisation, raw parameter must be set to True; as the converted wrapper functions should be inserted in the outer context, rather than the new ClassStringContext instance.

After conversion, the method will keep records of converted wrapper functions (Context.functions), converted lambda expressions (Context.lambdef) and left-hand-side variable names (Context.variables), class variable (ClassContext.cls_var), external variables (ClassContext.external_variables), wrapper functions for external variables (ClassContext.external_functions) into current instance as well.

Return type

None

_process_suite_node(node, func=False, raw=False, cls_ctx=None)[source]

Process indented suite (suite or others).

Parameters

  • node (parso.tree.NodeOrLeaf) – suite node

  • func (bool) – if node is suite from function definition

  • raw (bool) – raw processing flag

  • cls_ctx (Optional[str]) – class name if node is in class context

This method first checks if node contains assignment expression. If not, it will not perform any processing, rather just append the original source code to context buffer.

If node contains assignment expression, then it will initialise another ClassContext instance to perform the conversion process on such node; whilst if func is provided, then it will initialise a Context instance instead.

Note

If func is True, when initiating the Context instance, scope_keyword will be set as 'nonlocal', as in the wrapper function it will refer the original left-hand-side variable from the outer function scope rather than global namespace.

The method will keep global statements (Context.global_stmt()) from the temporary Context (or ClassContext) instance in the current instance.

And if raw is set as True, the method will keep records of converted wrapper functions (Context.functions()), converted lambda expressions (Context.lambdef()) and left-hand-side variable names (Context.variables()), class variable (ClassContext.cls_var()), external variables (ClassContext.external_variables()), wrapper functions for external variables (ClassContext.external_functions()) into current instance as well.

Important

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

Return type

None

_abc_impl = <_abc_data object>
_buffer: str

Final converted result.

_cls_ctx: str

Class context name.

Type

str

_cls_raw: bool

Raw context processing flag.

Type

bool

_cls_var: Dict[str, str]

Mapping for assignment variable and its UUID.

Type

Dict[str, str]

_context: List[str]

Variable names in global statements.

Type

List[str]

_ext_func: List[FunctionEntry]

Converted wrapper functions for class variable declared in global and/or nonlocal statements described as FunctionEntry.

Type

List[FunctionEntry]

_ext_vars: Dict[str, ScopeKeyword]

Original left-hand-side variable names in assignment expressions for class variable declared in global and/or nonlocal statements.

Type

Dict[str, Literal[‘global’, ‘nonlocal’]]

_func: List[FunctionEntry]

Converted wrapper functions described as FunctionEntry.

Type

List[FunctionEntry]

_indent_level: Final[int]

Current indentation level.

_indentation: Final[str]

Indentation sequence.

_lamb: List[LambdaEntry]

Converted lambda expressions described as LambdaEntry.

Type

List[LambdaEntry]

_linesep: Final[Linesep]

Line seperator.

Type

Final[Linesep]

_node_before_expr: Optional[parso.tree.NodeOrLeaf]

Preceding node with the target expression, i.e. the insertion point.

_pep8: Final[bool]

PEP 8 compliant conversion flag.

_prefix: str

Code before insertion point.

_prefix_or_suffix: bool

Flag to indicate whether buffer is now self._prefix.

_root: Final[parso.tree.NodeOrLeaf]

Root node given by the node parameter.

_scope_keyword: ScopeKeyword

Literal[‘global’, ‘nonlocal’]: The global / nonlocal keyword.

_suffix: str

Code after insertion point.

_uuid_gen: Final[UUID4Generator]

UUID generator.

_vars: List[str]

Original left-hand-side variable names in assignment expressions.

Type

List[str]

property cls_var

Mapping for assignment variable and its UUID (self._cls_var).

Return type

Dict[str, str]

config: Final[Config]

Internal configurations.

property external_functions

Assignment expression wrapper function records (self._ext_func) for class variable declared in global and/or nonlocal statements.

Return type

List[FunctionEntry]

property external_variables

Assignment expression variable records (self._ext_vars).

The variables are the left-hand-side variable name of the assignment expressions for class variable declared in global and/or nonlocal statements.

Return type

Dict[str, Literal[‘global’, ‘nonlocal’]]

class walrus.ClassStringContext(node, config, *, cls_ctx, cls_var=None, indent_level=0, scope_keyword=None, context=None, raw=True, external=None)[source]

Bases: walrus.ClassContext

String (f-string) conversion context.

This class is mainly used for converting formatted string literals inside a class suite (ClassVar).

Parameters
Keyword Arguments

  • cls_ctx (str) – class context name

  • cls_var (Dict[str, str]) – mapping for assignment variable and its UUID

  • indent_level (int) – current indentation level

  • scope_keyword (Optional[Literal['global', 'nonlocal']]) – scope keyword for wrapper function

  • context (Optional[List[str]]) – global context (namespace)

  • raw (Literal[True]) – raw context processing flag

  • external (Optional[Dict[str, Literal['global', 'nonlocal']]]) – mapping of class variable declared in global and/or nonlocal statements

Note

raw should always be True.

As the conversion in ClassContext introduced quotes (') into the converted code, it may cause conflicts on the string parsing if the assignment expression was inside a formatted string literal.

Therefore, we will use f2format ahead to convert such formatted string literals into normal str.format() calls then convert any assignment expressions it may contain.

Initialize BaseContext.

Parameters

  • node (PythonNode) – parso AST

  • config (Config) – conversion configurations

  • indent_level (int) – current indentation level

  • raw (Literal[True]) – raw processing flag

_abc_impl = <_abc_data object>
_buffer: str

Final converted result.

_cls_ctx: str

Class context name.

Type

str

_cls_raw: bool

Raw context processing flag.

Type

bool

_cls_var: Dict[str, str]

Mapping for assignment variable and its UUID.

Type

Dict[str, str]

_context: List[str]

Variable names in global statements.

Type

List[str]

_ext_func: List[FunctionEntry]

Converted wrapper functions for class variable declared in global and/or nonlocal statements described as FunctionEntry.

Type

List[FunctionEntry]

_ext_vars: Dict[str, ScopeKeyword]

Original left-hand-side variable names in assignment expressions for class variable declared in global and/or nonlocal statements.

Type

Dict[str, Literal[‘global’, ‘nonlocal’]]

_func: List[FunctionEntry]

Converted wrapper functions described as FunctionEntry.

Type

List[FunctionEntry]

_indent_level: Final[int]

Current indentation level.

_indentation: Final[str]

Indentation sequence.

_lamb: List[LambdaEntry]

Converted lambda expressions described as LambdaEntry.

Type

List[LambdaEntry]

_linesep: Final[Linesep]

Line seperator.

Type

Final[Linesep]

_node_before_expr: Optional[parso.tree.NodeOrLeaf]

Preceding node with the target expression, i.e. the insertion point.

_pep8: Final[bool]

PEP 8 compliant conversion flag.

_prefix: str

Code before insertion point.

_prefix_or_suffix: bool

Flag to indicate whether buffer is now self._prefix.

_root: Final[parso.tree.NodeOrLeaf]

Root node given by the node parameter.

_scope_keyword: ScopeKeyword

Literal[‘global’, ‘nonlocal’]: The global / nonlocal keyword.

_suffix: str

Code after insertion point.

_uuid_gen: Final[UUID4Generator]

UUID generator.

_vars: List[str]

Original left-hand-side variable names in assignment expressions.

Type

List[str]

config: Final[Config]

Internal configurations.

Internal Auxiliaries

Options & Defaults

walrus.WALRUS_SOURCE_VERSIONS = ['3.8', '3.9', '3.10']

Get supported source versions.

See also

bpc_utils.get_parso_grammar_versions()

Below are option getter utility functions. Option value precedence is:

explicit value (CLI/API arguments) > environment variable > default value
walrus._get_quiet_option(explicit=None)[source]

Get the value for the quiet option.

Parameters

explicit (Optional[bool]) – the value explicitly specified by user, None if not specified

Returns

the value for the quiet option

Return type

bool

Environment Variables

WALRUS_QUIET – the value in environment variable

See also

_default_quiet

walrus._get_concurrency_option(explicit=None)[source]

Get the value for the concurrency option.

Parameters

explicit (Optional[int]) – the value explicitly specified by user, None if not specified

Returns

the value for the concurrency option; None means auto detection at runtime

Return type

Optional[int]

Environment Variables

WALRUS_CONCURRENCY – the value in environment variable

See also

_default_concurrency

walrus._get_do_archive_option(explicit=None)[source]

Get the value for the do_archive option.

Parameters

explicit (Optional[bool]) – the value explicitly specified by user, None if not specified

Returns

the value for the do_archive option

Return type

bool

Environment Variables

WALRUS_DO_ARCHIVE – the value in environment variable

See also

_default_do_archive

walrus._get_archive_path_option(explicit=None)[source]

Get the value for the archive_path option.

Parameters

explicit (Optional[str]) – the value explicitly specified by user, None if not specified

Returns

the value for the archive_path option

Return type

str

Environment Variables

WALRUS_ARCHIVE_PATH – the value in environment variable

See also

_default_archive_path

walrus._get_source_version_option(explicit=None)[source]

Get the value for the source_version option.

Parameters

explicit (Optional[str]) – the value explicitly specified by user, None if not specified

Returns

the value for the source_version option

Return type

str

Environment Variables

WALRUS_SOURCE_VERSION – the value in environment variable

See also

_default_source_version

walrus._get_linesep_option(explicit=None)[source]

Get the value for the linesep option.

Parameters

explicit (Optional[str]) – the value explicitly specified by user, None if not specified

Returns

the value for the linesep option; None means auto detection at runtime

Return type

Optional[Literal[‘\n’, ‘\r\n’, ‘\r’]]

Environment Variables

WALRUS_LINESEP – the value in environment variable

See also

_default_linesep

walrus._get_indentation_option(explicit=None)[source]

Get the value for the indentation option.

Parameters

explicit (Optional[Union[str, int]]) – the value explicitly specified by user, None if not specified

Returns

the value for the indentation option; None means auto detection at runtime

Return type

Optional[str]

Environment Variables

WALRUS_INDENTATION – the value in environment variable

See also

_default_indentation

walrus._get_pep8_option(explicit=None)[source]

Get the value for the pep8 option.

Parameters

explicit (Optional[bool]) – the value explicitly specified by user, None if not specified

Returns

the value for the pep8 option

Return type

bool

Environment Variables

WALRUS_PEP8 – the value in environment variable

See also

_default_pep8

The following variables are used for fallback default values of options.

walrus._default_quiet = False

Default value for the quiet option.

walrus._default_concurrency = None

Default value for the concurrency option.

walrus._default_do_archive = True

Default value for the do_archive option.

walrus._default_archive_path = 'archive'

Default value for the archive_path option.

walrus._default_source_version = '3.10'

Default value for the source_version option.

walrus._default_linesep = None

Default value for the linesep option.

walrus._default_indentation = None

Default value for the indentation option.

walrus._default_pep8 = True

Default value for the pep8 option.

Important

For _default_concurrency, _default_linesep and _default_indentation, None means auto detection during runtime.

CLI Utilities

walrus.get_parser()[source]

Generate CLI parser.

Returns

CLI parser for walrus

Return type

argparse.ArgumentParser

The following variables are used for help messages in the argument parser.

walrus.__cwd__: str

Current working directory returned by os.getcwd().

walrus.__walrus_quiet__: Literal['quiet mode', 'non-quiet mode']

Default value for the --quiet option.

See also

walrus._get_quiet_option()

walrus.__walrus_concurrency__: Union[int, Literal['auto detect']]

Default value for the --concurrency option.

See also

walrus._get_concurrency_option()

walrus.__walrus_do_archive__: Literal['will do archive', 'will not do archive']

Default value for the --no-archive option.

See also

walrus._get_do_archive_option()

walrus.__walrus_archive_path__: str

Default value for the --archive-path option.

See also

walrus._get_archive_path_option()

walrus.__walrus_source_version__: str

Default value for the --source-version option.

See also

walrus._get_source_version_option()

walrus.__walrus_linesep__: Literal['LF', 'CRLF', 'CR', 'auto detect']

Default value for the --linesep option.

See also

walrus._get_linesep_option()

walrus.__walrus_indentation__: str

Default value for the --indentation option.

See also

walrus._get_indentation_option()

walrus.__walrus_pep8__: Literal['will conform to PEP 8', 'will not conform to PEP 8']

Default value for the --no-pep8 option.

See also

walrus._get_pep8_option()