Skip to main content

Back-port compiler for Python 3.8 positional-only parameter syntax.

Project description

poseur

PyPI - Downloads PyPI - Version PyPI - Format PyPI - Python Version

Travis CI - Status Codecov - Coverage License LICENSE

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 converted
  • source -- 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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

poseur-0.4.2.post1.tar.gz (12.2 kB view details)

Uploaded Source

Built Distribution

poseur-0.4.2.post1-py3-none-any.whl (12.2 kB view details)

Uploaded Python 3

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

Hashes for poseur-0.4.2.post1.tar.gz
Algorithm Hash digest
SHA256 0aa16c55a0d6e873a982995dc4a9ffdadc87be7c071ede76f03fb31d8ddd5079
MD5 3fc104aa4828e9cac2d8c0aae122bc70
BLAKE2b-256 f88bd02a303f2b26e723e63a86119248cf2ef4cfae15003bf893c8fac107d417

See more details on using hashes here.

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

Hashes for poseur-0.4.2.post1-py3-none-any.whl
Algorithm Hash digest
SHA256 813d6b179aa0039f2d2e71a6a9e394ad674f4cb8cda8b663770a103cdd6a5b16
MD5 1a133ef55fd0c06d45ea33bd1f55a5f4
BLAKE2b-256 24a8e59bdef518fd74525452bd455d38691d6a7290246a960ed1f7f0079767b7

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page