Transfers

Manage file uploads and downloads in Nicotine+

The Transfers module manages file uploads and downloads, including queue management, transfer status tracking, and bandwidth control.

Overview

The Transfers module consists of three main classes:

• Transfers: Main transfer coordinator
• Downloads: Download-specific management
• Uploads: Upload-specific management

Transfers Class

Initialization

from pynicotine.transfers import Transfers

transfers = Transfers()

Core Methods

get_downloads()

Returns the Downloads instance.

downloads = transfers.get_downloads()

get_uploads()

Returns the Uploads instance.

uploads = transfers.get_uploads()

set_transfer_speed_limit()

Sets bandwidth limits for transfers.

transfers.set_transfer_speed_limit(download_limit, upload_limit)

download_limit · int · required

Download speed limit in KB/s (0 for unlimited)

upload_limit · int · required

Upload speed limit in KB/s (0 for unlimited)

# Set 1 MB/s download limit, 500 KB/s upload limit
transfers.set_transfer_speed_limit(1024, 512)

# Unlimited transfers
transfers.set_transfer_speed_limit(0, 0)

Downloads Class

Download Management

add_download()

Adds a file to the download queue.

downloads.add_download(
    username="user123",
    virtual_path="Music/Album/song.flac",
    size=42000000,
    local_path="/home/user/Downloads/song.flac"
)

username · str · required

Username to download from

virtual_path · str · required

Virtual path of the file on the remote user’s share

size · int

File size in bytes (if known)

local_path · str

Local filesystem path where file will be saved

prioritize · bool · default: "False"

Place at front of download queue

abort_download()

Aborts an active download.

downloads.abort_download(username, virtual_path)

username · str · required

Username of the download

virtual_path · str · required

Virtual path of the file

abort_downloads()

Aborts multiple downloads.

downloads.abort_downloads([
    ("user1", "path/to/file1.mp3"),
    ("user2", "path/to/file2.flac")
])

downloads_list · list · required

List of (username, virtual_path) tuples

clear_download()

Removes a download from the queue.

downloads.clear_download(username, virtual_path)

retry_download()

Retries a failed download.

downloads.retry_download(username, virtual_path)

Download Queue Methods

get_downloads()

Returns all downloads.

all_downloads = downloads.get_downloads()

downloads · dict

Dictionary mapping (username, virtual_path) to download info

get_active_downloads()

Returns currently active downloads.

active = downloads.get_active_downloads()

get_queued_downloads()

Returns queued downloads waiting to start.

queued = downloads.get_queued_downloads()

get_user_downloads()

Returns downloads from a specific user.

user_downloads = downloads.get_user_downloads("username")

Download Folders

add_download_folder()

Downloads an entire folder from a user.

downloads.add_download_folder(
    username="user123",
    folder="Music/Complete Discography",
    local_path="/home/user/Downloads/Discography"
)

username · str · required

Username to download from

folder · str · required

Virtual folder path

local_path · str

Local directory to save files

prefix_username · bool · default: "False"

Prefix local folder name with username

Uploads Class

Upload Management

push_upload()

Queues a file for upload to a user.

uploads.push_upload(
    username="requesting_user",
    virtual_path="My Music/album/track.mp3",
    real_path="/home/user/Shares/Music/album/track.mp3",
    size=5000000
)

username · str · required

Username requesting the file

virtual_path · str · required

Virtual path in your shares

real_path · str · required

Actual filesystem path

size · int · required

File size in bytes

abort_upload()

Aborts an active upload.

uploads.abort_upload(username, virtual_path)

clear_upload()

Removes an upload from the queue.

uploads.clear_upload(username, virtual_path)

Upload Queue Methods

get_uploads()

Returns all uploads.

all_uploads = uploads.get_uploads()

uploads · dict

Dictionary mapping (username, virtual_path) to upload info

get_active_uploads()

Returns currently active uploads.

active = uploads.get_active_uploads()

get_queued_uploads()

Returns queued uploads.

queued = uploads.get_queued_uploads()

get_user_uploads()

Returns uploads to a specific user.

user_uploads = uploads.get_user_uploads("username")

Queue Management

update_upload_limits()

Updates the number of simultaneous upload slots.

uploads.update_upload_limits(slots=2, privileged_slots=1)

slots · int · default: "2"

Number of normal upload slots

