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 cogbot_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 installedrequired_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 executescog 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 toCOG
. Must be eitherCOG
orSHARED_LIBRARY
. IfSHARED_LIBRARY
thenhidden
will beTrue
.
API Reference¶
Installable¶
-
class
redbot.cogs.downloader.installable.
Installable
(location: pathlib.Path)[source]¶ 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.
-
bot_version
¶ tuple
ofint
– The minimum bot version required for this installation. Right now this is always3.0.0
.
bool
– Whether or not this cog will be hidden from the user when they useDownloader
’s commands.
-
required_cogs
¶ dict
– In the form{cog_name : repo_url}
, these are cogs which are required for this installation.
-
coroutine
copy_to
(target_dir: pathlib.Path) → 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
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)[source]¶ -
available_cogs
¶ tuple
ofinstallable
– All available cogs in this Repo.This excludes hidden or shared packages.
-
available_libraries
¶ tuple
ofinstallable
– All available shared libraries in this Repo.
-
coroutine
clone
() → typing.Tuple[str][source]¶ Clone a new repo.
Returns: All available module names from this repo. Return type: tuple
ofstr
-
coroutine
current_branch
() → str[source]¶ Determine the current branch using git commands.
Returns: The current branch name. Return type: str
-
coroutine
current_commit
(branch: str = 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
-
coroutine
hard_reset
(branch: str = None) → None[source]¶ 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[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:
-
coroutine
install_libraries
(target_dir: pathlib.Path, libraries: typing.Tuple[redbot.cogs.downloader.installable.Installable] = ()) → 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.
- libraries (
tuple
ofInstallable
) – A subset of available libraries.
Returns: The success of the installation.
Return type:
-
coroutine
install_raw_requirements
(requirements: typing.Tuple[str], target_dir: pathlib.Path) → bool[source]¶ Install a list of requirements using pip.
Parameters: - requirements (
tuple
ofstr
) – 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: - requirements (
-
coroutine
install_requirements
(cog: redbot.cogs.downloader.installable.Installable, target_dir: pathlib.Path) → 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:
-
Repo Manager¶
-
class
redbot.cogs.downloader.repo_manager.
RepoManager
(downloader_config: redbot.core.config.Config)[source]¶ -
coroutine
add_repo
(url: str, name: str, branch: str = 'master') → redbot.cogs.downloader.repo_manager.Repo[source]¶ Add and clone a git repository.
Parameters: Returns: New Repo object representing the cloned repository.
Return type:
-
coroutine
delete_repo
(name: str)[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
() → typing.Tuple[str][source]¶ Get all repo names.
Returns: Return type: tuple
ofstr
-
coroutine
Exceptions¶
-
exception
redbot.cogs.downloader.errors.
DownloaderException
[source]¶ Base class for Downloader exceptions.
-
exception
redbot.cogs.downloader.errors.
InvalidRepoName
[source]¶ Throw when a repo name is invalid. Check the message for a more detailed reason.
-
exception
redbot.cogs.downloader.errors.
ExistingGitRepo
[source]¶ Thrown when trying to clone into a folder where a git repo already exists.
-
exception
redbot.cogs.downloader.errors.
MissingGitRepo
[source]¶ Thrown when a git repo is expected to exist but does not.
-
exception
redbot.cogs.downloader.errors.
CloningError
[source]¶ Thrown when git clone returns a non zero exit code.
-
exception
redbot.cogs.downloader.errors.
CurrentHashError
[source]¶ Thrown when git returns a non zero exit code attempting to determine the current commit hash.
-
exception
redbot.cogs.downloader.errors.
HardResetError
[source]¶ Thrown when there is an issue trying to execute a hard reset (usually prior to a repo update).