GH-73991: Add pathlib.Path.copytree()

[barneygale]

Add pathlib.Path.copytree() method, which recursively copies one directory to another.

This differs from shutil.copytree() in the following respects:

1. Our method has a follow_symlinks argument, whereas shutil's has a symlinks argument with an inverted meaning.
2. Our method lacks something like a copy_function argument. It always uses Path.copy() to copy files.
3. Our method lacks something like a ignore_dangling_symlinks argument. Instead, users can filter out danging symlinks with ignore, or ignore exceptions with on_error
4. Our ignore argument is a callable that accepts a single path object, whereas shutil's accepts a path and a list of child filenames.
5. We add an on_error argument, which is a callable that accepts an OSError instance. (Path.walk() also accepts such a callable). This is done instead of aggregating exceptions into an shutil.Error instance.

• Issue: Support moving across filesystems in pathlib.Path, as shutil.move() does #73991

---

📚 Documentation preview 📚: https://cpython-previews--120718.org.readthedocs.build/

[barneygale]

Some parts of the design aren't obvious, particularly the ignore and on_error arguments. Happy to adjust or even remove some arguments if we'd like to kick the can down the road - I don't think either of those arguments are essential to expose straight away.

[barneygale]

@pfmoore I've requested your review as you've already given this idea some scrutiny on the forum! Hope that's alright, thank you.

[pfmoore]

The code LGTM. I've dome a partial review of the tests, but I'll be honest I'm not entirely clear what the follow_symlinks argument does (it's not something I use myself) so I didn't really review those parts of the tests.

I'll try to find some time to do a more detailed review later.

[barneygale]

Thanks for the reviews and fixes, both.

I'm not entirely clear what the follow_symlinks argument does (it's not something I use myself) so I didn't really review those parts of the tests.

The default behaviour (follow_symlinks=True) dereferences any symlinks in the source tree, so the final destination tree never contains symlinks. If you set follow_symlinks=False, any symlinks in the source tree will be re-created in the destination tree with the same targets.

Our forthcoming implementation of Path.move() will call source.copytree(target, follow_symlinks=False) then source.rmtree() (roughly), because users expect "move" operations to preserve symlinks (not follow them).

[pfmoore]

Thanks for the explanation - that's the clearest I've seen it expressed, and for the first time (possibly ever) I get what's going on.