All jobs

Replace the mock Backport With unittest.mock

Yes. An agent replaces the third-party mock package with unittest.mock, fixes the import order your linter enforces and drops the test dependency.

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

What the agent does

The mock package on PyPI is a backport of unittest.mock for interpreters that lack a recent one. A project that only supports Python 3 can import the standard library's copy and delete a test dependency. The agent's first step is to separate the third-party import from everything else spelled the same way, and in some repositories that takes care. In StackStorm/orquesta, a search for mock returns hundreds of lines, because the package has its own orquesta/specs/mock and orquesta/composers/mock.py, a mock = orquesta.composers.mock:WorkflowComposer entry point in setup.py, and a house rule in orquesta/tests/hacking/import_aliases_rule.py that those modules are imported as mock_specs and mock_models. The third-party package is imported in exactly one file, orquesta/tests/unit/commands/test_rehearse_command.py, as a bare import mock, and pinned as mock==4.0.3 in requirements-test.txt.

The edit is one line, from unittest import mock, and every mock.patch.object and mock.MagicMock below it keeps working. The lint configuration is what makes it more than one line. This project runs flake8 with the OpenStack hacking plugin, and replacing the line where it stands fails with H306: imports not in alphabetical order (unittest.mock, unittest), because the file already has import unittest on the next line. The agent moves the new import below it, then runs the three commands the pep8 environment in tox.ini runs: pylint -E, flake8 --config .flake8 and black --check -l 100.

The same plugin has a rule for this exact migration. H216 reports any import of the third-party package with the message that the unittest.mock module should be used instead, and .flake8 in this repository lists H216 under ignore. Once the last import is gone the exemption has no reason to exist. The agent removes H216 from ignore, adds it to enable-extensions, and runs flake8 over the whole orquesta package to confirm nothing else trips it. From then on a new import mock fails lint instead of quietly bringing the dependency back.

Last, it proves the dependency is unused by removing it. It deletes the mock==4.0.3 line, uninstalls the package from the environment, and runs the seven tests in the rehearsal command file and then the suite, on each interpreter in the tox.ini envlist: 3.10, 3.11 and 3.12. That matrix matters because the standard library's mock is not frozen at the backport's behaviour. On Python 3.12, reading called_once_with or has_calls from a mock raises AttributeError with the text is not a valid assertion, where mock 4.0.3 returns a child mock and lets a mistyped check pass. The agent searches the tests for those names and reports any it finds as assertions that were never checking anything.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Replace the third-party mock package with the standard library's unittest.mock in this Python project. First confirm every supported Python version is 3.x by reading setup.py or pyproject.toml, tox.ini and the CI matrix; if Python 2 is still supported, stop and report. Find the imports of the third-party package (import mock, from mock import ...) and keep them apart from the project's own modules, fixtures or entry points that happen to be named mock. Rewrite each import to unittest.mock, keeping the local name the file already uses so the test bodies do not change. Read the lint configuration: place the new import where the project's import-order rule wants it, and if the config ignores a rule that exists to forbid the third-party mock import, such as hacking's H216, enable that rule and show the linter passing on the whole package. Remove mock from every requirements file and from tox or CI install steps, uninstall it from the environment, and run the test suite and the project's lint commands on each Python version in the tox envlist. Search the tests for mock attributes that look like assertions but are not, such as called_once_with, has_calls or not_called used without the assert_ prefix, and report each with file and line; fix only the ones that are plainly typos of a real assertion and say what the corrected assertion found. Open a pull request with the lint and test output for each version.",
  "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 three small diffs: the import in test_rehearse_command.py, the deleted line in requirements-test.txt, and .flake8 with H216 moved from ignore to enable-extensions. The description shows the flake8 failure from the naive placement and the clean output after, the lint and test results per interpreter, and the line proving the package is gone from the environment the tests ran in.

The reviewer checks that no file under orquesta/specs/mock or orquesta/composers was touched, since those are product code that only share the name, and that the entry point in setup.py is unchanged. They read the per-version results rather than one summary line, because a mock-related difference would show on 3.12 first. If the search for assertion look-alikes finds something, it is listed as its own section with the test's name, so it can be fixed in this pull request or split out.

Run it on every GitHub issue labelled tech-debt

Backports outlive the interpreters they were written for, and removing one is the sort of issue that sits in a backlog for a year. Add an automation to the Project with a github trigger on issues.labeled and your label in its labels setting, and save the prompt above. When a repository owner, member or collaborator adds the label, a run starts, and the event is placed after the prompt as third-party data.

Because the prompt names the package, this automation does one job. For a general version, change its first sentence to ask for whichever backport the issue names, and keep the rest: the check that Python 2 is gone, the lint rule and the per-version test run apply to mock, typing and enum34 alike. A label applied by a bot never starts a run.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

A one-line import change is easy to make and easy to get subtly wrong three ways: in the wrong position for the linter, on one interpreter only, or with the package still installed so the old import would have kept working anyway. The run checks all three in its own sandbox, with three Python versions installed and the dependency removed, and the output of every command is kept with the session.

It also turns the change into a rule. Enabling H216 is the difference between cleaning up once and never having to again, and the run shows the rule passing on the whole package before the pull request asks anyone to trust it. A reviewer gets a diff of a few lines and the evidence for each of them.

Frequently asked questions

Is unittest.mock the same as the mock package?

They are the same code at different ages. mock is a rolling backport of the standard library module, so mock 4.0.3 matches the standard library of the Python version it was cut from, and your interpreter's own copy may be newer. patch, MagicMock, call and ANY have the same names in both.

Can I mix both in one test suite during the migration?

It works but invites confusion: mock.Mock and unittest.mock.Mock are different classes, so an isinstance check against one fails for objects made by the other. The agent converts every import in one pull request and removes the package, which leaves no mixed state.

What if my project still supports Python 2?

Then the backport is doing its job and should stay, usually behind a try and except ImportError pair. The prompt has the agent read the supported versions first and stop with a report if Python 2 is among them. Dropping Python 2 is a separate decision with its own pull request.

Why did a test start failing on Python 3.12 after the switch?

Most likely it read an attribute such as called_once_with from a mock without the assert_ prefix. Python 3.12's unittest.mock raises AttributeError for those names, while older versions and the 4.0.3 backport returned a new mock, so the line passed without checking anything. The failure is the test telling you it never asserted.

More jobs like this: Upgrade dependencies weekly

Keep reading