pychoco¶

GitHub commits since latest release (by SemVer including pre-releases)

Minimal choco command for use on non-Windows platforms.

Commands¶

choco¶

Minimal choco command.

Usage

choco [OPTIONS] COMMAND [ARGS]...

apikey¶

Manage API keys.

Usage

choco apikey [OPTIONS] COMMAND [ARGS]...

add¶

Add an API key for a source.

Usage

choco apikey add [OPTIONS]

Options

-d, --debug¶: Enable debug logging.

-k, --key <API_KEY>¶: Required API key.

-s, --source <SOURCE_URL>¶: Required Source URI.

-p, --path <PATH>¶: Storage file.

list¶

List sources associated with API keys. Does not display the API key values.

Usage

choco apikey list [OPTIONS]

Options

-d, --debug¶: Enable debug logging.

-p, --path <PATH>¶: Storage file.

config¶

Manage configuration.

Usage

choco config [OPTIONS] COMMAND [ARGS]...

set¶

Set a configuration value.

Usage

choco config set [OPTIONS]

Options

-d, --debug¶: Enable debug logging.

-n, --name <KEY>¶

Required Key to set.

Options:¶: defaultPushSource

-v, --value <VALUE>¶: Required Value to set.

-p, --path <PATH>¶: Storage file.

new¶

Create a new package.

Usage

choco new [OPTIONS] NAME

Options

-d, --debug¶: Enable debug logging.

Arguments

NAME¶: Required argument

pack¶

Create a package file for distribution.

Usage

choco pack [OPTIONS] [WORK_DIR]

Options

-d, --debug¶: Enable debug logging.

Arguments

WORK_DIR¶: Optional argument

push¶

Push a package to a source.

Usage

choco push [OPTIONS] PACKAGE

Options

-d, --debug¶: Enable debug logging.

-s, --source <URL>¶: Source to upload to.

--config-path <PATH>¶: Configuration storage file.

--api-keys-path <PATH>¶: API keys storage file.

Arguments

PACKAGE¶: Required argument

search¶

Search a source.

Usage

choco search [OPTIONS] TERMS

Options

--by-id-only¶: Only return packages where the id contains the search filter.

--by-tag-only, --by-tags-only¶: Only return packages where the search filter matches on the tags.

--id-starts-with¶: Only return packages where the id starts with the search filter.

--idonly, --id-only¶: Only return Package IDs in the list results.

--order-by-popularity¶: Sort package results by popularity.

--page <page>¶: The “page” of results to return.

--page-size <page_size>¶: Amount of packages to return in each page of results.

--pre, --prerelease¶: Include prereleases.

-a, --all, --allversions, --all-versions¶: Include results from all versions.

-d, --debug¶: Enable debug logging.

-e, --exact¶: Only return packages with this exact name.

-p, --password <password>¶: Password.

-s, --source <URL>¶: Source to search.

-u, --user <user>¶: User name.

Arguments

TERMS¶: Required argument

Library¶

Client.

choco.client.Auth = tuple[str, str] | niquests.auth.HTTPBasicAuth¶: Authentication details.

class choco.client.ChocolateyClient(config: Config = {'pychoco': {'defaultPushSource': 'https://push.chocolatey.org'}}, api_keys: Mapping[str, str] | None = None)¶

Chocolatey client.

Anything that involves interactions with the server will be in this class.

add_key(key: str, source: str) → None¶: Add an API key for a source.

config_set(name: ConfigKey, value: str) → None¶: Set a configuration value.

get_default_push_source() → str¶

Get the default push source URL.

Return type:¶: str

get_keys_available() → list[str]¶

Return a list of the sources that have keys.

Return type:¶: list[str]

async push(package: Path, source: str | None = None, auth: Auth | None = None) → None¶: Push a package to a source.

async search(terms: str, *, auth: Auth | None = None, all_versions: bool = False, by_id_only: bool = False, by_tag_only: bool = False, exact: bool = False, id_starts_with: bool = False, include_prerelease: bool = False, order_by_popularity: bool = False, page: int | None = None, page_size: int = 30, source: str | None = None) → AsyncIterator[SearchResult]¶

Search packages. Returns a deduplicated async iterator of results.

Yields:¶: SearchResult

update_api_key_header(source: str | None = None) → None¶

Update the shared session API key header.

If one does not exist, the existing header is removed if it is present.

Persistent configuration.

Read both configuration and API keys from the specified paths or defaults.

Parameters:¶

