feat: add verbose mode support to GitHubDownloader API

[Kcodess2807]

Add Verbose Logging Support to Python API

📋 Summary

This PR adds verbose logging functionality to the GitHubDownloader Python API, bringing feature parity with the CLI's --verbose option. Users can now enable detailed logging for debugging and monitoring download operations programmatically.

Related Issue

Closes #51 - Add verbose logging support to Python API

Changes Made

New Features

• Added verbose parameter to GitHubDownloader constructor

  • Default value: False (maintains backward compatibility)
  • When True: enables DEBUG-level logging with detailed operation info
  • When False: shows only INFO-level warnings and errors

• Added set_verbose() method for runtime control

  • Allows toggling verbose mode after initialization
  • Useful for conditional debugging scenarios

• Enhanced logging throughout download process

  • Repository information and metadata
  • Git reference resolution details
  • Download execution progress
  • File filtering and selection info
  • Error details and retry attempts

Technical Implementation

• Configures logger level based on verbose setting (DEBUG vs INFO)
• Maintains existing logger infrastructure without breaking changes
• Follows project's logging patterns and conventions
• Thread-safe verbose mode toggling

Usage Examples

Basic Usage

from forklet import GitHubDownloader
from pathlib import Path

# Initialize with verbose logging
downloader = GitHubDownloader(verbose=True)

# Download with detailed logging
result = await downloader.download(
    owner="octocat",
    repo="Hello-World",
    destination=Path("./downloads")
)

Runtime Control

# Start without verbose mode
downloader = GitHubDownloader()

# Enable verbose logging when needed
downloader.set_verbose(True)

# Download with detailed logging
result = await downloader.download_file(...)

# Disable verbose logging
downloader.set_verbose(False)

With Authentication

# Works seamlessly with authentication
downloader = GitHubDownloader(
    auth_token="ghp_xxxx",
    verbose=True
)

🧪 Testing

Test Coverage

• ✅ 9 new unit tests covering all verbose functionality
• ✅ 100% test coverage for new features
• ✅ All existing tests pass (72/72 tests)
• ✅ No breaking changes to existing API

Test Categories

• Default initialization behavior
• Verbose mode initialization
• Logger level configuration
• Runtime verbose toggling
• Integration with authentication
• Error handling scenarios

Before/After Comparison

Before (Non-verbose)

# Minimal output - only errors/warnings

After (Verbose enabled)

[2025-10-06 23:12:31] DEBUG [Forklet.download:136] Starting download for octocat/Hello-World@main
[2025-10-06 23:12:31] DEBUG [Forklet.download:137] Destination: ./downloads
[2025-10-06 23:12:31] DEBUG [Forklet.download:138] Strategy: DownloadStrategy.INDIVIDUAL
[2025-10-06 23:12:31] DEBUG [Forklet.download:145] Repository info: octocat/Hello-World, size: 1KB
[2025-10-06 23:12:31] DEBUG [Forklet.download:148] Resolved reference main to branch: abc123...
[2025-10-06 23:12:31] DEBUG [Forklet.download:180] Download completed: 5 files, 0 failures, 2048 bytes

Closes #51

[Einswilli]

First of all Good Job! 👍🏾

[Kcodess2807]

Thanks for the feedback! You're absolutely right about the redundant verbose checks.
I've removed all the unnecessary if self.verbose: conditions and the test block.
The logger level filtering handles this automatically once set to DEBUG.

Changes made:

• Removed redundant verbose checks in api.py
• Removed unnecessary main block in test file
• All tests still pass ✅

[Einswilli]

This looks cleaner, Thanks for your contributions!