All jobs

Migrate a Textual App From Poetry to uv

Yes. An agent rewrites a Textual app's pyproject from Poetry tables to PEP 621, locks with uv at the same versions, proves the tl command still runs, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how the project is built and installed before it changes a table, because a Poetry project's metadata, scripts and build backend all move at once. In an app laid out like Textualize/toolong, pyproject.toml has only Poetry tables: [tool.poetry] with the name toolong, version 1.5.0, an MIT license, the README and three repository URLs; [tool.poetry.dependencies] with python = "^3.8", click = "^8.1.7", textual = "^0.58.0" and typing-extensions = "^4.9.0"; a dev group with textual-dev = "^1.4.0"; [tool.poetry.scripts] mapping tl to toolong.cli:run; and a poetry-core build backend. poetry.lock was written by Poetry 1.8.2 at lock version 2.0 and resolves 21 packages, among them textual 0.58.0 and textual-dev 1.5.1. The code sits in src/toolong/, and cli.py reads its own version with importlib.metadata.version("toolong") for --version, which only works when the package is installed. README.md tells users to pipx install toolong or pip install toolong. There is no test suite, no Makefile and no CI workflow, so the proof has to come from installing and running the tool.

The translation is mechanical but the version ranges need care. Poetry's caret means something different on a 0.x version: ^0.58.0 is >=0.58.0,<0.59.0, while ^8.1.7 is >=8.1.7,<9. The agent writes a [project] table with requires-python = ">=3.8,<4.0", dependencies as click>=8.1.7,<9, textual>=0.58.0,<0.59.0 and typing-extensions>=4.9.0,<5, so the migration keeps the same resolution and does not smuggle in a Textual upgrade; the pull request says that textual is pinned to a release line far behind the current one and that widening it is a separate change. [project.scripts] gets tl = "toolong.cli:run", [project.urls] the three links, [dependency-groups] a dev group with textual-dev>=1.4.0,<2, and license the SPDX string MIT. The build backend becomes uv_build, whose default module path is src/<name>, which is what the repository already has; the agent runs uv build to confirm the backend finds src/toolong and leaves a note that hatchling is the alternative if the team prefers one build backend across projects.

uv lock writes uv.lock, and the agent compares it with the old lock before deleting that file: uv export --no-hashes against the package list in poetry.lock, which should show the same 21 names at the same versions on the sandbox's platform, with any difference called out by name. poetry.lock is removed, [tool.poetry] is gone, and .gitignore gains nothing because it already ignores build/ and dist/. The README's install section keeps pipx and pip and adds uv tool install toolong, and a short contributor paragraph names uv sync and uv run tl. The agent also writes a .python-version of 3.12 for contributors, since requires-python still allows 3.8 for users but no maintainer should develop on a release that old.

Then it proves the result the way a user would. uv sync creates the environment with the dev group, uv run tl --version prints 1.5.0 through importlib.metadata, so the editable install registered the package, uv run tl --help shows the --merge and --output-merge options from cli.py, and uv run python -c "import textual; print(textual.__version__)" prints 0.58.0. uv build produces the sdist and wheel under dist/, and uvx --from dist/toolong-1.5.0-py3-none-any.whl tl --version runs the built wheel in a fresh environment, which is the same path a pipx or uv tool user takes. Because tl is a full-screen terminal app, the agent does not try to drive its UI; it pipes a small log file through tl in non-TTY mode, which cli.py handles by reading stdin, and keeps the output.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Migrate this Textual application from Poetry to uv. Read pyproject.toml, poetry.lock, src/toolong/cli.py, README.md and .gitignore first. Replace the tool.poetry tables with a PEP 621 project table that keeps the same name, version, license, readme, urls and script, translate each caret range exactly as Poetry reads it including the 0.x case for textual, move the dev group to dependency-groups, and switch the build backend to uv_build. Run uv lock, compare the resolved packages and versions with poetry.lock and report any difference, then delete poetry.lock. Add a .python-version for contributors, and update the README install and contributing sections for uv without removing pipx or pip. Run uv sync, uv run tl --version, uv run tl --help, uv build, and run the built wheel with uvx, then pipe a small log file through tl in non-TTY mode. Open a pull request that shows each command's output and says that the Textual version range was kept rather than widened.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that rewrites pyproject.toml, adds uv.lock and .python-version, deletes poetry.lock and changes README.md. The description shows the [project] table beside the old [tool.poetry] one, the package-by-package comparison of the two locks, and the output of uv run tl --version, uv build and the uvx run of the wheel, so a reviewer can see the version string, the script entry point and the build backend all survived.

There is no workflow in this repository, so no check runs on the pull request; the run's record is the evidence, and it keeps uv lock, the export comparison and every run of tl in order. The pull request suggests a uv sync and uv build workflow as a follow-up and names the add-github-actions-ci job for it.

Before merging, a reviewer decides whether to widen the textual range now that the lock is under their control, whether requires-python should drop 3.8, and whether to keep uv_build or standardise on hatchling. The agent changes nothing under src.

Run it on every Python repository still on Poetry

A team with several Textual or Click tools on Poetry starts one run per repository from its own server: one POST /o/{org}/sessions each, with the repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own pyproject.toml, so a project with [tool.poetry.extras] gets [project.optional-dependencies], one with a packages include list outside src gets hatchling with the matching configuration instead of uv_build, and one already on PEP 621 tables gets only the lock swapped.

After that, an automation in the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "if this pull request changes pyproject.toml dependencies, check that uv.lock changed with it and that no tool.poetry table came back, and say so in a comment" keeps the lock honest. The trigger adds the pull request after the prompt and fires only for work by owners, members and collaborators.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A Poetry-to-uv migration done by hand goes wrong in the places a diff does not show: a ^0.58.0 turned into >=0.58.0 that silently upgrades Textual across many breaking releases, a script entry that no longer resolves so tl is gone after install, or a build backend that cannot find a src layout and ships an empty wheel. The agent locks, builds and runs the real tool in its sandbox, compares the two locks package by package and runs the built wheel in a clean environment before it opens the pull request.

Every command stays with the run, from uv lock to the uvx run of the wheel, and the pull request quotes them. The same migration over a dozen Python tools at once costs no more attention than one, because each run has its own machine, its own record and its own pull request.

Frequently asked questions

Will my dependency versions change?

Not by this pull request. Each Poetry caret is translated to the range Poetry itself reads, including the 0.x case where ^0.58.0 stops at 0.59.0, and uv lock is compared against poetry.lock so the resolution comes out the same. Widening textual is called out as a separate decision, because it crosses many releases with breaking changes.

Why uv_build and not hatchling or setuptools?

The repository already uses a src/toolong layout, which is exactly what uv_build expects with no configuration, so the switch adds no table. hatchling is the choice when a team wants one backend for projects that do not follow that layout, and the pull request says where its two lines would go. poetry-core could stay as the backend too, but keeping it means keeping Poetry metadata that PEP 621 now carries.

Does pipx install still work for users?

Yes. The wheel is a normal wheel with the tl entry point in its metadata, which pipx, pip and uv tool install all read the same way. The agent proves it by running the built wheel with uvx --from, which installs it into a fresh environment the way pipx does.

How is a terminal app tested without a terminal?

The agent does not drive the full-screen UI. It checks the entry point with --version and --help, and uses the non-TTY branch in cli.py that reads a log from standard input, piping a small file through it. Textual's own App.run_test harness is how a team would add real UI tests later, and the pull request names it.

More Textual jobs

The same job on other stacks

Keep reading