rclone-python

You can install rclone-python via pip. Note that rclone must be installed on your system for this wrapper to function.

pip install rclone-python

You can pass a rich.progress.Progress instance to transfer operations (like copy) via the pbar argument to customize the visual output.

from rclone_python import rclone
from rich.progress import (
    Progress,
    TextColumn,
    BarColumn,
    TaskProgressColumn,
    TransferSpeedColumn,
)

pbar = Progress(
    TextColumn("[progress.description]{task.description}"),
    BarColumn(),
    TaskProgressColumn(),
    TransferSpeedColumn(),
)

rclone.copy("data", "box:rclone_test/data1", pbar=pbar)

Use rclone.set_log_level(level) to change the logging verbosity. Setting it to logging.DEBUG will cause the wrapper to print the raw rclone progress output.

rclone.set_log_level(logging.DEBUG)

Use rclone.purge() to remove an entire directory including all files, subdirectories, and the directory itself.

from rclone_python import rclone

# remove the entire test_dir folder (and all files contained in it and it's subdirectories) on onedrive
rclone.purge('onedrive:test_dir')

Use rclone.hash() to generate hashes for files. Pass a hash type from HashTypes (e.g., HashTypes.sha1) and the path to the file or remote path.

from rclone_python import rclone
from rclone_python.hash_types import HashTypes

print(rclone.hash(HashTypes.sha1, "box:data")

Use rclone.copy(src, dst, ...) to copy files. You can pass additional rclone arguments via the args list and use ignore_existing=True to skip files that already exist at the destination.

from rclone_python import rclone

# copy all file in the test_dir on OneDrive to the local data folder.
rclone.copy('onedrive:data', 'data', ignore_existing=True, args=['--create-empty-src-dirs'])

You can create a new remote connection using rclone.create_remote(). You must provide a name for the remote and a type from RemoteTypes. For many cloud providers, you can also provide a client_id and client_secret.

from rclone_python import rclone
from rclone_python.remote_types import RemoteTypes

# Using default client credentials
rclone.create_remote('onedrive', RemoteTypes.onedrive)

# Using custom client credentials
rclone.create_remote('onedrive', RemoteTypes.onedrive, client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET')

By default, the wrapper uses the system's rclone configuration. You can specify a custom configuration file using rclone.set_config_file(path). All subsequent commands will use this file.

import pathlib
from rclone_python import rclone

CONFIG_FILE = pathlib.Path(__file__).parent / ".rclone.conf"

rclone.set_config_file(CONFIG_FILE)

Use rclone.check(src, dst) to compare files in a source and destination. It returns a tuple containing a boolean (True if they match) and a list of differences.

Difference symbols:

• = path: identical in both
• - path: missing in source (only in destination)
• + path: missing in destination (only in source)
• * path: present in both but different
• ! path: error reading or hashing

from rclone_python import rclone

print(rclone.check("data", "box:data"))

Use rclone.is_installed() to verify that the rclone binary is available in your system's PATH.

from rclone_python import rclone

print(rclone.is_installed())

Use rclone.delete() to remove specific files or directories. Note that when deleting a directory, only the files within the directory (and its subdirectories) are deleted; the folder structure itself remains.

from rclone_python import rclone

# delete a specific file on onedrive
rclone.delete('onedrive:data/video1.mp4')

The rclone object is the primary entrypoint for interacting with rclone. It provides methods to manage remotes, list files, copy data, delete files, and calculate hashes. Most methods accept remote paths in the format remote_name:path/to/file.

from rclone_python import rclone, remote_types
from rclone_python.hash_types import HashTypes

# Create a new remote
rclone.create_remote("box", remote_types.RemoteTypes.box)

# List remotes
print(rclone.get_remotes())

# List files with specific filters
print(rclone.ls("box:data", max_depth=1, files_only=True))

# Copy a remote directory to a local folder
rclone.copy("box:data", "data")

# Copy a local file to a remote destination
rclone.copy("some_local_folder/image.jpg", "box:new_image.jpg")

# Get a file hash
print(rclone.hash(HashTypes.sha1, "box:data"))