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

decorator – decorator function name as defined in Config.decorator
indentation – indentation sequence as defined in Config.indentation

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

node (parso.tree.NodeOrLeaf) – parso AST
config (Config) – conversion configurations
clx_ctx (Optional[str]) –
indent_level (int) –
raw (bool) –

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

node (parso.python.tree.Function) – function node
async_ctx (Optional[parso.python.tree.Keyword]) –

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

node (parso.tree.NodeOrLeaf) – suite node
cls_ctx (Optional[str]) –

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

node (parso.tree.NodeOrLeaf) –
cls_ctx (Optional[str]) –

_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

node (parso.python.tree.PythonNode) – parso AST
config (Config) – conversion configurations
clx_ctx (Optional[str]) –
indent_level (int) –
raw (Literal[True]) –

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.

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

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

API Reference¶

Public Interface¶

Runtime Decorator¶

Conversion Implementation¶

Data Structures¶

Conversion Templates¶

Conversion Contexts¶

Internal Auxiliaries¶

Options & Defaults¶

CLI Utilities¶

poseur

Navigation

Related Topics