API Reference¶

Complete API reference for littledl.

Core Functions¶

download_file_sync¶

Synchronous file download.

from littledl import download_file_sync

path = download_file_sync(
    url: str,
    save_path: str = ".",
    filename: str | None = None,
    config: DownloadConfig | None = None,
    progress_callback: Callable | None = None,
    chunk_callback: Callable | None = None,
) -> Path

download_file¶

Asynchronous file download.

from littledl import download_file

path = await download_file(
    url: str,
    save_path: str = ".",
    filename: str | None = None,
    config: DownloadConfig | None = None,
    progress_callback: Callable | None = None,
    chunk_callback: Callable | None = None,
) -> Path

Configuration Classes¶

DownloadConfig¶

from littledl import DownloadConfig

config = DownloadConfig(
    enable_chunking: bool = True,
    max_chunks: int = 16,
    chunk_size: int = 4 * 1024 * 1024,
    buffer_size: int = 64 * 1024,
    timeout: float = 300,
    resume: bool = True,
    verify_ssl: bool = True,
    auth: AuthConfig | None = None,
    proxy: ProxyConfig | None = None,
    speed_limit: SpeedLimitConfig | None = None,
    progress_callback: Callable | None = None,
    chunk_callback: Callable | None = None,
)

Methods¶

apply_style(style: Any) -> "DownloadConfig"

Quickly reconfigures all internal scheduling variables, chunking thresholds, and adaptive scheduling parameters based on a provided style. Supports either a DownloadStyle enum or a standard string style name (e.g., "SINGLE", "MULTI", "ADAPTIVE", "FUSION", or "HYBRID_TURBO"). Returns the modified DownloadConfig instance.

create_file_config(*, max_chunks: int | None = None, min_chunks: int | None = None, enable_chunking: bool | None = None) -> "DownloadConfig"

Creates a per-file DownloadConfig derived from the current one. Used internally by batch downloaders so FUSION, proxy, auth, retry, speed-limit, and other settings remain consistent while applying per-file chunk overrides.

Callback Events¶

ProgressEvent¶

Single-file download progress event. Includes file context when emitted by the Downloader.

ProgressEvent(
    downloaded: int,
    total: int,
    speed: float,
    eta: int,
    progress: float,
    remaining: int,
    timestamp: float,
    unknown_size: bool = False,
    filename: str = "",   # filename being downloaded
    url: str = "",        # URL being downloaded
)

ChunkEvent¶

ChunkEvent(
    chunk_index: int,
    status: str,  # started/downloading/completed/failed
    downloaded: int,
    total: int,
    progress: float,
    speed: float,
    error: str | None,
    timestamp: float,
)

Unified Callback System¶

The littledl.callback module provides a unified event system for building custom download managers.

EventType¶

from littledl import EventType

EventType.FILE_PROGRESS    # Single file progress update
EventType.FILE_COMPLETE    # Single file download complete
EventType.FILE_ERROR       # Single file download error
EventType.FILE_RETRY       # Single file retry
EventType.BATCH_PROGRESS   # Batch download progress
EventType.BATCH_COMPLETE   # Batch download complete
EventType.CHUNK_PROGRESS   # Chunk-level progress
EventType.CHUNK_COMPLETE   # Chunk-level complete
EventType.CHUNK_ERROR      # Chunk-level error

FileProgressEvent¶

Rich event object for file-level progress monitoring.

from littledl import FileProgressEvent

FileProgressEvent(
    event_type: EventType = EventType.FILE_PROGRESS,
    task_id: str = "",
    filename: str = "",
    url: str = "",
    file_size: int = 0,
    downloaded: int = 0,
    speed: float = 0.0,
    progress: float = 0.0,
    eta: float = -1.0,
    chunks_total: int = 0,
    chunks_completed: int = 0,
)

FileCompleteEvent¶

from littledl import FileCompleteEvent

FileCompleteEvent(
    event_type: EventType = EventType.FILE_COMPLETE,
    task_id: str = "",
    filename: str = "",
    url: str = "",
    file_size: int = 0,
    saved_path: str = "",
    error: str | None = None,
)

ThrottledCallback¶

Wraps a callback adapter to throttle emission frequency, preventing UI jank.

from littledl import UnifiedCallbackAdapter, ThrottledCallback

adapter = UnifiedCallbackAdapter(my_callback)
throttled = ThrottledCallback(adapter, min_interval=0.1)  # max 10 calls/sec
await throttled.emit(event)
await throttled.flush()  # emit any pending event

CallbackChain¶

Chain multiple callbacks together.

from littledl import CallbackChain

chain = CallbackChain()
chain.add(logging_callback)
chain.add(ui_callback)
await chain.emit(event)

### AuthConfig

```python
from littledl import AuthConfig, AuthType

auth = AuthConfig(
    auth_type: AuthType,
    username: str | None = None,
    password: str | None = None,
    token: str | None = None,
    api_key: str | None = None,
    api_key_header: str | None = None,
)

ProxyConfig¶

from littledl import ProxyConfig, ProxyMode

proxy = ProxyConfig(
    mode: ProxyMode = ProxyMode.SYSTEM,
    http_proxy: str | None = None,
    https_proxy: str | None = None,
    socks5_proxy: str | None = None,
)

SpeedLimitConfig¶

from littledl import SpeedLimitConfig, SpeedLimitMode

speed_limit = SpeedLimitConfig(
    enabled: bool = False,
    mode: SpeedLimitMode = SpeedLimitMode.GLOBAL,
    max_speed: int = 0,
)

Enums¶

AuthType¶

BASIC
BEARER
DIGEST
API_KEY
OAUTH2

ProxyMode¶

SYSTEM - Auto-detect system proxy
CUSTOM - Use custom proxy settings
NONE - No proxy

SpeedLimitMode¶

GLOBAL - Limit overall speed
PER_CHUNK - Limit per-chunk speed

Language Support¶

from littledl import set_language, get_available_languages

set_language("zh")  # or "en"
print(get_available_languages())  # {'en': 'English', 'zh': '中文'}

File Writers¶

FileWriter¶

Positional file writer used by chunked downloads. It writes through a single OS file descriptor with seek+write pairs serialized by a lock, and preallocates the target file so concurrent chunk writes to any offset are safe. Downloaded data lands in a .part file that is atomically renamed to the final name on success.

from littledl.writer import FileWriter

writer = FileWriter(
    file_path="/path/to/file.zip",
    file_size=1048576,   # preallocate (sparse) to this size
    resume=False,         # set True to keep existing bytes when resuming
)

await writer.open()
await writer.write_at(offset=0, data=b"chunk data")
await writer.close()

Note: FileWriter is used internally by the downloader; no manual configuration is needed.