zuke.tools.chocolatey

← Python API reference

@zuke/chocolatey 1.1.0: @zuke/chocolatey — ship a prebuilt Windows binary through [Chocolatey](https://chocolatey.org) from a Zuke build: ChocoTasks wraps the choco CLI, and ChocolateyTasks renders a package for a zip hosted on a release, verifies it installs, publishes it, and declares the CI job that verifies it on Windows.

zuke on PyPI ↗ 13 symbols

Symbols

ChocoApikeySettings

class

class ChocoApikeySettings(ChocoCommandSettings)

Settings for choco apikey, which manages the API keys choco saves per source — so a later choco push to that source needs no key on its command line.

`ts await ChocoTasks.apikey((s) => s.add().source("https://push.chocolatey.org/").apiKey(key) ); `

add needs a source and an apiKey; remove needs a source. With no action set, choco lists the saved keys (by source; it never prints a key itself).

list() -> Self
List the saved keys' sources (apikey list).
add() -> Self
Save the apiKey for the source (apikey add).
remove() -> Self
Remove the key saved for the source (apikey remove).
source(url: str) -> Self
The source the key is for (--source).
api_key(value: str) -> Self
The key to save (--api-key), for add. Masked in every rendering of the command and in its errors.

ChocoCommandSettings

class

class ChocoCommandSettings(ChocoSettings)

Base for a typed choco command: the command, then its operands, then its own options, then the common switches — the order choco's own usage lines print (choco install <pkg> [<options/switches>]). Anything added through the inherited .command(...)/.flag(...) escape hatches follows.

Valued options render as one --name=value token, the spelling choco's help prints, so a value that starts with - stays the option's value rather than becoming a switch of its own.

Operands are refused when choco would read them as a switch: a package id or file path never starts with -, and passing --force as a "package" would change what the command does rather than fail.

yes() -> Self
Answer yes to every prompt (--yes), which also accepts licenses.
force() -> Self
Force the behaviour (--force) — reinstall an installed package, say. Choco warns against it in normal operation.
no_progress() -> Self
Do not print download progress percentages (--no-progress).
limit_output() -> Self
Print only the essential information (--limit-output).
verbose() -> Self
Print verbose messages (--verbose).

ChocoInstallSettings

class

class ChocoInstallSettings(ChocoCommandSettings)

Settings for choco install.

packages(*ids: str) -> Self
Package ids to install (required); repeatable.
source(location: str) -> Self
Where to find the packages (--source): a feed URL, or a local directory holding .nupkg files. Defaults to the configured feeds.
version(value: str) -> Self
The exact version to install (--version).
prerelease() -> Self
Consider prerelease versions (--prerelease).

ChocolateyPackageSettings

class

class ChocolateyPackageSettings(Settings)

Settings for a package that installs a prebuilt binary from a zip.

id(value: str) -> Self
The package id (required), e.g. app: lowercase letters and digits, joined by single ., - or _, at most 100 characters. It is also the nuspec's file name, <id>.nuspec.
version(value: str) -> Self
The package version (required), a NuGet version such as 1.2.3, 1.2.3.4 or 1.2.3-beta.1 — usually the release's own version.
title(value: str) -> Self
The display title (<title>), e.g. App (Portable).
authors(*names: str) -> Self
The software's authors (<authors>, required); repeatable.
owners(*names: str) -> Self
The package's maintainers (<owners>) — on the community repository, the user names that may push it; repeatable.
project_url(url: str) -> Self
The software's homepage (<projectUrl>, required; must be https).
license_url(url: str) -> Self
The license's URL (<licenseUrl>, https) — the community repository requires it whenever the software has one.
icon_url(url: str) -> Self
The package icon's URL (<iconUrl>, https).
package_source_url(url: str) -> Self
Where the package's own source lives (<packageSourceUrl>, https) — typically the repository whose build renders it.
docs_url(url: str) -> Self
The software's documentation (<docsUrl>, https).
bug_tracker_url(url: str) -> Self
The software's issue tracker (<bugTrackerUrl>, https).
tags(*values: str) -> Self
Search tags (<tags>), each one word; repeatable.
copyright(text: str) -> Self
The software's copyright notice (<copyright>), one line — e.g. the line in its LICENSE, Copyright (c) 2026 Acme. The community repository's moderators ask for it whenever the software has one.
summary(text: str) -> Self
A one-line summary (<summary>).
description(text: str) -> Self
The description (<description>, required; Markdown is fine), held to the community repository's length rules: 30 to 4000 characters.
release_notes(text: str) -> Self
The release notes (<releaseNotes>): text, Markdown, or a URL.
url64bit(url: str) -> Self
The 64-bit zip on the release (required; must be https) — what the install script downloads (url64bit) and unpacks into the package's tools directory, where choco shims every .exe it holds.
checksum64(sha256: str) -> Self
The zip's SHA-256 (required; 64 hex digits) — checked by choco before anything is unpacked (checksum64, with checksumType64 = 'sha256').

ChocolateyPublishSettings

class

class ChocolateyPublishSettings(Settings)

Settings for publishing a package.

package(value: Mapping[str, object]) -> Self
The package to publish — what ChocolateyTasks.package rendered. It is packed in a temporary directory and the .nupkg pushed. Set this or nupkg, not both.
nupkg(path: str) -> Self
A .nupkg already built, pushed as it is. Set this or package.
api_key(value: str) -> Self
The source's API key — for the community repository, the one on https://community.chocolatey.org/account. Masked in every rendering of the push and in its errors. When unset, choco uses the key saved for the source with choco apikey add.
source(url: str) -> Self
The source to push to (https), defaulting to the community repository, https://push.chocolatey.org/. An internal feed's push URL works too.
tool_path(path: str) -> Self
The choco to run, when it is not on PATH.

ChocolateyTasks

class

class ChocolateyTasks

Tasks for shipping a prebuilt Windows binary through Chocolatey.

static async package(ctx: ServiceContext, configure: Callable[[ChocolateyPackageSettings], ChocolateyPackageSettings]) -> object
The files of a package that installs a prebuilt binary from a zip on a release: <id>.nuspec and tools/chocolateyinstall.ps1. Pure: nothing is read or written.
static async verify(ctx: ServiceContext, configure: Callable[[ChocolateyVerifySettings], ChocolateyVerifySettings]) -> None
Pack a rendered package in a temporary directory, install it from there, run the binary it puts on PATH, then uninstall it and remove the directory — the cleanup runs whether or not the install and check succeeded.
static async publish(ctx: ServiceContext, configure: Callable[[ChocolateyPublishSettings], ChocolateyPublishSettings]) -> object
Push a package — rendered, or a .nupkg already built — to the community repository or another source, with its API key masked.
static async verify_job(ctx: ServiceContext, configure: Callable[[ChocolateyVerifyJobSettings], ChocolateyVerifyJobSettings]) -> object
The CI job that runs a verifying target on Windows runners, ready to list in cicd({ invokes: [...] }).

ChocolateyVerifyJobSettings

class

class ChocolateyVerifyJobSettings(Settings)

Settings for the package-verification CI job.

target(value: object) -> Self
The target to run (required) — one that calls ChocolateyTasks.verify, or otherwise installs, checks and uninstalls the package.
runners(*labels: str) -> Self
The runner labels to verify on, replacing the default windows-latest — e.g. "windows-2022", "windows-2025" to cover both images. Each must be a Windows runner with Chocolatey installed.

ChocolateyVerifySettings

class

class ChocolateyVerifySettings(Settings)

Settings for verifying a rendered package.

package(value: Mapping[str, object]) -> Self
The package to verify (required) — what ChocolateyTasks.package rendered.
binary(name: str) -> Self
The command the package puts on PATH (required), e.g. app — choco names each shim after the .exe it found in the zip.
command(*args: str) -> Self
The arguments to run the binary with, e.g. "--version".
expect_version() -> Self
Require the binary's output to contain the package version.
expect_output(text: str) -> Self
Require the binary's output to contain text.
tool_path(path: str) -> Self
The choco to run, when it is not on PATH.

ChocoPackSettings

class

class ChocoPackSettings(ChocoCommandSettings)

Settings for choco pack, which builds a .nupkg from a .nuspec. With no nuspec named, choco packs the one in the working directory.

nuspec(path: str) -> Self
The .nuspec to pack; defaults to the one in the working directory.
version(value: str) -> Self
The version to write into the package, overriding the nuspec's (--version).
output_directory(path: str) -> Self
Where to write the .nupkg (--output-directory); defaults to the working directory.

ChocoPushSettings

class

class ChocoPushSettings(ChocoCommandSettings)

Settings for choco push, which uploads a .nupkg to a source. With no package named, choco pushes the only .nupkg in the working directory.

The API key is an argument — choco reads it from nowhere else — so it is registered with the run's redactor and masked out of any error the push raises. It is still visible in the process table for the push's duration; on a shared host, save it once with choco apikey add instead and leave apiKey unset, and choco looks it up by source.

nupkg(path: str) -> Self
The .nupkg to push.
source(url: str) -> Self
The source to push to (--source), e.g. https://push.chocolatey.org/ for the community repository.
api_key(value: str) -> Self
The source's API key (--api-key). Masked in every rendering of the command and in its errors.

ChocoSettings

class

class ChocoSettings(SubcommandSettings)

Settings for a choco invocation.

ChocoTasks

class

class ChocoTasks

Typed task functions for the Chocolatey choco CLI.

static async run(ctx: ServiceContext, configure: Callable[[ChocoSettings], ChocoSettings] | None=None) -> ExecResult
Run any choco command, built with .command(...)/.flag(...).
static async pack(ctx: ServiceContext, configure: Callable[[ChocoPackSettings], ChocoPackSettings] | None=None) -> ExecResult
Build a .nupkg from a .nuspec (choco pack).
static async push(ctx: ServiceContext, configure: Callable[[ChocoPushSettings], ChocoPushSettings] | None=None) -> ExecResult
Upload a .nupkg to a source (choco push); the API key is masked.
static async install(ctx: ServiceContext, configure: Callable[[ChocoInstallSettings], ChocoInstallSettings]) -> ExecResult
Install packages (choco install).
static async uninstall(ctx: ServiceContext, configure: Callable[[ChocoUninstallSettings], ChocoUninstallSettings]) -> ExecResult
Uninstall packages (choco uninstall).
static async apikey(ctx: ServiceContext, configure: Callable[[ChocoApikeySettings], ChocoApikeySettings] | None=None) -> ExecResult
List, save or remove a source's API key (choco apikey).

ChocoUninstallSettings

class

class ChocoUninstallSettings(ChocoCommandSettings)

Settings for choco uninstall.

packages(*ids: str) -> Self
Package ids to uninstall (required); repeatable.
source(location: str) -> Self
The source the packages came from (--source).
version(value: str) -> Self
The installed version to uninstall (--version).
all_versions() -> Self
Uninstall every installed version (--all-versions).