The shutil Module in Python

The shutil module in Python is a powerful utility for high-level file operations, such as copying, moving, and removing files and directories. It also provides functions for managing disk space and archiving. This article will explore the various functionalities of the shutil module, providing examples to illustrate its usage.

Overview of the shutil Module

The shutil module offers a range of functions that simplify tasks related to file and directory management. Some of the key functions include:

• shutil.copy()
• shutil.copy2()
• shutil.copyfile()
• shutil.copytree()
• shutil.move()
• shutil.rmtree()
• shutil.disk_usage()
• shutil.make_archive()

Let’s delve into each of these functions.

Copying Files

shutil.copy()

The shutil.copy() function copies the contents of a source file to a destination file. It also preserves the source file’s permissions.

import shutil

# Copying a file
shutil.copy('source.txt', 'destination.txt')

In this example:

• The contents of source.txt are copied to destination.txt.
• If destination.txt already exists, it will be overwritten.

shutil.copy2()

The shutil.copy2() function is similar to shutil.copy() but also attempts to preserve metadata such as timestamps.

import shutil

# Copying a file with metadata
shutil.copy2('source.txt', 'destination.txt')

shutil.copyfile()

The shutil.copyfile() function copies the contents of a source file to a destination file but does not preserve metadata or permissions.

import shutil

# Copying a file without metadata or permissions
shutil.copyfile('source.txt', 'destination.txt')

Copying Directories

shutil.copytree()

The shutil.copytree() function recursively copies an entire directory tree rooted at the source to a destination directory.

import shutil

# Copying a directory
shutil.copytree('source_directory', 'destination_directory')

In this example:

• The entire directory source_directory and its contents are copied to destination_directory.

You can also specify a custom copy function using the copy_function parameter:

import shutil

# Copying a directory with a custom copy function
shutil.copytree('source_directory', 'destination_directory', copy_function=shutil.copy2)

Moving Files and Directories

shutil.move()

The shutil.move() function moves a file or directory to a new location.

import shutil

# Moving a file or directory
shutil.move('source.txt', 'destination_directory/')

In this example:

• source.txt is moved to destination_directory/.
• If the destination is an existing directory, the source file is moved inside it.

Removing Files and Directories

shutil.rmtree()

The shutil.rmtree() function deletes an entire directory tree.

import shutil

# Removing a directory tree
shutil.rmtree('directory_to_remove')

In this example:

• The directory directory_to_remove and all its contents are deleted.

Managing Disk Usage

shutil.disk_usage()

The shutil.disk_usage() function returns the total, used, and free space on a disk.

import shutil

# Getting disk usage statistics
usage = shutil.disk_usage('/')
print(f"Total: {usage.total // (2**30)} GiB")
print(f"Used: {usage.used // (2**30)} GiB")
print(f"Free: {usage.free // (2**30)} GiB")

In this example:

• Disk usage statistics for the root directory ('/') are printed in GiB.

Archiving

shutil.make_archive()

The shutil.make_archive() function creates an archive (e.g., ZIP or TAR) from a directory.

import shutil

# Creating a ZIP archive
shutil.make_archive('archive_name', 'zip', 'directory_to_archive')

In this example:

• A ZIP archive named archive_name.zip is created from the contents of directory_to_archive.

You can also specify the format of the archive (e.g., 'tar', 'gztar', 'bztar', 'xztar'):

import shutil

# Creating a TAR archive
shutil.make_archive('archive_name', 'tar', 'directory_to_archive')

Extracting Archives

While shutil itself does not provide functions to extract archives, you can use the tarfile and zipfile modules in Python for this purpose.

Extracting a ZIP Archive

import zipfile

# Extracting a ZIP archive
with zipfile.ZipFile('archive_name.zip', 'r') as zip_ref:
    zip_ref.extractall('destination_directory')

Extracting a TAR Archive

import tarfile

# Extracting a TAR archive
with tarfile.open('archive_name.tar', 'r') as tar_ref:
    tar_ref.extractall('destination_directory')

Practical Examples

Example: Backup and Restore

This example demonstrates how to use shutil to create a backup of a directory and then restore it.

import shutil
import os

# Backup directory
source_dir = 'important_data'
backup_dir = 'backup'

# Create a backup
shutil.copytree(source_dir, backup_dir)

# Make some changes (e.g., delete the original directory)
shutil.rmtree(source_dir)

# Restore the backup
shutil.copytree(backup_dir, source_dir)

Example: Disk Space Monitoring

This example shows how to monitor disk space usage and trigger an alert if free space falls below a threshold.

import shutil

# Threshold in bytes
threshold = 10 * (2**30)  # 10 GiB

# Get disk usage statistics
usage = shutil.disk_usage('/')

# Check if free space is below the threshold
if usage.free < threshold:
    print("Warning: Low disk space!")
else:
    print("Disk space is sufficient.")

The shutil module in Python is a versatile and essential tool for file and directory operations. Whether you’re copying, moving, or removing files and directories, managing disk usage, or creating and extracting archives, shutil provides a comprehensive set of functions to handle these tasks efficiently.