API Reference

Public Interface

poseur.convert(code, filename=None, *, source_version=None, linesep=None, indentation=None, pep8=None, dismiss=None, decorator=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 (str | None) –

  • linesep (typing_extensions.Literal[ , , ] | None) –

  • indentation (str | int | None) –

  • pep8 (bool | None) –

  • dismiss (bool | None) –

  • decorator (str | None) –

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

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

    in CLI

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

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

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

  • POSEUR_DISMISS – same as the --dismiss-runtime option in CLI

  • POSEUR_DECORATOR – same as the --decorator-name option in CLI

Returns:

converted source code

Return type:

str

Raises:

ValueError – if decorator is not a valid identifier name or starts with double underscore

poseur.poseur(filename, *, source_version=None, linesep=None, indentation=None, pep8=None, dismiss=None, decorator=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 (str | None) –

  • linesep (typing_extensions.Literal[ , , ] | None) –

  • indentation (str | int | None) –

  • pep8 (bool | None) –

  • dismiss (bool | None) –

  • decorator (str | None) –

  • quiet (bool | None) –

  • 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:
  • POSEUR_SOURCE_VERSION – same as the source-version argument and the --source-version option

    in CLI

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

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

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

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

  • POSEUR_DISMISS – same as the --dismiss-runtime option in CLI

  • POSEUR_DECORATOR – same as the --decorator-name option in CLI

Return type:

None

poseur.main(argv=None)[source]

Entry point for poseur.

Parameters:

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

Environment Variables:

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

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

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

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

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

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

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

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

  • POSEUR_DISMISS – same as the --dismiss-runtime option in CLI

  • POSEUR_DECORATOR – same as the --decorator-name option in CLI

Return type:

int

Runtime Decorator

As you may wish to provide runtime positional-only parameter checks for your own code, poseur exposed the decorator function for developers to use by themselves.

poseur.decorator(*poseur)

Positional-only parameters runtime checker.

Parameters:

*poseur – Name list of positional-only parameters.

Raises:

TypeError – If any position-only parameters were passed as keyword parameters.

The decorator function may decorate regular function and/or lambda function to provide runtime checks on the original positional-only parameters.

Conversion Implementation

The main logic of the poseur conversion is to extract all positional-only parameters and add a :term:`decorator` for the function and/or lambda definition to provide runtime checks with the extracted parameters.

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

decorator: str

Name of the decorator function for runtime checks on original positional-only parameters.

dismiss: bool

Flag if integrate runtime checks, i.e. the decorator function, on original positional-only parameters.

Conversion Templates

For general conversion scenarios, the decorator function will be rendered based on the following templates.

poseur.DECORATOR_TEMPLATE: List[str]
['def %(decorator)s(*poseur):',
 '%(indentation)s"""Positional-only parameters runtime checker.',
 '%(indentation)s',
 '%(indentation)s    Args:',
 '%(indentation)s        *poseur: Name list of positional-only parameters.',
 '%(indentation)s',
 '%(indentation)s    Raises:',
 '%(indentation)s        TypeError: If any position-only parameters were passed as',
 '%(indentation)s            keyword parameters.',
 '%(indentation)s',
 '%(indentation)s    The decorator function may decorate regular :term:`function` and/or',
 '%(indentation)s    :term:`lambda` function to provide runtime checks on the original',
 '%(indentation)s    positional-only parameters.',
 '%(indentation)s',
 '%(indentation)s"""',
 '%(indentation)simport functools',
 '%(indentation)sdef caller(func):',
 '%(indentation)s%(indentation)s@functools.wraps(func)',
 '%(indentation)s%(indentation)sdef wrapper(*args, **kwargs):',
 '%(indentation)s%(indentation)s%(indentation)sposeur_args = set(poseur).intersection(kwargs)',
 '%(indentation)s%(indentation)s%(indentation)sif poseur_args:',
 "%(indentation)s%(indentation)s%(indentation)s%(indentation)sraise TypeError('%%s() got some positional-only arguments passed as keyword arguments: %%r' %% (func.__name__, ', '.join(poseur_args)))",
 '%(indentation)s%(indentation)s%(indentation)sreturn func(*args, **kwargs)',
 '%(indentation)s%(indentation)sreturn wrapper',
 '%(indentation)sreturn caller']

Decorator function to provide runtime checks on the original positional-only parameters.

Variables:

Important

Actually, the poseur.decorator() function is rendered and evaluated at runtime using this template.

Conversion Contexts

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

Bases: BaseContext

General conversion context.

Parameters:
Keyword Arguments:

  • clx_ctx (Optional[str]) – class context name

  • indent_level (int) – current indentation level

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

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

  • clx_ctx (str | None) –

classmethod _check_funcdef(node)[source]

Check if function definition contains positional-only parameters.

Parameters:

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

Returns:

if function definition contains positional-only parameters

Return type:

bool

classmethod _check_lambdef(node)[source]

Check if lambda definition contains positional-only parameters.

Parameters:

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

Returns:

if lambda definition contains positional-only parameters

Return type:

bool

_concat()[source]

Concatenate final string.

This method tries to inserted the runtime check decorator function at the very location where starts to contain positional-only parameters, i.e. between the converted code as self._prefix and self._suffix.

The inserted code is rendered from DECORATOR_TEMPLATE. If self._pep8 is True, it will insert the code in compliance with PEP 8.

Return type:

None

_process_async_funcdef(node)[source]

Process async function definition (async_funcdef).

Parameters:

node (parso.python.tree.PythonNode) – async function node

Return type:

None

This method processes an async function node. It will extract the async keyword node (parso.python.tree.Keyword) and the function node (parso.python.tree.Function) then pass on the processing to self._process_funcdef.

_process_async_stmt(node)[source]

Process async statement (async_stmt).

Parameters:

node (parso.python.tree.PythonNode) – async statement node

Return type:

None

This method processes an async statement node. If such statement is an async function, then it will pass on the processing to self._process_funcdef.

_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 Context 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, *, async_ctx=None)[source]

Process function definition (funcdef).

Parameters:
Keyword Arguments:

async_ctx (Optional[parso.python.tree.Keyword]) – async keyword AST node

Return type:

None

_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

_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 position-only parameters. 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 initiate 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.

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

_process_suite_node(node, *, cls_ctx=None)[source]

Process indented suite (suite or others).

Parameters:
Keyword Arguments:

cls_ctx (Optional[str]) – class context name

Return type:

None

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

If node contains positional-only parameters, then it will initiate another Context` instance to perform the conversion process on such node.

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

Check if node has positional-only parameters.

Parameters:

node (parso.tree.NodeOrLeaf) – parso AST

Returns:

if node has positional-only parameters

Return type:

bool

classmethod has_poseur(node)

Check if node has positional-only parameters.

Parameters:

node (parso.tree.NodeOrLeaf) – parso AST

Returns:

if node has positional-only parameters

Return type:

bool

normalizer(name)[source]

Variable name normalizer.

If self._cls_ctx is None, the methold will simply class normalize() on the variable name; otherwise, it will call mangle() on the variable name.

Parameters:

name (str) – variable name

Returns:

normalized variable name

Return type:

str

_abc_impl = <_abc_data object>
_cls_ctx: Optional[str]

Class context name. This is rather useful as we might need to mangle and/or normalize variable names in certain scenario.

Type:

Optional[str]

_decorator: str

Decorator name.

Type:

str

_dismiss: bool

Dismiss runtime checks for positional-only parameters.

Type:

bool

property decorator: str

Name of the poseur decorator.

Return type:

str

pattern_funcdef = re.compile('^\\s*(async\\s+)?def\\s', re.ASCII)

Pattern to find the function definition line.

Type:

re.Pattern

class poseur.StringContext(node, config, *, clx_ctx=None, indent_level=0, raw=True)[source]

Bases: Context

String (f-string) conversion context.

This class is mainly used for converting formatted strings.

Parameters:
Keyword Arguments:

  • clx_ctx (Optional[str]) – class context name

  • indent_level (int) – current indentation level

  • 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

  • clx_ctx (str | None) –

_abc_impl = <_abc_data object>
_buffer: str

Final converted result.

_cls_ctx: Optional[str]

Class context name. This is rather useful as we might need to mangle and/or normalize variable names in certain scenario.

Type:

Optional[str]

_decorator: str

Decorator name.

Type:

str

_dismiss: bool

Dismiss runtime checks for positional-only parameters.

Type:

bool

_indent_level: Final[int]

Current indentation level.

_indentation: Final[str]  # type: ignore[attr-defined]

Indentation sequence.

_linesep: Final[Linesep]  # type: ignore[attr-defined]

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]  # type: ignore[attr-defined]

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.

_suffix: str

Code after insertion point.

_uuid_gen: Final[UUID4Generator]

UUID generator.

config: Final[Config]

Internal configurations.

Internal Auxiliaries

Options & Defaults

poseur.POSEUR_SOURCE_VERSIONS = ['3.8', '3.9']

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

POSEUR_QUIET – the value in environment variable

See also

_default_quiet

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

POSEUR_CONCURRENCY – the value in environment variable

See also

_default_concurrency

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

POSEUR_DO_ARCHIVE – the value in environment variable

See also

_default_do_archive

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

POSEUR_ARCHIVE_PATH – the value in environment variable

See also

_default_archive_path

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

POSEUR_SOURCE_VERSION – the value in environment variable

See also

_default_source_version

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

POSEUR_LINESEP – the value in environment variable

See also

_default_linesep

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

POSEUR_INDENTATION – the value in environment variable

See also

_default_indentation

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

POSEUR_PEP8 – the value in environment variable

See also

_default_pep8

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

poseur._default_quiet = False

Default value for the quiet option.

poseur._default_concurrency = None

Default value for the concurrency option.

poseur._default_do_archive = True

Default value for the do_archive option.

poseur._default_archive_path = 'archive'

Default value for the archive_path option.

poseur._default_source_version = '3.9'

Default value for the source_version option.

poseur._default_linesep = None

Default value for the linesep option.

poseur._default_indentation = None

Default value for the indentation option.

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

poseur.get_parser()[source]

Generate CLI parser.

Returns:

CLI parser for poseur

Return type:

argparse.ArgumentParser

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

poseur.__cwd__: str

Current working directory returned by os.getcwd().

poseur.__poseur_quiet__: Literal[\'quiet mode\', \'non-quiet mode\']

Default value for the --quiet option.

See also

poseur._get_quiet_option()

poseur.__poseur_concurrency__: Union[int, Literal[\'auto detect\']]

Default value for the --concurrency option.

See also

poseur._get_concurrency_option()

poseur.__poseur_do_archive__: Literal[\'will do archive\', \'will not do archive\']

Default value for the --no-archive option.

See also

poseur._get_do_archive_option()

poseur.__poseur_archive_path__: str

Default value for the --archive-path option.

See also

poseur._get_archive_path_option()

poseur.__poseur_source_version__: str

Default value for the --source-version option.

See also

poseur._get_source_version_option()

poseur.__poseur_linesep__: Literal[\'LF\', \'CRLF\', \'CR\', \'auto detect\']

Default value for the --linesep option.

See also

poseur._get_linesep_option()

poseur.__poseur_indentation__: str

Default value for the --indentation option.

See also

poseur._get_indentation_option()

poseur.__poseur_pep8__: Literal[\'will conform to PEP 8\', \'will not conform to PEP 8\']

Default value for the --no-pep8 option.

See also

poseur._get_pep8_option()