Skip to content

Usage#

CLI#

usage: pyprojectx [-h] [--version] [--toml TOML] [--install-dir INSTALL_DIR]
                  [--force-install] [--verbose] [--quiet] [--info] [--init]
                  ...

Execute commands or aliases defined in the [tool.pyprojectx] section of
pyproject.toml. Use the -i or --info option to see available tools and
aliases.

positional arguments:
  command               The command/alias with optional arguments to execute.

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --toml TOML, -t TOML  The toml config file. Defaults to 'pyproject.toml' in
                        the same directory as the pw script.
  --install-dir INSTALL_DIR
                        The directory where all tools (including pyprojectx)
                        are installed; defaults to the PYPROJECTX_INSTALL_DIR
                        environment value if set, else '.pyprojectx' in the
                        same directory as the invoked pw script
  --force-install, -f   Force clean installation of the virtual environment
                        used to run cmd, if any
  --verbose, -v         Give more output. This option is additive and can be
                        used up to 2 times.
  --quiet, -q           Suppress output
  --info, -i            Show the configuration details of a command in stead
                        of running it. If the command is not configured as
                        tool or alias, a list with all available tools and
                        aliases is shown.
  --init                Create or prepare a pyproject.toml and pyprojectx
                        wrapper scripts. Run with '--init help' to show
                        available init options

Initialize a new or existing project#

Pyprojectx can create or update a pyproject.toml file for either a plain, a PDM or a Poetry project.

Cd into your existing project directory (or create a new empty directory), download the wrapper scripts, and run the init command.

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

Plain Python project#

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

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
.\pw --init project

Now you can use the pw or px script to show available tools and commands: ./pw -i.

PDM project#

Start the interactive PDM initializer:

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

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
.\pw --init pdm

Any extra arguments are passed to PDM's init command, f.e. ./pw --init pdm --non-interactive.

Now you can run any PDM command with the pw or px script, f.e. ./pw pdm install

Poetry project#

Start the interactive poetry initializer:

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

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
.\pw --init poetry

Any extra arguments are passed to Poetry's init command, f.e. ./pw --init poetry --no-interaction.

Now you can run any Poetry command with the pw or px script, f.e. ./pw poetry install

In-project virtual environment

--init poetry will also copy a poetry.toml to your project directory: 

[virtualenvs]
in-project = true
This makes Poetry create a .venv in your project directory instead of somewhere in your home directory. It makes it easier to locate files and to keep your system clean when removing the project.

Install the global px script#

Pyprojectx provides a small px script that delegates everything to the pw wrapper script. The pw script is searched in the current working directory and its parents.

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

To install:

./pw --init global

.\pw --init global

Global tools#

Besides the px script, pw --init global also copies other files: * pxg script in ~/.pyprojectx * pw script and example pyproject.toml in ~/.pyprojectx/global

pxg can be uses as a lightweight pipx to install tools globally.

Example usage: pyproject.toml contains by default httpie so you can make http requests: 

pxg http POST pie.dev/post hello=world

Uninstalling all global tools is just a matter of rm -rf ~/.pyprojectx/global/.pyprojectx