Update prod env for Heroku, and automate doing so in the future.

pyproject.toml

@@ -70,6 +70,13 @@ api = [
     "uvicorn>=0.30.1",
 ]
 
+heroku = [
+    "readalongs[api]",
+    # We don't actually use the panphon 0.22 improvements on heroku so stick to
+    # 0.21 with its lighter weight dependencies
+    "panphon<0.22",
+]
+
 ci = [
     "readalongs[api]",
     "coverage",
@@ -107,7 +114,7 @@ include = [
 requires = [ "hatch-pip-compile" ]
 
 [tool.hatch.envs.prod]
-features = [ "api" ]
+features = [ "heroku" ]
 type = "pip-compile"
 python = "3.13"
 lock-filename = "requirements.txt"

readme-heroku.md

@@ -7,13 +7,17 @@ Our production Heroku deployment is controlled by the following files:
 Updating dependencies:
  - Our dependencies are declared in `pyproject.toml`. This is where changes should be made first.
  - `requirements.txt` is the generated "lock" file that Heroku uses. To update it,
-   run these commands, preferably from a Linux machine to match the Heroku context:
+   run these commands on a **Linux** machine to match the Heroku context:
 
+       pip install hatch hatch-pip-compile
        hatch env remove prod
        rm requirements.txt
        hatch env create prod
 
-   Then manually remove the soundswallower line, since it's not needed for the web api.
+   Then manually do the following edits, and commit `requirements.txt` when you're done:
+    - remove the soundswallower line, since it's not needed for the web api;
+    - replace the g2p line by `g2p @ git+https://github.com/roedoejet/g2p.git@main` because we
+      always want to deploy on Heroku with the latest g2p main branch.
 
    It is also possible to edit it manually, e.g., to handle a critical vulnerability report,
    but an occasional full rebuild is a good idea, to keep things up to date.

requirements.txt

@@ -17,18 +17,19 @@
 # - soundswallower~=0.6.0
 # - webvtt-py==0.5.1
 # - gunicorn>=23.0.0; platform_system != "Windows"
+# - panphon<0.22
 # - uvicorn>=0.30.1
 #
 
 annotated-types==0.7.0
     # via pydantic
-anyio==4.9.0
+anyio==4.10.0
     # via starlette
-audioop-lts==0.2.1 ; python_version >= "3.13"
+audioop-lts==0.2.2 ; python_version >= "3.13"
     # via hatch.envs.prod
-certifi==2025.4.26
+certifi==2025.8.3
     # via requests
-charset-normalizer==3.4.2
+charset-normalizer==3.4.3
     # via requests
 chevron==0.14.0
     # via hatch.envs.prod
@@ -45,14 +46,12 @@ editdistance==0.8.1
     # via panphon
 et-xmlfile==2.0.0
     # via openpyxl
-fastapi==0.115.12
+fastapi==0.116.1
     # via hatch.envs.prod
-
 # Manual override: for deployment on Heroku, we want the latest g2p@main on GitHub
 g2p @ git+https://github.com/roedoejet/g2p.git@main
-#g2p==2.2.1
+# g2p==2.2.2
     # via hatch.envs.prod
-
 gunicorn==23.0.0 ; platform_system != "Windows"
     # via hatch.envs.prod
 h11==0.16.0
@@ -63,11 +62,11 @@ idna==3.10
     # via
     #   anyio
     #   requests
-lxml==5.4.0
+lxml==6.0.0
     # via hatch.envs.prod
 munkres==1.1.4
     # via panphon
-numpy==2.2.5
+numpy==2.3.2
     # via
     #   hatch.envs.prod
     #   panphon
@@ -76,7 +75,9 @@ openpyxl==3.1.5
 packaging==25.0
     # via gunicorn
 panphon==0.21.2
-    # via g2p
+    # via
+    #   hatch.envs.prod
+    #   g2p
 pydantic==2.8.2
     # via
     #   hatch.envs.prod
@@ -86,36 +87,34 @@ pydantic-core==2.20.1
     # via pydantic
 pydub==0.25.1
     # via hatch.envs.prod
-pympi-ling==1.70.2
+pympi-ling==1.71
     # via hatch.envs.prod
 python-slugify==5.0.0
     # via hatch.envs.prod
 pyyaml==6.0.2
     # via
     #   g2p
     #   panphon
-regex==2024.11.6
+regex==2025.7.34
     # via
     #   g2p
     #   panphon
-requests==2.32.4
+requests==2.32.5
     # via hatch.envs.prod
 sniffio==1.3.1
     # via anyio
-
-# Remove soundswallower because the web_api backend does not need it
-#soundswallower==0.6.5
+# Manual override: soundswallower is not needed for the web API so ignore it.
+# soundswallower==0.6.5
     # via hatch.envs.prod
-
-starlette==0.46.2
+starlette==0.47.2
     # via fastapi
 text-unidecode==1.3
     # via
     #   g2p
     #   python-slugify
 tqdm==4.67.1
     # via g2p
-typing-extensions==4.13.2
+typing-extensions==4.14.1
     # via
     #   fastapi
     #   g2p
@@ -125,7 +124,7 @@ unicodecsv==0.14.1
     # via panphon
 urllib3==2.5.0
     # via requests
-uvicorn==0.34.2
+uvicorn==0.35.0
     # via hatch.envs.prod
 webvtt-py==0.5.1
     # via hatch.envs.prod

update-heroku.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Refresh the production environment for Heroku, i.e., update requirements.txt
+
+if [[ $(uname) != Linux ]]; then
+    echo Please run this command on Linux
+    exit 1
+fi
+
+if ! which uvx > /dev/null; then
+    echo Please install uv: "https://docs.astral.sh/uv/getting-started/installation/"
+    echo "Simplest: curl -LsSf https://astral.sh/uv/install.sh | sh"
+    exit 1
+fi
+
+echo "Removing old prod env"
+uvx --with hatch-pip-compile hatch env remove prod
+rm requirements.txt
+echo "Creating new prod env -- errors about pip's dependency resolver are expected and normal"
+uvx --with hatch-pip-compile hatch env create prod
+
+echo "Applying manual overrides"
+sed -i -e '/^soundswallower=/i # Manual override: soundswallower is not needed for the web API so ignore it.' \
+       -e 's/^soundswallower=/# soundswallower=/' requirements.txt
+
+sed -i -e '/^g2p=/i # Manual override: for deployment on Heroku, we want the latest g2p@main on GitHub' \
+       -e '/^g2p=/i g2p @ git+https://github.com/roedoejet/g2p.git@main' \
+       -e 's/^g2p=/# g2p=/' \
+       requirements.txt
+
+echo "Please review the changes to requirements.txt and commit them if they're OK."