Back-port compiler for Python 3.8 positional-only parameter syntax.
Project description
poseur
Write positional-only parameters in Python 3.8 flavour, and let
poseur
worry about back-port issues :beer:
Since PEP 570, Python introduced positional-only parameters
syntax in version 3.8. For those who wish to use positional-only parameters in their code, poseur
provides an
intelligent, yet imperfect, solution of a backport compiler by removing positional-only parameters syntax whilst
introducing a decorator for runtime checks, which guarantees you to always write positional-only parameters in Python
3.8 flavour then compile for compatibility later.
Installation
Note that
poseur
only supports Python versions since 3.3 🐍
For macOS users, poseur
is now available through Homebrew:
brew tap jarryshaw/tap
brew install poseur
# or simply, a one-liner
brew install jarryshaw/tap/poseur
Simply run the following to install the current version from PyPI:
pip install poseur
Or install the latest version from the git repository:
git clone https://github.com/JarryShaw/poseur.git
cd poseur
pip install -e .
# and to update at any time
git pull
Basic Usage
CLI
It is fairly straightforward to use poseur
:
context in
${...}
changes dynamically according to runtime environment
usage: poseur [options] <python source files and folders...>
Back-port compiler for Python 3.8 positional-only parameters.
positional arguments:
SOURCE python source files and folders to be converted (${CWD})
optional arguments:
-h, --help show this help message and exit
-V, --version show program's version number and exit
-q, --quiet run in quiet mode
archive options:
duplicate original files in case there's any issue
-n, --no-archive do not archive original files
-p PATH, --archive-path PATH
path to archive original files (${CWD}/archive)
convert options:
compatibility configuration for none-unicode files
-c CODING, --encoding CODING
encoding to open source files (${LOCALE_ENCODING})
-v VERSION, --python VERSION
convert against Python version (${LATEST_VERSION})
-s SEP, --linesep SEP
line separator to process source files (${OS_LINESEP})
-d, --dismiss dismiss runtime checks for positional-only parameters
-nl, --no-linting do not lint converted codes
-r VAR, --decorator VAR
name of decorator for runtime checks (${DECORATOR})
-t INDENT, --tabsize INDENT
indentation tab size (4)
poseur
will read then convert all positional-only parameters syntax in every Python
file under this path. In case there might be some problems with the conversion, poseur
will
duplicate all original files it is to modify into archive
directory ahead of the process,
if -n
not set.
Besides, to keep consistency of API to users, poseur
ships with a decorator for
such functions to check positional-only parameters at runtime, if -nl
not set.
Developer Reference
Environments
poseur
currently supports three environment arguments:
POSEUR_QUIET
-- run in quiet mode (same as--quiet
option in CLI)POSEUR_VERSION
-- convert against Python version (same as--python
option in CLI)POSEUR_ENCODING
-- encoding to open source files (same as--encoding
option in CLI)POSEUR_LINESEP
-- line separator to process source files (same as--linesep
option in CLI)POSEUR_DISMISS
-- dismiss runtime checks for positional-only arguments (same as--dismiss
option in CLI)POSEUR_LINTING
-- lint converted codes (same as--linting
option in CLI)POSEUR_DECORATOR
-- name of decorator for runtime checks (same as--decorator
option in CLI)POSEUR_TABSIZE
-- indentation tab size (same as--tabsize
option in CLI)
APIs
poseur
-- wrapper works for conversion
poseur(filename)
Args:
filename
--str
, file to be converted
Envs:
POSEUR_QUIET
-- run in quiet mode (same as--quiet
option in CLI)POSEUR_ENCODING
-- encoding to open source files (same as--encoding
option in CLI)POSEUR_VERSION
-- convert against Python version (same as--python
option in CLI)POSEUR_LINESEP
-- line separator to process source files (same as--linesep
option in CLI)POSEUR_DISMISS
-- dismiss runtime checks for positional-only arguments (same as--dismiss
option in CLI)POSEUR_LINTING
-- lint converted codes (same as--linting
option in CLI)POSEUR_DECORATOR
-- name of decorator for runtime checks (same as--decorator
option in CLI)POSEUR_TABSIZE
-- indentation tab size (same as--tabsize
option in CLI)
Raises:
ConvertError
-- when source code contains syntax errors
convert
-- the main conversion process
convert(string, source='<unknown>')
Args:
string
--str
, context to be convertedsource
--str
, source of the context
Envs:
POSEUR_VERSION
-- convert against Python version (same as--python
option in CLI)POSEUR_LINESEP
-- line separator to process source files (same as--linesep
option in CLI)POSEUR_DISMISS
-- dismiss runtime checks for positional-only arguments (same as--dismiss
option in CLI)POSEUR_LINTING
-- lint converted codes (same as--linting
option in CLI)POSEUR_DECORATOR
-- name of decorator for runtime checks (same as--decorator
option in CLI)POSEUR_TABSIZE
-- indentation tab size (same as--tabsize
option in CLI)
Returns:
str
-- converted string
Raises:
ConvertError
-- when source code contains syntax errors
Internal exceptions
class ConvertError(SyntaxError):
"""Parso syntax error."""
class EnvironError(EnvironmentError):
"""Invalid environment."""
Test
See test.py
.
Contribution
Contributions are very welcome, especially fixing bugs and providing test cases. Note that code must remain valid and reasonable.
See Also
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file poseur-0.4.2.post1.tar.gz
.
File metadata
- Download URL: poseur-0.4.2.post1.tar.gz
- Upload date:
- Size: 12.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/3.7.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0aa16c55a0d6e873a982995dc4a9ffdadc87be7c071ede76f03fb31d8ddd5079 |
|
MD5 | 3fc104aa4828e9cac2d8c0aae122bc70 |
|
BLAKE2b-256 | f88bd02a303f2b26e723e63a86119248cf2ef4cfae15003bf893c8fac107d417 |
File details
Details for the file poseur-0.4.2.post1-py3-none-any.whl
.
File metadata
- Download URL: poseur-0.4.2.post1-py3-none-any.whl
- Upload date:
- Size: 12.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/3.7.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 813d6b179aa0039f2d2e71a6a9e394ad674f4cb8cda8b663770a103cdd6a5b16 |
|
MD5 | 1a133ef55fd0c06d45ea33bd1f55a5f4 |
|
BLAKE2b-256 | 24a8e59bdef518fd74525452bd455d38691d6a7290246a960ed1f7f0079767b7 |