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
- 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 thesource_versionargument and the--source-versionoptionin CLI
POSEUR_LINESEP– same as the linesep argument and the--linesepoption in CLIPOSEUR_INDENTATION– same as theindentationargument and the--indentationoption in CLIPOSEUR_PEP8– same as thepep8argument and the--no-pep8option in CLI (logical negation)POSEUR_DISMISS– same as the--dismiss-runtimeoption in CLIPOSEUR_DECORATOR– same as the--decorator-nameoption in CLI
- Returns
converted source code
- Return type
- Raises
ValueError – if
decoratoris 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
- 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 thesource-versionargument and the--source-versionoptionin CLI
POSEUR_LINESEP– same as thelinesepargument and the--linesepoption in CLIPOSEUR_INDENTATION– same as theindentationargument and the--indentationoption in CLIPOSEUR_PEP8– same as thepep8argument and the--no-pep8option in CLI (logical negation)POSEUR_QUIET– same as thequietargument and the--quietoption in CLIPOSEUR_DISMISS– same as the--dismiss-runtimeoption in CLIPOSEUR_DECORATOR– same as the--decorator-nameoption in CLI
- Return type
- poseur.main(argv=None)[source]¶
Entry point for poseur.
- Parameters
argv (Optional[List[str]]) – CLI arguments
- Environment Variables
POSEUR_QUIET– same as the--quietoption in CLIPOSEUR_CONCURRENCY– same as the--concurrencyoption in CLIPOSEUR_DO_ARCHIVE– same as the--no-archiveoption in CLI (logical negation)POSEUR_ARCHIVE_PATH– same as the--archive-pathoption in CLIPOSEUR_SOURCE_VERSION– same as the--source-versionoption in CLIPOSEUR_LINESEP– same as the--linesepoption in CLIPOSEUR_INDENTATION– same as the--indentationoption in CLIPOSEUR_PEP8– same as the--no-pep8option in CLI (logical negation)POSEUR_DISMISS– same as the--dismiss-runtimeoption in CLIPOSEUR_DECORATOR– same as the--decorator-nameoption in CLI
- Return type
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.
- linesep: Literal['\n', '\r\n', '\r']¶
Line separator.
- source_version: Optional[str]¶
Parse the code as this Python version (uses the latest version by default).
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.decoratorindentation – 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.BaseContextGeneral conversion context.
- Parameters
node (parso.tree.NodeOrLeaf) – parso AST
config (Config) – conversion configurations
clx_ctx (Optional[str]) –
indent_level (int) –
raw (bool) –
- Keyword Arguments
Important
rawshould beTrueonly if thenodeis in the clause of another context, where the converted wrapper functions should be inserted.For the
Contextclass ofposeurmodule, it will process nodes with following methods: