Download File Utility

Common errors

• ModuleNotFoundError: No module named 'download'

  cause The 'download' library is not installed in the current Python environment.
  fix Install the library using pip: `pip install download`.

• AttributeError: module 'download' has no attribute 'download'

  cause This error typically occurs if you're trying to call `download.download()` but have a local file named `download.py` that shadows the installed library, or if `from download import download` was intended but used incorrectly. It can also happen if you're trying to access a non-existent attribute.
  fix Ensure you are calling the function correctly: `from download import download` then `download(...)` OR `import download` then `download.download(...)`. Verify no local files named `download.py` are interfering.

• URLError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain (_ssl.c:XXXX)>

  cause The target HTTPS server uses an invalid, expired, or self-signed SSL/TLS certificate, and Python's `urllib.request` (used by `download`) is enforcing strict certificate validation.
  fix Confirm the server's certificate is valid. If you control the server, update the certificate. If this is a known issue for an internal server, you might need to explore options to manage SSL contexts, but disabling verification is a security risk.

• PermissionError: [Errno 13] Permission denied: '/path/to/protected_dir/file.zip'

  cause The Python process lacks the necessary write permissions to save the file or create the directory at the specified `path`.
  fix Run your Python script with a user account that has write access to the target directory. Alternatively, specify an output directory where write permissions are granted (e.g., a temporary directory or a user-specific folder).

Warnings

• gotcha The `download` library, leveraging `urllib.request`, performs strict SSL/TLS certificate verification. Downloads from HTTPS URLs with invalid, expired, or self-signed certificates will typically fail with an `URLError` containing `CERTIFICATE_VERIFY_FAILED`. The library does not expose a direct `verify=False` parameter.
  Fix: The recommended fix is to ensure the target server has a valid SSL certificate. If this is not possible and you understand the security implications, you might need to globally or contextually bypass SSL verification using Python's `ssl` module, which is outside the direct scope of the `download` library's API.
• gotcha By default, `download.download()` will *not* overwrite an existing file at the target path. If a file with the same name already exists, the download operation will be skipped silently, potentially leading to stale local files.
  Fix: To ensure that existing files are always updated, explicitly set the `replace=True` argument when calling `download.download()`.
• gotcha While `download` automatically creates the output directory if it doesn't exist, issues can arise from insufficient write permissions for the specified `path` or if a file (rather than a directory) already exists at the intended output `path`.
  Fix: Ensure the user running the Python script has write permissions to the specified output directory. Pre-creating the directory with `os.makedirs(path, exist_ok=True)` can help isolate permission issues. Handle `PermissionError` or `IsADirectoryError` if encountered.

Install

• pip install download Install stable version

Imports

• download
  wrong:

  import download.download

  correct:

  from download import download

  The primary functionality is exposed as a function named 'download' within the 'download' module. You can also import the module and call `download.download(...)`.

Quickstart

The quickstart demonstrates the core functionality of downloading a file from a URL to a specified directory. It uses `download.download()` with `verbose=True` for progress and `replace=True` to ensure idempotency. The library also supports `extract=True` for automatic unzipping of archives.

import download
import os

# Define the output directory
output_dir = './my_downloads'
os.makedirs(output_dir, exist_ok=True)

# Example of a small, public file to download (e.g., a license file from GitHub)
# Using a raw GitHub URL to ensure direct file access for demonstration.
file_url = 'https://raw.githubusercontent.com/choldgraf/download/main/LICENSE'

try:
    print(f"Attempting to download {file_url} to {output_dir}")
    # Download the file with progress and replace if it exists
    download.download(
        url=file_url,
        path=output_dir,
        replace=True, # Overwrite if file exists
        verbose=True  # Show progress bar
    )
    print(f"Successfully downloaded {file_url} to {output_dir}")

    # Example of downloading and extracting a zip file (if you have a test zip URL)
    # For this example, we'll just demonstrate the call signature, as a suitable public test zip is not always guaranteed.
    # zip_file_url = 'https://github.com/choldgraf/download/archive/refs/heads/main.zip'
    # print(f"\nAttempting to download and extract a zip from {zip_file_url}")
    # download.download(
    #     url=zip_file_url,
    #     path=output_dir,
    #     extract=True,  # Extract the contents of the zip file
    #     replace=True,
    #     verbose=True
    # )
    # print(f"Successfully downloaded and extracted {zip_file_url} to {output_dir}")

except Exception as e:
    print(f"An error occurred during download: {e}")

# Optional: Clean up the created directory
# import shutil
# if os.path.exists(output_dir):
#     print(f"\nCleaning up {output_dir}")
#     shutil.rmtree(output_dir)