pyprojectx 0.8.3

Execute scripts from pyproject.toml, installing tools on-the-fly

pyprojectx

Execute scripts from pyproject.toml, installing tools on-the-fly

Getting started with a Python project should be a one-liner:

git clone https://github.com/houbie/pyprojectx.git && cd pyprojectx && ./pw build

Pyprojectx provides a 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 and PDM

Pyprojectx brings npm run to Python with:

• less keystrokes
• isolated dependencies: tools are not required to be development dependencies

Installation

Copy the wrapper scripts into the root of your project.

Python >= 3.7 must be available on your PATH.

• osx / linux :

curl -LO https://github.com/houbie/pyprojectx/releases/latest/download/wrappers.zip && unzip wrappers.zip && rm -f wrappers.zip

• windows: unpack the wrappers zip

NOTE On windows you need to explicitly mark the osx/linux script as executable before adding it to version control. When using git:

git add pw pw.bat
git update-index --chmod=+x pw

Configuration

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

Each entry has the form

tool = "pip-install-arguments"

Example:

[tool.pyprojectx]
# 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.pyprojectx.aliases section can contain optional commandline aliases in the form

alias = [@tool_key:] command

Example:

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

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

# simple shell commands (watch out for variable substitutions and string literals containing whitespace or special characters )
clean = "rm -f .coverage && rm -rf .pytest_cache"

# when running an alias from within another alias, prefix it with `pw@`
check = "pw@pylint && pw@test"

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 in the .pyprojectx directory of your project (where pyproject.toml is located).

Usage

Instead of calling the commandline of a tool directly, prefix it with path\to\pw.

Examples:

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

... or on Windows:

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

Check pw specific options with pw --help

Bonus

If you want to avoid typing ./pw (or ../pw when in a subdirectory), you can install the px script in your home directory with ./pw --init global (or pw --init global on Windows) and add ~/.pyprojectx to your PATH.

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

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

Uninstall / cleaning up

• Delete the .pyprojectx directory in your project's root.
• Delete the global .pyprojectx directory in your home directory.

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 often 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)
• Projects that still use the python-wraptor scripts and need to be migrated to pyprojectx
  • Pyprojectx examples
  • Facebook's PathPicker fork (using Poetry)

Development

• Build/test:

git clone [e-mail]:houbie/pyprojectx.git
cd pyprojectx
./pw build

• Set the path to pyprojectx in the PYPROJECTX_PACKAGE environment variable to use your local pyprojectx copy in another project.

# *nix
export PYPROJECTX_PACKAGE=path/to/pyprojectx
# windows
set PYPROJECTX_PACKAGE=path/to/pyprojectx