### Quick Start: Check rclone, List Remotes, and Copy Files

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/OVERVIEW.md

This snippet demonstrates basic usage: checking if rclone is installed, listing configured remotes, and performing a file copy operation. Ensure rclone is installed and configured before running.

```python
from rclone_python import rclone

# Check if rclone is installed
if rclone.is_installed():
    # List configured remotes
    remotes = rclone.get_remotes()
    print(remotes)
    
    # Copy files
    rclone.copy('source:path', 'dest:path')
```

--------------------------------

### Example: Hash File and Verify

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/hash-types.md

Provides a complete example of generating hashes for files in a directory and then verifying them against a saved checksum file.

```APIDOC
## Example: Hash File and Verify

This example demonstrates generating hashes for multiple files and then verifying their integrity.

### Code Example

```python
from rclone_python import rclone
from rclone_python.hash_types import HashTypes
import json

# Generate SHA256 hashes for all files in 'box:data'
hashes = rclone.hash(HashTypes.sha256, 'box:data')

# Save the generated hashes to a JSON file for later verification
with open('expected_hashes.json', 'w') as f:
    json.dump(hashes, f, indent=2)

# Later, verify the files against the saved hashes
results = rclone.hash(
    HashTypes.sha256,
    'box:data',
    checkfile='expected_hashes.json'
)

print("Verification Results:")
for filename, is_valid in results.items():
    status = "✓ unchanged" if is_valid else "✗ CHANGED"
    print(f"  {filename}: {status}")
```
```

--------------------------------

### Install rclone-python

Source: https://github.com/johannes11833/rclone_python/blob/master/README.md

Install the rclone-python library using pip. Ensure rclone is installed on your system.

```shell
pip install rclone-python
```

```shell
pip install .
```

--------------------------------

### Multi-Remote Sync Example

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/remote-types.md

Demonstrates setting up and synchronizing data between multiple different remote services using rclone_python.

```python
from rclone_python import rclone
from rclone_python.remote_types import RemoteTypes

# Set up multiple remotes
rclone.create_remote('googlebox', RemoteTypes.drive)
rclone.create_remote('dropboxsync', RemoteTypes.dropbox)
rclone.create_remote('s3backup', RemoteTypes.s3, 
    access_key_id='KEY', secret_access_key='SECRET')

# Now sync between them
rclone.sync('googlebox:projects', 'dropboxsync:projects')
rclone.copy('dropboxsync:important', 's3backup:important')
```

--------------------------------

### Encrypted Backup Example

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/remote-types.md

Shows how to create an encrypted remote wrapper over an existing S3 remote for secure backups.

```python
from rclone_python import rclone
from rclone_python.remote_types import RemoteTypes

# Create an S3 remote
rclone.create_remote('s3', RemoteTypes.s3,
    access_key_id='KEY', secret_access_key='SECRET')

# Create encrypted wrapper over S3
rclone.create_remote('encrypted', RemoteTypes.crypt,
    remote='s3:mybucket/encrypted',
    filename_encryption='standard',
    directory_name_encryption='true',
    password='mypassword')

# Backup with automatic encryption
rclone.copy('local:/important/data', 'encrypted:/')
```

--------------------------------

### Archive Migration Example

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/remote-types.md

Illustrates migrating archive data from one cloud storage service to another using rclone_python.

```python
from rclone_python import rclone
from rclone_python.remote_types import RemoteTypes

# Set up source and destination
rclone.create_remote('oldservice', RemoteTypes.box)
rclone.create_remote('newservice', RemoteTypes.onedrive)

# Migrate all files
rclone.sync('oldservice:archive', 'newservice:archive')
```

--------------------------------

### Import rclone Module

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Import the main rclone module to start using its functionalities.

```python
from rclone_python import rclone
```

--------------------------------

### Hash File and Verify with JSON

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/hash-types.md

This example demonstrates generating SHA256 hashes for files in a directory, saving them to a JSON file, and later verifying if the files have changed against the saved hashes.

```python
from rclone_python import rclone
from rclone_python.hash_types import HashTypes
import json

# Generate SHA256 hashes for all files in a directory
hashes = rclone.hash(HashTypes.sha256, 'box:data')

# Save to file for later verification
with open('expected_hashes.json', 'w') as f:
    json.dump(hashes, f, indent=2)

# Later: verify files haven't changed
results = rclone.hash(
    HashTypes.sha256,
    'box:data',
    checkfile='expected_hashes.json'
)

print("Verification Results:")
for filename, is_valid in results.items():
    status = "✓ unchanged" if is_valid else "✗ CHANGED"
    print(f"  {filename}: {status}")
```

--------------------------------

### Setup: Configure and Verify a New Remote

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/OVERVIEW.md

This snippet shows how to configure a new cloud storage remote and verify its existence. It uses the `RemoteTypes` enum to specify the cloud provider.

```python
from rclone_python import rclone
from rclone_python.remote_types import RemoteTypes

# Configure a new remote
rclone.create_remote('mybox', RemoteTypes.box)

# Verify it exists
if rclone.check_remote_existing('mybox'):
    print("Remote configured successfully")
```

--------------------------------

### is_installed()

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Checks if rclone is installed or if a custom executable path is configured. It returns a boolean indicating the installation status.

