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: