adds docs fixes , compatibility fixes , lint , ci , precommit improvements

Author: Josephrp

.github/workflows/build-documentation.yml

@@ -1,6 +1,21 @@
 name: Build Documentation
 
 on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'dev/mkdocs.yml'
+      - '.readthedocs.yaml'
+      - 'dev/requirements-rtd.txt'
+      - 'ccbt/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'dev/mkdocs.yml'
+      - '.readthedocs.yaml'
+      - 'dev/requirements-rtd.txt'
   workflow_dispatch:
     # Can be triggered manually from any branch for testing
     # Documentation is automatically published to Read the Docs when changes are pushed
@@ -94,16 +109,13 @@ jobs:
       
       - name: Generate coverage report
         run: |
-          uv run pytest -c dev/pytest.ini tests/ --cov=ccbt --cov-report=html:site/reports/htmlcov || echo "⚠️  Coverage report generation failed, continuing..."
+          uv run pytest -c dev/pytest.ini tests/ --cov=ccbt --cov-report=html:site/reports/htmlcov
         continue-on-error: true
 
-      - name: Generate Bandit reports
+      - name: Generate Bandit report
         run: |
           uv run python tests/scripts/ensure_bandit_dir.py
-          # Generate main bandit report
-          uv run bandit -r ccbt/ -f json -o docs/reports/bandit/bandit-report.json --severity-level medium -x tests,benchmarks,dev,dist,docs,htmlcov,site,.venv,.pre-commit-cache,.pre-commit-home,.pytest_cache,.ruff_cache,.hypothesis,.github,.ccbt,.cursor,.benchmarks || echo "⚠️  Bandit report generation failed"
-          # Generate all severity levels report
-          uv run bandit -r ccbt/ -f json -o docs/reports/bandit/bandit-report-all.json --severity-level all -x tests,benchmarks,dev,dist,docs,htmlcov,site,.venv,.pre-commit-cache,.pre-commit-home,.pytest_cache,.ruff_cache,.hypothesis,.github,.ccbt,.cursor,.benchmarks || echo "⚠️  Bandit all report generation failed"
+          uv run bandit -r ccbt/ -f json -o docs/reports/bandit/bandit-report.json --severity-level medium -x tests,benchmarks,dev,dist,docs,htmlcov,site,.venv,.pre-commit-cache,.pre-commit-home,.pytest_cache,.ruff_cache,.hypothesis,.github,.ccbt,.cursor,.benchmarks
         continue-on-error: true
 
       - name: Ensure report files exist in documentation location
@@ -162,6 +174,34 @@ jobs:
           path: site/
           retention-days: 7
 
+      - name: Trigger Read the Docs build
+        if: env.RTD_API_TOKEN != ''
+        env:
+          RTD_API_TOKEN: ${{ secrets.RTD_API_TOKEN }}
+          RTD_PROJECT_SLUG: ${{ secrets.RTD_PROJECT_SLUG || 'ccbittorrent' }}
+          BRANCH_NAME: ${{ github.ref_name }}
+        run: |
+          echo "Triggering Read the Docs build for branch: $BRANCH_NAME"
+          curl -X POST \
+            -H "Authorization: Token $RTD_API_TOKEN" \
+            -H "Content-Type: application/json" \
+            "https://readthedocs.org/api/v3/projects/$RTD_PROJECT_SLUG/versions/$BRANCH_NAME/builds/" \
+            -d "{}" || echo "⚠️  Failed to trigger Read the Docs build. This may be expected if the branch is not configured in Read the Docs."
+        continue-on-error: true
+      
+      - name: Read the Docs build info
+        if: env.RTD_API_TOKEN == ''
+        run: |
+          echo "ℹ️  Read the Docs API token not configured."
+          echo "   To enable automatic Read the Docs builds from any branch:"
+          echo "   1. Get your Read the Docs API token from https://readthedocs.org/accounts/token/"
+          echo "   2. Add it as a GitHub secret named RTD_API_TOKEN"
+          echo "   3. Optionally set RTD_PROJECT_SLUG secret (defaults to 'ccbittorrent')"
+          echo ""
+          echo "   Note: Read the Docs will only build branches configured in your project settings."
+          echo "   By default, only 'main' and 'dev' branches are built automatically."
+      
       # Note: Documentation is automatically published to Read the Docs
-      # when changes are pushed to the repository. No GitHub Pages deployment needed.
+      # when changes are pushed to the repository for configured branches (main/dev by default).
+      # To build other branches, configure them in Read the Docs project settings or use the API trigger above.
 

ccbt/cli/main.py

@@ -1236,7 +1236,7 @@ def _apply_nat_overrides(cfg: Config, options: dict[str, Any]) -> None:
 
 def _apply_protocol_v2_overrides(cfg: Config, options: dict[str, Any]) -> None:
     """Apply Protocol v2-related CLI overrides."""
-    # v2_only flag sets all v2 options
+    # v2_only flag sets all v2 options (takes precedence)
     if options.get("v2_only"):
         cfg.network.protocol_v2.enable_protocol_v2 = True
         cfg.network.protocol_v2.prefer_protocol_v2 = True
@@ -1435,6 +1435,10 @@ def cli(ctx, config, verbose, debug):
 )
 @click.option("--unchoke-interval", type=float, help=_("Unchoke interval (s)"))
 @click.option("--metrics-interval", type=float, help=_("Metrics interval (s)"))
+@click.option("--enable-v2", "enable_v2", is_flag=True, help=_("Enable Protocol v2 (BEP 52)"))
+@click.option("--disable-v2", "disable_v2", is_flag=True, help=_("Disable Protocol v2 (BEP 52)"))
+@click.option("--prefer-v2", "prefer_v2", is_flag=True, help=_("Prefer Protocol v2 when available"))
+@click.option("--v2-only", "v2_only", is_flag=True, help=_("Use Protocol v2 only (disable v1)"))
 @click.pass_context
 def download(
     ctx,
@@ -1771,6 +1775,10 @@ async def _add_torrent_to_daemon():
 )
 @click.option("--unchoke-interval", type=float, help=_("Unchoke interval (s)"))
 @click.option("--metrics-interval", type=float, help=_("Metrics interval (s)"))
+@click.option("--enable-v2", "enable_v2", is_flag=True, help=_("Enable Protocol v2 (BEP 52)"))
+@click.option("--disable-v2", "disable_v2", is_flag=True, help=_("Disable Protocol v2 (BEP 52)"))
+@click.option("--prefer-v2", "prefer_v2", is_flag=True, help=_("Prefer Protocol v2 when available"))
+@click.option("--v2-only", "v2_only", is_flag=True, help=_("Use Protocol v2 only (disable v1)"))
 @click.pass_context
 def magnet(
     ctx,

ccbt/cli/overrides.py

@@ -488,11 +488,14 @@ def _apply_utp_overrides(cfg: Config, options: dict[str, Any]) -> None:
 
 
 def _apply_protocol_v2_overrides(cfg: Config, options: dict[str, Any]) -> None:
+    """Apply Protocol v2-related CLI overrides."""
+    # v2_only flag sets all v2 options (takes precedence)
     if options.get("v2_only"):
         cfg.network.protocol_v2.enable_protocol_v2 = True
         cfg.network.protocol_v2.prefer_protocol_v2 = True
         cfg.network.protocol_v2.support_hybrid = False
-    if not options.get("v2_only"):
+    else:
+        # Individual flags (only if v2_only is not set)
         if options.get("enable_v2"):
             cfg.network.protocol_v2.enable_protocol_v2 = True
         if options.get("disable_v2"):

ccbt/consensus/__init__.py

@@ -25,3 +25,9 @@
     "RaftState",
     "RaftStateType",
 ]
+
+
+
+
+
+

ccbt/nat/port_mapping.py

