API Reference

Public Interface

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

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

Internal Auxiliaries

Options & Defaults

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

explicit value (CLI/API arguments) > environment variable > default value

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

Important

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

CLI Utilities

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