[docs] [issue31154] Path.replace and Path.rename naming, behavior and documentation

[Alberto Gomez-Casado]

New submission from Alberto Gomez-Casado:

I find the naming of Path.replace quite unfortunate, coming from the os.path and basestring mindset, the expectation would be that it would change some substring by another substring in the Path instance. Instead, it _moves_ the file indicated by the Path object in the file system. Most of the methods of Path have no effect in the filesystem, and we have here one with a slightly misleading name which goes and moves your files around.

Practically the same operation is done with Path.rename, which is less surprising since it matches popular OS commands/UIs (ren, Rename).

IMHO Path.replace should not exist as is and a keyword modifier (silent?) for Path.rename toggles between the minor behavior differences of the two. 

Additionally:

Both calls lack any kind of return, which leads me to expect after a rename/replace the Path instance would be changed to the new path. This is not the case, after the call the Path instance keeps "pointing" to the previous (and quite likely now useless) path. Returning the new path would be another reasonable option. In any case, I think the documentation should mention this behavior explicitly. 

And, while we are at it, having implemented the relatively dangerous replace/rename (along with convenience shorcuts for reading, writing, opening...), why was a Path.copy not included?

----------
assignee: docs at python
components: Documentation, Library (Lib)
messages: 299976
nosy: Alberto Gomez-Casado, docs at python
priority: normal
severity: normal
status: open
title: Path.replace and Path.rename naming, behavior and documentation
type: behavior
versions: Python 3.6

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue31154>
_______________________________________