# littledl

> littledl is a Python 3.10+ download library and CLI for single-file and batch downloads. It focuses on chunked HTTP Range downloading, resume support, adaptive scheduling, progress callbacks, proxy/auth support, speed limiting, and downloader-building use cases.

Important notes:

- Package version is 0.8.0; the import package is `littledl` under `src/littledl`.
- For library usage questions, start with the English docs and API reference below.
- For implementation questions, read the source map section instead of relying on README alone.
- English and Chinese docs are both available; Chinese links are listed in the `Optional` section.

## Start Here

- [README](README.md): project overview, quick start, download styles, callback examples, and CLI summary.
- [Documentation Index](docs/en/index.md): top-level English documentation map.
- [Getting Started](docs/en/getting-started/index.md): installation, sync/async usage, and progress callback basics.
- [API Reference](docs/en/api-reference/index.md): public functions, configuration types, callback events, and unified callback helpers.

## Usage Guides

- [CLI Guide](docs/en/cli/index.md): command-line usage, output modes, JSON output, and batch examples.
- [Configuration](docs/en/configuration/index.md): DownloadConfig, retry behavior, chunking, limits, and verification settings.
- [Batch Download](docs/en/batch-download/index.md): BatchDownloader, BatchProgress, adaptive concurrency, and batch callbacks.
- [Authentication](docs/en/authentication/index.md): Basic, Bearer, Digest, API key, and OAuth2 setup.
- [Proxy](docs/en/proxy/index.md): system proxy, custom proxy, and SOCKS5 configuration.
- [Error Handling](docs/en/error-handling/index.md): exceptions, retry expectations, and failure handling patterns.
- [Advanced Usage](docs/en/advanced/index.md): style selection, tuning, and advanced downloader features.

## Source Map

- [Public API Exports](src/littledl/__init__.py): package-level exports and the supported public surface.
- [Single File Downloader](src/littledl/downloader.py): Downloader, ProgressEvent, ChunkEvent, callback adapters, and chunked download flow.
- [Batch Downloader](src/littledl/batch.py): BatchDownloader, EnhancedBatchDownloader, FileTask, BatchProgress, and batch callback handling.
- [Callback System](src/littledl/callback.py): EventType, FileProgressEvent, FileCompleteEvent, UnifiedCallbackAdapter, ThrottledCallback, and CallbackChain.
- [CLI Entrypoint](src/littledl/__main__.py): argparse interface, output modes, progress display, and batch CLI behavior.
- [Configuration Models](src/littledl/config.py): DownloadConfig and related config classes/enums.
- [Connection and Transport](src/littledl/connection.py): connection pool and request construction.
- [Scheduling](src/littledl/scheduler.py): chunk scheduling and adaptive worker behavior.
- [Workers](src/littledl/worker.py): worker execution model for downloads.
- [Tests](tests/test_littledl.py): usage examples and regression coverage for callbacks, CLI, scheduler behavior, and batch download logic.

## Project Metadata

- [pyproject.toml](pyproject.toml): package metadata, dependencies, entry points, linting, and pytest configuration.
- [CHANGELOG](CHANGELOG.md): release history.
- [CONTRIBUTING](CONTRIBUTING.md): contribution workflow and repo guidance.
- [SECURITY](SECURITY.md): security reporting and policy.

## Optional

- [Chinese README](README.zh.md): Chinese overview and quick start.
- [Chinese Documentation Index](docs/zh/index.md): top-level Chinese documentation map.
- [Chinese Getting Started](docs/zh/getting-started/index.md): Chinese installation and basic usage.
- [Chinese API Reference](docs/zh/api-reference/index.md): Chinese API and callback reference.
- [Chinese CLI Guide](docs/zh/cli/index.md): Chinese CLI documentation.
- [Chinese Batch Download Guide](docs/zh/batch-download/index.md): Chinese batch download documentation.
- [Live Documentation Site](https://shu-shu-1.github.io/Little-Tree-Downloader/): published project documentation.