BiTorrentPy

BiTorrentPy is a lightweight, dependency-free BitTorrent client written entirely in Python.

It implements the core BitTorrent protocol from scratch, including a custom Bencode parser, UDP tracker communication, and multi-threaded peer wire protocol handling. This project serves as an educational deep-dive into network programming, binary data manipulation, and file synchronization.

🚀 Key Features

• Zero Dependencies: Uses only Python's standard library (socket, struct, threading, os, etc.). No pip install required.
• Custom Bencode Parser: Includes a full implementation of a Bencode decoder and encoder.
• UDP Tracker Support: Implements the binary UDP tracker protocol (Connect/Announce).
• Multi-Threaded Architecture: Handles multiple peer connections simultaneously using threading.
• Rate Limiting: Built-in Token Bucket algorithm to throttle Upload and Download speeds.
• Sparse File Allocation: Efficiently handles storage for multi-file torrents.
• CLI Interface: Simple command-line arguments for control.

💻 Usage

Run the script directly from the terminal. You need a valid .torrent file.

Basic Download

python TorrentPy.py path/to/file.torrent

Advanced Usage

You can limit bandwidth and specify the output directory.

python TorrentPy.py file.torrent --out "./MyDownloads" --down 1024 --up 512

Arguments:

• torrent: (Required) Path to the .torrent metafile.
• --out: Directory to save downloaded files (Default: TorrentDownloads).
• --down: Max download speed in KB/s (Default: 0/Unlimited).
• --up: Max upload speed in KB/s (Default: 0/Unlimited).

🏗️ Architecture

The codebase is modularized into specific functional components:

1. Bencode Engine: Handles the recursive parsing of integers, strings, lists, and dictionaries from the .torrent file.
2. RateLimiter: A thread-safe implementation of the "Token Bucket" algorithm to ensure bandwidth compliance.
3. Network Layer:
   • UDP Tracker: Performs binary packing/unpacking (struct) to communicate with trackers and retrieve peer IPs.
   • PeerWorker: A threaded worker class that manages the TCP handshake, state (Choke/Unchoke), and block exchange with individual peers.
4. Storage Manager:
   • Maps the global byte-stream of the torrent to specific file paths on the disk.
   • Handles reading/writing of specific byte ranges across file boundaries.
5. Session Manager: Orchestrates the bitfield (pieces downloaded), validates piece hashes (SHA1), and assigns work to peers.

🤝 Protocol Support

This client implements the following BitTorrent specifications:

• Bencoding (Parsing/Encoding)
• UDP Tracker Protocol (BEP 15)
• Peer Wire Protocol (Handshake, Bitfield, Request, Piece, Choke, Unchoke)
• Multi-file Torrent support

📝 Example Output

Reading linux-iso.torrent...
Total Size: 850.00 MB
Saving to:  /home/user/TorrentDownloads
Finding peers...
Connected to 35 peers. Starting Download...
12.5% | Down: 2500 KB/s | Up: 50 KB/s | Peers: 28 

⚠️ Disclaimer

This software is developed for educational purposes to demonstrate network protocol implementation. Please respect copyright laws and only use this tool to download content you have the legal right to access (e.g., Open Source Linux ISOs, Public Domain content).