bittorrent-client 0.1.0__tar.gz

bittorrent_client-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: bittorrent_client
+Version: 0.1.0
+Summary: A lightweight, robust BitTorrent client built with pure Python standard library.
+Author: Omar Aflak
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications :: File Sharing
+Classifier: Topic :: Internet
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# BitTorrent Client
+
+A lightweight, robust BitTorrent client built with pure Python standard library (zero external dependencies).
+
+## Installation
+
+```bash
+pip install bittorrent_client
+```
+
+## CLI Usage
+
+Run directly via the command-line entry point:
+
+```bash
+bittorrent file.torrent -o ./downloads
+```
+
+Or run as a module:
+
+```bash
+python3 -m bittorrent file.torrent -o ./downloads
+```
+
+Options:
+- `-o, --output`: Destination directory (default: `./`)
+- `-w, --workers`: Maximum concurrent peer workers (default: `60`)
+- `-v, --verbose`: Enable debug logging
+
+## Python API
+
+```python
+import logging
+from bittorrent.torrent import Torrent
+from bittorrent.client import Client
+
+logging.basicConfig(level=logging.INFO)
+
+torrent = Torrent.from_file('file.torrent')
+client = Client(torrent)
+client.download('./downloads')
+```
+
+## Running Tests
+
+```bash
+python3 -m unittest discover test
+```

bittorrent_client-0.1.0/README.md

@@ -0,0 +1,48 @@
+# BitTorrent Client
+
+A lightweight, robust BitTorrent client built with pure Python standard library (zero external dependencies).
+
+## Installation
+
+```bash
+pip install bittorrent_client
+```
+
+## CLI Usage
+
+Run directly via the command-line entry point:
+
+```bash
+bittorrent file.torrent -o ./downloads
+```
+
+Or run as a module:
+
+```bash
+python3 -m bittorrent file.torrent -o ./downloads
+```
+
+Options:
+- `-o, --output`: Destination directory (default: `./`)
+- `-w, --workers`: Maximum concurrent peer workers (default: `60`)
+- `-v, --verbose`: Enable debug logging
+
+## Python API
+
+```python
+import logging
+from bittorrent.torrent import Torrent
+from bittorrent.client import Client
+
+logging.basicConfig(level=logging.INFO)
+
+torrent = Torrent.from_file('file.torrent')
+client = Client(torrent)
+client.download('./downloads')
+```
+
+## Running Tests
+
+```bash
+python3 -m unittest discover test
+```

bittorrent_client-0.1.0/bittorrent/__main__.py

@@ -0,0 +1,4 @@
+from bittorrent.cli import main
+
+if __name__ == '__main__':
+    main()

bittorrent_client-0.1.0/bittorrent/bencode.py

