Backblaze B2 Python SDK

The b2sdk supports continuing interrupted upload or creation sessions for large files. Continuation can be handled in two ways:

1. Automatic Continuation

For local-only input sources, b2sdk.v3.Bucket.create_file automatically attempts to find and resume an unfinished large file with the same file_name, file_info, and media type. It verifies checksums of uploaded parts against local sources to select the most complete valid candidate.

For other input types (e.g., remote sources), the SDK uses 'plan information' stored in the file_info. It looks for an unfinished large file with matching plan info and verifies checksums. If checksum verification fails for all candidates, an error is raised; in this case, you should manually cancel the corrupted unfinished files and retry, or disable auto-continuation.

2. Manual Continuation

If automatic continuation is not available or you want to avoid ambiguity when multiple matching sessions exist, you can use the large_file_id. You can extract this ID via the large_file_callback during the initial operation and pass it into the subsequent call.

Support Matrix:

• b2sdk.v3.Bucket.create_file: Supports both automatic and manual continuation.
• b2sdk.v3.Bucket.create_file_stream: Supports only manual continuation for local-only inputs.
• b2sdk.v3.Bucket.concatenate and b2sdk.v3.Bucket.concatenate_stream: concatenate_stream supports only manual continuation of local sources.
• b2sdk.v3.Bucket.upload and b2sdk.v3.Bucket.copy: Support both automatic and manual continuation.

# Manual continuation example
def large_file_callback(large_file):
    # Store the ID (e.g., in a database) to use later
    storage.store({'name': remote_name, 'large_file_id': large_file.id})

# Initial attempt
bucket.create_file(input_sources, remote_name, file_info, large_file_callback=large_file_callback)

# ... later, to resume ...
large_file_id = storage.query({'name': remote_name})[0]['large_file_id']
bucket.create_file(input_sources, remote_name, file_info, large_file_id=large_file_id)

Synchronization is the preferred method for moving data into and out of B2 because it parallelizes scanning and data transfer for high performance.

To perform a sync, you use the Synchronizer class along with:

• parse_folder(): To convert local paths or B2 URLs (e.g., b2://bucket-name) into folder objects.
• ScanPoliciesManager: To define how files are scanned (e.g., exclude_all_symlinks=True).
• SyncReport: To handle progress reporting and output.
• EncryptionSettingsProvider: To map file metadata (like bucket_name) to specific EncryptionSettings.

If you need to provide unique encryption keys on a per-file basis rather than per-bucket, you must implement your own AbstractSyncEncryptionSettingsProvider.

from b2sdk.v3 import ScanPoliciesManager, parse_folder, Synchronizer, SyncReport, BasicSyncEncryptionSettingsProvider, EncryptionSettings, EncryptionMode, EncryptionKey
import time
import sys

# Setup source and destination
source = parse_folder('/home/user1/b2_example', b2_api)
destination = parse_folder('b2://example-mybucket-b2', b2_api)

# Configure scanning and synchronization
policies_manager = ScanPoliciesManager(exclude_all_symlinks=True)
synchronizer = Synchronizer(
    max_workers=10,
    policies_manager=policies_manager,
    dry_run=False,
    allow_empty_source=True,
)

# Define encryption mapping
encryption_settings_provider = BasicSyncEncryptionSettingsProvider({
    'bucket1': EncryptionSettings(mode=EncryptionMode.SSE_B2),
    'bucket2': EncryptionSettings(
        mode=EncryptionMode.SSE_C,
        key=EncryptionKey(secret=b'VkYp3s6v9y$B&E)H@McQfTjWmZq4t7w!', id='user-generated-key-id')
    ),
    'bucket3': None,
})

# Execute sync
with SyncReport(sys.stdout, no_progress=False) as reporter:
    synchronizer.sync_folders(
        source_folder=source,
        dest_folder=destination,
        now_millis=int(round(time.time() * 1000)),
        reporter=reporter,
        encryption_settings_provider=encryption_settings_provider,
    )

A specific numbered interface (like v3) is not guaranteed to be identical throughout its lifespan. Developers should design their code to tolerate the following changes:

• Exceptions: The exception hierarchy may change in a backwards-compatible way. Best Practice: Use isinstance() and super() properly. Avoid calling parent class constructors by directly naming them, as this might skip intermediate classes in a changing hierarchy.
• Extensions: Classes, enums, and objects may gain new fields (visible in as_dict() or __repr__). Methods may start accepting new optional arguments, and new methods may be added to existing classes.
• Performance: While effort is made to maintain performance, some old interfaces may experience slight degradation in newer releases. If performance is critical, pin your dependency to a specific minor version (e.g., b2sdk>=X.Y.0,<X.Y+1.0).