Day: May 17, 2024

The shutil Python Module

The shutil module in Python, part of the standard utility modules, provides a number of high-level operations on files and collections of files. This module comes in handy especially for tasks involving copying and archiving files and directory trees. Here’s an overview of some of the key functionalities offered by shutil:

1. Copying Files and Directories

  • shutil.copy(src, dst): Copies the file src to the file or directory dst. If dst specifies a directory, the file will be copied into dst using the base filename from src.
  • shutil.copy2(src, dst): Similar to shutil.copy, but copy2 also attempts to preserve all file metadata.
  • shutil.copytree(src, dst): Recursively copies an entire directory tree rooted at src to a directory named dst and attempts to preserve metadata. This function also offers the ability to ignore certain files or directories during the copy process with the ignore argument.

2. Moving Files and Directories

  • shutil.move(src, dst): Recursively moves a file or directory (src) to another location (dst). If the destination is on the current filesystem, then os.rename() is used. Otherwise, src is copied to dst using copy2() and then removed.

3. Deleting Files and Directories

  • shutil.rmtree(path): Recursively deletes a directory tree; path must point to a directory (but not a symbolic link to a directory).

4. Disk Usage

  • shutil.disk_usage(path): Returns disk usage statistics about the given path as a named tuple with the attributes total, used, and free, which represent the total, used, and free disk space in bytes, respectively.

5. Archiving Operations

  • shutil.make_archive(base_name, format, root_dir): Create an archive file (such as zip or tar) and return its name. base_name is the name of the file to create, including the path, minus any format-specific extension. format is the archive format: one of “zip”, “tar”, “gztar”, “bztar”, or “xztar”.
  • shutil.unpack_archive(filename, extract_dir, format): Unpacks an archive. filename is the full path of the archive file, extract_dir is the directory to unpack into, and format is the archive format.

6. File Metadata

  • shutil.chown(path, user=None, group=None): Changes the owner and/or group of the given path to the numeric user and group ids.
  • shutil.which(cmd): Similar to the Unix which command, it returns the path to an executable which would be run if the given cmd were called. If no cmd is found, returns None.

Example of Copying a File

Here’s a simple example of how to use shutil to copy a file:

import shutil

# Copy src file to dst file. The destination can be a directory.
shutil.copy('path/to/source/file.txt', 'path/to/destination/file.txt')

Example of Removing a Directory Tree

import shutil

# Recursively delete a directory tree
shutil.rmtree('path/to/directory')

The shutil module is very powerful for managing files and directories in Python, providing a higher-level interface that’s easier to use for complex operations compared to the os module that handles similar tasks at a lower level.