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 (Optional[str]) –

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

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

  • pep8 (Optional[bool]) –

  • dismiss (Optional[bool]) –

  • decorator (Optional[str]) –

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 (Optional[str]) –

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

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

  • pep8 (Optional[bool]) –

  • dismiss (Optional[bool]) –

  • decorator (Optional[str]) –

  • quiet (Optional[bool]) –

  • dry_run (bool) –

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

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

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

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

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

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

Environment Variables
  • 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: 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).

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: bpc_utils.context.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 (Optional[str]) –

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.

Return type

None

Parameters

node (parso.python.tree.PythonNode) –

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

Return type

None

Parameters

node (parso.python.tree.PythonNode) –

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

Return type

None

Parameters

node (parso.python.tree.Class) –

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

Return type

None

Parameters

node (parso.python.tree.ForStmt) –

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

Return type

None

Parameters

node (parso.python.tree.IfStmt) –

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

Return type

None

Parameters

node (parso.python.tree.PythonNode) –

_process_strings(node)[source]

Process concatenable strings (stringliteral).

Parameters

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

Return type

None

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

Return type

None

Parameters

node (parso.python.tree.PythonNode) –

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

Return type

None

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

Return type

None

Parameters

node (parso.python.tree.TryStmt) –

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

Return type

None

Parameters

node (parso.python.tree.WhileStmt) –

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

Return type

None

Parameters

node (parso.python.tree.WithStmt) –

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: poseur.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 (Optional[str]) –

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

Indentation sequence.

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

_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', '3.10']

Get supported source 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

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

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

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

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

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

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.

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

Default value for the --concurrency option.

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

Default value for the --no-archive option.

poseur.__poseur_archive_path__: str

Default value for the --archive-path option.

poseur.__poseur_source_version__: str

Default value for the --source-version option.

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

Default value for the --linesep option.

poseur.__poseur_indentation__: str

Default value for the --indentation option.

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

Default value for the --no-pep8 option.