Methods on pathlib.PosixPath() and other objects that alter files on the file system should return new object instances with new information. For example, if there exists a file on the system called 'bar', then

bar_var = pathlib.PosixPath('bar')
bar_var.rename('foo')

will rename the file 'bar' to 'foo' on the system and leave 'bar' as a still-valid object that no longer points to a system file. Changing the return type of .rename() to return a new pathlib.PosixPath() object with path 'foo' could help reduce confusion about the behavior. For example:

bar_var = pathlib.PosixPath('bar')
foo_var = bar_var.rename('foo')

and foo_var would then be a pathlib.PosixPath() object pointing to 'foo'.

The idea in general seems reasonable. Anyone else have an opinion?

Path.rename() is simple wrapper around os.rename() and returns the result of os.rename(). If os.rename() became returning something useful, this change will made impossible to return it from Path.rename().

Why not create destination Path object explicitly?

    bar_var = pathlib.PosixPath('bar')
    foo_var = pathlib.PosixPath('foo')
    bar_var.rename(foo_var)

Note, that in 3.6 you can also write

    os.rename(bar_var, foo_var)

If Path.rename() were made to be slightly more than a wrapper around os.rename(), then any future changes to the return value of os.rename() could be taken into consideration in the return value of Path.rename(). I don't see how anything would become impossible then.

Creating the destination Path object explicitly is my solution right now. Since it had become such a pattern in my code, I figured it could be delegated up to the level of the Path object and make for cleaner looking code.