# Exercise: Downloads Sorter

Finish a command-line tool that sorts a folder's files into Photos, Documents, Installers and Archives, planning the moves first, showing them with --dry-run, and never replacing or deleting a file, while pytest checks each step on folders it builds for itself.

Journeyman · Python · Updated November 19, 2026

By Gregor Dzierzon

A Downloads folder fills up with vacation photos, receipts, installers and zip files until nothing can be found in it. You'll finish the Downloads Sorter: a command-line tool that moves each file into a folder for its type, `Photos`, `Documents`, `Installers` or `Archives`. It plans first, shows the plan with `--dry-run`, and never puts a file on top of another or deletes one. It works on a practice folder that comes with the exercise, never on your real Downloads folder, and the tests build their own small folders in a temporary place.

## Get the exercise code

Open this lesson's GitHub repository, [github.com/ask-codey/exercise-python-downloads-sorter](https://github.com/ask-codey/exercise-python-downloads-sorter), also linked from the **Exercise** box beside the lesson. Clone it into your `python-course` folder. In VS Code's terminal:

```bash
cd ~/python-course
git clone https://github.com/ask-codey/exercise-python-downloads-sorter.git
```

Git makes a folder, `exercise-python-downloads-sorter`, with the exercise code inside. Open that folder in VS Code (**File > Open Folder**), open its terminal with **Terminal > New Terminal**, and make the exercise's virtual environment. On Windows (PowerShell):

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

On a Mac (zsh):

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

The prompt starts with `(.venv)` once the virtual environment is on. The exercise's README says what each command does, and what to do if PowerShell won't run the second one.

The folder holds:

- `sorter.py`: the tool, for you to finish. `FOLDERS`, which says where each type of file goes, is ready.
- `make_practice.py`: makes `practice-downloads`, a practice folder of eleven small files, one of them in a folder named `Old stuff`. Ready to use.
- `tests/test_sorter.py`: the tests. Each one builds its own small folder in a temporary folder pytest makes (`tmp_path`), calls your functions, and checks what they return, print and move. You don't need to change it.
- `requirements.txt` and `pytest.ini`: the package the tests need, and where pytest finds the tests and your code.

## What to do

The four functions in `sorter.py` are declared with their names and parameters, and for now each stops with a `NotImplementedError` that says *Not built yet.* The docstring under each one says what it should do, with examples. Finish them in order, because each one uses the one before:

1. **`category_for(path)`** returns the folder a file belongs in, looked up in `FOLDERS` by its extension, such as `"Photos"` for `beach-day.jpg`. Capital letters don't matter (`SUNSET.JPG` is a photo too), and a type that isn't in `FOLDERS` gets `None`: it stays where it is.
2. **`plan_moves(folder)`** returns the moves that would tidy `folder`, as a list of `(source, destination)` pairs in alphabetical order, where the destination is `folder / category / name`. It looks only at the files directly in `folder`, leaves out a file whose category is `None` or whose destination is already taken, and changes nothing.
3. **`apply_moves(moves, dry_run)`** goes through the pairs. With `dry_run` true it prints `Would move beach-day.jpg to Photos` for each and changes nothing; otherwise it makes the folder, moves the file and prints `Moved beach-day.jpg to Photos`. A destination that's already taken prints `Skipped beach-day.jpg: Photos already has one` and moves nothing. It returns how many files moved, or would move.
4. **`main(argv=None)`** reads a positional argument, `folder`, and a `--dry-run` flag with `argparse`, then plans the moves and applies them. A folder that isn't there prints `No folder named ...` and moves nothing. Its last line is `Files that would move: 9` in a dry run, or `Files moved: 9`.

Nothing in the tool deletes a file, and nothing should.

## Check your work

Run the tests from the exercise folder, with the virtual environment on:

```bash
pytest
```

At first all 17 tests fail. That's expected: each function you finish turns its tests green. A failing test's message says what it called, what it expected and what came back.

To see the tool at work on the practice folder, make the folder, look at the plan, then sort it:

```bash
python make_practice.py
python sorter.py practice-downloads --dry-run
python sorter.py practice-downloads
```

## Hints

