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: str | None

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

source_version: str | None

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: 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

Return type:

None

This method processes arguments from function argument list.

_process_classdef(node)[source]

Process class definition (classdef).

Parameters:

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

Return type:

None

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

_process_for_stmt(node)[source]

Process for statement (for_stmt).

Parameters:

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

Return type:

None

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

_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

Return type:

None

This method converts the function suite with _process_suite_node().

_process_global_stmt(node)[source]

Process function definition (global_stmt).

Parameters:

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

Return type:

None

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

_process_if_stmt(node)[source]

Process if statement (if_stmt).

Parameters:

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

Return type:

None

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

_process_lambdef(node)[source]

Process lambda definition (lambdef).

Parameters:

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

Return type:

None

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.

_process_namedexpr_test(node)[source]

Process assignment expression (namedexpr_test).

Parameters:

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

Return type:

None

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.

_process_string_context(node)[source]

Process string contexts (stringliteral).

Parameters:

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

Return type:

None

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.

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

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

_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

Return type:

None

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.

_process_try_stmt(node)[source]

Process try statement (try_stmt).

Parameters:

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

Return type:

None

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

_process_while_stmt(node)[source]

Process while statement (while_stmt).

Parameters:

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

Return type:

None

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

_process_with_stmt(node)[source]

Process with statement (with_stmt).

Parameters:

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

Return type:

None

This method processes the indented suite under the with statement.

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

Variable names in global statements.

Type:

List[str]

_func

Converted wrapper functions described as FunctionEntry.

Type:

List[FunctionEntry]

_lamb

Converted lambda expressions described as LambdaEntry.

Type:

List[LambdaEntry]

_scope_keyword

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

_vars

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: 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

Final converted result.

_context

Variable names in global statements.

Type:

List[str]

_func

Converted wrapper functions described as FunctionEntry.

Type:

List[FunctionEntry]

_indent_level

Current indentation level.

_indentation

Indentation sequence.

_lamb

Converted lambda expressions described as LambdaEntry.

Type:

List[LambdaEntry]

_linesep

Line seperator.

Type:

Final[Linesep]

_node_before_expr

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

_pep8

PEP 8 compliant conversion flag.

_prefix

Code before insertion point.

_prefix_or_suffix

Flag to indicate whether buffer is now self._prefix.

_root

Root node given by the node parameter.

_scope_keyword

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

_suffix

Code after insertion point.

_uuid_gen

UUID generator.

_vars

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

Type:

List[str]

config

Internal configurations.

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

Bases: 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

Final converted result.

_context

Variable names in global statements.

Type:

List[str]

_func

Converted wrapper functions described as FunctionEntry.

Type:

List[FunctionEntry]

_indent_level

Current indentation level.

_indentation

Indentation sequence.

_lamb

Converted lambda expressions described as LambdaEntry.

Type:

List[LambdaEntry]

_linesep

Line seperator.

Type:

Final[Linesep]

_node_before_expr

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

_pep8

PEP 8 compliant conversion flag.

_prefix

Code before insertion point.

_prefix_or_suffix

Flag to indicate whether buffer is now self._prefix.

_root

Root node given by the node parameter.

_scope_keyword

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

_suffix

Code after insertion point.

_uuid_gen

UUID generator.

_vars

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

Type:

List[str]

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: 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

Return type:

None

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.

_process_expr_stmt(node)[source]

Process variable name (expr_stmt).

Parameters:

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

Return type:

None

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.

_process_global_stmt(node)[source]

Process function definition (global_stmt).

Parameters:

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

Return type:

None

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

_process_namedexpr_test(node)[source]

Process assignment expression (namedexpr_test).

Parameters:

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

Return type:

None

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.

_process_nonlocal_stmt(node)[source]

Process function definition (nonlocal_stmt).

Parameters:

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

Return type:

None

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

_process_string_context(node)[source]

Process string contexts (stringliteral).

Parameters:

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

Return type:

None

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.

_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

Return type:

None

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.

_abc_impl = <_abc_data object>
_buffer

Final converted result.

_cls_ctx

Class context name.

Type:

str

_cls_raw

Raw context processing flag.

Type:

bool

_cls_var

Mapping for assignment variable and its UUID.

Type:

Dict[str, str]

_context

Variable names in global statements.

Type:

List[str]

_ext_func

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

Type:

List[FunctionEntry]

_ext_vars

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

Converted wrapper functions described as FunctionEntry.

Type:

List[FunctionEntry]

_indent_level

Current indentation level.

_indentation

Indentation sequence.

_lamb

Converted lambda expressions described as LambdaEntry.

Type:

List[LambdaEntry]

_linesep

Line seperator.

Type:

Final[Linesep]

_node_before_expr

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

_pep8

PEP 8 compliant conversion flag.

_prefix

Code before insertion point.

_prefix_or_suffix

Flag to indicate whether buffer is now self._prefix.

_root

Root node given by the node parameter.

_scope_keyword

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

_suffix

Code after insertion point.

_uuid_gen

UUID generator.

_vars

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

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: 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

Final converted result.

_cls_ctx

Class context name.

Type:

str

_cls_raw

Raw context processing flag.

Type:

bool

_cls_var

Mapping for assignment variable and its UUID.

Type:

Dict[str, str]

_context

Variable names in global statements.

Type:

List[str]

_ext_func

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

Type:

List[FunctionEntry]

_ext_vars

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

Converted wrapper functions described as FunctionEntry.

Type:

List[FunctionEntry]

_indent_level

Current indentation level.

_indentation

Indentation sequence.

_lamb

Converted lambda expressions described as LambdaEntry.

Type:

List[LambdaEntry]

_linesep

Line seperator.

Type:

Final[Linesep]

_node_before_expr

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

_pep8

PEP 8 compliant conversion flag.

_prefix

Code before insertion point.

_prefix_or_suffix

Flag to indicate whether buffer is now self._prefix.

_root

Root node given by the node parameter.

_scope_keyword

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

_suffix

Code after insertion point.

_uuid_gen

UUID generator.

_vars

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

Type:

List[str]

config

Internal configurations.

Internal Auxiliaries

Options & Defaults

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

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.12'

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()