```APIDOC
## is_installed()

### Description
Returns whether rclone is correctly installed on the system or a valid custom executable path is configured.

### Method
`is_installed()`

### Parameters
(none)

### Returns
`bool` — True if rclone is installed and accessible, False otherwise.

### Example
```python
from rclone_python import rclone

if rclone.is_installed():
    print("rclone is ready to use")
else:
    print("Please install rclone from https://rclone.org/")
```
```

--------------------------------

### Create Remote for Local and HTTP

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/remote-types.md

Examples for creating remotes that do not require authentication, such as local filesystem or read-only HTTP access.

```python
# Local filesystem
rclone.create_remote('local', RemoteTypes.local)

# HTTP (read-only)
rclone.create_remote('web', RemoteTypes.http)
```

--------------------------------

### Check rclone Installation

Source: https://github.com/johannes11833/rclone_python/blob/master/README.md

Verify if rclone is installed on the system using the is_installed() function.

```python
from rclone_python import rclone

print(rclone.is_installed())
```

--------------------------------

### Check rclone Installation

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Verify if rclone is installed and accessible on the system or if a custom executable path is set. This is a prerequisite for most other rclone operations.

```python
from rclone_python import rclone

if rclone.is_installed():
    print("rclone is ready to use")
else:
    print("Please install rclone from https://rclone.org/")
```

--------------------------------

### Compare Hash Algorithms Performance

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/hash-types.md

This snippet is a starting point for comparing the performance of different hash algorithms by computing various hashes of the same file.

```python
from rclone_python import rclone
from rclone_python.hash_types import HashTypes
import time

file_path = 'box:large_file.iso'

print("Computing various hashes of the same file...\n")


```

--------------------------------

### Check for Rclone Installation

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/errors.md

Verify if rclone is installed on the system before proceeding with operations. Raise a RuntimeError if rclone is not found.

```python
from rclone_python import rclone

if not rclone.is_installed():
    raise RuntimeError("rclone must be installed to use this module")
```

--------------------------------

### List and Inspect: Get Directory Size and Tree Structure

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/OVERVIEW.md

This snippet demonstrates how to list files in a directory, retrieve the total size and file count, and generate a tree-like representation of the directory structure. It uses `ls`, `size`, and `tree` functions.

```python
from rclone_python import rclone

# List top-level files
files = rclone.ls('myremote:data', max_depth=1, files_only=True)

# Get directory size
info = rclone.size('myremote:data')
print(f"Total: {info['bytes']} bytes in {info['count']} files")

# View tree structure
tree = rclone.tree('myremote:data')
print(tree)
```

--------------------------------

### rclone-main-module Functions

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/INDEX.md

Core functions for interacting with rclone, including installation checks, remote management, file operations, and information retrieval.

```APIDOC
## rclone-main-module Functions

### Description
Provides a set of functions to manage rclone remotes, perform file operations, and retrieve information about the rclone installation and remotes.

### Functions
- **is_installed()**: Checks if rclone is installed and available in the system's PATH.
- **about()**: Retrieves storage information for a remote.
- **check_remote_existing(remote_name)**: Verifies if a specified remote exists.
- **create_remote(remote_name, remote_type, ...)**: Sets up a new rclone remote configuration.
- **get_remotes()**: Lists all configured rclone remotes.
- **mkdir(remote_path)**: Creates a directory on the specified remote path.
- **cat(remote_path)**: Outputs the contents of a file from the specified remote path.
- **copy(source_path, destination_path)**: Copies files from source to destination, skipping existing files.
- **copyto(source_path, destination_path)**: Copies files from source to destination, allowing path transformation.
- **move(source_path, destination_path)**: Moves files from source to destination, then deletes the source.
- **moveto(source_path, destination_path)**: Moves files with renaming from source to destination, then deletes the source.
- **sync(source_path, destination_path)**: Synchronizes directories from source to destination, modifying the destination only.
- **delete(remote_path)**: Deletes files at the specified remote path, keeping directories.
- **purge(remote_path)**: Recursively deletes all files and directories at the specified remote path.
- **link(remote_path)**: Creates a public link for the specified remote path.
- **ls(remote_path)**: Lists directory contents, returning Name, Size, ModTime, and IsDir.
- **size(remote_path)**: Gets the total size and file count of a directory.
- **tree(remote_path)**: Generates a string representation of the directory tree.
- **hash(remote_path, hash_type)**: Generates or validates hashes for files.
- **check(source_path, destination_path)**: Compares source and destination files.
- **version()**: Returns the installed rclone version.
- **set_config_file(path)**: Specifies a custom rclone configuration file path.
- **set_executable_file(path)**: Specifies the path to the rclone executable.
- **set_log_level(level)**: Sets the logging level for rclone operations.
```

--------------------------------

### Console Output of Custom Progress Bar

Source: https://github.com/johannes11833/rclone_python/blob/master/README.md

This is an example of the console output when using a custom progress bar during an rclone transfer.

```console
Copying data to data1 ━━━━━━╸━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  17% 5.3 MB/s                                                                                                            
 ├─video1.mp4         ━━━━━━━━━━━━━━━╺━━━━━━━━━━━━━━━━━━━━━━━━  38% 4.2 MB/s                                                                                                            
 ├─video2.mp4         ━╸━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   5% 1.6 MB/s
 └─another.mp4        ━╸━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   4% 1.4 MB/s
```

