Python API

Python API#

Querying the JDK index#

cjdk.list_vendors(**kwargs)#

Return the list of available JDK vendors.

Parameters:

  • None

  • index_url (str, optional) – Alternative URL for the JDK index.

Returns:

The available JDK vendors.

Return type:

list[str]

Added in version 0.4.0.

cjdk.list_jdks(*, vendor=None, version=None, cached_only=True, **kwargs)#

Return the list of JDKs matching the given criteria.

Parameters:

  • vendor (str, optional) – JDK vendor name, such as “adoptium”.

  • version (str, optional) – JDK version expression, such as “17+”.

  • cached_only (bool, optional) – If True, list only already-cached JDKs. If False, list all matching JDKs in the index.

  • jdk (str, optional) – JDK vendor and version, such as “adoptium:17+”. Cannot be specified together with vendor or version.

  • cache_dir (pathlib.Path or str, optional) – Override the root cache directory.

  • index_url (str, optional) – Alternative URL for the JDK index.

  • os (str, optional) – Operating system for the JDK (default: current operating system).

  • arch (str, optional) – CPU architecture for the JDK (default: current architecture).

Returns:

JDKs (vendor:version) matching the criteria.

Return type:

list[str]

Added in version 0.4.0.

Working with cached JDKs#

cjdk.java_home(*, vendor=None, version=None, **kwargs)#

Return the JDK home directory for the given JDK, installing if necessary.

Parameters are the same as for cache_jdk().

Returns:

The JDK home directory satisfying the requested parameters.

Return type:

pathlib.Path

cjdk.java_env(*, vendor=None, version=None, add_bin=True, **kwargs)#

Context manager to set environment variables for the given JDK, installing if necessary.

Parameters are the same as for cache_jdk(), with the following addition.

Parameters:

add_bin (bool, default: True) – Whether to prepend the Java “bin” directory to PATH, in addition to setting JAVA_HOME. If false, PATH is not modified.

Returns:

Context manager that temporarily sets the JAVA_HOME and (optionally) PATH environment variables for the JDK satisfying the requested parameters. Its value is the JDK home directory.

Return type:

ContextManager[pathlib.Path]

cjdk.cache_jdk(*, vendor=None, version=None, **kwargs)#

Download and extract the given JDK if it is not already cached.

Parameters:

  • vendor (str, optional) – JDK vendor name, such as “adoptium”.

  • version (str, optional) – JDK version expression, such as “17+”.

  • jdk (str, optional) – JDK vendor and version, such as “adoptium:17+”. Cannot be specified together with vendor or version.

  • cache_dir (pathlib.Path or str, optional) – Override the root cache directory.

  • index_url (str, optional) – Alternative URL for the JDK index.

  • index_ttl (int or float, optional) – Time to live (in seconds) for the cached index.

  • os (str, optional) – Operating system for the JDK (default: current operating system).

  • arch (str, optional) – CPU architecture for the JDK (default: current architecture).

  • progress (bool, default: True) – Whether to show progress bars.

Return type:

None

Added in version 0.2.0.

More details about the choices and defaults for vendor, version, cache_dir, index_url, and index_ttl are available on separate pages.

Caching arbitrary files and packages#

The following functions allow cjdk’s file download and extract logic to cache arbitrary resources from the Internet. They can be used, for example, to install an application JAR.

cjdk.cache_file(name, url, filename, **kwargs)#

Install any file resource into the cache, downloading if necessary.

Parameters are the same as for cache_jdk() (JDK-specific parameters are ignored), with the following additions.

Parameters:

  • name (str) – Name to display in case of showing progress.

  • url (str) – The URL of the file resource. The scheme must be https.

  • filename (str) – The filename under which the file will be stored.

  • ttl (int) – Time to live (in seconds) for the cached file resource.

  • sha1 (str) – SHA-1 hash that the downloaded file must match.

  • sha256 (str) – SHA-256 hash that the downloaded file must match.

  • sha512 (str) – SHA-512 hash that the downloaded file must match.

Returns:

Path to the cached file resource, whose final component is the given filename.

Return type:

pathlib.Path

Notes

The check for SHA-1/SHA-256/SHA-512 hashes is only performed after a download; it is not performed if the file already exists in the cache.

Added in version 0.2.0.

cjdk.cache_package(name, url, **kwargs)#

Install any package into the cache, downloading and extracting if necessary.

Parameters are the same as for cache_jdk() (JDK-specific parameters are ignored), with the following additions.

Parameters:

  • name (str) – Name to display in case of showing progress.

  • url (str) – The URL of the file resource. The scheme must be tgz+https or zip+https.

  • sha1 (str) – SHA-1 hash that the downloaded file must match.

  • sha256 (str) – SHA-256 hash that the downloaded file must match.

  • sha512 (str) – SHA-512 hash that the downloaded file must match.

Returns:

Path to the cached directory into which the package was extracted.

Return type:

pathlib.Path

Notes

The check for SHA-1/SHA-256/SHA-512 hashes is only performed (on the unextracted archive) after a download; it is not performed if the directory already exists in the cache.

Added in version 0.2.0.

Contents