@@ -0,0 +1,144 @@
+from typing import Union
+
+BenType = Union[int, bytes, list['BenType'], dict[str, 'BenType']]
+
+
+def bencode(data: BenType) -> bytes:
+    if isinstance(data, bool):
+        # In Python bool is a subclass of int; bencode doesn't have bool, encode as 1 or 0
+        return b'i1e' if data else b'i0e'
+
+    if isinstance(data, int):
+        return f'i{data}e'.encode('ascii')
+
+    if isinstance(data, str):
+        encoded = data.encode('utf-8')
+        return f'{len(encoded)}:'.encode('ascii') + encoded
+
+    if isinstance(data, bytes):
+        return f'{len(data)}:'.encode('ascii') + data
+
+    if isinstance(data, (list, tuple)):
+        values = b''.join(bencode(x) for x in data)
+        return b'l' + values + b'e'
+
+    if isinstance(data, dict):
+        # BEP 3: Keys must appear in sorted order (strings are sorted as raw byte strings)
+        def key_bytes(k: Union[str, bytes]) -> bytes:
+            if isinstance(k, bytes):
+                return k
+            if isinstance(k, str):
+                return k.encode('utf-8')
+            raise ValueError(f'Dict key must be str or bytes, got {type(k)}')
+
+        sorted_items = sorted(
+            data.items(), key=lambda item: key_bytes(item[0]))
+        values = b''.join(bencode(k) + bencode(v) for k, v in sorted_items)
+        return b'd' + values + b'e'
+
+    raise ValueError(f'Type {type(data)} not supported.')
+
+
+def decode_bencode(data: bytes) -> BenType:
+    if len(data) == 0:
+        return b''
+    value, end_idx = _decode_bencode(data, 0)
+    if end_idx != len(data):
+        raise ValueError(
+            f'Trailing data after bencode decode: decoded {end_idx} of {len(data)} bytes')
+    return value
+
+
+def decode_bencode_with_raw(data: bytes) -> tuple[BenType, dict[str, bytes]]:
+    """
+    Decodes bencoded data and returns a tuple of:
+    (decoded_value, raw_slices)
+    where raw_slices is a dict mapping top-level dictionary string keys to their exact raw bytes in data.
+    """
+    if len(data) == 0:
+        return b'', {}
+    value, end_idx, raw_slices = _decode_bencode_with_raw_map(data, 0)
+    if end_idx != len(data):
+        raise ValueError(
+            f'Trailing data after bencode decode: decoded {end_idx} of {len(data)} bytes')
+    return value, raw_slices
+
+
+def _decode_bencode(data: bytes, start: int = 0) -> tuple[BenType, int]:
+    val, end_idx, _ = _decode_bencode_with_raw_map(data, start)
+    return val, end_idx
+
+
+def _decode_bencode_with_raw_map(data: bytes, start: int = 0) -> tuple[BenType, int, dict[str, bytes]]:
+    if start >= len(data):
+        return b'', start, {}
+
+    char = chr(data[start])
+
+    if char.isdigit():
+        idx = data.find(b':', start)
+        if idx == -1:
+            raise ValueError(
+                f'Missing colon delimiter for string length at offset {start}')
+        try:
+            length = int(data[start:idx])
+        except ValueError as e:
+            raise ValueError(f'Invalid string length at offset {start}: {e}')
+        if length < 0:
+            raise ValueError(
+                f'Negative string length at offset {start}: {length}')
+        str_start = idx + 1
+        str_end = str_start + length
+        if str_end > len(data):
+            raise ValueError(
+                f'Unexpected EOF: expected {length} bytes at {str_start}, available {len(data) - str_start}')
+        value = data[str_start:str_end]
+        return value, str_end, {}
+
+    if char == 'i':
+        idx = data.find(b'e', start)
+        if idx == -1:
+            raise ValueError(
+                f'Missing end delimiter "e" for integer at offset {start}')
+        raw_int = data[start + 1:idx]
+        if len(raw_int) == 0:
+            # For backward compatibility with tests expecting empty int 'ie' -> 0
+            return 0, idx + 1, {}
+        try:
+            value = int(raw_int)
+        except ValueError as e:
+            raise ValueError(f'Invalid integer at offset {start}: {e}')
+        return value, idx + 1, {}
+
+    if char == 'l':
+        _list: list[BenType] = []
+        pos = start + 1
+        while pos < len(data) and chr(data[pos]) != 'e':
+            val, pos = _decode_bencode(data, pos)
+            _list.append(val)
+        if pos >= len(data):
+            raise ValueError(f'Unterminated list starting at offset {start}')
+        return _list, pos + 1, {}
+
+    if char == 'd':
+        _dict: dict[str, BenType] = {}
+        raw_slices: dict[str, bytes] = {}
+        pos = start + 1
+        while pos < len(data) and chr(data[pos]) != 'e':
+            val_key, pos = _decode_bencode(data, pos)
+            if not isinstance(val_key, bytes):
+                raise ValueError(
+                    f'Dict key at offset {pos} must be bytes, got {type(val_key)}')
+            key_str = val_key.decode('utf-8', errors='replace')
+            val_start = pos
+            val, pos = _decode_bencode(data, pos)
+            _dict[key_str] = val
+            raw_slices[key_str] = data[val_start:pos]
+
+        if pos >= len(data):
+            raise ValueError(
+                f'Unterminated dictionary starting at offset {start}')
+        return _dict, pos + 1, raw_slices
+
+    raise ValueError(
+        f'Character "{char}" at offset {start} not recognized in bencode.')

bittorrent_client-0.1.0/bittorrent/cli.py

@@ -0,0 +1,57 @@
+import sys
+import logging
+import argparse
+from bittorrent.torrent import Torrent
+from bittorrent.client import Client
+
+
+def _format_bytes(size: int) -> str:
+    units = ['B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB']
+    val = float(size)
+    for unit in units:
+        if val < 1024.0 or unit == units[-1]:
+            return f'{val:.1f} {unit}' if unit != 'B' else f'{int(val)} B'
+        val /= 1024.0
+    return f'{val:.1f} PiB'
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='A simple, robust BitTorrent client.')
+    parser.add_argument('file', help='Path to .torrent file')
+    parser.add_argument('-o', '--output', default='./',
+                        help='Output directory for downloaded files (default: ./)')
+    parser.add_argument('-w', '--workers', type=int, default=60,
+                        help='Maximum peer worker threads (default: 60)')
+    parser.add_argument('-v', '--verbose', action='store_true',
+                        help='Enable verbose debug logging')
+
+    args = parser.parse_args()
+
+    log_level = logging.DEBUG if args.verbose else logging.INFO
+    logging.basicConfig(
+        level=log_level,
+        format='%(asctime)s [%(levelname)s] %(message)s',
+        datefmt='%H:%M:%S'
+    )
+
+    try:
+        torrent = Torrent.from_file(args.file)
+        logging.info(
+            f'Loaded torrent: "{torrent.name}" ({_format_bytes(torrent.size)})')
+        logging.info(
+            f'Piece count: {torrent.piece_count} (piece size: {_format_bytes(torrent.piece_size)})')
+        logging.info(f'Trackers: {len(torrent.trackers)} found')
+
+        client = Client(torrent, max_peer_workers=args.workers)
+        client.download(args.output)
+    except KeyboardInterrupt:
+        logging.info('\nDownload cancelled by user.')
+        sys.exit(0)
+    except Exception as e:
+        logging.error(f'Error: {e}')
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