--------------------------------

### Custom Progress Bar with rclone-python

Source: https://github.com/johannes11833/rclone_python/blob/master/README.md

Integrate a custom rich progress bar for file transfers. Ensure 'rich' library is installed. The progress bar can be customized with various columns.

```python
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)
```

--------------------------------

### Get Size Information with Rclone Python

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Calculate the total size and object count for a given path. Returns the number of files, total bytes, and count of empty directories.

```python
from rclone_python import rclone

size_info = rclone.size('box:my_folder')
print(f"Total files: {size_info['count']}")
print(f"Total size: {size_info['bytes']} bytes")
print(f"Empty dirs: {size_info['nEmptyDir']}")
```

--------------------------------

### set_executable_file(executable_file, validate)

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Sets a custom rclone executable path for the wrapper, allowing the use of non-standard installations. Optionally validates the path.

```APIDOC
## set_executable_file(executable_file, validate)

### Description
Change the rclone executable path used by this wrapper. Allows using a custom or non-standard installation of rclone.

### Method
`set_executable_file(executable_file: str, validate: bool = True)`

### Parameters
#### Path Parameters
- **executable_file** (str) - Required - Path to the rclone executable
- **validate** (bool) - Optional - If True, validates that the path exists before setting. Defaults to True.

### Returns
`None`

### Raises
`FileNotFoundError` — If validate is True and the executable path does not exist

### Example
```python
from rclone_python import rclone

# Use a custom rclone installation
rclone.set_executable_file('/custom/path/to/rclone', validate=True)

# Or skip validation
rclone.set_executable_file('/usr/local/bin/rclone', validate=False)
```
```

--------------------------------

### Read File Portions with rclone.cat

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/configuration.md

Demonstrates how to read specific portions of a file using the 'cat' operation. You can specify the number of bytes to read, the first N characters, the last N characters, or a range starting from a specific offset.

```python
from rclone_python import rclone

# Read first 1000 bytes
start = rclone.cat('box:file.txt', head=1000)

# Read last 500 bytes
end = rclone.cat('box:file.txt', tail=500)

# Read 200 bytes starting at position 100
middle = rclone.cat('box:file.txt', offset=100, count=200)
```

--------------------------------

### Get Rclone Version and Check for Updates

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Retrieves the currently installed rclone version. Optionally, it can check for the latest stable and beta release versions. Requires rclone to be installed.

```python
from rclone_python import rclone

# Get current version
current = rclone.version()
print(f"Current rclone version: {current}")

# Check for updates
current, latest, beta = rclone.version(check=True)
print(f"Current: {current}")
print(f"Latest: {latest}")
print(f"Latest beta: {beta}")

if latest and current != latest:
    print(f"Update available: {latest}")
```

--------------------------------

### Get Remote Path Information

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Execute the rclone 'about' command to retrieve details about a remote path, including total, used, and free space. Requires rclone to be installed.

```python
from rclone_python import rclone

# Get information about a remote
info = rclone.about('box:')
print(f"Total space: {info.get('total', 'N/A')}")
print(f"Used space: {info.get('used', 'N/A')}")
print(f"Free space: {info.get('free', 'N/A')}")
```

--------------------------------

### version

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Get the currently installed rclone version and optionally check for updates. This function retrieves the rclone version and can also perform an online check for the latest stable and beta releases.

```APIDOC
## version(check, args)

### Description
Get the currently installed rclone version and optionally check for updates.

### Method
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **check** (bool) - Optional - Default: False - If True, perform an online check to compare with latest release and beta versions
- **args** (List[str]) - Optional - Default: None - List of additional rclone flags/arguments

### Returns
- `str` — Current version string if check=False
- `Tuple[str, str, str]` — (current_version, latest_version, latest_beta_version) if check=True. Latest versions may be None if the check fails.

### Raises
- `RcloneException` — If rclone is not installed

### Example
```python
from rclone_python import rclone

# Get current version
current = rclone.version()
print(f"Current rclone version: {current}")

# Check for updates
current, latest, beta = rclone.version(check=True)
print(f"Current: {current}")
print(f"Latest: {latest}")
print(f"Latest beta: {beta}")

if latest and current != latest:
    print(f"Update available: {latest}")
```
```

--------------------------------

### Handle Unsupported Algorithms with Download

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/hash-types.md

Illustrates how to use the `download=True` parameter when a backend does not support the requested hash algorithm, forcing a local download and hash computation.

```python
from rclone_python import rclone
from rclone_python.hash_types import HashTypes

# Backend doesn't support SHA512, so download and hash locally
hashes = rclone.hash(HashTypes.sha512, 'dropbox:data', download=True)
```

--------------------------------

### Check if rclone is Installed

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/errors.md

Verify if rclone is installed on the system before proceeding with rclone operations. This is useful for providing user-friendly installation instructions.

```python
from rclone_python import rclone

if not rclone.is_installed():
    print("rclone is not installed")
    print("Install from: https://rclone.org/")
else:
    # Proceed with rclone operations
    pass
```