@@ -7,12 +7,12 @@
 import time
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
-from typing import Optional
+from typing import Optional, Tuple
 
 logger = logging.getLogger(__name__)
 
 # Type alias for renewal callback (using string for forward reference)
-RenewalCallback = Callable[["PortMapping"], Awaitable[tuple[bool, Optional[int]]]]
+RenewalCallback = Callable[["PortMapping"], Awaitable[Tuple[bool, Optional[int]]]]
 
 
 @dataclass

ccbt/session/checkpointing.py

@@ -679,6 +679,9 @@ async def resume_from_checkpoint(
             # Restore security state if available
             await self._restore_security_state(checkpoint, session)
 
+            # Restore rate limits if available
+            await self._restore_rate_limits(checkpoint, session)
+
             # Restore session state if available
             await self._restore_session_state(checkpoint, session)
 
@@ -1106,6 +1109,44 @@ async def _restore_security_state(
             if self._ctx.logger:
                 self._ctx.logger.debug("Failed to restore security state: %s", e)
 
+    async def _restore_rate_limits(
+        self, checkpoint: TorrentCheckpoint, session: Any
+    ) -> None:
+        """Restore rate limits from checkpoint."""
+        try:
+            if not checkpoint.rate_limits:
+                return
+
+            # Get session manager
+            session_manager = getattr(session, "session_manager", None)
+            if not session_manager:
+                return
+
+            # Get info hash
+            info_hash = getattr(self._ctx.info, "info_hash", None)
+            if not info_hash:
+                return
+
+            # Convert info hash to hex string for set_rate_limits
+            info_hash_hex = info_hash.hex()
+
+            # Restore rate limits via session manager
+            if hasattr(session_manager, "set_rate_limits"):
+                down_kib = checkpoint.rate_limits.get("down_kib", 0)
+                up_kib = checkpoint.rate_limits.get("up_kib", 0)
+                await session_manager.set_rate_limits(
+                    info_hash_hex, down_kib, up_kib
+                )
+                if self._ctx.logger:
+                    self._ctx.logger.debug(
+                        "Restored rate limits: down=%d KiB/s, up=%d KiB/s",
+                        down_kib,
+                        up_kib,
+                    )
+        except Exception as e:
+            if self._ctx.logger:
+                self._ctx.logger.debug("Failed to restore rate limits: %s", e)
+
     async def _restore_session_state(
         self, checkpoint: TorrentCheckpoint, session: Any
     ) -> None:

ccbt/session/download_startup.py

@@ -3,3 +3,9 @@
 This module handles the initialization and startup sequence for torrent downloads,
 including metadata retrieval, piece manager setup, and initial peer connections.
 """
+
+
+
+
+
+

ccbt/session/manager_startup.py

@@ -3,3 +3,9 @@
 This module handles the startup sequence for the session manager, including
 component initialization, service startup, and background task coordination.
 """
+
+
+
+
+
+

ccbt/session/session.py

@@ -4091,6 +4091,10 @@ async def add_torrent(
             session = AsyncTorrentSession(torrent_data, session_output_dir, self)
             self.torrents[info_hash] = session
 
+        # Add to private_torrents set if torrent is private (BEP 27)
+        if session.is_private:
+            self.private_torrents.add(info_hash)
+
         # Get torrent name for callback
         if isinstance(torrent_data, dict):
             torrent_name = torrent_data.get("name", "Unknown")

ccbt/transport/utp.py

@@ -20,7 +20,7 @@
 import time
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import Callable, Optional
+from typing import Callable, Optional, Tuple
 
 from ccbt.config.config import get_config
 
@@ -230,7 +230,7 @@ def unpack(data: bytes) -> UTPPacket:
 
 
 # Connection state tracking tuple: (packet, send_time, retry_count)
-_PacketInfo = tuple[UTPPacket, float, int]
+_PacketInfo = Tuple[UTPPacket, float, int]
 
 
 class UTPConnection: