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