--------------------------------

### Config Initialization and Retrieval

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/utils-module.md

Initializes the Config singleton or retrieves the existing instance. Subsequent calls do not overwrite existing configuration.

```python
from rclone_python.utils import Config

# First initialization sets the values
config = Config(config_path='/etc/rclone.conf', executable_path='/usr/bin/rclone')

# Subsequent calls return the same instance
config2 = Config()  # Same instance as config
print(config2.config_path)  # '/etc/rclone.conf'
```

--------------------------------

### Handling Unsupported Algorithms

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/hash-types.md

Explains how to handle cases where a backend does not support a requested hash algorithm by using the `download=True` parameter.

```APIDOC
## Backend Compatibility: Handling Unsupported Algorithms

Some backends may not support all hash algorithms. In such cases, you can force rclone to download the file locally and compute the hash using the `download=True` parameter.

### Example: Handling Unsupported Algorithms

```python
from rclone_python import rclone
from rclone_python.hash_types import HashTypes

# The backend might not support SHA512. Download and hash locally.
hashes = rclone.hash(HashTypes.sha512, 'dropbox:data', download=True)
```
```

--------------------------------

### Import Utilities

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/INDEX.md

Import utility classes for exception handling and configuration.

```python
# Utilities
from rclone_python.utils import RcloneException, Config
```

--------------------------------

### Create Remote with Additional Parameters

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/remote-types.md

Configure remotes with specific parameters such as host details for SFTP, custom endpoints for S3, or local paths.

```python
from rclone_python import rclone
from rclone_python.remote_types import RemoteTypes

# SFTP with host details
rclone.create_remote(
    'mysftp',
    RemoteTypes.sftp,
    host='sftp.example.com',
    user='username',
    password='password',
    port='22'
)

# S3 with custom endpoint
rclone.create_remote(
    'myminios3',
    RemoteTypes.s3,
    provider='other',
    endpoint='https://minio.example.com',
    access_key_id='YOUR_KEY',
    secret_access_key='YOUR_SECRET'
)

# Local path
rclone.create_remote(
    'mylocal',
    RemoteTypes.local,
    path='/mnt/storage'
)
```

--------------------------------

### Configuration Documentation

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/COMPLETION_SUMMARY.txt

Information on runtime configuration options for the rclone_python library, including parameters and environment variables.

```APIDOC
## configuration

This section describes the configuration options for the rclone_python library.

### Runtime Configuration Options

- **`RCLONE_CONFIG_PATH`**
  - Description: Specifies the path to the rclone configuration file.
  - Type: `str`
  - Default: `~/.config/rclone/rclone.conf`
  - Environment Variable: `RCLONE_CONFIG_PATH`

- **`RCLONE_LOG_LEVEL`**
  - Description: Sets the logging level for rclone operations.
  - Type: `str` or `LogLevel` enum
  - Valid Values: `DEBUG`, `INFO`, `ERROR`
  - Default: `INFO`
  - Environment Variable: `RCLONE_LOG_LEVEL`

- **`RCLONE_DRY_RUN`**
  - Description: Enables or disables dry run mode.
  - Type: `bool`
  - Default: `False`
  - Environment Variable: `RCLONE_DRY_RUN`
```

--------------------------------

### Create Directory with Rclone

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Create a directory at a specified path on a remote or locally. Additional rclone flags can be passed as a list of strings.

```python
from rclone_python import rclone

# Create directory on a remote
rclone.mkdir('box:my_new_folder')

# Create directory locally
rclone.mkdir('./local_folder')

# Create with additional arguments
rclone.mkdir('drive:data', args=['--metadata', 'Custom-Key=value'])
```

--------------------------------

### Import Main API

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/INDEX.md

Import the main rclone API module for general use.

```python
# Main API
from rclone_python import rclone
```

--------------------------------

### Create Remote with Enum or String

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/types.md

Demonstrates creating a remote configuration using either the RemoteTypes enum or a direct string value for the remote type.

```python
import rclone
from rclone_python.remote_types import RemoteTypes

# Create remote using enum
rclone.create_remote('mybox', RemoteTypes.box)

# Or use string value directly
rclone.create_remote('mybox', 'box')
```

--------------------------------

### Get File Hash with rclone

Source: https://github.com/johannes11833/rclone_python/blob/master/README.md

Generate a hash for files in a specified location using different hash types like SHA1.

```python
from rclone_python import rclone
from rclone_python.hash_types import HashTypes

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

--------------------------------

### Configuration Options

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/INDEX.md

Details on runtime configuration and transfer operation options.

```APIDOC
## Configuration and Options

### Runtime Configuration
- **set_config_file(path)**: Use a custom rclone configuration file.
- **set_executable_file(path)**: Specify the path to the rclone executable.
- **set_log_level(level)**: Control the verbosity of rclone logging.

### Transfer Operation Options
- **progress**: Enable or disable progress reporting.
- **ignore_existing**: Skip files that already exist at the destination.
- **args**: Pass additional arguments directly to the rclone command.

### Operation Specific Options
- **List operation filtering**: Options for filtering the output of `ls()`.
- **Hash operation modes**: Specify modes for `hash()` and `check()` operations.
- **Check operation variants**: Different comparison methods for `check()`.
- **Link operation configuration**: Settings for creating public links with `link()`.
- **Cat operation slicing**: Specify byte ranges for `cat()`.

