empyrean.download_data

download_data(*, data_dir=None)

Provision a usable data directory with the required SPICE kernels.

Provisions the OS-appropriate XDG data directory by default (see default_data_dir()); pass data_dir to target another. Idempotent: files already present are kept; only missing files are downloaded.

If the B612 Foundation data packages (naif-de440, jpl-small-bodies-de441-n16, naif-eop-high-prec, naif-eop-historical, naif-eop-predict, mpc-obscodes) are installed and no explicit data_dir is given, their kernels are staged from the installed wheels with zero network access, and only what they do not supply (e.g. bias.dat) is downloaded.

Parameters:

data_dir (str | Path | None) – Target directory. Defaults to the value returned by default_data_dir() (honors EMPYREAN_DATA_DIR).

Return type:

str

Returns:

str – Path to the provisioned data directory.

Raises:

• RuntimeError – If EMPYREAN_OFFLINE=1 is set. That variable is a floor on the process, and it downgrades a context construction from “refresh” to “resolve what is already here” — but provisioning has no such second mode, because reaching the network is the call. So it refuses rather than ignoring the assertion, naming the variable. Build against an already-provisioned directory with initialize() and refresh=False instead, or unset the variable for the process that must provision.

• RuntimeError – If a kernel fetch was attempted and failed — a 404 from an upstream that rotated or withdrew a pinned kernel, a refused connection, a mid-transfer failure. The message leads with "Data download     failed: " and carries the request context (GET <url>: ...), so the kernel that could not be fetched is named by its URL. The remedy is connectivity, or — when the URL 404s — staging that file by hand into data_dir, or moving to a release whose kernel pin is still served. Retrying this call does not help, and neither does local file repair: nothing is wrong on disk.