Downloader Framework¶

Info.json¶

The optional info.json file may exist inside every package folder in the repo, as well as in the root of the repo. The following sections describe the valid keys within an info file (and maybe how the Downloader cog uses them).

Keys common to both repo and cog info.json (case sensitive)¶

author (list of strings) - list of names of authors of the cog or repo.
description (string) - A long description of the cog or repo. For cogs, this is displayed when a user executes !cog info.
install_msg (string) - The message that gets displayed when a cog is installed or a repo is added

Tip

You can use the [p] key in your string to use the prefix used for installing.
short (string) - A short description of the cog or repo. For cogs, this info is displayed when a user executes !cog list

Keys specific to the cog info.json (case sensitive)¶

min_bot_version (string) - Min version number of Red in the format MAJOR.MINOR.MICRO
max_bot_version (string) - Max version number of Red in the format MAJOR.MINOR.MICRO, if min_bot_version is newer than max_bot_version, max_bot_version will be ignored
hidden (bool) - Determines if a cog is visible in the cog list for a repo.
disabled (bool) - Determines if a cog is available for install.
required_cogs (map of cogname to repo URL) - A map of required cogs that this cog depends on. Downloader will not deal with this functionality but it may be useful for other cogs.
requirements (list of strings) - list of required libraries that are passed to pip on cog install. SHARED_LIBRARIES do NOT go in this list.
tags (list of strings) - A list of strings that are related to the functionality of the cog. Used to aid in searching.
type (string) - Optional, defaults to COG. Must be either COG or SHARED_LIBRARY. If SHARED_LIBRARY then hidden will be True.

API Reference¶

Installable¶

class redbot.cogs.downloader.installable.Installable(location)[source]¶

Bases: redbot.cogs.downloader.json_mixins.RepoJSONMixin

Base class for anything the Downloader cog can install.

Modules

Repo Libraries

Other stuff?

The attributes of this class will mostly come from the installation’s info.json.

repo_name¶

Name of the repository which this package belongs to.

Type:	`str`

author¶

Name(s) of the author(s).

Type:	`tuple` of `str`, optional

bot_version¶

The minimum bot version required for this installation. Right now this is always 3.0.0.

Type:	`tuple` of `int`

min_python_version¶

The minimum python version required for this cog. This field will not apply to repo info.json’s.

Type:	`tuple` of `int`

hidden¶

Whether or not this cog will be hidden from the user when they use Downloader’s commands.

Type:	`bool`

required_cogs¶

In the form {cog_name : repo_url}, these are cogs which are required for this installation.

Type:	`dict`

requirements¶

Required libraries for this installation.

Type:	`tuple` of `str`

tags¶

List of tags to assist in searching.

Type:	`tuple` of `str`

type¶

The type of this installation, as specified by InstallationType.

Type:	`int`

await copy_to(target_dir) → bool[source]¶

Copies this cog/shared_lib to the given directory. This will overwrite any files in the target directory.

Parameters:	target_dir (pathlib.Path) – The installation directory to install to.
Returns:	Status of installation
Return type:	bool

name¶

The name of this package.

Type:	`str`

Repo¶

class redbot.cogs.downloader.repo_manager.Repo(name, url, branch, folder_path, available_modules = (), loop = None)[source]¶

Bases: redbot.cogs.downloader.json_mixins.RepoJSONMixin

available_cogs¶

All available cogs in this Repo.

This excludes hidden or shared packages.

Type:	`tuple` of `installable`

available_libraries¶

All available shared libraries in this Repo.

Type:	`tuple` of `installable`

await clone() → Tuple[str][source]¶

Clone a new repo.

Returns:	All available module names from this repo.
Return type:	`tuple` of `str`

await current_branch() → str[source]¶

Determine the current branch using git commands.

Returns:	The current branch name.
Return type:	str

await current_commit(branch = None) → str[source]¶

Determine the current commit hash of the repo.

Parameters:	branch (`str`, optional) – Override for repo’s branch attribute.
Returns:	The requested commit hash.
Return type:	str

await current_url(folder = None) → str[source]¶

Discovers the FETCH URL for a Git repo.

Parameters:	folder (pathlib.Path) – The folder to search for a URL.
Returns:	The FETCH URL.
Return type:	str
Raises:	NoRemoteURL – When the folder does not contain a git repo with a FETCH URL.

await hard_reset(branch = None) → None[source]¶

Perform a hard reset on the current repo.

Parameters:	branch (`str`, optional) – Override for repo branch attribute.

await install_cog(cog, target_dir) → bool[source]¶

Install a cog to the target directory.

Parameters:	cog (Installable) – The package to install. target_dir (pathlib.Path) – The target directory for the cog installation.
Returns:	The success of the installation.
Return type:	bool

await install_libraries(target_dir, req_target_dir, libraries = ()) → bool[source]¶

Install shared libraries to the target directory.

If libraries is not specified, all shared libraries in the repo will be installed.

Parameters:	target_dir (pathlib.Path) – Directory to install shared libraries to. req_target_dir (pathlib.Path) – Directory to install shared library requirements to. libraries (`tuple` of `Installable`) – A subset of available libraries.
Returns:	The success of the installation.
Return type:	bool

await install_raw_requirements(requirements, target_dir) → bool[source]¶

Install a list of requirements using pip.

Parameters:	requirements (`tuple` of `str`) – List of requirement names to install via pip. target_dir (pathlib.Path) – Path to directory where requirements are to be installed.
Returns:	Success of the installation
Return type:	bool

await install_requirements(cog, target_dir) → bool[source]¶

Install a cog’s requirements.

Requirements will be installed via pip directly into target_dir.

Parameters:	cog (Installable) – Cog for which to install requirements. target_dir (pathlib.Path) – Path to directory where requirements are to be installed.
Returns:	Success of the installation.
Return type:	bool

await update() -> (<class 'str'>, <class 'str'>)[source]¶

Update the current branch of this repo.

Returns:	:py:code`(old commit hash, new commit hash)`
Return type:	`tuple` of `str`

Repo Manager¶

class redbot.cogs.downloader.repo_manager.RepoManager[source]¶

Bases: object

await add_repo(url, name, branch = None) → redbot.cogs.downloader.repo_manager.Repo[source]¶

Add and clone a git repository.

Parameters:	url (str) – URL to the git repository. name (str) – Internal name of the repository. branch (str) – Name of the default branch to checkout into.
Returns:	New Repo object representing the cloned repository.
Return type:	Repo

await delete_repo(name)[source]¶

Delete a repository and its folders.

Parameters:	name (str) – The name of the repository to delete.
Raises:	MissingGitRepo – If the repo does not exist.

get_all_repo_names() → Tuple[str][source]¶

Get all repo names.

Returns:
Return type:	`tuple` of `str`

get_repo(name) → Optional[redbot.cogs.downloader.repo_manager.Repo][source]¶

Get a Repo object for a repository.

Parameters:	name (str) – The name of the repository to retrieve.
Returns:	Repo object for the repository, if it exists.
Return type:	`Repo` or `None`