### Default Paths and Precedence
Information on default file paths and how configuration settings are prioritized.
```

--------------------------------

### Get Configured Rclone Remotes

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Retrieve a list of all configured rclone remote names. The function takes no parameters and returns a list of strings.

```python
from rclone_python import rclone

remotes = rclone.get_remotes()
print(f"Configured remotes: {remotes}")

for remote in remotes:
    print(f"  - {remote}")
```

--------------------------------

### Verify Data: Compare Directories and Validate Checksums

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/OVERVIEW.md

This snippet illustrates how to compare directory contents between source and destination, and how to validate file checksums using SHA256. It shows how to interpret the results of the `check` and `hash` operations.

```python
from rclone_python import rclone
from rclone_python.hash_types import HashTypes

# Compare directories
match, results = rclone.check('source', 'dest')
if not match:
    for symbol, filepath in results:
        print(f"{symbol} {filepath}")

# Validate checksums
hashes = rclone.hash(HashTypes.sha256, 'myremote:data')
```

--------------------------------

### Set Custom rclone Executable Path

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Configure a custom path to the rclone executable, useful for non-standard installations. Validation of the path can be optionally skipped.

```python
from rclone_python import rclone

# Use a custom rclone installation
rclone.set_executable_file('/custom/path/to/rclone', validate=True)

# Or skip validation
rclone.set_executable_file('/usr/local/bin/rclone', validate=False)
```

--------------------------------

### Create Backblaze B2 Remote

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/remote-types.md

Configure a Backblaze B2 remote using account ID and application key for authentication.

```python
from rclone_python import rclone
from rclone_python.remote_types import RemoteTypes

# Backblaze B2
rclone.create_remote(
    'myb2',
    RemoteTypes.b2,
    account_id='YOUR_ACCOUNT_ID',
    app_key='YOUR_APP_KEY'
)
```

--------------------------------

### Copy Files Between Clouds

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/README.md

Demonstrates how to set up two cloud remotes and copy data between them using rclone_python. Ensure the necessary remote types are imported.

```python
from rclone_python import rclone
from rclone_python.remote_types import RemoteTypes

rclone.create_remote('src', RemoteTypes.dropbox)
rclone.create_remote('dst', RemoteTypes.drive)
rclone.copy('src:data', 'dst:data')
```

--------------------------------

### Rclone Main Module API Reference

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/COMPLETION_SUMMARY.txt

Detailed documentation for the main rclone module, including function signatures, parameter types, return values, and exceptions.

```APIDOC
## rclone-main-module

This module provides the core functionality for interacting with rclone.

### Functions

- **`rclone_main_function(param1: str, param2: int = 10) -> bool`**
  - Description: A sample function demonstrating core features.
  - Parameters:
    - `param1` (str) - Required - The first parameter.
    - `param2` (int) - Optional - Defaults to 10. The second parameter.
  - Returns: `bool` - True if successful, False otherwise.
  - Raises:
    - `ValueError`: If param1 is empty.
    - `TypeError`: If param2 is not an integer.

### Data Structures

- **`RcloneConfig`**
  - Description: Represents the rclone configuration.
  - Fields:
    - `path` (str) - Path to the configuration file.
    - `name` (str) - Name of the remote.

### Enums

- **`LogLevel`**
  - Description: Defines the logging levels.
  - Members:
    - `DEBUG` (int) - Value: 1
    - `INFO` (int) - Value: 2
    - `ERROR` (int) - Value: 3
```

--------------------------------

### List Files and Directories with Depth Control

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/configuration.md

List files and directories with options for depth, filtering by type, and passing additional rclone flags.

```python
from rclone_python import rclone

# List files only in top-level directory
files = rclone.ls('box:data', max_depth=1, files_only=True)

# List only subdirectories
dirs = rclone.ls('box:data', dirs_only=True)

# List entire tree
all_items = rclone.ls('box:data')
```

--------------------------------

### Get a Specific Task from Progress Bar

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/utils-module.md

Retrieves a specific task from a Rich Progress object using its TaskID. Use this when you need to access or modify individual tasks within a progress display.

```python
from rclone_python.utils import get_task, create_progress_bar

pbar = create_progress_bar()
task_id = pbar.add_task("Processing", total=100)

task = get_task(task_id, pbar)
print(f"Task description: {task.description}")
```

--------------------------------

### Cat Operation Configuration

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/configuration.md

Allows reading specific portions of a file using the `cat` operation. You can specify the number of characters to read, the first N characters, the last N characters, or a range starting from an offset.

```APIDOC
## cat

### Description
Reads a specified portion of a file.

### Method
```python
cat(
    path: str,
    count: Optional[int] = None,
    head: Optional[int] = None,
    offset: Optional[int] = None,
    tail: Optional[int] = None,
    args: List[str] = None,
) -> str
```

### Parameters
#### Path Parameters
- **path** (str) - Required - The path to the file to read.

