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
await update_all_repos() → MutableMapping[redbot.cogs.downloader.repo_manager.Repo, Tuple[str, str]][source]

Call Repo.update on all repositories.

Returns:A mapping of Repo objects that received new commits to a tuple of str containing old and new commit hashes.
Return type:dict

Exceptions

exception redbot.cogs.downloader.errors.DownloaderException[source]

Bases: Exception

Base class for Downloader exceptions.

exception redbot.cogs.downloader.errors.GitException[source]

Bases: redbot.cogs.downloader.errors.DownloaderException

Generic class for git exceptions.

exception redbot.cogs.downloader.errors.InvalidRepoName[source]

Bases: redbot.cogs.downloader.errors.DownloaderException

Throw when a repo name is invalid. Check the message for a more detailed reason.

exception redbot.cogs.downloader.errors.ExistingGitRepo[source]

Bases: redbot.cogs.downloader.errors.DownloaderException

Thrown when trying to clone into a folder where a git repo already exists.

exception redbot.cogs.downloader.errors.MissingGitRepo[source]

Bases: redbot.cogs.downloader.errors.DownloaderException

Thrown when a git repo is expected to exist but does not.

exception redbot.cogs.downloader.errors.CloningError[source]

Bases: redbot.cogs.downloader.errors.GitException

Thrown when git clone returns a non zero exit code.

exception redbot.cogs.downloader.errors.CurrentHashError[source]

Bases: redbot.cogs.downloader.errors.GitException

Thrown when git returns a non zero exit code attempting to determine the current commit hash.

exception redbot.cogs.downloader.errors.HardResetError[source]

Bases: redbot.cogs.downloader.errors.GitException

Thrown when there is an issue trying to execute a hard reset (usually prior to a repo update).

exception redbot.cogs.downloader.errors.UpdateError[source]

Bases: redbot.cogs.downloader.errors.GitException

Thrown when git pull returns a non zero error code.

exception redbot.cogs.downloader.errors.GitDiffError[source]

Bases: redbot.cogs.downloader.errors.GitException

Thrown when a git diff fails.

exception redbot.cogs.downloader.errors.NoRemoteURL[source]

Bases: redbot.cogs.downloader.errors.GitException

Thrown when no remote URL exists for a repo.

exception redbot.cogs.downloader.errors.PipError[source]

Bases: redbot.cogs.downloader.errors.DownloaderException

Thrown when pip returns a non-zero return code.