Migrate Python CLI template to uv #21

jonavellecuerdo · 2026-01-16T15:46:43Z

Purpose and background context

Migrate Python CLI template to uv

How can a reviewer manually see the effects of these changes?

The uv-based GitHub CI workflow has been tested in MITLibraries/timdex-embeddings#33

Includes new or updated dependencies?

YES

Changes expectations for external applications?

NO

What are the relevant tickets?

Code review

Code review best practices are documented here and you are encouraged to have a constructive dialogue with your reviewers about their preferences and expectations.

jonavellecuerdo · 2026-01-16T15:47:33Z

Question for @ehanson8 and @ghukill : Should we exclude the uv.lock file similar to how we excluded the Pipfile.lock so as to avoid pinning dependencies for the template?

Why these changes are being introduced: This is the first pass in migrating to uv from pipenv. How this addresses that need: * Removes Pipfile and Pipfile.lock * Updates pyproject.toml to be a valid uv project * All dependencies handled via 'uv add' and exist in pyproject.toml * Makefile and pre-commits updated to use uv syntax * Github actions *temporarily* hardcoded in local workflows, with a TODO to move these to a shared workflow when things settle down * Bumps python to 3.13 Side effects of this change: * Many! Hard pivot from Pipenv installation and running of the application. At this time, the largest side effect is the loss of 'pipenv run <appname>'. A future commit will apply a new strategy, but that is not present now. A workaround is 'uv run my_app/cli.py`. Relevant ticket(s): * https://mitlibraries.atlassian.net/browse/IN-1425

Why these changes are being introduced: As we continue to slowly build out this uv driven version of the CLI template, finding little things to update along the way. How this addresses that need: * Updated Dockerfile to use uv in image build * Add convenience docker methods in Makefile, unassociated with AWS ECR (helpful for local testing) * Update dependencies Side effects of this change: * None Relevant ticket(s): * None

coveralls · 2026-01-16T15:52:26Z

Pull Request Test Coverage Report for Build 21072504558

Details

0 of 0 changed or added relevant lines in 0 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage remained the same at 100.0%

Totals
Change from base Build 17270497594:	0.0%
Covered Lines:	35
Relevant Lines:	35

💛 - Coveralls

ehanson8 · 2026-01-16T20:27:59Z

Question for @ehanson8 and @ghukill : Should we exclude the uv.lock file similar to how we excluded the Pipfile.lock so as to avoid pinning dependencies for the template?

We don't seem to be excluding Pipfile.lock here, was that a recent decision?

ehanson8

Looking good but a few questions and comments

ehanson8 · 2026-01-16T20:31:15Z

Dockerfile


-COPY Pipfile* /
-RUN pipenv install
+# Install package into system python, includes "marimo-launcher" script


This docstring probably shouldn't have the marimo-launcher reference

ehanson8 · 2026-01-16T20:33:39Z

Makefile

+# Docker
+####################################
+docker-build: # Build local image for testing
+	docker build -t python-cli-template:latest .


Is there a reason this is python-cli-template rather than my-app? It would simplify the find/replace if they were the same

Seconded! Sort of...

While we're on this block, I might propose fully removing this # Docker section. I just recently removed it from the timdex-embeddings project.

It was helpful for a bit, whilst experimenting with uv deployments, but I don't think we need it. Until InfraEng adds the makd dist-dev style commands to a project, I think it's reasonable we could figure out how to build and test docker containers. The maintenance of this section feels like it outweighs the benefits.

ehanson8 · 2026-01-16T20:34:02Z

pyproject.toml

 # https://mitlibraries.atlassian.net/wiki/spaces/IN/pages/3432415247/Python+Project+Linters#Template-for-pyproject.toml

+[project]
+name = "python-cli-template"


Again, could this be my-app?

ehanson8 · 2026-01-16T20:41:29Z

pyproject.toml

+[project]
+name = "python-cli-template"
+version = "2.0.0"
+requires-python = ">=3.12"


I think we want ~=3.12.0 rather than >=3.12 to avoid inadvertently upgrading to 3.13, ~=3.12.0 keeps it in 3.12 but gets the newest patch version

Smart. Agreed.

I could find links, but it's Google-able: uv takes the position of upgrading where possible but not downgrading. It's a little surprising at first, but it seems pretty well established. For libraries within the project, I think that's okay. But python versions we do control pretty closely.

