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.7+ 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
isort = "isort"
# 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

KotlinIsland / pyprojectx