Downloader Framework

Info.json

The info.json file may exist inside every package folder in the repo, it is optional however. This string describes the valid keys within an info file (and maybe how the Downloader cog uses them).

KEYS (case sensitive):

• author (list of strings) - list of names of authors of the cog
• bot_version (list of integer) - Min version number of Red in the format (MAJOR, MINOR, PATCH)
• description (string) - A long description of the cog that appears when a user executes `!cog info.
• hidden (bool) - Determines if a cog is available for install.
• install_msg (string) - The message that gets displayed when a cog is installed
• 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.
• short (string) - A short description of the cog that appears when a user executes cog 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: pathlib.Path)

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

str – Name of the repository which this package belongs to.

author

tuple of str, optional – Name(s) of the author(s).

bot_version

tuple of int – The minimum bot version required for this installation. Right now this is always 3.0.0.

hidden

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

required_cogs

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

requirements

tuple of str – Required libraries for this installation.

tags

tuple of str – List of tags to assist in searching.

type

int – The type of this installation, as specified by InstallationType.

coroutine copy_to(target_dir: pathlib.Path) → bool

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

str – The name of this package.

Repo

class redbot.cogs.downloader.repo_manager.Repo(name: str, url: str, branch: str, folder_path: pathlib.Path, available_modules: typing.Tuple[redbot.cogs.downloader.installable.Installable] = (), loop: asyncio.events.AbstractEventLoop = None)

available_cogs

tuple of installable – All available cogs in this Repo.

This excludes hidden or shared packages.

available_libraries

tuple of installable – All available shared libraries in this Repo.

coroutine clone() → typing.Tuple[str]

Clone a new repo.

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

coroutine current_branch() → str

Determine the current branch using git commands.

Returns:The current branch name. Return type:str

coroutine current_commit(branch: str = None) → str

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

coroutine hard_reset(branch: str = None) → None

Perform a hard reset on the current repo.

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

coroutine install_cog(cog: redbot.cogs.downloader.installable.Installable, target_dir: pathlib.Path) → bool

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

coroutine install_libraries(target_dir: pathlib.Path, libraries: typing.Tuple[redbot.cogs.downloader.installable.Installable] = ()) → bool

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.
• libraries (tuple of Installable) – A subset of available libraries.

Returns:

The success of the installation.

Return type:

bool

coroutine install_raw_requirements(requirements: typing.Tuple[str], target_dir: pathlib.Path) → bool

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

coroutine install_requirements(cog: redbot.cogs.downloader.installable.Installable, target_dir: pathlib.Path) → bool

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

coroutine update() -> (<class 'str'>, <class 'str'>)

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(downloader_config: redbot.core.config.Config)

coroutine add_repo(url: str, name: str, branch: str = 'master') → redbot.cogs.downloader.repo_manager.Repo

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

coroutine delete_repo(name: str)

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() → typing.Tuple[str]

Get all repo names.

Returns: Return type:tuple of str

get_repo(name: str) → typing.Union[redbot.cogs.downloader.repo_manager.Repo, NoneType]

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

coroutine update_all_repos() → typing.MutableMapping[redbot.cogs.downloader.repo_manager.Repo, typing.Tuple[str, str]]

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

Base class for Downloader exceptions.

exception redbot.cogs.downloader.errors.GitException

Generic class for git exceptions.

exception redbot.cogs.downloader.errors.InvalidRepoName

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

exception redbot.cogs.downloader.errors.ExistingGitRepo

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

exception redbot.cogs.downloader.errors.MissingGitRepo

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

exception redbot.cogs.downloader.errors.CloningError

Thrown when git clone returns a non zero exit code.

exception redbot.cogs.downloader.errors.CurrentHashError

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

exception redbot.cogs.downloader.errors.HardResetError

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

exception redbot.cogs.downloader.errors.UpdateError

Thrown when git pull returns a non zero error code.

exception redbot.cogs.downloader.errors.GitDiffError

Thrown when a git diff fails.

exception redbot.cogs.downloader.errors.PipError

Thrown when pip returns a non-zero return code.