pathlibPathrename

PathlibPathrename refers to the rename operation provided by Python's pathlib module, typically used through Path.rename. It moves or renames a filesystem object to a new path and returns the destination path. This operation is designed for use within the same filesystem and is implemented as a method on Path instances.

Behavior and limitations: Path.rename will raise FileNotFoundError if the source does not exist and FileExistsError if the destination already exists. The exact behavior can vary by platform; for example, cross-file-system moves may fail on some systems. On Windows, renaming across drives or changing an object type may require different handling than on POSIX systems.

PathlibPathrename vs Path.replace: If you need to overwrite an existing destination, the Path.replace method provides semantics similar to os.replace, replacing the target if it exists. Path.replace is the preferred option when overwriting is desired, while Path.rename preserves the existing destination and raises an error instead.

Usage example: from pathlib import Path; p = Path('old_name.txt'); p.rename('new_name.txt'). This renames the file if the destination does not already exist. To overwrite, use Path('old').replace(Path('new')) or Path('new').replace('existing') depending on the context.

Exceptions and safety: Common exceptions include FileNotFoundError, FileExistsError, PermissionError, and NotADirectoryError. It is advisable to check that the source exists and that the destination does not (or handle the exception) and to consider permissions and potential race conditions in multi-process contexts.

See also: pathlib module, os.rename, os.replace, shutil.move.