File Download Operations

def download(
    url=None,
    output=None,
    quiet=False,
    proxy=None,
    speed=None,
    use_cookies=True,
    verify=True,
    id=None,
    fuzzy=False,
    resume=False,
    format=None,
    user_agent=None,
    log_messages=None
) -> str:
    """
    Download file from URL with Google Drive support.

    Parameters:
    - url (str): URL to download from. Google Drive URLs supported.
    - output (str): Output filename/directory. Defaults to basename of URL.
                   If ends with '/', treated as parent directory.
    - quiet (bool): Suppress terminal output. Default: False.
    - proxy (str): Proxy configuration in format 'protocol://host:port'.
    - speed (float): Download speed limit in bytes per second (e.g., 256*1024 for 256KB/s).
    - use_cookies (bool): Use cookies from ~/.cache/gdown/cookies.txt. Default: True.
    - verify (bool/str): TLS certificate verification. True/False or path to CA bundle. Default: True.
    - id (str): Google Drive file ID. Cannot be used with url parameter.
    - fuzzy (bool): Extract Google Drive file ID from any URL format. Default: False.
    - resume (bool): Resume interrupted downloads, skip completed files. Default: False.
    - format (str): Export format for Google Docs/Sheets/Slides.
                   Defaults: Docs='docx', Sheets='xlsx', Slides='pptx'.
    - user_agent (str): Custom user agent string.
    - log_messages (dict): Custom messages with keys 'start' and 'output'.

    Returns:
    str: Path to downloaded file.

    Raises:
    FileURLRetrievalError: When unable to retrieve download URL.
    ValueError: When both url and id are specified or neither.
    """

import gdown

# Download with URL
url = "https://drive.google.com/uc?id=1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ"
output_path = gdown.download(url, "my_file.npz")
print(f"Downloaded to: {output_path}")

# Direct file ID usage
file_id = "1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ"
output_path = gdown.download(id=file_id, output="my_file.npz")

# Copy-paste any Google Drive URL format
messy_url = "https://drive.google.com/file/d/1l_5RK28JRL19wpT22B-DY9We3TVXnnQQ/view?usp=sharing&resourcekey=0-WWs_XOSctfaY_0-sJBKRSQ"
gdown.download(messy_url, "output.npz", fuzzy=True)

# Download Google Doc as PDF
doc_url = "https://docs.google.com/document/d/DOCUMENT_ID/edit"
gdown.download(doc_url, "document.pdf", format="pdf")

# Download Google Sheet as CSV
sheet_url = "https://docs.google.com/spreadsheets/d/SHEET_ID/edit"
gdown.download(sheet_url, "data.csv", format="csv")

# Download Google Slides as PowerPoint
slides_url = "https://docs.google.com/presentation/d/PRESENTATION_ID/edit"
gdown.download(slides_url, "presentation.pptx", format="pptx")

# Resume interrupted download with speed limit
gdown.download(
    url="https://drive.google.com/uc?id=LARGE_FILE_ID",
    output="large_file.zip",
    resume=True,
    speed=1024*1024,  # 1MB/s limit
    proxy="http://proxy.company.com:8080"
)

# Download to stdout (for piping)
import sys
gdown.download(url, output=sys.stdout.buffer, quiet=True)

# Custom logging messages
custom_messages = {
    "start": "🚀 Starting custom download...\n",
    "output": "📁 Saving to: {}\n"
}

gdown.download(
    url="https://drive.google.com/uc?id=FILE_ID",
    output="file.zip",
    log_messages=custom_messages
)

from gdown.exceptions import FileURLRetrievalError

try:
    gdown.download("https://drive.google.com/uc?id=INVALID_ID", "output.zip")
except FileURLRetrievalError as e:
    print(f"Download failed: {e}")
    # Handle permission issues, network errors, etc.

# Netscape HTTP Cookie File
.google.com	TRUE	/	FALSE	0	cookie_name	cookie_value