All jobs

Migrate a Python CLI From optparse to argparse

Yes. An agent ports each option to argparse, compares help text, parsed values and exit codes with the old parser, and opens a PR listing every difference.

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 the parser as a contract before it rewrites it. In a downloader like everdrone/nts, nts/cli.py builds one OptionParser with the usage string Usage: %prog [options] args and four options: -o/--out-dir with type="string" and metavar="DIR", and three store_true flags, -v/--version, -q/--quiet and -a/--albumize. parser.parse_args() returns the options and a list of leftover arguments, which the command treats as URLs or files of URLs. With no arguments it prints a message and the help and exits with status 1. setup.py installs the function as the nts console script.

Before changing code it captures the old behaviour as data. It runs the existing command with --help, --version, no arguments, an unknown option, an option missing its value, and options placed between positional arguments, and saves each output and exit status. The repository has no tests, so this table is the safety net, and the agent turns it into a small pytest file that drives the parser directly.

The port is mostly renaming: ArgumentParser, add_argument, type=str or nothing in place of type="string", and a positional nargs="*" argument for the URLs. The differences that bite are in the details. argparse runs every help string through % formatting, and the --out-dir help mentions %USERPROFILE%\Downloads, so an unescaped port raises ValueError: unsupported format character 'U' the moment a user asks for --help; it needs %%. The usage string must use %(prog)s and lose its Usage: prefix, which argparse adds itself. And where optparse accepts nts -q first.txt -a second.txt, argparse's parse_args() rejects the second positional as unrecognized; parse_intermixed_args() restores the old behaviour.

Then it decides what to keep on purpose. The hand-written --version branch becomes action="version" with the version read from nts/downloader.py, which prints the same line and exits 0. The no-arguments check stays as written, with nargs="*", because switching to nargs="+" would change the exit status from 1 to argparse's 2 and replace the project's message. The agent reruns the table against the new parser and reports each row as same or different.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Migrate this command-line tool from optparse to argparse without changing how users call it. Find every OptionParser, add_option, parse_args, OptionGroup, callback action and use of parser.error or print_help. Before editing, run the existing command with: --help, the version flag, no arguments, an unknown option, an option that needs a value without one, options placed before, between and after positional arguments, and a literal -- followed by an argument that starts with a dash. Save each stdout, stderr and exit status as a table. Port the parser to argparse. Keep every option string, dest, default and metavar. Escape literal percent signs in help strings and convert %prog and %default to argparse's %(prog)s and %(default)s. Turn leftover positional arguments into a declared positional argument, and choose nargs so that the behaviour with zero arguments, including the message and exit status, stays what it was. If the old parser accepted options interleaved with positionals, use parse_intermixed_args. Convert a hand-written version flag to action='version' only if the output and exit status stay the same. Add tests that call the parser with each case in the table. Run the table again against the new parser and report every row as same or different, with the old and new output for the different ones. Update any help text pasted into the README. Do not change option names, add subcommands or fix unrelated bugs; list those instead. Open a pull request.",
  "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

A pull request with the rewritten parser, a new test file, and a README change. The README matters here because nts pastes its help output into readme.md, and argparse lays help out differently: a lowercase usage: line, an options: heading, --out-dir DIR in place of --out-dir=DIR, and a section for the positional argument. The agent regenerates that block from the new parser and does not hand-edit it.

The description holds the before and after table. Most rows read same. The rows that differ are named with both outputs, so the reviewer decides whether each is acceptable. One example is a literal -- followed by a dash-prefixed argument: optparse hands it through as a positional, and on Python 3.11 parse_intermixed_args() reports it as unrecognized. That is an edge most tools never hit, and it is the reviewer's call, not something to discover after release.

The agent also lists what it noticed and did not touch. In cli.py the Windows default for the download directory is assigned and then overwritten two lines later, and os.path.abspath is applied to the raw option so the expanduser result above it is discarded. Both predate the migration and both would change behaviour if fixed, so they go in the description as findings.

Run it on every repository that still imports optparse

An organisation with many internal scripts can do this as a batch from a terminal. Search your code host for from optparse import, then start one run per repository with this request and that repository's URL in resources. From an MCP client such as Claude Code or Cursor connected to Rush's MCP server, that is one create_session call per repository followed by wait_for_sessions, which waits up to 50 seconds per call for one or several sessions to settle.

An API key runs at most its max_concurrent runs at once, 4 by default, within the plan limit of the member who created it. Runs past that are still accepted with status queued and start in order as slots free, so the batch needs no retry loop. Send a request_id that is a UUID v5 of the repository name with each start, and a script that is interrupted and run again gets the runs it already started back instead of duplicates.

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

Why run it on Rush?

A parser migration is easy to write and tedious to verify, because the contract is the command's behaviour under every odd invocation and nobody remembers all of them. The run does the tedious part: it executes the old command and the new one in its own sandbox, case by case, and the transcript keeps both outputs. The %USERPROFILE% crash is a good example of what that catches. Nothing fails at import or in normal use; only --help breaks, and a reviewer reading the diff would likely not see it.

Handing this off from a terminal also fits the size of the job. It is too small to schedule and too fiddly to do well between other tasks, and there are usually several such scripts. Each run works on one repository in isolation, installs that project's own dependencies, and comes back with a pull request and a table, so reviewing ten of them is ten short reads.

Frequently asked questions

Is optparse going away?

It still imports without a warning on current Python, so nothing forces the move today. The reasons to migrate are practical: argparse handles positional arguments, subcommands and required options itself, and tools that generate shell completion or documentation generally read argparse parsers. The agent does the port when you ask for it and does not present it as urgent.

Will my users have to change how they call the tool?

The prompt forbids it, and the before and after table is how that is checked. Option names, defaults and exit statuses for the tested cases stay the same. The differences that remain, usually help layout and one or two edge cases around --, are listed in the pull request for you to accept or reject.

What happens to optparse callback actions?

argparse has no callback action. A callback that validates or converts a value becomes a type= function, and one with side effects becomes a custom Action subclass. The agent ports each one individually and adds a test for it, since callbacks are where the two libraries differ most.

Does it handle abbreviated long options?

Both parsers accept an unambiguous prefix such as --out for --out-dir, so existing abbreviations keep working. The agent includes one abbreviated call in its table to confirm that for your options, and mentions allow_abbrev=False only as an option you could choose later.

More jobs like this: Hand off a long task

Keep reading