Python wraptor

This project is deprecated in favor of pyprojectx

CLI wrapper for automatic installation of Python tools:

• Make it be a breeze for others to get started with your project or tutorial
• Get reproducible builds by always using the correct versions of your build tools
• Plays well with build tools like Poetry

Installation

No tools to install (besides Python 3) 😍

Copy pw and pw.bat to your project's root directory and add it under version control.

python3 (or python on Windows) >= 3.6 and pip3 must be available on your path.

Configuration

Add the tool.wraptor section inside pyproject.toml in your project's root directory.

Each entry has the form

tool = "pip-install-arguments"

Example:

[tool.wraptor]
# require a specific poetry version
poetry = "poetry==1.1.11"
# use the latest black
black = "black"
# install flake8 in combination with plugins
flake8 = """
flake8
flake8-bandit
pep8-naming
flake8-isort
flake8-pytest-style"""

The tool.wraptor.alias section can contain optional commandline aliases in the form

alias = [tool_key:] command

Example:

[tool.wraptor.alias]
# convenience shortcuts
run = "poetry run"
test = "poetry run pytest"

# tell pw that the bandit binary is installed as part of flake8
bandit = "flake8: bandit my_package tests -r"

# simple shell commands (string literals and variable substitutions can possibly expand to invalid shell commands)
clean = "rm -f .coverage && rm -rf .pytest_cache"

# when combining multiple wraptor aliases, prefix them with ./pw
# this works on all OS and in sub folders because ./pw will be replaced with the correct script
check-pylint = "./pw poetry run pylint && ./pw tests"

# push to git if all checks pass
release = "&: check push"

Aliases can be invoked as is or with extra arguments:

./pw bandit

./pw poetry run my-script
# same as above, but using the run alias
./pw run my-script

Isolation

Each tool gets installed in an isolated virtual environment.

These are all located in the user's platform-specific home directory under .python-wraptor/venvs.

This location can be modified by setting the PYTHON_WRAPTOR_VENVS_DIR environment variable (f.e. on your CI/CD server).

Usage

Add path\to\pw in front of the usual command line.

Examples:

./pw poetry add -D pytest
cd src
../pw black *.py

... or on Windows:

pw poetry add -D pytest
cd src
..\pw black *.py

pw specific options:

# upgrade a tool with pip (has no effect if the tool is specified with a fixed version in pyproject.toml)
./pw --pw-upgrade black

# clear and re-install the virtual environment for a tool
./pw --pw-clear poetry

# clear the complete wraptor cache
./pw --pw-clear-all poetry

Bonus

If you want to avoid typing ./pw (or ../pw when in a subdirectory), you can copy the px script to a location on your PATH (f.e. /usr/local/bin, or create a symlink with ln -fs $(pwd)/px /usr/local/bin/px).

From then on, you can replace pw with px and invoke it from any (sub)directory containing the pw script.

cd my-pw-project
px test
cd tests
px test sometest.py

Uninstall / cleaning up

To clean up everything that was installed via the Python Wraptor, just delete the .python-wraptor directory in your home directory or run ./pw --pw-clear-all

Why yet another tool when we already have pipx etc.?

• As Python noob I had hard times setting up a project and building existing projects
• There is always someone in the team having issues with his setup, either with a specific tool, with Homebrew, pipx, ...
• Adding tools as dev dependencies leads to dependency conflicts
• Different projects often require different versions of the same tool

Best practices

• Separate your tools from your project dependencies
• Use a build tool with decent dependency management that locks all dependencies, f.e. Poetry or PDM
• Pin down the version of your build tool to prevent the "project doesn't build anymore" syndrome. Eventually a new version of the build tool with breaking changes will be released.
• There is a category of tools that you don't want to version: tools that interact with changing environments. You probably want to update those on a regular basis by running ./pw --upgrade my-evolving-tool.

Examples

• This project (using Poetry)
• Wraptor examples
• Facebook's PathPicker fork (using Poetry)

TODO

• px script for Windows
• init script that copies the pw scripts and initializes pyproject.toml + publish to PyPi