v2.0.0

[2.0.0] - 2026-02-28

⚠️ BREAKING CHANGES

• Python Requirements: Minimum Python version increased from 3.7 to 3.10
• Public API: Replaced multiple entry points with a single download() function
• CLI --progress: Removed none mode; simple is now the default; added live-update and fancy modes
• Build System: Migrated from Poetry to Hatch for dependency management

Added

• Public API: New single download() entry point in s3fetch.api replacing the old multi-function API
• on_complete callback: download() accepts an on_complete callable invoked with each object key as it completes
• DownloadResult: Structured result object with key, file_size, success, and error fields emitted per download
• ProgressProtocol: Protocol class for implementing custom progress trackers compatible with both CLI and library usage
• --progress live-update: Real-time single-line status display (overwrites in place) with final summary; suppresses per-object output
• --progress fancy: Rich-powered progress bar with transfer speed and elapsed time; requires pip install s3fetch[fancy]
• s3fetch[fancy] optional extra: rich>=13.0.0 installable as an optional dependency
• Python 3.14 support: Added to test matrix and CI
• Atomic writes: Downloads write to a temporary file first and rename on completion, preventing partial files on failure or interruption
• Path traversal protection: Destination paths are validated against the download directory using Path.is_relative_to()
• Adaptive progress units: Progress summary displays sizes in B/KB/MB/GB as appropriate
• Demo: Animated GIF demo added to README
• Development Environment: Full Hatch integration with locked dependencies via hatch-pip-compile
• Type Safety: Comprehensive type annotations across all modules
• Code Quality: Pre-commit hooks with Ruff, mypy, bandit, and formatting checks
• Testing: Structured test organisation (unit, integration, e2e) with 160+ tests
• CLI Validation: Input validation for regex patterns, thread counts, S3 URIs, and download directories
• Error Handling: Actionable error messages with troubleshooting suggestions for common AWS errors

Changed

• --progress simple: Now the default mode; prints each object key as it downloads with no summary (previously none was the default)
• --progress detailed: Prints per-object keys plus a final summary (previously tried and failed to show a live status line)
• --quiet: Now explicitly mutually exclusive with --progress; suppresses all stdout but errors still go to stderr
• Thread count warning: Now warns instead of erroring when thread count exceeds 1000
• Minimum Python Version: Now requires Python 3.10 or higher
• Build System: Migrated from Poetry to Hatch
• Code Formatting: Migrated from Black to Ruff
• Type Annotations: All public functions now have complete type hints
• Error Messages: More actionable and user-friendly error messages

Fixed

• --progress detailed live line: The \r overwrite line was broken when per-object output was active; fixed by moving the live display to live-update mode which correctly suppresses per-object output
• --progress fancy completion: Progress bar now reliably reaches 100% before the summary prints
• on_complete race condition: Fixed a race condition in download() where the on_complete callback could be invoked after the function returned
• Logging Configuration: Global logging setup no longer interferes with library usage
• Path traversal: Fixed vulnerability where crafted S3 keys could write files outside the download directory
• Disk-full errors: OSError during download now gives a clear error message instead of an unhandled exception

Deprecated

• Python 3.7-3.9: No longer supported (use version 1.x for older Python versions)