#### Optional Parameters
- **count** (int) - Optional - Number of characters to read.
- **head** (int) - Optional - First N characters to read.
- **offset** (int) - Optional - Start position (negative values indicate position from the end of the file).
- **tail** (int) - Optional - Last N characters to read.
- **args** (List[str]) - Optional - Additional rclone flags to pass to the command.

### Request Example
```python
from rclone_python import rclone

# Read first 1000 bytes
start = rclone.cat('box:file.txt', head=1000)

# Read last 500 bytes
end = rclone.cat('box:file.txt', tail=500)

# Read 200 bytes starting at position 100
middle = rclone.cat('box:file.txt', offset=100, count=200)
```
```

--------------------------------

### Project Directory Structure

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/MANIFEST.md

Illustrates the organization of the documentation files within the project. This structure helps in navigating and understanding the scope of the documentation.

```text
output/
├── README.md ......................... Entry point and overview
├── OVERVIEW.md ....................... Quick start and capabilities
├── INDEX.md .......................... Complete index
├── types.md .......................... Type definitions
├── configuration.md .................. Config options
├── errors.md ......................... Error reference
├── MANIFEST.md ....................... This file
└── api-reference/
    ├── rclone-main-module.md ......... 25+ main functions
    ├── utils-module.md ............... Utilities
    ├── hash-types.md ................. Hash algorithms
    └── remote-types.md ............... Cloud providers
```

--------------------------------

### Create SFTP Remote

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/remote-types.md

Configure an SFTP remote specifying host, username, and password for authentication.

```python
from rclone_python import rclone
from rclone_python.remote_types import RemoteTypes

rclone.create_remote(
    'mysftp',
    RemoteTypes.sftp,
    host='example.com',
    user='username',
    password='password'
)
```

--------------------------------

### Create Remote with OAuth Credentials

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/remote-types.md

Configure remotes for services like Google Drive or OneDrive using custom OAuth client IDs and secrets.

```python
from rclone_python import rclone
from rclone_python.remote_types import RemoteTypes

# Google Drive with custom OAuth credentials
rclone.create_remote(
    'mydrive',
    RemoteTypes.drive,
    client_id='YOUR_CLIENT_ID.apps.googleusercontent.com',
    client_secret='YOUR_CLIENT_SECRET'
)

# OneDrive with custom credentials
rclone.create_remote(
    'myonedrive',
    RemoteTypes.onedrive,
    client_id='YOUR_APP_ID',
    client_secret='YOUR_APP_PASSWORD'
)
```

--------------------------------

### Utils Module

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/INDEX.md

Internal utilities for configuration management, error handling, and running rclone commands.

```APIDOC
## Utils Module

### Description
Provides internal utilities for the rclone_python library, including configuration management, custom exception handling, and a wrapper for running rclone commands.

### Components
- **Config class**: A singleton class for managing rclone configuration settings.
- **RcloneException class**: A custom exception class for handling rclone-related errors.
- **run_rclone_cmd(*args, **kwargs)**: A utility function to execute rclone commands with specified arguments and options.
- **Progress tracking functions**: Utilities for monitoring the progress of rclone operations.
```

--------------------------------

### Sync local directory to remote

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Use the `sync` function to make the destination directory identical to the source directory. It only transfers files that are different or missing in the destination.

```python
from rclone_python import rclone

rclone.sync('local_folder', 'box:remote_folder')

rclone.sync('folder1', 'folder2', show_progress=False)
```

--------------------------------

### File Copy with Progress Monitoring

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/INDEX.md

Copy files and monitor the progress using a callback function. The listener function receives update dictionaries with progress information.

```python
def on_progress(update):
    print(f"{update['progress']*100:.1f}%")

rclone.copy('source', 'dest', listener=on_progress)
```

--------------------------------

### List Files and Directories with Filters

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/README.md

Retrieve file and directory listings from a remote path. Supports filtering by maximum depth, listing only files, or listing only directories.

```python
# Top-level files only
files = rclone.ls('remote:path', max_depth=1, files_only=True)

# Directories only
dirs = rclone.ls('remote:path', dirs_only=True)

# Tree structure
tree = rclone.tree('remote:path')
```

--------------------------------

### Transfer Files: Copy with Progress Monitoring

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/OVERVIEW.md

This snippet demonstrates copying files with progress monitoring. A callback function `on_progress` is provided to receive and display update information during the transfer.

```python
from rclone_python import rclone

# Copy with progress monitoring
def on_progress(update):
    print(f"Progress: {update['progress']*100:.1f}%")

rclone.copy('mybox:source', 'local_dest', listener=on_progress)
```

--------------------------------

### mkdir

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Creates a directory at the specified path. This function can be used for both local paths and paths on rclone remotes, and supports additional rclone arguments.

```APIDOC
## mkdir(path, args)

### Description
Create a directory at the specified path if it doesn't already exist.

### Method
`mkdir`

### Parameters
#### Path Parameters
* **path** (str) - Required - Path to create. Specify remote as 'remote_name:path'
* **args** (List[str]) - Optional - List of additional rclone flags/arguments

### Returns
`None`

### Raises
`RcloneException` — If rclone is not installed or the command fails