- **Lowercase the extension first.** `path.suffix` of `SUNSET.JPG` is `.JPG`; `.lower()` turns it into a key `FOLDERS` has. `FOLDERS.get(...)` gives `None` for a key that isn't there. *Paths and Folders with pathlib* shows a path's parts.
- **Plan with paths, not text.** `folder / category / file.name` builds the destination, and `exists()` says whether it's taken. `is_file()` tells a file from a folder.
- **The folder's name comes from the destination.** `destination.parent.name` is `Photos` for `.../Photos/beach-day.jpg`, which is what the printed lines need.
- **Make the folder before the move.** `mkdir(parents=True, exist_ok=True)` makes it when it's missing and does nothing when it's there. *Copying, Moving and Renaming Files Safely* shows the checks and the dry run.
- **Hand `parse_args` the list.** `parser.parse_args(argv)` reads the tests' list, and the terminal's words when `argv` is `None`. *Command-Line Options with argparse* shows the flag.

## When you're done

Every test is green: pytest's last line says `17 passed`. On the practice folder, the dry run shows the plan and moves nothing:

```text
practice-downloads is ready: 11 files added.
Would move beach-day.jpg to Photos
Would move canyon-hike.JPG to Photos
Would move family-reunion.png to Photos
Would move grocery-receipt.pdf to Documents
Would move hardware-receipt.pdf to Documents
Would move meeting-notes.docx to Documents
Would move packing-list.txt to Documents
Would move photo-editor-setup.exe to Installers
Would move vacation-photos.zip to Archives
Files that would move: 9
```

Then `python sorter.py practice-downloads` prints the same nine lines with `Moved` instead of `Would move`, and `Files moved: 9`. `budget-2026.xlsx` and the `Old stuff` folder stay where they were.

Now run `python make_practice.py` again, which puts nine fresh files with the same names in the folder, and run the dry run once more. It says `Files that would move: 0`. Why does it plan no moves at all, and what would `shutil.move` have done to the photos already in `Photos` without your `exists()` checks?

To run the sorter every week, *Running a Script on a Schedule* shows the steps.

## Submit your exercise

The exercise is how you finish this lesson. When your work is done, put it on GitHub in a repo of your own, then submit that repo's address here. *Hand In Your Work with Git* walks through each step.

1. On GitHub, click **+**, then **New repository**. Name it (for example `exercise-python-downloads-sorter`), choose **Public**, and click **Create repository**. Leave out the README: your folder already has one.
2. In VS Code's terminal, in your exercise folder, send your work to your new repo. Point your copy at your own repo, then commit and push:

   ```bash
   git remote set-url origin https://github.com/your-name/exercise-python-downloads-sorter.git
   git add .
   git commit -m "My solution"
   git push -u origin main
   ```

3. Paste your repo's address, such as `https://github.com/your-name/exercise-python-downloads-sorter`, into **Submit your exercise** on this page. The site checks that the repo is public and holds your commits, and then the lesson is complete.

Changed something after you submitted? Push it, and submit again: your latest submission is the one that counts.

## So what

A tool that plans before it acts, shows the plan on request and refuses to overwrite is one you can point at a real folder, and the same shape fits every chore you'll automate next.

## Key terms

- [pathlib](https://www.ask-codey.com/glossary/pathlib)
- [shutil](https://www.ask-codey.com/glossary/shutil)
- [argparse](https://www.ask-codey.com/glossary/argparse)
- [Dry run](https://www.ask-codey.com/glossary/dry-run)
- [pytest](https://www.ask-codey.com/glossary/pytest)

## Related

- [Paths and Folders with pathlib](https://www.ask-codey.com/lessons/python-automation-paths-with-pathlib)
- [Copying, Moving and Renaming Files Safely](https://www.ask-codey.com/lessons/python-automation-copy-move-rename)
- [Command-Line Options with argparse](https://www.ask-codey.com/lessons/python-automation-command-line-arguments)
- [Running a Script on a Schedule](https://www.ask-codey.com/lessons/python-automation-scheduled-jobs)

Source: https://www.ask-codey.com/lessons/exercise-python-downloads-sorter
