Documentation Index
Fetch the complete documentation index at: https://mintlify.com/nicotine-plus/nicotine-plus/llms.txt
Use this file to discover all available pages before exploring further.
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 speed limit in KB/s (0 for unlimited)
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 to download from
Virtual path of the file on the remote user’s share
File size in bytes (if known)
Local filesystem path where file will be saved
Place at front of download queue
abort_download()
Aborts an active download.
downloads.abort_download(username, virtual_path)
abort_downloads()
Aborts multiple downloads.
downloads.abort_downloads([
("user1", "path/to/file1.mp3"),
("user2", "path/to/file2.flac")
])
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()
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 to download from
Local directory to save files
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 requesting the file
Virtual path in your shares
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()
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)
Number of normal upload slots
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:
- 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
- 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