config_path : Path | str | None¶: Path to the configuration file.
api_keys_path : Path | str | None¶: Path to the API keys file.

Return type:¶

tuple[Config, dict[str, str] | None]

async choco.config.read_api_keys(path: Path | str | None = None) → dict[str, str]¶

Read API keys stored in given path or the default path.

Parameters:¶

path : Path | str | None¶: Path to the API keys file.

Return type:¶

dict[str, str]

async choco.config.read_config(path: Path | str | None = None) → Config¶

Read configuration from the given path or the default path.

Parameters:¶

path : Path | str | None¶: Path to the configuration file.

Return type:¶

Config

async choco.config.write_api_keys(api_keys: Mapping[str, str], path: Path | str | None = None) → None¶

Write API keys dictionary to the given path or the default path.

Parameters:¶

api_keys : Mapping[str, str]¶: Mapping of source URLs to API keys.
path : Path | str | None¶: Path to the API keys file.

async choco.config.write_config(config: Config, path: Path | str | None = None) → None¶

Write configuration to the given path or the default path.

Parameters:¶

config : Config¶: Configuration dictionary to write.
path : Path | str | None¶: Path to the configuration file.

Packaging-related functions.

choco.packaging.is_valid_package_name(value: str) → bool¶

Check if a package name is valid.

Parameters:¶

value : str¶: The package name to validate.

Return type:¶

bool

async choco.packaging.new_package(name: str) → Path¶

Scaffolding to create a new package.

Parameters:¶

name : str¶: The name of the package to create.

Return type:¶

Path

Raises:¶

InvalidPackageName – If the package name is invalid.
DirectoryExistsError – If a directory with the specified name already exists.

Utility functions.

choco.utils.append_dir_to_zip_recursive(root: Path, z: zipfile.ZipFile) → None¶

Append a directory recursively to a zip file.

Parameters:¶

root : Path¶: The root directory to append.
z : zipfile.ZipFile¶: The zip file to append to.

choco.utils.entry_to_search_result(entry: Element, ns: Mapping[str, str] = {'': 'http://www.w3.org/2005/Atom', 'd': 'http://schemas.microsoft.com/ado/2007/08/dataservices', 'm': 'http://schemas.microsoft.com/ado/2007/08/dataservices/metadata'}) → SearchResult¶

Convert an <entry> to a SearchResult dict.

Parameters:¶

entry : Element¶: The XML entry element to convert.
ns : Mapping[str, str]¶: XML namespace mapping.

Return type:¶

SearchResult

Raises:¶

InvalidEntryError – If the entry is invalid or does not contain the required metadata.

choco.utils.generate_unique_id() → str¶

Generate a unique ID for elements in _rels/.rels.

Return type:¶: str

choco.utils.tag_text_or(tag: Element | None, default: str | None = None) → str | None¶

Return text from a tag or the default value specified.

Parameters:¶

tag : Element | None¶: The XML element to extract text from.
default : str | None¶: The default value to return if the tag has no text.

Return type:¶

str | None

Constants¶

Constants.

choco.constants.CHOCOLATEY_UNINSTALL_PS1¶

Uninstall PowerShell template.

choco.constants.CONTENT_TYPES_XML¶

Used in creating the [Content_Types].xml file.

choco.constants.FEED_AUTHOR_TAG¶

Feed author tag.

choco.constants.FEED_ENTRY_TAG¶

Feed entry tag.

choco.constants.FEED_ID_TAG¶

Feed id tag.

choco.constants.FEED_NAMESPACES¶

Namespaces used in parsing package feeds.

choco.constants.FEED_SUMMARY_TAG¶

Feed summary tag.

choco.constants.FEED_TITLE_TAG¶

Feed title tag.

choco.constants.FEED_UPDATED_TAG¶

Feed updated tag.

choco.constants.METADATA_DESCRIPTION_TAG¶

Feed d:Description tag.

choco.constants.METADATA_DOCS_URL_TAG¶

Feed d:DocsUrl tag.

choco.constants.METADATA_DOWNLOAD_COUNT_TAG¶

Feed d:DownloadCount tag.

choco.constants.METADATA_GALLERY_DETAILS_URL_TAG¶

Feed d:GalleryDetailsUrl tag.

choco.constants.METADATA_IS_APPROVED_TAG¶

Feed d:IsApproved tag.

choco.constants.METADATA_IS_DOWNLOAD_CACHE_AVAILABLE_TAG¶

Feed d:IsDownloadCacheAvailable tag.