### Example
```python
from rclone_python import rclone

# Create directory on a remote
rclone.mkdir('box:my_new_folder')

# Create directory locally
rclone.mkdir('./local_folder')

# Create with additional arguments
rclone.mkdir('drive:data', args=['--metadata', 'Custom-Key=value'])
```
```

--------------------------------

### Import rclone_python Public APIs

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/OVERVIEW.md

Import necessary components from the rclone_python library, including the main API, types, enums, utilities, and exceptions.

```python
# Main API
from rclone_python import rclone

# Types and enums
from rclone_python.hash_types import HashTypes
from rclone_python.remote_types import RemoteTypes

# Utilities and exceptions
from rclone_python.utils import RcloneException, Config
```

--------------------------------

### Move files with rclone-python

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Use the `move` function to transfer files from a source to a destination. You can optionally ignore existing files in the destination.

```python
from rclone_python import rclone

rclone.move('local_folder', 'box:remote_folder')

rclone.move('source', 'destination', ignore_existing=True)
```

--------------------------------

### copy with progress options

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/configuration.md

Performs a copy operation with options to control progress display, including showing a progress bar, using a custom listener for updates, or providing a custom progress bar object.

```APIDOC
## copy with progress options

### Description
Display progress bar during transfer, use a callback function for updates, or provide a custom Progress object.

### Method
```python
def copy(
    in_path: str,
    out_path: str,
    show_progress: bool = True,
    listener: Callable[[Dict], None] = None,
    pbar: Optional[Progress] = None,
    ...
)
```

### Parameters
#### Path Parameters
- **show_progress** (bool) - Optional - Display progress bar during transfer. Defaults to True.
- **listener** (Callable) - Optional - Callback function called with each progress update.
- **pbar** (rich.progress.Progress) - Optional - Custom Progress object for custom UI integration.

### Request Example: Using Listener
```python
from rclone_python import rclone

def on_progress(update):
    # update contains: tasks, total, sent, progress, transfer_speed, rclone_output
    print(f"Transferred: {update['sent']}/{update['total']} bytes")
    print(f"Speed: {update['transfer_speed']/1024:.2f} KB/s")

rclone.copy('source', 'dest', listener=on_progress)
```

### Request Example: Using Custom Progress Bar
```python
from rclone_python import rclone
from rich.progress import Progress, TextColumn, BarColumn, TaskProgressColumn

# Create custom progress bar
pbar = Progress(
    TextColumn("[progress.description]{task.description}"),
    BarColumn(),
    TaskProgressColumn(),
)

rclone.copy('source', 'dest', show_progress=True, pbar=pbar)
```

### Request Example: Disable Progress
```python
from rclone_python import rclone

# Silent transfer
rclone.copy('source', 'dest', show_progress=False)
```
```

--------------------------------

### Quick Size Check Between Source and Destination

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/configuration.md

Perform a fast check by comparing only the sizes of files between source and destination. Useful for a quick verification.

```python
from rclone_python import rclone

# Fast check: only compare sizes
match, results = rclone.check('source', 'dest', size_only=True)
```

--------------------------------

### Using String Values

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/hash-types.md

Illustrates how to use string representations of hash algorithms when calling the `rclone.hash()` function.

```APIDOC
## Usage: Using String Values

This section demonstrates how to use string values directly for hash algorithms with the `rclone.hash()` function.

### Example: Using String Values

```python
from rclone_python import rclone
from rclone_python.hash_types import HashTypes

# Pass the hash algorithm as a string
hashes = rclone.hash('sha256', 'box:data')

# Alternatively, use the .value attribute of the enum member
hashes = rclone.hash(HashTypes.sha256.value, 'box:data')
```
```

--------------------------------

### Convert Empty Arguments to String

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/utils-module.md

Demonstrates converting an empty list of arguments to an empty string using args2string.

```python
from rclone_python.utils import args2string

# Empty args
result = args2string([])
print(f"'{result}'")  # Output: ''
```

--------------------------------

### Copy Files with rclone

Source: https://github.com/johannes11833/rclone_python/blob/master/README.md

Copy files from a source to a destination. Supports options like ignoring existing files and creating empty source directories.

```python
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'])
```

--------------------------------

### size(path, args)

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Retrieves the total size and number of objects within a specified path. Returns a dictionary containing the count of files, total bytes, and the number of empty directories.

```APIDOC
## size(path, args)

### Description
Get the total size and number of objects at the specified path.

### Method
Not applicable (Python function)

### Parameters
#### Path Parameters
- **path** (str) - Required - Path to calculate size for. Specify remote as 'remote_name:path'
- **args** (List[str]) - Optional - List of additional rclone flags/arguments

### Returns
- **Dict** - Dictionary with keys 'count' (number of files), 'bytes' (total size in bytes), and 'nEmptyDir' (number of empty directories)

### Raises
- **RcloneException** - If rclone is not installed or the operation fails

### Example
```python
from rclone_python import rclone

size_info = rclone.size('box:my_folder')
print(f"Total files: {size_info['count']}")
print(f"Total size: {size_info['bytes']} bytes")
print(f"Empty dirs: {size_info['nEmptyDir']}")
```
```

--------------------------------

### about(path)

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Executes the rclone 'about' command to retrieve information about a specified remote or path. Returns sizes in bytes.

```APIDOC
## about(path)

### Description
Execute the rclone about command and retrieve information about the remote/path. Returns all sizes in bytes.

