# 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 Rush](https://cloud.getrush.ai/run/migrate-appdirs-to-platformdirs/appdirs/). Opens 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`

```json
{
  "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.

## 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

- [Migrate From atty to std::io::IsTerminal in Rust](https://getrush.ai/run/migrate-atty-to-is-terminal/atty/)
- [Migrate From AWS SDK for Go v1 to v2](https://getrush.ai/run/migrate-aws-sdk-go-v1-to-v2/aws-sdk-go/)
- [Migrate AWS SDK for JavaScript v2 to v3 in an Express S3 App](https://getrush.ai/run/migrate-aws-sdk-v2-to-v3/aws-sdk/)
- [Replace Axios With Native fetch in a Node.js Library](https://getrush.ai/run/migrate-axios-to-fetch/axios/)
- [Migrate From babel-eslint to @babel/eslint-parser](https://getrush.ai/run/migrate-babel-eslint-to-babel-eslint-parser/babel-eslint/)
- [Migrate a Go Project From Blackfriday to goldmark](https://getrush.ai/run/migrate-blackfriday-to-goldmark/blackfriday/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
