{"id":51220964,"url":"https://github.com/sankhya007/python-bittorrent-implementation","last_synced_at":"2026-06-28T07:03:06.524Z","repository":{"id":321181768,"uuid":"1084720473","full_name":"sankhya007/python-bittorrent-implementation","owner":"sankhya007","description":"Python BitTorrent Client - Complete protocol implementation from scratch. Features torrent parsing, HTTP/UDP trackers, peer connections, piece management, and file downloading. Educational project for learning P2P networking.","archived":false,"fork":false,"pushed_at":"2025-10-28T07:56:02.000Z","size":76,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-28T09:29:09.055Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sankhya007.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-28T04:20:51.000Z","updated_at":"2025-10-28T07:56:05.000Z","dependencies_parsed_at":"2025-10-28T09:29:14.374Z","dependency_job_id":null,"html_url":"https://github.com/sankhya007/python-bittorrent-implementation","commit_stats":null,"previous_names":["sankhya007/python-bittorrent-implementation"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sankhya007/python-bittorrent-implementation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sankhya007%2Fpython-bittorrent-implementation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sankhya007%2Fpython-bittorrent-implementation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sankhya007%2Fpython-bittorrent-implementation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sankhya007%2Fpython-bittorrent-implementation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sankhya007","download_url":"https://codeload.github.com/sankhya007/python-bittorrent-implementation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sankhya007%2Fpython-bittorrent-implementation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34880191,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-28T07:03:05.351Z","updated_at":"2026-06-28T07:03:06.502Z","avatar_url":"https://github.com/sankhya007.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"🧲 Python BitTorrent Client\n============================\n\nA fully-featured, production-ready BitTorrent client implemented from scratch in Python. \nThis isn't just another toy implementation - it's a robust, efficient client with smart \npeer selection, comprehensive error handling, and real-world performance optimizations.\n\n📋 Table of Contents\n• Features\n• Architecture Overview\n• Installation\n• Quick Start\n• Usage Examples\n• Advanced Usage\n• Project Structure\n• Protocol Support\n• Performance Features\n• Troubleshooting\n• Contributing\n• License\n\n✨ Features\n===========\n\n🚀 Core Capabilities\n• Full BitTorrent Protocol - Complete implementation of the BitTorrent specification\n• Multi-Tracker Support - HTTP \u0026 UDP trackers with automatic fallback\n• Smart Peer Selection - Performance-based peer scoring and rarest-piece-first algorithm\n• Efficient Downloading - Parallel piece downloads with intelligent request scheduling\n• File Management - Support for both single-file and multi-file torrents\n• Memory Efficient - Stream-based processing for large files\n\n🎯 Advanced Features\n• Peer Scoring System - Dynamic peer performance evaluation\n• Rarest-First Algorithm - Optimized piece selection for swarm health\n• Comprehensive Error Handling - Network resilience and corruption recovery\n• Real-time Progress Tracking - Live download statistics and ETA\n• Automatic Retry Logic - Exponential backoff for failed connections\n• Connection Pooling - Efficient management of multiple peer connections\n\n🔧 Utility Tools\n• Torrent Debugger - Analyze and validate torrent files\n• Tracker Debugger - Test tracker connectivity and peer discovery\n• Network Diagnostics - Comprehensive connectivity testing\n• Torrent Enhancer - Add public trackers to improve availability\n• Torrent Downloader - Fetch test torrents automatically\n\n🏗 Architecture Overview\n=======================\n\nThe client follows a modular, thread-safe architecture:\n\n```\nMain Controller (main.py)\n├── Torrent Parser (torrent.py) - Bencode decoding/encoding\n├── Tracker Manager (tracker.py) - Peer discovery via HTTP/UDP\n├── Peer Manager (peers_manager.py) - Connection pool management\n├── Pieces Manager (pieces_manager.py) - Download orchestration\n├── Piece Manager (piece.py) - Individual piece handling\n├── Block Manager (block.py) - 16KB block operations\n└── Rarest Pieces (rarest_piece.py) - Optimized piece selection\n```\n\n📥 Installation\n===============\n\nPrerequisites\n• Python 3.8 or higher\n• 50MB free disk space\n• Network connectivity (obviously!)\n\n1. Clone the repository:\ngit clone https://github.com/yourusername/python-bittorrent-client.git\ncd python-bittorrent-client\n\n2. Install dependencies:\npip install requests bitstring\n\n3. Verify installation:\npython main.py --help\n\n🚀 Quick Start\n==============\n\n1. Get a torrent file:\npython download_torrents.py\n\n2. Enhance with public trackers (optional):\npython enhance_torrents.py\n\n3. Start downloading:\npython main.py ubuntu-22.04.torrent\n\n\n📖 Usage Examples\n=================\n\nBasic Download\npython main.py debian-12.2.0-amd64-netinst.iso.torrent\n\nDebug Torrent File\npython debug_torrent.py my_torrent.torrent -v\n\nTest Tracker Connectivity\npython debug_tracker.py my_torrent.torrent --verbose\n\nEnhance Torrent with Trackers\npython enhance_torrent.py ubuntu.torrent -o ubuntu_enhanced.torrent\n\nTest Network Connectivity\npython test_connectivity.py\n\n🔧 Advanced Usage\n=================\n\nPerformance Tuning\n# Increase concurrent peers (default: 15)\nEdit peers_manager.py: max_peers_connected = 25\n\n# Adjust request timeouts (default: 30s)\nEdit peer.py: timeout_seconds = 45\n\n# Modify block size (default: 16KB)\nEdit block.py: BLOCK_SIZE = 2 ** 14  # 16KB\n\nMonitoring and Debugging\n# Enable detailed logging\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\n# Real-time peer statistics\npython main.py torrent.file 2\u003e\u00261 | grep \"Peer stats\"\n\n# Download progress to file\npython main.py torrent.file \u003e download.log 2\u003e\u00261\n\n📁 Project Structure\n====================\n\n```\npython-bittorrent-client/\n├── core/\n│   ├── main.py              # Main client and controller\n│   ├── torrent.py           # Torrent file parsing (bencode)\n│   ├── tracker.py           # Tracker communication\n│   ├── peer.py              # Peer connection management\n│   ├── message.py           # Protocol message handling\n│   ├── pieces_manager.py    # Download orchestration\n│   ├── piece.py             # Piece management\n│   ├── block.py             # Block operations\n│   ├── peers_manager.py     # Peer connection pool\n│   └── rarest_piece.py      # Rarest-first algorithm\n├── utilities/\n│   ├── debug_torrent.py     # Torrent file analysis\n│   ├── debug_tracker.py     # Tracker connectivity testing\n│   ├── download_torrents.py # Torrent file fetcher\n│   ├── enhance_torrents.py  # Tracker enhancer\n│   ├── validate_torrents.py # Torrent validation\n│   └── test_connectivity.py # Network diagnostics\n├── logs/\n│   └── bittorrent_client.log # Automatic logging\n└── downloads/               # Completed files\n```\n\n📡 Protocol Support\n===================\n\n✅ Fully Implemented\n• BitTorrent Protocol v1.0\n• HTTP Trackers (announce/scrape)\n• UDP Trackers (connection/announce)\n• Bencoding (decode/encode)\n• Piece/Block protocol\n• Peer wire protocol\n• Choking/Unchoking algorithm\n• Interested/Not Interested\n• Have/Piece messages\n\n🔜 Planned Features\n• DHT (Distributed Hash Table)\n• Magnet URI support\n• Peer Exchange (PEX)\n• UDP Hole Punching\n\n⚡ Performance Features\n======================\n\nSmart Peer Selection\n• Dynamic scoring based on transfer speed, reliability, and response time\n• Automatic unhealthy peer detection and removal\n• Priority given to unchoked, high-performance peers\n\nEfficient Resource Usage\n• Non-blocking I/O with select() for socket management\n• Memory-mapped file writing for large downloads\n• Configurable connection limits to prevent overload\n\nDownload Optimization\n• Rarest-piece-first algorithm for better swarm participation\n• Parallel block requests across multiple peers\n• Request pipelining and congestion control\n\nNetwork Resilience\n• Automatic retry with exponential backoff\n• Multiple tracker fallback support\n• Connection keep-alive and health monitoring\n\n🛠 Troubleshooting\n==================\n\nCommon Issues and Solutions\n\n❌ \"No peers found from trackers\"\n• Run: python test_connectivity.py\n• Try: python enhance_torrents.py\n• Check firewall/antivirus settings\n\n❌ \"Torrent file invalid or corrupted\"\n• Run: python debug_torrent.py your_file.torrent\n• Verify file integrity: python validate_torrents.py\n\n❌ \"Download stalls at low percentage\"\n• This is normal BitTorrent behavior - peers may be choking\n• Client will automatically retry and find new peers\n• Monitor peer count: python debug_tracker.py your_file.torrent\n\n❌ \"Connection timeouts\"\n• Check: python test_connectivity.py\n• Increase timeouts in peer.py\n• Verify network stability\n\n📊 Performance Tips\n\n• Use wired connection instead of WiFi for better stability\n• Ensure sufficient disk space (torrent size + 10% buffer)\n• Run during off-peak hours for better peer availability\n• Use enhance_torrents.py to add more trackers\n\n🤝 Contributing\n===============\n\nWe welcome contributions! Here's how you can help:\n\n1. Fork the repository\n2. Create a feature branch: git checkout -b feature/amazing-feature\n3. Commit your changes: git commit -m 'Add amazing feature'\n4. Push to the branch: git push origin feature/amazing-feature\n5. Open a Pull Request\n\nAreas for Contribution\n• DHT implementation\n• Web interface\n• Performance optimizations\n• Additional protocol features\n• Documentation improvements\n• Bug fixes and testing\n\n🌟 Acknowledgments\n==================\n\nThis implementation represents a complete ground-up rebuild of the BitTorrent protocol\nwith modern Python practices, comprehensive error handling, and production-ready\nreliability. Special thanks to the BitTorrent protocol specification and the open-source\ncommunity for reference implementations and testing resources.\n\n---\n**Happy Downloading!** 🎉\n\nFor support, create an issue on GitHub or check the troubleshooting guide above.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsankhya007%2Fpython-bittorrent-implementation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsankhya007%2Fpython-bittorrent-implementation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsankhya007%2Fpython-bittorrent-implementation/lists"}