GH-73991: Make `pathlib.Path.delete()` private. by barneygale · Pull Request #123315 · python/cpython

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"...