[New-bugs-announce] [issue27886] Docs: the difference between rename and replace is not obvious

[Andrew Svetlov]

New submission from Andrew Svetlov:

Hi.

On reading the doc for pathlib I've stuck with `.rename()` and `.replace()` (https://docs.python.org/3/library/pathlib.html#pathlib.Path.rename).

What's the difference?

Going to pathlib's source code I've figured out that methods are use different functions from `os` module: `os.rename()` and `os.replace()`.

But the documentation for `os` module is not obvious too: 
the docs for both functions are almost equal from my perspective, the only significant difference is that `os.rename()` suggests to use `os.replace()` for cross-compatibility.

Could anybody explain the difference?

Also, at least the doc for `pathlib.Path.rename` worth to have a sentence like borrowed from `os.rename`: "If you want cross-platform overwriting of the destination, use replace()."

----------
assignee: docs at python
components: Documentation
keywords: easy
messages: 273836
nosy: asvetlov, docs at python, pitrou
priority: low
severity: normal
status: open
title: Docs: the difference between rename and replace is not obvious
type: behavior
versions: Python 3.4, Python 3.5, Python 3.6

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue27886>
_______________________________________