GH-73991: Make pathlib.Path.delete() private.

[barneygale]

Per feedback from Paul Moore on GH-123158, it's better to defer making Path.delete() public than ship it with under-designed error handling capabilities.

We leave a remnant _delete() method, which is used by move(). Any functionality not needed by move() is deleted.

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

---

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

[barneygale]

The primary reason why I don't want to expose on_error is that it makes it harder to write a compatible implementation of delete() in a future user subclass of PathBase. Any algorithmic deviation would result in an observable change in how/when the error handler is called, even if the end result is the same. If we keep a delete() method with an on_error handler, I'd feel I'd boxed myself into a corner.

[pfmoore]

Any algorithmic deviation would result in an observable change in how/when the error handler is called, even if the end result is the same.

Ah. I hadn't appreciated that was your concern. I think it's a valid reason to be cautious, but I suspect it's something that we won't be able to do anything about. In the medium term, we may be best simply documenting our way out of the issue - stating in the API docs that users cannot rely on when, if or how on_error will be called, just that if it's called, an error will have occurred, and if the operation completes without on_error being called, then no errors occurred that the implementation couldn't automatically handle. Long term, maybe we'll be able to give tighter API guarantees, but let's not hold up implementing something useful in order to wait for that. And yes, some people will rely on implementation details and be caught out, but we can't do anything about that beyond say "we told you so"...