Downloader Framework


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


    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
  • min_python_version (list of integers) - Min version number of Python in the format [MAJOR, MINOR, PATCH]
  • 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


class redbot.cogs.downloader.installable.Installable(location, repo=None, commit='')[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.


Name of the repository which this package belongs to.


Repo object of the Installable, if repo is missing this will be None

Type:Repo, optional

Installable’s commit. This is not the same as repo.commit

Type:str, optional

Name(s) of the author(s).

Type:tuple of str, optional

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

Type:tuple of int

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

Type:tuple of int

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


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


Required libraries for this installation.

Type:tuple of str

List of tags to assist in searching.

Type:tuple of str

The type of this installation, as specified by InstallationType.

await copy_to(target_dir)[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

The name of this package.



class redbot.cogs.downloader.installable.InstalledModule(location, repo=None, commit='', pinned=False, json_repo_name='')[source]

Bases: redbot.cogs.downloader.installable.Installable

Base class for installed modules, this is basically instance of installed Installable used by Downloader.


Whether or not this cog is pinned, always False if module is not a cog.



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

Bases: redbot.cogs.downloader.json_mixins.RepoJSONMixin


All available cogs in this Repo.

This excludes hidden or shared packages.

Type:tuple of installable

All available shared libraries in this Repo.

Type:tuple of installable
checkout(rev=None, *, exit_to_rev=None, force_checkout=False)[source]

Checks out repository to provided revision.

The return value of this method can also be used as an asynchronous context manager, i.e. with async with syntax. This will checkout repository to exit_to_rev on exit of the context manager.

  • rev (str, optional) – Revision to checkout to, when not provided, method won’t do anything
  • exit_to_rev (str, optional) – Revision to checkout to after exiting context manager, when not provided, defaults to current commit This will be ignored, when used with await or when rev is None.
  • force_checkout (bool) – When True checkout will be done even if self.commit is the same as target hash (applies to exiting context manager as well) If provided revision isn’t full sha1 hash, checkout will be done no matter to this parameter. Defaults to False.

UnknownRevision – When git cannot checkout to provided revision.


Sanitized repo URL (with removed HTTP Basic Auth)

await clone()[source]

Clone a new repo.

Returns:All available module names from this repo.
Return type:tuple of str
await current_branch()[source]

Determine the current branch using git commands.

Returns:The current branch name.
Return type:str
await current_commit()[source]

Determine the current commit hash of the repo.

Returns:The requested commit hash.
Return type:str
await current_url(folder=None)[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 get_full_sha1(rev)[source]

Gets full sha1 object name.


rev (str) – Revision to search for full sha1 object name.


Full sha1 object name for provided revision.

Return type:


await get_last_module_occurrence(module_name, descendant_rev=None)[source]

Gets module’s Installable from last commit in which it still occurs.

  • module_name (str) – Name of module to get.
  • descendant_rev (str, optional) – Revision from which the module’s commit must be reachable (i.e. descendant commit), defaults to repo’s branch if not given.

Module from last commit in which it still occurs or None if it couldn’t be found.

Return type:


await get_modified_modules(old_rev, new_rev=None)[source]

Gets modified modules between the two revisions. For every module that doesn’t exist in new_rev, it will try to find last commit, where it still existed

  • old_rev (str) – Pre-update revision, ancestor of new_rev
  • new_rev (str, optional) – Post-update revision, defaults to repo’s branch if not given

List of changed modules between the two revisions.

Return type:

tuple of Installable

await hard_reset(branch=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)[source]

Install a cog to the target directory.

  • cog (Installable) – The package to install.
  • target_dir (pathlib.Path) – The target directory for the cog installation.

Cog instance.

Return type:



CopyingError – When cog couldn’t be copied.

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

Install shared libraries to the target directory.

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

  • 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.

2-tuple of installed and failed libraries.

Return type:


await install_raw_requirements(requirements, target_dir)[source]

Install a list of requirements using pip.

  • 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.

Success of the installation

Return type:


await install_requirements(cog, target_dir)[source]

Install a cog’s requirements.

Requirements will be installed via pip directly into target_dir.

  • cog (Installable) – Cog for which to install requirements.
  • target_dir (pathlib.Path) – Path to directory where requirements are to be installed.

Success of the installation.

Return type:


await is_ancestor(maybe_ancestor_rev, descendant_rev)[source]

Check if the first is an ancestor of the second.

  • maybe_ancestor_rev (str) – Revision to check if it is ancestor of descendant_rev
  • descendant_rev (str) – Descendant revision

True if maybe_ancestor_rev is ancestor of descendant_rev or False otherwise

Return type:


await is_on_branch()[source]

Check if repo is currently on branch.

Returns:True if repo is on branch or False otherwise
Return type:bool
await latest_commit(branch=None)[source]

Determine the latest commit hash of the repo.

Parameters:branch (str, optional) – Override for repo’s branch attribute.
Returns:The requested commit hash.
Return type:str
await update()[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)[source]

Add and clone a git repository.

  • url (str) – URL to the git repository.
  • name (str) – Internal name of the repository.
  • branch (str) – Name of the default branch to checkout into.

New Repo object representing the cloned repository.

Return type:


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 cogs.

Return type:tuple of Installable

Get all repo names.

Returns:Repo names.
Return type:tuple of str

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()[source]

Call Repo.update on all repositories.

Returns:A mapping of Repo objects that received new commits to a 2-tuple of str containing old and new commit hashes.
Return type:Dict[Repo, Tuple[str, str]]
await update_repo(repo_name)[source]

Update repo with provided name.

Parameters:name (str) – The name of the repository to update.
Returns:A 2-tuple with Repo object and a 2-tuple of str containing old and new commit hashes.
Return type:Tuple[Repo, Tuple[str, str]]


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.CopyingError[source]

Bases: redbot.cogs.downloader.errors.DownloaderException

Throw when there was an issue during copying of module’s files.

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.UnknownRevision[source]

Bases: redbot.cogs.downloader.errors.GitException

Thrown when specified revision cannot be found.

exception redbot.cogs.downloader.errors.AmbiguousRevision(message, candidates)[source]

Bases: redbot.cogs.downloader.errors.GitException

Thrown when specified revision is ambiguous.

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

Bases: redbot.cogs.downloader.errors.DownloaderException

Thrown when pip returns a non-zero return code.