I'm not 100% sure that behavior is applied at this python version level, but I feel like I've almost encountered it myself, and would believe it.

Nice catch @ehanson8!

ghukill · 2026-01-20T14:02:17Z

Question for @ehanson8 and @ghukill : Should we exclude the uv.lock file similar to how we excluded the Pipfile.lock so as to avoid pinning dependencies for the template?

I would propose that we keep the uv.lock file. My understanding has always been that version controlling the lock files is good practice. That way, without a dependency update we know the Docker CI build will be identical. A little unsure why we were formerly excluding the Pipfile.lock files.

Looking at this commit @jonavellecuerdo, I'd propose re-adding it as a commit.

ghukill

Overall, looking great. Did request a couple of small changes, mostly things pointed out by @ehanson8.

I'd also like to propose an update to the README about running the CLI.

Under the section ## Development I'd propose updating this:

- To run the app: `uv run my-app --help` (Note the hyphen `-` vs underscore `_` that matches the `project.scripts` in `pyproject.toml`)

To the following, which shows two options:

- To run the app:
  - `my-app`
    - utilizes `uv` built entrypoint (see `project.scripts` in `pyproject.toml`)
    - does not support loading a `.env` file
  - `uv run --env-file .env my-app`
    - more verbose, but supports loading with a `.env` file

Thoughts?

ghukill · 2026-01-20T14:05:40Z

Makefile

+# Docker
+####################################
+docker-build: # Build local image for testing
+	docker build -t python-cli-template:latest .


Seconded! Sort of...

While we're on this block, I might propose fully removing this # Docker section. I just recently removed it from the timdex-embeddings project.

It was helpful for a bit, whilst experimenting with uv deployments, but I don't think we need it. Until InfraEng adds the makd dist-dev style commands to a project, I think it's reasonable we could figure out how to build and test docker containers. The maintenance of this section feels like it outweighs the benefits.

ghukill · 2026-01-20T14:08:37Z

pyproject.toml

+[project]
+name = "python-cli-template"
+version = "2.0.0"
+requires-python = ">=3.12"


Smart. Agreed.

I could find links, but it's Google-able: uv takes the position of upgrading where possible but not downgrading. It's a little surprising at first, but it seems pretty well established. For libraries within the project, I think that's okay. But python versions we do control pretty closely.

I'm not 100% sure that behavior is applied at this python version level, but I feel like I've almost encountered it myself, and would believe it.

Nice catch @ehanson8!

ghukill · 2026-01-20T14:09:14Z

README.md

 ## App Setup (delete this section and above after initial application setup)

-1. Rename "my_app" to the desired app name across the repo. (May be helpful to do a project-wide find-and-replace).
+1. Rename "my_app" and "python-cli-template" to the desired app name across the repo. (May be helpful to do a project-wide find-and-replace).


If taking Eric's suggestions to defaultg to my_app, then probably want to update this.

jonavellecuerdo requested review from a team, ehanson8 and ghukill January 16, 2026 15:46

ghukill added 4 commits January 16, 2026 10:50

Update dependencies and add uv script section

4d4638d

Run CI for pushes to branches with PRs

8331067

jonavellecuerdo force-pushed the IN-1425-uv branch from 95fceb3 to 8331067 Compare January 16, 2026 15:51

jonavellecuerdo added 2 commits January 16, 2026 10:54

Update dependencies

ca733ec

Remove uv.lock

7d37d6b

ehanson8 self-assigned this Jan 16, 2026

ehanson8 reviewed Jan 16, 2026

View reviewed changes

ghukill requested changes Jan 20, 2026

View reviewed changes

Migrate Python CLI template to uv #21

Are you sure you want to change the base?

Migrate Python CLI template to uv #21

Conversation

jonavellecuerdo commented Jan 16, 2026

Purpose and background context

How can a reviewer manually see the effects of these changes?

Includes new or updated dependencies?

Changes expectations for external applications?

What are the relevant tickets?

Code review

Uh oh!

jonavellecuerdo commented Jan 16, 2026

Uh oh!

coveralls commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 21072504558

Details

💛 - Coveralls

Uh oh!

ehanson8 commented Jan 16, 2026

Uh oh!

ehanson8 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ghukill commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ghukill left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

coveralls commented Jan 16, 2026 •

edited

Loading

ghukill commented Jan 20, 2026 •

edited

Loading