### Method
`about(path: str)`

### Parameters
#### Path Parameters
- **path** (str) - Required - Path to examine. Can be a local path or remote path specified as 'remote_name:path'

### Returns
`Dict` — Dictionary containing remote properties such as free space, used space, total space, etc. The exact keys depend on the backend.

### Raises
`RcloneException` — If rclone is not installed

### Example
```python
from rclone_python import rclone

# Get information about a remote
info = rclone.about('box:')
print(f"Total space: {info.get('total', 'N/A')} bytes")
print(f"Used space: {info.get('used', 'N/A')} bytes")
print(f"Free space: {info.get('free', 'N/A')} bytes")
```
```

--------------------------------

### run_rclone_cmd

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/utils-module.md

Executes an rclone command with specified arguments and options, returning the command's output. This function handles the invocation of the rclone executable, including the use of custom configuration and executable paths, and provides options for error handling.

```APIDOC
## run_rclone_cmd(command, args, shell, encoding, raise_errors)

Execute an rclone command and return its output. Handles custom config and executable paths.

```python
def run_rclone_cmd(
    command: str,
    args: List[str] = (),
    shell=True,
    encoding="utf-8",
    raise_errors: bool = True,
) -> Union[Tuple[str, str], Tuple[int, str, str]]
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| command | str | Yes | — | The rclone command to run (e.g., 'copy "src" "dst"') |
| args | List[str] | No | () | List of additional rclone flags/arguments |
| shell | bool | No | True | If True, run command in shell context |
| encoding | str | No | "utf-8" | Text encoding for subprocess output |
| raise_errors | bool | No | True | If True, raise RcloneException on non-zero exit. If False, return exit code |

**Returns:**
- If `raise_errors=True`: `Tuple[str, str]` — (stdout, stderr)
- If `raise_errors=False`: `Tuple[int, str, str]` — (returncode, stdout, stderr)

**Raises:** `RcloneException` — If raise_errors=True and command exits with non-zero code

**Example:**

```python
from rclone_python.utils import run_rclone_cmd

# Run with error raising (default)
stdout, stderr = run_rclone_cmd('version')
print(stdout)

# Run without raising errors
returncode, stdout, stderr = run_rclone_cmd('listremotes', raise_errors=False)
if returncode == 0:
    print("Remotes:", stdout)
else:
    print("Error:", stderr)

# Run with additional arguments
stdout, _ = run_rclone_cmd('ls "box:"', args=['--max-depth', '1'])
```
```

--------------------------------

### Generate Directory Tree with Rclone Python

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/rclone-main-module.md

Display a hierarchical tree structure of a directory. Useful for visualizing folder organization.

```python
from rclone_python import rclone

tree_output = rclone.tree('box:my_folder')
print(tree_output)
```

--------------------------------

### Use String Values for Hashing

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/hash-types.md

Shows how to pass hash algorithm names as strings or use the enum's value attribute directly with rclone.hash().

```python
from rclone_python import rclone

# Pass hash algorithm as string
hashes = rclone.hash('sha256', 'box:data')

# Or use the string value directly
hashes = rclone.hash(HashTypes.sha256.value, 'box:data')
```

--------------------------------

### Execute Rclone Command with Progress Monitoring

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/api-reference/utils-module.md

Executes an rclone command and monitors its progress, optionally displaying a progress bar and calling a listener function with each update. Errors are returned as a list.

```python
from rclone_python.utils import rclone_progress

def on_update(update):
    print(f"Transferred: {update['sent']}/{update['total']} bytes")

process, errors = rclone_progress(
    'copy "source" "destination" --stats 0.1s --stats-unit bytes --use-json-log -v',
    "Copying files",
    show_progress=True,
    listener=on_update
)

if errors:
    print("Errors during transfer:", errors)
```

--------------------------------

### List Operation

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/configuration.md

Lists directories and files at a given path. Supports filtering by depth, type (dirs/files only), and passing additional rclone flags.

```APIDOC
## List Operation Configuration

```python
def ls(
    path: str,
    max_depth: Union[int, None] = None,
    dirs_only: bool = False,
    files_only: bool = False,
    args: List[str] = None,
) -> List[Dict]
```

### Parameters
#### Path Parameters
- **path** (str) - Required - The path to list.
#### Query Parameters
- **max_depth** (int) - Optional - Maximum directory depth (1 = current level only).
- **dirs_only** (bool) - Optional - Return only directories.
- **files_only** (bool) - Optional - Return only files.
- **args** (List[str]) - Optional - Additional rclone flags.

### Request Example
```python
from rclone_python import rclone

# List files only in top-level directory
files = rclone.ls('box:data', max_depth=1, files_only=True)

# List only subdirectories
dirs = rclone.ls('box:data', dirs_only=True)

# List entire tree
all_items = rclone.ls('box:data')
```
```

--------------------------------

### Full Content Verification Between Source and Destination

Source: https://github.com/johannes11833/rclone_python/blob/master/_autodocs/configuration.md

Perform a thorough check by downloading and comparing the actual content of files between source and destination. This is slower but more accurate.

```python
from rclone_python import rclone

# Download and compare actual content
match, results = rclone.check('source', 'dest', download=True)
```