Skip to content

Pyprojectx

ALL-INCLUSIVE PYTHON PROJECTS

Introduction#

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

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
# for the poetry version: git checkout poetry
cd px-demo
./pw build

git clone https://github.com/pyprojectx/px-demo.git
# for the poetry version: git checkout poetry
cd px-demo
pw build

Clone and 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:

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

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

With the wrapper scripts in place, you can start adding tools:

# initialize a PDM project
./pw --add pdm,ruff,pre-commit,px-utils
./pw pdm init
# omit './pw' by activating the tool context
source .pyprojectx/main/activate
pdm --version
ruff check src
# initialize a poetry project
./pw --add poetry
./pw poetry init

# initialize a PDM project
pw --add pdm,ruff,pre-commit,px-utils
pw pdm init
# omit 'pw' by activating the tool context
source .pyprojectx/main/activate
pdm --version
ruff check src
# initialize a poetry project
pw --add poetry
pw poetry init

Tip: Add the wrapper scripts to version control

When using Git: 

git add pw pw.bat
git update-index --chmod=+x pw
echo .pyprojectx/ >> .gitignore

Tip: Install the px utility script

You can copy a small script to .pyprojectx in your home directory. When added to your PATH, you can replace ./pw with the shorter px. This also works from subdirectories: ../../pw can also be replaced with px

./pw --install-px

pw --install-px

If you don't want to prefix every command with px or ./pw, you can activate a tool context.