Execute scripts from pyproject.toml, installing tools on-the-fly
Project description
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 git@github.com: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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pyprojectx-0.8.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 63573181ada14fb9008283389ac250a459401bdf3dffa928f31a06a1ea864869 |
|
MD5 | db360b592163b6cef30fa41a88ec2bd1 |
|
BLAKE2b-256 | 38f346e0d98695f3496057d619427f614d60ec51b0a4a77597cb1e9bf4c57221 |