python-walrus 0.1.3

Back-port compiler for Python 3.8 assignment expressions.

walrus

Write assignment expressions in Python 3.8 flavour, and let walrus worry about back-port issues :beer:

  Since PEP 572, Python introduced assignment expressions syntax in version 3.8. For those who wish to use assignment expressions in their code, walrus provides an intelligent, yet imperfect, solution of a backport compiler by replacing assignment expressions syntax with old-fashioned assignment-then-conditional syntax, which guarantees you to always write assignment expressions in Python 3.8 flavour then compile for compatibility later.

Installation

Note that walrus only supports Python versions since 3.3 🐍

  For macOS users, walrus is now available through Homebrew:

brew tap jarryshaw/tap
brew install walrus
# or simply, a one-liner
brew install jarryshaw/tap/walrus

  Simply run the following to install the current version from PyPI:

pip install python-walrus

  Or install the latest version from the git repository:

git clone https://github.com/JarryShaw/walrus.git
cd walrus
pip install -e .
# and to update at any time
git pull

Basic Usage

CLI

  It is fairly straightforward to use walrus:

context in ${...} changes dynamically according to runtime environment

usage: walrus [options] <python source files and folders...>

Back-port compiler for Python 3.8 assignment expressions.

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

  -na, --no-archive     do not archive original files
  -p PATH, --archive-path PATH
                        path to archive original files (${CWD}/archive)

convert options:
  compatibility configuration for non-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})
  -nl, --no-linting     do not lint converted codes
  -t INDENT, --tabsize INDENT
                        indentation tab size (4)

  walrus will read then convert all assignment expressions syntax in every Python file under this path. In case there might be some problems with the conversion, walrus 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, walrus ships with a decorator for such functions to check assignment expressions at runtime, if -nl not set.

Developer Reference

Environments

walrus currently supports three environment arguments:

• WALRUS_QUIET -- run in quiet mode (same as --quiet option in CLI)
• WALRUS_VERSION -- convert against Python version (same as --python option in CLI)
• WALRUS_ENCODING -- encoding to open source files (same as --encoding option in CLI)
• WALRUS_LINESEP -- line separator to process source files (same as --linesep option in CLI)
• WALRUS_LINTING -- lint converted codes (same as --linting option in CLI)
• WALRUS_TABSIZE -- indentation tab size (same as --tabsize option in CLI)

APIs

walrus -- wrapper works for conversion

walrus(filename)

Args:

• filename -- str, file to be converted

Envs:

• WALRUS_QUIET -- run in quiet mode (same as --quiet option in CLI)
• WALRUS_ENCODING -- encoding to open source files (same as --encoding option in CLI)
• WALRUS_VERSION-- convert against Python version (same as --python option in CLI)
• WALRUS_LINESEP -- line separator to process source files (same as --linesep option in CLI)
• WALRUS_LINTING -- lint converted codes (same as --linting option in CLI)
• WALRUS_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:

• WALRUS_VERSION -- convert against Python version (same as --python option in CLI)
• WALRUS_LINESEP -- line separator to process source files (same as --linesep option in CLI)
• WALRUS_LINTING -- lint converted codes (same as --linting option in CLI)
• WALRUS_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 ContextError(RuntimeError):
    """Missing conversion context."""

class EnvironError(EnvironmentError):
    """Invalid environment."""

Test

  See tests folder.

Known issues

  Since walrus is currently based on parso project, it had encountered several compatibility and parsing issues.

• Parsing f-strings with := formatter produces incorrect SyntaxError (#89)

• Parsing invalid use cases of assignment expressions do not raise SyntaxError (#89)

Contribution

  Contributions are very welcome, especially fixing bugs and providing test cases. Note that code must remain valid and reasonable.

See Also

• babel
• f2format
• poseur
• vermin