Deployment - pypackitup - Python Package Template
Author: Wren J. Rudolph for Wrencode, LLC

# Deployment

### Table of Contents

- Initial Deployment
- Subsequent Deployment

### Initial Deployment

- (Required for initial publication on PyPI as needed) Register a new account on PyPI (do the same for Test PyPI as needed).

- (Required for initial publication on PyPI) Configure API token authentication for PyPI by creating an API token (do the same for Test PyPI as needed) and copy the value of the API token.

- (Required for initial publication on PyPI) Create a `.env` file by running `cp .env.template .env` in the command line from the project root directory and paste the PyPI API token from the previous step as the value for `UV_PUBLISH_TOKEN` (this environment variable is used in the Makefile by `uv publish` to publish the package using uv).

- (Optional after initial package publication on PyPI) Configure a new package-specific PyPI API token and update the above `UV_PUBLISH_TOKEN` environment variable in the `.env` to use it.

- (Optional if using Twine) Install `twine` (if not already installed) with `uv add twine`.

- (Optional if using custom domain for GitHub Pages) Follow the steps for managing a custom domain for GitHub Pages.

- If you want to use a subdomain, you should follow the steps for configuring a subdomain for GitHub Pages, which require the creation of a `CNAME` DNS record for your custom domain.

- Note: If you are using CloudFlare and you create a `CNAME` record for your GitHub Pages subdomain, you must turn off “Proxy status” so that it is “DNS only” or else HTTPS will not work!

### Subsequent Deployment

- (Optional) Check `pyproject.toml` for latest dependency versions.

- (Optional) Update virtual machine with the latest dependencies (`make update` in Makefile):

    uv sync --all-extras --dev

- Lint code with `ruff` (`make lint` in Makefile):

    ruff check .

- Check code security with `bandit` (`make secure` in Makefile):

    bandit -c pyproject.toml -r .

- (Optional) Run all `pytest` tests (see following commands for running subsets of tests) (`make test_code` in Makefile):

    uv run pytest tests

- (Optional) Run all `pytest` tests verbosely:

     uv run pytest -v -s tests

- (Optional) Run all tests from `pytest` file:

    uv run pytest -v -s tests/test_helloworld.py

- (Optional) Run specific test from `pytest` file:

    uv run pytest -v -s tests/test_helloworld.py -k test_main

- (Optional) Test Python support using act for GitHub Actions:

    act -j build

Note: If `act` is unable to locate Docker, make sure that the required `/var/run/docker.sock` symlink exists. If it does not, you can fix it by running:

    sudo ln -s "$HOME/.docker/run/docker.sock" /var/run/docker.sock`

Note: If you are running macOS on a devices with an M-series chip (Apple Silicon), you will need to specify `linux/amd64` architecture when running `act`:

    act --container-architecture linux/amd64 -j build

- (Optional) Build the PyPI package independent of deployment:

    make build

- (Optional) Test packages for PyPI deployment:

    make verify_build

- (Optional) Check MkDocs documentation by serving it at http://localhost:8000/ locally:

    make test_docs

- (Optional) Build the PyPI package and MkDocs documentation independent of deployment:

    make docs

Note: Running `make test_docs` from the previous step recreates the documentation without building the PyPI package.

- Create a git commit:

    git add .
    git commit -m 'commit message'

- Update the git tag with the new version (`git tag -a [tag_name/version] -m [message]`):

    git tag -a v1.0.0 -m 'release message'
    git push origin --tags

- (Optional) Test deployment by building the PyPI packages, recreating the documentation, and deploying to Test PyPI:

    make uv_test_deploy

- Deploy the package by building it, recreating the documentation, and deploying the package to PyPI:

    make uv_deploy

- Create a second git commit with updated version number and documentation:

    git add .
    git commit -m 'updated version number and documentation'

- Update package git repository:

    git push

GitHub « Previous Next »