CopyBot/Red-DiscordBot
1
0
Fork 0
mirror of https://github.com/Cog-Creators/Red-DiscordBot.git synced 2025-11-21 02:16:09 -05:00
Code Issues Packages Projects Releases Wiki Activity

[V3] NumPy Docstrings (#1032)

Browse Source 
* ALL THE DOCSTRINGS

* Remove imports in drivers package

* Fixed build warnings
This commit is contained in:
Tobotimus
2017-10-18 13:01:59 +11:00
committed by Will
parent 684004d614
commit c80684a129
14 changed files with 976 additions and 560 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
redbot/core/cog_manager.py
View File

@@ -16,10 +16,12 @@ __all__ = ["CogManager"]
class CogManager:
"""
This module allows you to load cogs from multiple directories and even from outside the bot
directory. You may also set a directory for downloader to install new cogs to, the default
being the :code:`cogs/` folder in the root bot directory.
"""Directory manager for Red's cogs.
This module allows you to load cogs from multiple directories and even from
outside the bot directory. You may also set a directory for downloader to
install new cogs to, the default being the :code:`cogs/` folder in the root
bot directory.
"""
def __init__(self, paths: Tuple[str]=()):
self.conf = Config.get_conf(self, 2938473984732, True)
@@ -33,8 +35,13 @@ class CogManager:
self._paths = list(paths)
async def paths(self) -> Tuple[Path, ...]:
"""
All currently valid path directories.
"""Get all currently valid path directories.
Returns
-------
`tuple` of `pathlib.Path`
All valid cog paths.
"""
conf_paths = await self.conf.paths()
other_paths = self._paths
@@ -47,26 +54,40 @@ class CogManager:
return tuple(p.resolve() for p in paths if p.is_dir())
async def install_path(self) -> Path:
"""
The install path for 3rd party cogs.
"""Get the install path for 3rd party cogs.
Returns
-------
pathlib.Path
The path to the directory where 3rd party cogs are stored.
"""
p = Path(await self.conf.install_path())
return p.resolve()
async def set_install_path(self, path: Path) -> Path:
"""
Install path setter, will return the absolute path to
the given path.
"""Set the install path for 3rd party cogs.
.. note::
Note
----
The bot will not remember your old cog install path which means
that **all previously installed cogs** will no longer be found.
The bot will not remember your old cog install path which means
that ALL PREVIOUSLY INSTALLED COGS will now be unfindable.
:param pathlib.Path path:
Parameters
----------
path : pathlib.Path
The new directory for cog installs.
:raises ValueError:
Returns
-------
pathlib.Path
Absolute path to the new install directory.
Raises
------
ValueError
If :code:`path` is not an existing directory.
"""
if not path.is_dir():
raise ValueError("The install path must be an existing directory.")
@@ -76,14 +97,16 @@ class CogManager:
@staticmethod
def _ensure_path_obj(path: Union[Path, str]) -> Path:
"""
Guarantees an object will be a path object.
"""Guarantee an object will be a path object.
Parameters
----------
path : `pathlib.Path` or `str`
Returns
-------
pathlib.Path
:param path:
:type path:
pathlib.Path or str
:rtype:
pathlib.Path
"""
try:
path.exists()
@@ -92,17 +115,21 @@ class CogManager:
return path
async def add_path(self, path: Union[Path, str]):
"""
Adds a cog path to current list, will ignore duplicates. Does have
a side effect of removing all invalid paths from the saved path
list.
"""Add a cog path to current list.
:param path:
This will ignore duplicates. Does have a side effect of removing all
invalid paths from the saved path list.
Parameters
----------
path : `pathlib.Path` or `str`
Path to add.
:type path:
pathlib.Path or str
:raises ValueError:
Raises
------
ValueError
If :code:`path` does not resolve to an existing directory.
"""
path = self._ensure_path_obj(path)
@@ -121,15 +148,18 @@ class CogManager:
await self.set_paths(all_paths)
async def remove_path(self, path: Union[Path, str]) -> Tuple[Path, ...]:
"""
Removes a path from the current paths list.
"""Remove a path from the current paths list.
:param path: Path to remove.
:type path:
pathlib.Path or str
:return:
Parameters
----------
path : `pathlib.Path` or `str`
Path to remove.
Returns
-------
`tuple` of `pathlib.Path`
Tuple of new valid paths.
:rtype: tuple
"""
path = self._ensure_path_obj(path)
all_paths = list(await self.paths())
@@ -139,27 +169,35 @@ class CogManager:
return tuple(all_paths)
async def set_paths(self, paths_: List[Path]):
"""
Sets the current paths list.
"""Set the current paths list.
:param List[pathlib.Path] paths_:
Parameters
----------
paths_ : `list` of `pathlib.Path`
List of paths to set.
"""
str_paths = [str(p) for p in paths_]
await self.conf.paths.set(str_paths)
async def find_cog(self, name: str) -> ModuleSpec:
"""
Finds a cog in the list of available paths.
"""Find a cog in the list of available paths.
:param name:
Parameters
----------
name : str
Name of the cog to find.
:raises RuntimeError:
If there is no cog with the given name.
:return:
Returns
-------
importlib.machinery.ModuleSpec
A module spec to be used for specialized cog loading.
:rtype:
importlib.machinery.ModuleSpec
Raises
------
RuntimeError
If there is no cog with the given name.
"""
resolved_paths = [str(p.resolve()) for p in await self.paths()]
for finder, module_name, _ in pkgutil.iter_modules(resolved_paths):
@@ -173,11 +211,10 @@ class CogManager:
@staticmethod
def invalidate_caches():
"""
"""Re-evaluate modules in the py cache.
This is an alias for an importlib internal and should be called
any time that a new module has been installed to a cog directory.
*I think.*
"""
invalidate_caches()