ensure

ensure(key: str, *subkeys: str, url: str, name: str | None = None, version: None | str | Callable[[], str | None] = None, force: bool = False, download_kwargs: DownloadKwargs | None = None) → Path[source]

Ensure a file is downloaded.

Parameters:

  • key – The name of the module. No funny characters. The envvar <key>_HOME where key is uppercased is checked first before using the default home directory.

  • subkeys – A sequence of additional strings to join. If none are given, returns the directory for this module.

  • url – The URL to download.

  • name – Overrides the name of the file at the end of the URL, if given. Also useful for URLs that don’t have proper filenames with extensions.

  • version –

    The optional version, or no-argument callable that returns an optional version. This is prepended before the subkeys.

    The following example describes how to store the versioned data from the Rhea database for biologically relevant chemical reactions.

    import pystow
import requests

def get_rhea_version() -> str:
    res = requests.get("https://ftp.expasy.org/databases/rhea/rhea-release.properties")
    _, _, version = res.text.splitlines()[0].partition("=")
    return version

path = pystow.ensure(
    "rhea",
    url="ftp://ftp.expasy.org/databases/rhea/rdf/rhea.rdf.gz",
    version=get_rhea_version,
)

  • force – Should the download be done again, even if the path already exists? Defaults to false.

  • download_kwargs – Keyword arguments to pass through to pystow.utils.download().

Returns:

The path of the file that has been downloaded (or already exists)