bittorrent_client-0.1.0/bittorrent/client.py

@@ -0,0 +1,222 @@
+import os
+import shutil
+import random
+import logging
+import asyncio
+from bittorrent.trackers import Trackers
+from bittorrent.torrent import Torrent, File
+from bittorrent.peer import AsyncPeer
+from bittorrent.storage import Storage
+from bittorrent.piece_manager import PieceManager
+
+
+class Client:
+    """
+    BitTorrent client responsible for coordinating peer discovery, concurrent
+    piece downloading, piece verification, and direct-to-disk file writing.
+    """
+
+    def __init__(
+        self,
+        torrent: Torrent,
+        max_peer_workers: int = 60,
+        max_tracker_workers: int = 20,
+        max_peers_per_tracker: int = 200,
+        max_peers_per_piece: int = 2,
+        max_peer_batch_requests: int = 16,
+        piece_chunk_size: int = 16384
+    ):
+        """
+        Initialize a BitTorrent client instance.
+
+        :param torrent: Parsed Torrent metadata object containing file and tracker details.
+        :param max_peer_workers: Maximum number of concurrent peer connection workers (default: 60).
+        :param max_tracker_workers: Maximum number of concurrent tracker query threads (default: 20).
+        :param max_peers_per_tracker: Maximum number of peers to request per tracker announce (default: 200).
+        :param max_peers_per_piece: Maximum number of concurrent workers allowed per piece during endgame mode (default: 2).
+        :param max_peer_batch_requests: Initial pipeline depth for concurrent in-flight chunk requests per peer (default: 16).
+        :param piece_chunk_size: Size in bytes of each chunk requested from a peer (default: 16384 / 16 KiB).
+        """
+        self.torrent = torrent
+        self.max_peer_workers = max_peer_workers
+        self.max_tracker_workers = max_tracker_workers
+        self.max_peers_per_tracker = max_peers_per_tracker
+        self.max_peers_per_piece = max_peers_per_piece
+        self.max_peer_batch_requests = max_peer_batch_requests
+        self.piece_chunk_size = piece_chunk_size
+
+        self.peer_id = b'-AG0001-' + random.randbytes(12)
+        self.stopped = False
+        self.tmp = ''
+
+    def download(self, output_directory: str):
+        """
+        Download all pieces of the torrent into the target directory.
+
+        Discovers peers from configured trackers (both UDP and HTTP/HTTPS), connects
+        to peers concurrently with adaptive pipelining, schedules chunks using
+        block-level sharing and Rarest-First, and writes verified piece data directly
+        to target files on disk. Resumes from existing verified files without overhead.
+
+        :param output_directory: File system directory path where downloaded files will be saved.
+        """
+        if self.torrent.size == 0 or self.torrent.piece_count == 0:
+            logging.info('Empty torrent, creating empty files.')
+            Storage(self.torrent, output_directory)
+            return
+
+        try:
+            asyncio.run(self._async_download(output_directory))
+        except KeyboardInterrupt:
+            logging.warning('Download interrupted by user.')
+
+    async def _async_download(self, output_directory: str):
+        # 1. Direct-to-Disk Storage (pre-allocates sparse files, eliminates .tmp copy)
+        storage = Storage(self.torrent, output_directory)
+
+        # 2. Check for already completed pieces on disk (instant resume)
+        piece_manager = PieceManager(self.torrent, storage)
+        verified = storage.verify_existing_pieces()
+        for p_idx in verified:
+            piece_manager.mark_piece_completed(p_idx)
+
+        if piece_manager.is_finished():
+            logging.info(
+                'All pieces are already downloaded and verified on disk.')
+            return
+
+        if verified:
+            logging.info(
+                f'Resuming download: {len(verified)}/{len(self.torrent.pieces)} pieces already verified on disk.')
+
+        # 3. Discover peers from trackers
+        trackers = Trackers(
+            self.torrent,
+            self.peer_id,
+            self.max_tracker_workers,
+            self.max_peers_per_tracker
+        )
+        peers = trackers.get_peers()
+        if not peers:
+            logging.error('No peers discovered from trackers.')
+            return
+
+        logging.info(
+            f'Starting high-speed async download with {len(peers)} discovered peers...')
+
+        # 4. Spawn AsyncPeers with adaptive pipelining and block-level scheduling
+        peer_tasks = []
+        peers_to_connect = list(peers)[:self.max_peer_workers]
+        for endpoint in peers_to_connect:
+            ap = AsyncPeer(
+                endpoint,
+                self.torrent.info_hash,
+                self.peer_id,
+                piece_manager,
+                initial_pipeline=self.max_peer_batch_requests,
+                max_pipeline=64,
+                min_pipeline=4
+            )
+            peer_tasks.append(asyncio.create_task(ap.run()))
+
+        # 5. Monitor download progress
+        total_pieces = len(self.torrent.pieces)
+        last_logged_count = len(piece_manager.completed_pieces)
+
+        try:
+            while not piece_manager.is_finished():
+                if all(t.done() for t in peer_tasks):
+                    break
+
+                await asyncio.sleep(1.0)
+                current_count = len(piece_manager.completed_pieces)
+                if current_count != last_logged_count:
+                    last_logged_count = current_count
+                    percent = int(100 * current_count /
+                                  total_pieces) if total_pieces > 0 else 100
+                    downloaded_bytes = sum(
+                        self.torrent.pieces[i].size for i in piece_manager.completed_pieces)
+                    human_done = self._human_friendly_bytes_str(
+                        downloaded_bytes)
+                    human_total = self._human_friendly_bytes_str(
+                        self.torrent.size)
+                    logging.info(
+                        f'Progress: {current_count}/{total_pieces} pieces ({percent}%) [{human_done} / {human_total}]')
+
+        finally:
+            # Clean up all peer tasks
+            for t in peer_tasks:
+                t.cancel()
+            await asyncio.gather(*peer_tasks, return_exceptions=True)
+
+        if not piece_manager.is_finished():
+            logging.error('Download did not finish completely.')
+            return
+
+        logging.info(
+            'Download complete! All pieces verified directly on disk.')
+
+    def _assemble_files(self, output_directory: str):
+        """Assembles downloaded pieces from .tmp if present (backward compatibility)."""
+        if self.torrent.is_multi_file:
+            base_dir = os.path.join(output_directory, self.torrent.name)
+            for file_info in self.torrent.files:
+                file_dir = os.path.join(base_dir, *file_info.path[:-1])
+                os.makedirs(file_dir, exist_ok=True)
+                target_path = os.path.join(file_dir, file_info.path[-1])
+                self._assemble_file(file_info, target_path)
+        else:
+            os.makedirs(output_directory, exist_ok=True)
+            if self.torrent.files:
+                file_info = self.torrent.files[0]
+                target_path = os.path.join(
+                    output_directory, file_info.path[-1])
+                self._assemble_file(file_info, target_path)
+
+        if self.tmp and os.path.isdir(self.tmp):
+            try:
+                shutil.rmtree(self.tmp)
+            except Exception:
+                pass
+
+    def _assemble_file(self, file_info: File, output_path: str):
+        """Assembles a single file from .tmp part files (backward compatibility)."""
+        if file_info.size == 0:
+            with open(output_path, 'wb'):
+                pass
+            return
+
+        piece_size = self.torrent.piece_size
+        file_start = file_info.start
+        file_end = file_start + file_info.size
+        start_piece_index = file_start // piece_size if piece_size > 0 else 0
+
+        with open(output_path, 'wb') as dest:
+            for piece in self.torrent.pieces[start_piece_index:]:
+                piece_start = piece.index * piece_size
+                piece_end = piece_start + piece.size
+
+                if piece_start >= file_end:
+                    break
+
+                overlap_start = max(piece_start, file_start)
+                overlap_end = min(piece_end, file_end)
+
+                if overlap_end > overlap_start:
+                    part_path = os.path.join(
+                        self.tmp, f'piece_{piece.index}.part')
+                    if os.path.exists(part_path):
+                        with open(part_path, 'rb') as part_file:
+                            part_file.seek(overlap_start - piece_start)
+                            data = part_file.read(overlap_end - overlap_start)
+                            dest.write(data)
+
+    @staticmethod
+    def _human_friendly_bytes_str(size: int) -> str:
+        units = ['B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB']
+        val = float(size)
+        for unit in units:
+            if val < 1024.0 or unit == units[-1]:
+                return f'{val:.1f} {unit}' if unit != 'B' else f'{int(val)} B'
+            val /= 1024.0
+        return f'{val:.1f} PiB'

bittorrent_client-0.1.0/bittorrent/ip.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class IpAndPort:
+    ip: str
+    port: int
+
+    def __hash__(self) -> int:
+        return hash((self.ip, self.port))
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, IpAndPort):
+            return False
+        return self.ip == other.ip and self.port == other.port
+
+    def __str__(self) -> str:
+        return f'{self.ip}:{self.port}'