pyprojectx 2.0.0

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

Pyprojectx: All-inclusive Python Projects

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

Full documentation

Introduction

Pyprojectx makes it easy to create all-inclusive Python projects; no need to install any tools upfront, not even Pyprojectx itself!

Tools that are specified within your pyproject.toml file will be installed on demand when invoked from Pyprojectx:

> ./pw black src
Collecting black ...
Successfully installed black-23.9.1 ...

All done! ✨ 🍰 ✨
18 files left unchanged.

Feature highlights

• Reproducible builds by treating tools and utilities as (versioned) dev-dependencies
• No global installs, everything is stored inside your project directory (like npm's node_modules)
• Bootstrap your entire build process with a small wrapper script (like Gradle's gradlew wrapper)
• Configure shortcuts for routine tasks
• Simple configuration in pyproject.toml

Projects can be build/tested/used immediately without explicit installation nor initialization:

git clone https://github.com/pyprojectx/px-demo.git
cd px-demo
./pw build

Installation

One of the key features is that there is no need to install anything explicitly (except a Python 3.8+ interpreter).

cd into your project directory and download the wrapper scripts:

Linux/Mac

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

Windows

Invoke-WebRequest https://github.com/pyprojectx/pyprojectx/releases/latest/download/wrappers.zip -OutFile wrappers.zip; Expand-Archive -Path wrappers.zip -DestinationPath .; Remove-Item -Path wrappers.zip

Project initialization

Initialize a new or existing project with the --init option (on Windows, replace ./pw with pw):

• ./pw --init project: add pyprojectx example sections to an existing or new pyproject.toml in the current directory.
• ./pw --init pdm: initialize a PDM project and add pyprojectx example sections to pyproject.toml.
• ./pw --init poetry: initialize a Poetry project and add pyprojectx example sections to pyproject.toml.

Configuration

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

Each entry has the form tool = "pip-requirements", where pip-requirements adheres to the requirements file format.

Example:

[tool.pyprojectx]
# require a specific poetry version
poetry = "poetry==1.1.13"
# use the latest black
black = "black"
# install flake8 in combination with plugins
flake8 = ["flake8", "flake8-black"]

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

alias = [@tool_key:] command

Example:

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

# flake8-black also contains the black script
black = "@flake8: black"

# simple shell commands
clean = "rm -f .coverage .pytest_cache"

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

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

Aliases can be invoked as is or with extra arguments:

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

Why yet another tool?

• 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, ...
• Using (PDM or Poetry) dev-dependencies to install tools, impacts your production dependencies and can even lead to dependency conflicts
• Different projects often require different versions of the same tool

Example projects

• This project (using PDM)
• px-demo (using PDM)

Development

• Build/test:

git clone https://github.com/pyprojectx/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.

# Linux, Mac
export PYPROJECTX_PACKAGE=path/to/pyprojectx
# windows
set PYPROJECTX_PACKAGE=path/to/pyprojectx