Preliminaries: Once and for All#

2 min read

1. Install UV #

UV will handle all the issues related to package management (dependencies, versioning, deployment) for you.

To install it, please follow the instructions from https://docs.astral.sh/uv/getting-started/installation/

Please install the standalone version

One of the benefit of UV is that it does not need to be attached to a specific Python distribution. It can use existing distributions if they are compatible with the requirements of a project, or it can ship its own versions. This means:

Having Python installed is not required.
If you break/update your global Python distribution, UV won’t be affected.
You can easily and transparently upgrade your Python version in your UV projects.

Check that it works:

$ uv --version

2. Install Package Helper 3#

In a terminal (Anaconda Prompt, Bash, Windows Powershell, etc):

$ uv tool install package-helper-3

This will install PH3 as a uv tool. Check that the installation is correct:

$ ph3 --help

Note

If you have a python distribution with pip on your system, you can also install with

$ pip install package-helper-3

However, this will tie PH3 to your python distribution.

3. Create Accounts on the Websites#

Ensure that you have accounts (preferably with the same login) on:

GitHub,
PyPI.
You will need access to Codecov, but you can login with your GitHub account.
Optionally, create an account on Software Heritage to archive your code for long-term preservation (also works without an account for public repos).

Note

In previous PH3 versions, you were asked to get an API token from PyPI. This is not required anymore, as PyPI now proposes a Trusted Publishers approach.

4. Install Git#

Git will be used to maintain your projects branches locally and remotely.

Install git: https://git-scm.com/downloads. You may need to restart your computer.

Test it:

$ git --version

Ensure your version is recent enough (>=2.40).

5. Install Pandoc#

PH3 gives you the possibility to insert Jupyter Notebooks in your documentation. This requires the installation of the Pandoc converter: https://pandoc.org/installing.html

6. Install an IDE#

You need an IDE to develop your package. Two common choices are PyCharm and VS Code.

Option A: PyCharm#

Install using the binaries available here: https://www.jetbrains.com/pycharm/download/.

Link PyCharm to your GitHub account#

In PyCharm settings: Version Control → GitHub → Add account.

Two options are available:

Log In with Token. The first time, click on the generate button to open a GitHub page that will create an access token. Copy the token and paste it in PyCharm. PyCharm should remind it but to avoid generating a new token every other week you should keep a copy somewhere else as well (in a very safe place!).
Log In via GitHub will open a GitHub page to grant you access (2FA is likely to be required).

Change the documentation style

We recommend the Numpy documentation style.

In PyCharm settings: Tools → Python Integrated Tools → Docstrings → Docstring format → NumPy.

Option B: VS Code#

Install from https://code.visualstudio.com/.

Install the Python extension (by Microsoft). It provides test discovery, linting, and debugger integration.