Merge pull request #66 from Promptly-Technologies-LLC/64-switch-from-poetry-to-uv

Migrate from poetry to uv for dependency management

Author: chriscarrollsmith

.github/workflows/test.yml

@@ -12,7 +12,6 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ["3.12"]
-        poetry-version: [latest]
         os: [ubuntu-latest]
 
     runs-on: ${{ matrix.os }}
@@ -35,15 +34,16 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install and configure Poetry
-        uses: snok/install-poetry@v1
-
       - name: Install project
-        run: poetry install
+        run: uv sync --all-extras --dev
 
       - name: Set env variables for pytest
         run: |
@@ -68,7 +68,7 @@ jobs:
           [ -n "$RESEND_API_KEY" ]
 
       - name: Run type checking with mypy
-        run: poetry run mypy .
+        run: uv run mypy .
 
       - name: Run tests with pytest
-        run: poetry run pytest -s tests/
+        run: uv run pytest tests/

README.md

@@ -55,7 +55,7 @@ to deploy to any major cloud hosting platform.
 
 **Additional technologies:**
 
-- [Poetry](https://python-poetry.org/): Python dependency manager
+- [uv](https://docs.astral.sh/uv/): Python dependency manager
 - [Pytest](https://docs.pytest.org/en/7.4.x/): testing framework
 - [Docker](https://www.docker.com/): development containerization
 - [Github Actions](https://docs.github.com/en/actions): CI/CD pipeline
@@ -72,56 +72,73 @@ to deploy to any major cloud hosting platform.
 For comprehensive installation instructions, see the [installation
 page](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/docs/installation.html).
 
-### Python and Docker
+### uv
 
-- [Python 3.12 or higher](https://www.python.org/downloads/)
-- [Docker and Docker Compose](https://docs.docker.com/get-docker/)
+MacOS and Linux:
 
-### PostgreSQL headers
+``` bash
+wget -qO- https://astral.sh/uv/install.sh | sh
+```
 
-For Ubuntu/Debian:
+Windows:
 
 ``` bash
-sudo apt update && sudo apt install -y python3-dev libpq-dev
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
-For macOS:
+See the [uv installation
+docs](https://docs.astral.sh/uv/getting-started/installation/) for more
+information.
+
+### Python
+
+Install Python 3.12 or higher from either the official [downloads
+page](https://www.python.org/downloads/) or using uv:
 
 ``` bash
-brew install postgresql
+# Installs the latest version
+uv python install
 ```
 
-For Windows:
+### Docker and Docker Compose
 
-- No installation required
+Install Docker Desktop and Coker Compose for your operating system by
+following the [instructions in the
+documentation](https://docs.docker.com/compose/install/).
 
-### Python dependencies
+### PostgreSQL headers
 
-1.  Install Poetry
+For Ubuntu/Debian:
 
 ``` bash
-pipx install poetry
+sudo apt update && sudo apt install -y python3-dev libpq-dev
 ```
 
-2.  Install project dependencies
+For macOS:
 
 ``` bash
-poetry install
+brew install postgresql
 ```
 
-3.  Activate shell
+For Windows:
+
+- No installation required
+
+### Python dependencies
+
+From the root directory, run:
 
 ``` bash
-poetry shell
+uv venv
+uv sync
 ```
 
-(Note: You will need to activate the shell every time you open a new
-terminal session. Alternatively, you can use the `poetry run` prefix
-before other commands to run them without activating the shell.)
+This will create an in-project virtual environment and install all
+dependencies.
 
 ### Set environment variables
 
-Copy .env.example to .env with `cp .env.example .env`.
+Copy `.env.example` to `.env` with `cp .env.example .env`.
 
 Generate a 256 bit secret key with `openssl rand -base64 32` and paste
 it into the .env file.
@@ -134,6 +151,9 @@ account, verify a domain, get an API key, and paste the API key into the
 
 ### Start development database
 
+To start the development database, run the following command in your
+terminal from the root directory:
+
 ``` bash
 docker compose up -d
 ```
@@ -155,14 +175,31 @@ Navigate to http://localhost:8000/
 mypy .
 ```
 
-### Contributing
+## Developing with LLMs
+
+In line with the [llms.txt standard](https://llmstxt.org/), we have
+provided a Markdown-formatted prompt—designed to help LLM agents
+understand how to work with this template—as a text file:
+[llms.txt](docs/static/llms.txt).
+
+One use case for this file, if using the Cursor IDE, is to rename it to
+`.cursorrules` and place it in your project directory (see the [Cursor
+docs](https://docs.cursor.com/context/rules-for-ai) on this for more
+information). Alternatively, you could use it as a custom system prompt
+in the web interface for ChatGPT, Claude, or the LLM of your choice.
+
+We have also exposed the full Markdown-formatted project documentation
+as a [single text file](docs/static/documentation.txt) for easy
+downloading and embedding for RAG workflows.
+
+## Contributing
 
 Your contributions are welcome! See the [issues
 page](https://github.com/promptly-technologies-llc/fastapi-jinja2-postgres-webapp/issues)
 for ideas. Fork the repository, create a new branch, make your changes,
 and submit a pull request.
 
-### License
+## License
 
 This project is created and maintained by [Promptly Technologies,
 LLC](https://promptlytechnologies.com/) and licensed under the MIT

docs/customization.qmd

@@ -4,18 +4,23 @@ title: "Customization"
 
 ## Development workflow
 
-### Dependency management with Poetry
+### Dependency management with `uv`
 
-The project uses Poetry to manage dependencies:
+The project uses `uv` to manage dependencies:
 
-- Add new dependency: `poetry add <dependency>`
-- Add development dependency: `poetry add --dev <dependency>`
-- Remove dependency: `poetry remove <dependency>`
-- Update lock file: `poetry lock`
-- Install dependencies: `poetry install`
-- Update all dependencies: `poetry update`
+- Add new dependency: `uv add <dependency>`
+- Add development dependency: `uv add --dev <dependency>`
+- Remove dependency: `uv remove <dependency>`
+- Update lock file: `uv lock`
+- Install all dependencies: `uv sync`
+- Install only production dependencies: `uv sync --no-dev`
+- Upgrade dependencies: `uv lock --upgrade`
 
-If you are using VSCode or Cursor as your IDE, you will need to select the Poetry-managed Python version as your interpreter for the project. To find the location of the Poetry-managed Python interpreter, run `poetry env info` and look for the `Path` field. Then, in VSCode, go to `View > Command Palette`, search for `Python: Select Interpreter`, and either select Poetry's Python version from the list (if it has been auto-detected) or "Enter interpreter path" manually.
+### IDE configuration
+
+If you are using VSCode or Cursor as your IDE, you will need to select the `uv`-managed Python version as your interpreter for the project. Go to `View > Command Palette`, search for `Python: Select Interpreter`, and select the Python version labeled `('.venv':venv)`.
+
+If your IDE does not automatically detect and display this option, you can manually select the interpreter by selecting "Enter interpreter path" and then navigating to the `.venv/bin/python` subfolder in your project directory.
 
 ### Testing
 

docs/installation.qmd

@@ -9,9 +9,12 @@ If you use VSCode with Docker to develop in a container, the following VSCode De
 ``` json
 {
 	"name": "Python 3",
-	"image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
-	"postCreateCommand": "sudo apt update && sudo apt install -y python3-dev libpq-dev graphviz && pipx install poetry && poetry install && poetry shell",
+	"image": "mcr.microsoft.com/devcontainers/python:1-3.12-bookworm",
+	"postCreateCommand": "sudo apt update && sudo apt install -y python3-dev libpq-dev graphviz && uv venv && uv sync",
 	"features": {
+		"ghcr.io/va-h/devcontainers-features/uv:1": {
+			"version": "latest"
+		},
 		"ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},
 		"ghcr.io/rocker-org/devcontainer-features/quarto-cli:1": {}
 	}
@@ -24,10 +27,34 @@ Simply create a `.devcontainer` folder in the root of the project and add a `dev
 
 ## Install development dependencies manually
 
-### Python and Docker
+### uv
 
-- [Python 3.12 or higher](https://www.python.org/downloads/)
-- [Docker and Docker Compose](https://docs.docker.com/get-docker/)
+MacOS and Linux:
+
+``` bash
+wget -qO- https://astral.sh/uv/install.sh | sh
+```
+
+Windows:
+
+``` bash
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+See the [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/) for more information.
+
+### Python
+
+Install Python 3.12 or higher from either the official [downloads page](https://www.python.org/downloads/) or using uv:
+
+``` bash
+# Installs the latest version
+uv python install
+```
+
+### Docker and Docker Compose
+
+Install Docker Desktop and Docker Compose for your operating system by following the [instructions in the documentation](https://docs.docker.com/compose/install/).
 
 ### PostgreSQL headers
 
@@ -49,31 +76,25 @@ For Windows:
 
 ### Python dependencies
 
-1.  Install Poetry
+From the root directory, run:
 
 ``` bash
-pipx install poetry
+uv venv
 ```
 
-2.  Install project dependencies
+This will create an in-project virtual environment. Then run:
 
 ``` bash
-poetry install
+uv sync
 ```
 
-(Note: if `psycopg2` installation fails with a `ChefBuildError`, you just need to install the PostgreSQL headers first and then try again.)
-
-3.  Activate shell
-
-``` bash
-poetry shell
-```
+This will install all dependencies.
 
-(Note: You will need to activate the shell every time you open a new terminal session. Alternatively, you can use the `poetry run` prefix before other commands to run them without activating the shell.)
+(Note: if `psycopg2` installation fails, you probably just need to install the PostgreSQL headers first and then try again.)
 
 ### Configure IDE
 
-If you are using VSCode or Cursor as your IDE, you will need to select the Poetry-managed Python version as your interpreter for the project. To find the location of the Poetry-managed Python interpreter, run `poetry env info` and look for the `Path` field. Then, in VSCode, go to `View > Command Palette`, search for `Python: Select Interpreter`, and either select Poetry's Python version from the list (if it has been auto-detected) or "Enter interpreter path" manually.
+If you are using VSCode or Cursor as your IDE, you will need to select the `uv`-managed Python version as your interpreter for the project. Go to `View > Command Palette`, search for `Python: Select Interpreter`, and select the Python version labeled `('.venv':venv)`.
 
 It is also recommended to install the [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) and [Quarto](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) IDE extensions.