IN 1434 - utilize uv script and tool building

[ghukill]

Purpose and background context

As outlined in the git commit, this PR leans more heavily into uv tooling to streamline how this CLI is run locally for development, installed in the Docker container for production use, and even can be used as a standalone "tool" installed directly from the repository.

The key section is here in the pyproject.toml:

[project.scripts]
marimo-launcher = "launcher.cli:cli"
mitlib-marimo-launcher = "launcher.cli:cli"

Though the word "script" is used I think it's more helpful to think of these as "entry points" for the application. And, that this begins to convert this application into something "installable".

Local Development

When developing locally, you can now just run the following:

uv run marimo-launcher

A build is technically performed each time, but this is quick. Code changes are immediately reflected. Better yet, sneaky errors will pop up if the dependencies in the pyproject.toml don't support the project (e.g. a manual pip install was performed that has a library locally, but wouldn't have been present during build).

You can see this usage in the updated Makefile testing commands.

Docker Image

Installing this CLI as a uv tool also dramatically simplifies the Dockerfile. The key lines here are:

# Copy project metadata
COPY pyproject.toml uv.lock* ./

# Copy CLI source
COPY launcher ./launcher

# Install package into system python, includes "marimo-launcher" script
RUN uv pip install --system .

We copy the metadata files pyproject.toml and uv.lock into the container, and the application itself at /launcher. Then we quite literally install the application to the system wide python installation, which in a container is an expected and good thing.

Now, inside the container, we have a bonafied marimo-launcher script/entrypoint/command (whatever you want to call it) that we can call directly. And you can see that we do in the updated ENTRYPOINT.

Standalone uv Tool

Maybe one of the more exciting things this opens up is the ability to install this CLI as a tool anywhere quite easily. This CLI can now be installed a machine, directly from the Github repository, with a uv tool install ... command (more on this in the testing section below).

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

Local Testing

Run the CLI directly:

uv run marimo-launcher run --help

Run a test notebook (also Makefile command cli-test-inline-run):

uv run marimo-launcher run --mount=tests/fixtures/inline_deps

Docker Testing

Build image:

make docker-build

Jump into a bash shell of a container and note that marimo-launcher is installed:

# enter shell
make docker-shell

# show marimo
whereis marimo-launcher

# run it
marimo-launcher run --help

Standalone uv Tool Testing

Arguably the most fun part 😎, install as a standalone uv tool. Start a new shell, somewhere on your machine completely unassociated with this project.

Install the CLI as a tool directly from github (the @<branch> is just temporary until a merge to main):

uv tool install --from git+https://github.com/MITLibraries/marimo-launcher@IN-1434-uv-tooling marimo-launcher

Confirm it's installed (similar to inside the Docker container):

whereis marimo-launcher

Run a notebook that is also in Github!

marimo-launcher run --repo https://github.com/MITLibraries/marimo-helloworld

• navigate to http://localhost:2718

And to take this principle to the absolute moon, you can run it all as a one liner in a completely isolated and ephemeral way via uvx (link):

uvx --from git+https://github.com/MITLibraries/marimo-launcher@IN-1434-uv-tooling marimo-launcher run --repo=https://github.com/MITLibraries/marimo-helloworld

Includes new or updated dependencies?

NO

Changes expectations for external applications?

NO

What are the relevant tickets?

• https://mitlibraries.atlassian.net/browse/IN-1434

[ghukill]

It'll be interesting to discuss this more as a team.

Now that we can start to theoretically install our CLIs and applications as standalone tools, we may want to consider giving them a namespace prefix like mitlib-*. Imagine we had a tool we called... oh I don't know.... transform (link). This could collide with other linux, homebrew, or a myriad of other scripts on our machines.

If we were to start prefixing our uv tools / entrypoints with mitlib-* we might be able to start to build an ecosystem of terminal / CLI tooling from our own applications.

[ehanson8]

Good call, looking forward to that discussion!

[coveralls]

Pull Request Test Coverage Report for Build 17132166923

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 87.755%

---

Totals
Change from base Build 17105537802:	0.0%
Covered Lines:	86
Relevant Lines:	98

---

💛 - Coveralls

[ehanson8]

This all looks great, glad we're beginning to develop some uv conventions through this work

[ehanson8]

Good call, looking forward to that discussion!