= PPH: Python Project Helper
PPH (Python Project Helper) is a tool designed to help develop Python software projects.
It is intended to be similar to https://python-poetry.org/[Poetry] or https://hatch.pypa.io/[Hatch], in that it helps you do things like create isolated virtual environments for your project. However, it is _unlike_ Poetry or Hatch in that it does not implement its own https://peps.python.org/pep-0517/[PEP 517] build backend. Instead, PPH works with _any_ build backend, using existing tools to build packages using the standard PEP 517 interface.
It is therefore also intended to be similar to https://pipenv.pypa.io/[Pipenv], being primarily a wrapper around existing tools. However, it is _unlike_ Pipenv in that Pipenv is explicitly only designed to support the case of building an "application" and not a "library". Instead, PPH makes no assumptions about the purpose or structure of your project.
The PPH command-line and `pyproject.toml` interfaces are loosely inspired by Hatch, but I make no claim or attempt at direct compatibility.
.Features
[%autowidth]
|===
|Feature |Status
|Automatically create venvs for your project |*Done* but still adding features
|Inspect and extract project metadata |*WIP*
|JSON output for scripting |*WIP*
|Run project scripts |*TODO*
|Build wheels, wrapping https://pypi.org/project/build/[Build] |*TODO*
|Upload to PyPI, wrapping https://pypi.org/project/twine/[Twine] |*TODO*
|CLI documentation & man page |*TODO*
|Stable Python API with documentation + readthedocs hosting |*TODO*
|Test suite |*TODO*
|CI/CD |*TODO*
|Repo packaging |*TODO*
|Generate "locked" requirements files, wrapping https://pypi.org/project/pip-tools/[Pip-tools] |*TODO*
|Better UI/UX: shell completion, separating detailed logs from informational output, progress bars, etc. |*TODO*
|"Matrix" environments and/or add an interface to Tox or Nox |*Speculative*
|Pass extra arguments to underlying tools (Pip, Venv, etc) |*TODO*/*Speculative*
|Support https://pdm.fming.dev/latest/[PDM] as a drop-in replacement for Pip? |*Speculative*
|Support https://virtualenv.pypa.io/[Virtualenv] as a drop-in replacement for Venv? |*Speculative*
|===
I am deeply grateful to the many developers working hard on the Python packaging ecosystem, and I mean no disrespect or negativity towards other projects. I built this tool to meet my own needs, but I hope it will be useful to other people.
Contributions are welcome, but I am doing this in my spare time and I can't guarantee rapid movement on anything.
**WARNING**: PPH is _alpha-quality_ software under active development. The CLI and its output formats are subject to change. Not currently suitable for scripting.
== Installation
https://pypa.github.io/pipx/[Pipx] is recommended for installing PPH for general-purpose use. However it may also be installed using Pip or any other PyPI-compatible package manager (such as PDM).
In the future, I hope to package PPH for package managers such as Homebrew, Macports, Arch Linux, Debian, etc.
.Installation
[,shell]
----
# Install into the current environment:
pip install python-project-helper
# Install into an isolated environment with Pipx:
pipx install python-project-helper
----
== Usage
.Usage outline
[,shell]
----
pph
pph project
pph project inspect
pph env
pph env create {name}
pph env delete {name}
----
Virtual environments are created inside `+$XDG_STATE_HOME/python-project-helper/`. The format inside this directory is subject to change; do not depend on it for now.
== Dev instructions
.Recommended setup
[source,shell#setup-script]
----
#!/bin/sh
set -eux
git clone git@git.sr.ht:~wintershadows/python-project-helper pph
cd pph
sourcehut='git@git.sr.ht:~wintershadows/python-project-helper'
github='git@github.com:gwerbin/python-project-helper.git'
git config user.name '...'
git config user.email '...'
git config user.signingkey '...'
git remote add sourcehut "$sourcehut"
git remote add github "$github"
git remote add all "$sourcehut"
# https://stackoverflow.com/a/14290145/2954547
git remote set-url --add --push all "$sourcehut"
git remote set-url --add --push all "$github"
python -m venv dev.venv
dev.venv/bin/pip install --upgrade pip wheel
dev.venv/bin/pip install \
--requirement requirements-dev.in \
--editable '.[tests]'
source dev.venv/bin/activate
----
.Building
[source,shell#building]
----
dev.venv/bin/python -m build
----
.Publishing
[source,shell#building]
----
# dev.venv/bin/twine upload --sign --identity '...' --repository testpypi dist/*~*+g*
dev.venv/bin/twine upload --repository testpypi dist/*~*+g*
python -m venv --clear test.venv
test.venv/bin/pip install --index-url https://test.pypi.org/simple/ python-project-helper
test.venv/bin/pph project inspect
# dev.venv/bin/twine upload --sign --identity '...' dist/*~*+g*
dev.venv/bin/twine upload dist/*~*+g*
python -m venv --clear test.venv
test.venv/bin/pip install python-project-helper
test.venv/bin/pph project inspect
rm -rf test.venv
----
Metadata
Release files for python-project-helper 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| python-project-helper-0.2.1.tar.gz | 12.0 kB | Without provenance | Details for python-project-helper-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| python_project_helper-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for python_project_helper-0.2.1-py3-none-any.whl |
Total release size: 21.4 kB
Release files / python-project-helper-0.2.1.tar.gz
| Download URL | python-project-helper-0.2.1.tar.gz |
|---|---|
| Size | 12.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
447ced9527378e04ba049b2a2cc7d7d23a70ca34bd03ce7e3fb45880e4e8d5ec
|
|
BLAKE2b-256 checksum How to use checksums |
09a5326d7f6a7fbcafb98ef0ed12b6fa1c8cd0d3de0bfbda83c8a035343d6919
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.11.6
|
Release files / python_project_helper-0.2.1-py3-none-any.whl
| Download URL | python_project_helper-0.2.1-py3-none-any.whl |
|---|---|
| Size | 9.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9174551b15579c6d4574b623bab9cf1d30580658a91112758c5f11620e624956
|
|
BLAKE2b-256 checksum How to use checksums |
aa63e7cb371d61af93360d14752f6a920502e002fc9f5f40fa0457bc78007b99
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.11.6
|
Security for python-project-helper 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.