choco.constants.METADATA_LICENSE_URL_TAG¶

Feed d:LicenseUrl tag.

choco.constants.METADATA_PACKAGE_APPROVED_DATE_TAG¶

Feed d:PackageApprovedDate tag.

choco.constants.METADATA_PACKAGE_SOURCE_URL_TAG¶

Feed d:PackageSourceUrl tag.

choco.constants.METADATA_PACKAGE_STATUS_TAG¶

Feed d:PackageStatus tag.

choco.constants.METADATA_PACKAGE_TEST_RESULT_STATUS_DATE_TAG¶

Feed d:PackageTestResultStatusDate tag.

choco.constants.METADATA_PACKAGE_TEST_RESULT_STATUS_TAG¶

Feed d:PackageTestResultStatus tag.

choco.constants.METADATA_PROJECT_URL_TAG¶

Feed d:ProjectUrl tag.

choco.constants.METADATA_PUBLISHED_TAG¶

Feed d:Published tag.

choco.constants.METADATA_RELEASE_NOTES_TAG¶

Feed d:ReleaseNotes tag.

choco.constants.METADATA_SUMMARY_TAG¶

Feed d:Summary tag.

choco.constants.METADATA_TAGS_TAG¶

Feed d:Tags tag.

choco.constants.METADATA_VERSION_DOWNLOAD_COUNT_TAG¶

Feed d:VersionDownloadCount tag.

choco.constants.METADATA_VERSION_TAG¶

Feed d:Version tag.

choco.constants.NUSPEC_FIELD_AUTHORS¶

Nuspec authors tag.

choco.constants.NUSPEC_FIELD_DESCRIPTION¶

Nuspec description tag.

choco.constants.NUSPEC_FIELD_ID¶

Nuspec id tag.

choco.constants.NUSPEC_FIELD_TAGS¶

Nuspec tags tag.

choco.constants.NUSPEC_FIELD_VERSION¶

Nuspec version tag.

choco.constants.OBJECT_REF_NOT_SET_ERROR_MESSAGE¶

Error message for object reference not set as seen from chocolatey.org when using the search API.

choco.constants.PYCHOCO_API_KEYS_TOML_PATH¶

Where pychoco’s API key list is stored.

choco.constants.PYCHOCO_TOML_PATH¶

Where pychoco’s main configuration file is by default.

choco.constants.VALID_NAME_RE¶

Valid name for a package regular expression.

Templates¶

Template instances.

choco.templates.CHOCOLATEY_INSTALL_PS1_TEMPLATE¶

Chocolatey PowerShell install template.

choco.templates.NUSPEC_TEMPLATE¶

Used in construction of the Nuspec file.

choco.templates.PSMDCP_XML_TEMPLATE¶

Used in construction of packages/services/metadata/core-properties/{id}.psmdcp.

choco.templates.RELS_XML_TEMPLATE¶

Used in construction of _rels/.rels file.

choco.templates.SEARCH_RESULT_TEMPLATE¶

Search result template.

Typing¶

Typing helpers.

class choco.typing.Config¶: Configuration dictionary after de-serialisation.

choco.typing.ConfigKey¶

Available keys for ChocolateyClient.config_set.

alias of Literal[‘defaultPushSource’]

class choco.typing.SearchResult¶

Represents a package search result.

approval_date : datetime | None¶: Approval date.

description : str | None¶: Description.

documentation_uri : str | None¶: Documentation URL.

is_approved : bool¶: If the package is approved.

is_cached : bool¶: If the package has been cached.

license : str | None¶: License URL.

num_downloads : int¶: Total number of downloads.

num_version_downloads : int¶: Number of downloads for this version of the package.

package_src_uri : str | None¶: Nuspec source.

package_url : str | None¶: Package download URL.

publish_date : datetime | None¶: Publication date.

release_notes_uri : str | None¶: Release notes URL.

site : str | None¶: Package website.

summary : str | None¶: Summary.

tags : list[str]¶: Associated tags.

testing_date : datetime | None¶: Last testing date.

testing_status : TestingStatus¶: Testing status.

title : str | None¶: Unique title of the package.

version : str | None¶: Version.

choco.typing.TestingStatus¶

Testing state of a package.

alias of Literal[‘Passing’, ‘Failing’]

pychoco¶

Commands¶

choco¶

apikey¶

add¶

list¶

config¶

set¶

new¶

pack¶

push¶

search¶

Library¶

Constants¶

Templates¶

Typing¶

Indices and tables¶