Metadata-Version: 2.1
Name: python-project-helper
Version: 0.2.1
Author-email: Gregory Werbin <outthere@me.gregwerbin.com>
License: BSD 3-Clause License
        
        Copyright (c) 2023, Gregory Werbin
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Changelog, https://github.com/gwerbin/python-project-helper/blob/main/CHANGELOG.adoc
Project-URL: Source code (Github), https://github.com/gwerbin/python-project-helper
Project-URL: Source code (Sourcehut), https://git.sr.ht/~wintershadows/python-project-helper
Classifier: Programming Language :: Python
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.8
Description-Content-Type: text/plain
License-File: LICENSE
Requires-Dist: build
Provides-Extra: tests
Requires-Dist: pytest~=7.0; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Requires-Dist: pytest-mock; extra == "tests"
Requires-Dist: coverage; extra == "tests"
Requires-Dist: hypothesis; extra == "tests"
Requires-Dist: mypy~=1.0; extra == "tests"

= 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
----
