All jobs

Replace appdirs With platformdirs in a Python Package

Yes. An agent swaps the deprecated appdirs for platformdirs and proves each directory your code asks for resolves to the same path on Linux, macOS and Windows.

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

What the agent does

appdirs has had no release since 1.4.4 in May 2020 and its maintainers point users to platformdirs, the fork that kept the same function names. The code change is small. The promise that needs checking is that nobody's files move: a cache, config or log directory that resolves somewhere new looks to a user like lost settings. So the agent starts by listing each call and its arguments. In a package like KimiNewt/pyshark there is one, in src/pyshark/cache.py: appdirs.user_cache_dir(appname="pyshark", version=tshark_version), wrapped in pathlib.Path and created on first use. ek_field_mapping.py stores a JSON mapping there per tshark version, and clear_cache removes the directory with shutil.rmtree.

The package name appears in more places than the import. install_requires in src/setup.py lists appdirs, the root requirements.txt lists it for development, and src/tox.ini lists it under deps. The agent changes all three with the import, since a file left behind keeps installing a library nothing uses. It does not pin a version without a reason. Current platformdirs releases require a newer Python than the oldest one this project tests in .github/workflows/test.yml, and pip handles that by choosing an older release on an older interpreter. The agent reads the release metadata to confirm that the release each supported Python would receive still has every function the code calls.

Then it compares paths. With both libraries installed in one environment it calls every directory function the project uses, with the project's own arguments, and prints the old and new result. A Linux sandbox gives the Linux answer directly. For macOS and Windows it evaluates each library's platform-specific code path with the home and AppData locations supplied by hand, and labels those rows as computed on Linux, not observed on the real system. For this project's call the three results agree: the versioned folder under ~/.cache/pyshark on Linux, under ~/Library/Caches/pyshark on macOS, and under AppData\Local\pyshark\pyshark\Cache on Windows.

It runs the comparison for the functions the project does not call as well and adds the one row that differs, because the next contributor will reach for it. On Linux user_log_dir moves from ~/.cache/<app>/log under appdirs to ~/.local/state/<app>/log under platformdirs. pyshark never calls it, so nothing changes here, and a project that does call it gets a line in the pull request and a choice: keep the old location explicitly, or move and migrate existing files. Last, the agent installs tshark the way the workflow does and runs python -m pytest -v before and after.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Replace the appdirs package with platformdirs in this Python project. First list every import of appdirs and every call, with its exact arguments (appname, appauthor, version, roaming, multipath) and what the code stores in the returned directory. List every other place the package is named: setup.py or pyproject, requirements files, tox.ini, conda environment files, CI workflows, docs and type stub packages such as types-appdirs. Run the existing tests and save the output; install any system tool the CI workflow installs first. Before editing, install both libraries in one environment and write a throwaway script that calls each directory function this project uses, with this project's arguments, through both libraries, and prints both paths and whether they are equal. Do it for Linux directly, and for macOS and Windows by evaluating each library's platform-specific implementation with the home, LOCALAPPDATA and APPDATA locations supplied by hand; label those rows as computed, not observed. Also run it for user_data_dir, user_config_dir, user_cache_dir, user_state_dir, user_log_dir and site_data_dir whether or not the project calls them, and report any row that differs. If a directory the project actually uses would move on any platform, stop and report it with both paths instead of changing the dependency. Otherwise make the change everywhere the package is named, keeping the same function calls. Read the Python versions the project supports from its classifiers, tox envlist and CI matrix, find which platformdirs release pip would select on the oldest one, and confirm that release has every function the code calls; add a lower bound only if one is needed and say why. Run the tests again. Do not commit the comparison script; put its output in the pull request. 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 four small edits: the import and call in src/pyshark/cache.py, install_requires in src/setup.py, the development list in requirements.txt, and deps in src/tox.ini. The body of get_cache_dir reads the same as before with one module name changed.

The description carries the path table: one row per function and platform with the appdirs path, the platformdirs path and an equal or different mark, and a column saying whether the row was run on that system or computed. The reviewer looks first at the rows for functions the code calls, which must all be equal, then at the note on user_log_dir. They also check the paragraph on Python versions, which names the platformdirs release each interpreter in the test matrix would get and confirms user_cache_dir exists in the oldest.

Test output from before and after is attached. tests/test_ek_field_mapping.py replaces the cache module with a mock that points at tests/data, so the suite does not exercise the real cache path at all; the description says so, and that is why the path table, not the green test run, is the evidence for this change. The session's changes read shows the same diff the pull request does.

Run it on every Monday morning

This is a good job for a standing dependency sweep. In the Project for a repository, add an automation with a schedule trigger, a cron for Monday morning in your time zone, and a prompt that asks the agent to look for dependencies whose maintainers have declared them deprecated in favour of a named successor, starting with this one. Each fire starts a run with that prompt; when the swap is already merged, the run reports that nothing is left and opens no pull request.

To cover many repositories in one pass, call POST /o/{org}/sessions from a script with this body, once per repository, each with its own request_id as a UUID v5 of the repository name. Runs past the key's max_concurrent wait as queued and start in order.

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

Why run it on Rush?

A developer making this change on a Mac sees one platform's path and assumes the rest. The run evaluates all three, with both libraries side by side in a fresh environment, and the script's output is kept in the session's transcript. The reviewer does not have to trust a sentence that says the paths match; the table shows each pair.

It also runs the project's real test command with the system tool the workflow installs, which here is tshark, on a machine set up for this run alone. Nothing about a contributor's laptop leaks into the result: no leftover cache directory from an earlier version to make a first-use bug disappear, and no globally installed appdirs to keep a missed import working.

Frequently asked questions

Is platformdirs a drop-in replacement for appdirs?

For the function API, yes: user_data_dir, user_cache_dir, user_config_dir and the rest take the same arguments, so most projects change one import. The returned paths are mostly identical too. The agent checks the ones your code uses on each platform before it changes the dependency.

Will my users' existing cache or config files be found after the switch?

If the path table shows equal for every function you call, yes, because the directory is the same string. Where a row differs the agent stops and reports both paths. You then decide between passing the old location explicitly and writing a one-time move.

Which paths differ between the two libraries?

In the comparison this page describes, the log directory on Linux: appdirs puts it under the cache directory and platformdirs under the state directory. Data, config, cache and state directories matched on Linux, macOS and Windows for a plain appname. Results depend on the versions installed, which is why the run prints them.

Do I need to pin platformdirs for old Python versions?

Usually not. Each platformdirs release declares the Python versions it supports, and pip selects the newest release that fits the interpreter. A pin is only needed if your code calls something added after the release your oldest Python receives.

More jobs like this: Upgrade dependencies weekly

Keep reading