Registry / devops / setuptools-download

setuptools-download

library1.1.0pypypiunverified

setuptools-download is a plugin for setuptools that enables the declarative downloading of external files as part of a Python package's build process. It allows specifying URLs, SHA256 checksums, and extraction methods (zip, tar) directly within the `pyproject.toml` or `setup.cfg` file. Currently at version 1.1.0, it is actively maintained with infrequent but targeted releases.

devops

pip install setuptools-download

github ↗package ↗

INSTALL

IMPORT

SIG · SETUPTOOLS-DOWNLOA

setuptools-download

devopspythonv1.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

setuptools-download is configured declaratively, typically in `pyproject.toml` under the `[tool.setuptools-download]` section. Each download is defined by a unique key (e.g., `download_example_asset`) with required `url` and `sha256` fields, and an optional `dest` field. After configuration, running `python -m build` will execute the download as part of the source distribution (sdist) or wheel (bdist_wheel) build process. Replace `url` and `sha256` with your actual file and its checksum.

# pyproject.toml [build-system] requires = ["setuptools>=61.0", "setuptools-download==1.1.0"] build-backend = "setuptools.build_meta" [project] name = "my-package-with-downloads" version = "0.0.1" description = "A package that downloads an external file during build" readme = "README.md" requires-python = ">=3.8" [tool.setuptools-download] # Define a download target: key is an arbitrary name, value is a table of settings download_example_asset = { url = "https://example.com/sample.txt", sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", # SHA256 of an empty file, replace with actual asset's SHA256 dest = "src/my_package/data/sample.txt" } # To build the package (which triggers the download): pip install build python -m build

Debug

Known issues

gotchaThe `sha256` checksum is a mandatory field for every download entry. Omitting it will result in a build error. This is a security feature to ensure the integrity and authenticity of downloaded files.

fix

Always provide the correct SHA256 checksum for each file you intend to download.

affects: All versions

gotchaThis plugin is designed for declarative configuration via `pyproject.toml` or `setup.cfg`. While `setuptools` still supports `setup.py`, relying on direct programmatic usage within `setup.py` for `setuptools-download`'s features is not the intended or documented pattern and may not work as expected.

fix

Prefer using `pyproject.toml` (recommended) or `setup.cfg` to define download operations.

affects: All versions

breakingAs a plugin, setuptools-download operates within the setuptools build environment. Frequent breaking changes in upstream `setuptools` (e.g., removal of `setup.py` commands, stricter configuration parsing, changes to internal APIs) can indirectly affect this plugin's functionality or the project's ability to build. Users should pin specific versions of `setuptools` for stability.

fix

Pin your `setuptools` version in `pyproject.toml`'s `build-system.requires` (e.g., `setuptools>=61.0,<80.0.0`) and regularly test against newer `setuptools` releases.

affects: setuptools versions >=70.0.0, >=78.0.0, >=80.0.0

Errors

Common errors & fixes

Unknown distribution option: 'download_data'

`setuptools-download` is not correctly specified as a build dependency, preventing setuptools from recognizing its custom `download_data` option.

fix

Add `setuptools-download` to the `build-system.requires` list in `pyproject.toml` (e.g., `requires = ["setuptools>=61.0", "setuptools-download"]`) or `setup_requires` in `setup.py`.

setuptools_download.DownloadError: SHA256 checksum mismatch for URL: <your_url_here>

The SHA256 checksum specified in the package configuration (`pyproject.toml` or `setup.cfg`) does not match the actual checksum of the file downloaded from the provided URL.

fix

Update the SHA256 checksum in your `pyproject.toml` or `setup.cfg` to match the correct hash of the downloaded file, or verify the URL points to the expected file.

setuptools_download.DownloadError: Failed to download from URL: <your_url_here> - <exception_details>

The package failed to download the external file, typically due to network connectivity issues, an invalid URL, a server error (e.g., 404 Not Found), or proxy problems.

fix

Verify the URL is correct and accessible, check your internet connection, ensure any proxy settings are configured properly, or try downloading the file manually to diagnose the issue.

jsonschema.exceptions.ValidationError: <validation_error_details>

The `download_data` configuration in `pyproject.toml` (or `setup.cfg`) does not conform to the expected schema, often due to missing required keys like `url` or `sha256`, or incorrect data types.

fix

Review your `download_data` configuration in `pyproject.toml` or `setup.cfg` against the `setuptools-download` documentation to ensure all required fields are present and correctly formatted.

Upgrade

Version history

1.1.0latest on PyPI · released Jul 7, 2024

Audit

Dependencies

setuptoolsrequiredThis library is a plugin for setuptools and requires it to function. It should be listed in your build-system requirements.