privileged_slots · int · default: "1"

Number of slots for privileged users

ban_user()

Bans a user from downloading.

uploads.ban_user("username")

unban_user()

Removes a user from the ban list.

uploads.unban_user("username")

Transfer Status

Transfers have several possible statuses:

Show Download Status

• Queued: Waiting to start
• Getting status: Requesting file info
• Transferring: Actively downloading
• Paused: Manually paused
• Filtered: Blocked by file filter
• Finished: Completed successfully
• Failed: Transfer failed
• Aborted: Manually cancelled

Show Upload Status

• Queued: Waiting to start
• Transferring: Actively uploading
• Finished: Completed successfully
• Failed: Transfer failed
• Aborted: Manually cancelled
• Banned: User is banned

Events

The Transfers module emits events for tracking transfer progress:

from pynicotine.events import events

# Download started
events.connect("download-started", on_download_started)

# Download progress
events.connect("download-progress", on_download_progress)

# Download finished
events.connect("download-finished", on_download_finished)

# Upload started
events.connect("upload-started", on_upload_started)

# Upload finished
events.connect("upload-finished", on_upload_finished)

def on_download_started(username, virtual_path):
    print(f"Download started: {virtual_path} from {username}")

def on_download_progress(username, virtual_path, bytes_downloaded, total_size):
    progress = (bytes_downloaded / total_size) * 100
    print(f"Download progress: {progress:.1f}%")

def on_download_finished(username, virtual_path, local_path):
    print(f"Download complete: {local_path}")

def on_upload_started(username, virtual_path):
    print(f"Upload started: {virtual_path} to {username}")

def on_upload_finished(username, virtual_path):
    print(f"Upload complete to {username}")

Complete Example

from pynicotine.transfers import Transfers
from pynicotine.events import events
from pynicotine.core import core

# Initialize transfers
transfers = Transfers()
downloads = transfers.get_downloads()
uploads = transfers.get_uploads()

# Configure bandwidth limits
transfers.set_transfer_speed_limit(
    download_limit=2048,  # 2 MB/s
    upload_limit=1024     # 1 MB/s
)

# Configure upload slots
uploads.update_upload_limits(slots=3, privileged_slots=2)

# Track downloads
active_downloads = {}

def on_download_started(username, virtual_path):
    key = (username, virtual_path)
    active_downloads[key] = {
        'started': time.time(),
        'bytes': 0
    }
    print(f"Started: {virtual_path}")

def on_download_progress(username, virtual_path, bytes_downloaded, total_size):
    key = (username, virtual_path)
    active_downloads[key]['bytes'] = bytes_downloaded
    
    # Calculate speed
    elapsed = time.time() - active_downloads[key]['started']
    speed = bytes_downloaded / elapsed / 1024  # KB/s
    progress = (bytes_downloaded / total_size) * 100
    
    print(f"{virtual_path}: {progress:.1f}% @ {speed:.1f} KB/s")

def on_download_finished(username, virtual_path, local_path):
    key = (username, virtual_path)
    if key in active_downloads:
        elapsed = time.time() - active_downloads[key]['started']
        print(f"Completed in {elapsed:.1f}s: {local_path}")
        del active_downloads[key]

# Connect events
events.connect("download-started", on_download_started)
events.connect("download-progress", on_download_progress)
events.connect("download-finished", on_download_finished)

# Add downloads
downloads.add_download(
    username="user123",
    virtual_path="Music/Album/01-track.flac",
    size=45000000,
    local_path="/home/user/Downloads/track.flac"
)

# Download entire folder
downloads.add_download_folder(
    username="user456",
    folder="Music/Complete Discography",
    local_path="/home/user/Downloads/Discography",
    prefix_username=True
)

# Check queue status
print(f"Active downloads: {len(downloads.get_active_downloads())}")
print(f"Queued downloads: {len(downloads.get_queued_downloads())}")
print(f"Active uploads: {len(uploads.get_active_uploads())}")

Best Practices

• Set reasonable bandwidth limits to avoid network congestion
• Monitor transfer events for real-time progress tracking
• Use prioritize flag for urgent downloads
• Handle failed transfers with retry logic
• Clean up completed transfers periodically
• Configure upload slots based on your upload bandwidth
• Use folder downloads for batch operations
• Implement queue management to control simultaneous transfers