From c206056f07aacfaee10c4e6b193265c2fc79eea4 Mon Sep 17 00:00:00 2001 From: Nick Sweeting Date: Sun, 17 Nov 2024 20:26:56 -0800 Subject: [PATCH] add better docstrings to abx package --- archivebox/pkgs/abx/abx.py | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/archivebox/pkgs/abx/abx.py b/archivebox/pkgs/abx/abx.py index 8e76ead5..7df8647d 100644 --- a/archivebox/pkgs/abx/abx.py +++ b/archivebox/pkgs/abx/abx.py @@ -2,7 +2,7 @@ __package__ = 'abx' __id__ = 'abx' __label__ = 'ABX' __author__ = 'Nick Sweeting' -__homepage__ = 'https://github.com/ArchiveBox' +__homepage__ = 'https://github.com/ArchiveBox/ArchiveBox' __order__ = 0 @@ -26,9 +26,11 @@ ParamsT = ParamSpec("ParamsT") ReturnT = TypeVar('ReturnT') class HookSpecDecoratorThatReturnsFirstResult(Protocol): + """Type of a plugin method decorated with @hookspec(firstresult=True), which returns a single result (from the first plugin that implements the hook)""" def __call__(self, func: Callable[ParamsT, ReturnT]) -> Callable[ParamsT, ReturnT]: ... class HookSpecDecoratorThatReturnsListResults(Protocol): + """Type of a plugin method decorated with @hookspec(firstresult=False), which returns a list of results (one for each plugin that implements the hook)""" def __call__(self, func: Callable[ParamsT, ReturnT]) -> Callable[ParamsT, List[ReturnT]]: ... @@ -111,10 +113,12 @@ impl = hookimpl = HookimplMarker("abx") def is_valid_attr_name(x: str) -> str: + """Check if a string is a valid attribute name (used to validate hook method names on a plugin)""" assert x.isidentifier() and not x.startswith('_') return x def is_valid_module_name(x: str) -> str: + """Check if a string e.g. "some_pkg.some_plugin_name" is a valid module name (used to validate plugin IDs)""" assert x.isidentifier() and not x.startswith('_') and x.islower() return x @@ -123,6 +127,7 @@ PluginId = Annotated[str, AfterValidator(is_valid_module_name)] class PluginInfo(TypedDict, total=True): + """Full Metadata Dictionary containing all info about a plugin, returned by abx.get_plugin()""" id: PluginId package: AttrName label: str @@ -213,6 +218,7 @@ pm = ABXPluginManager("abx") def get_plugin_order(plugin: PluginId | Path | ModuleType | Type) -> Tuple[int, Path]: + """Get the order a plugin should be loaded in by reading its ./.plugin_order file or .__order__ attr""" assert plugin plugin_module = None plugin_dir = None @@ -259,6 +265,7 @@ def get_plugin_order(plugin: PluginId | Path | ModuleType | Type) -> Tuple[int, # @cache def get_plugin(plugin: PluginId | ModuleType | Type) -> PluginInfo: + """Get the full PluginInfo metadata for a plugin, given its plugin ID, module, or class""" assert plugin # import the plugin module by its name @@ -325,7 +332,7 @@ def get_plugin(plugin: PluginId | ModuleType | Type) -> PluginInfo: def get_all_plugins() -> Dict[PluginId, PluginInfo]: - """Get the metadata for all the plugins registered with Pluggy.""" + """Get the PluginInfo metadata for all the loaded plugins""" plugins = {} for plugin_module in pm.get_plugins(): plugin_info = get_plugin(plugin=plugin_module) @@ -335,7 +342,7 @@ def get_all_plugins() -> Dict[PluginId, PluginInfo]: def get_all_hook_names() -> Set[str]: - """Get a set of all hook names across all plugins""" + """Get the names of all hookspec/hookimpl methods available across all loaded plugins""" return { hook_name for plugin_module in pm.get_plugins() @@ -446,7 +453,7 @@ def load_plugins(plugins: Iterable[PluginId | ModuleType | Type] | Dict[PluginId @cache def get_plugin_hooks(plugin: PluginId | ModuleType | Type | None) -> Dict[AttrName, Callable]: - """Get all the functions marked with @hookimpl on a module.""" + """Get all the functions marked with @hookimpl on a plugin module or class.""" if not plugin: return {} @@ -475,12 +482,12 @@ def get_plugin_hooks(plugin: PluginId | ModuleType | Type | None) -> Dict[AttrNa ReturnT = TypeVar('ReturnT') def as_list(results: List[List[ReturnT]]) -> List[ReturnT]: - """Flatten a list of lists returned by a pm.hook.call() into a single list""" + """Flatten a list of lists returned by a pm.hook.call() into a single list of [result1, result2, ...]""" return list(itertools.chain(*results)) def as_dict(results: List[Dict[PluginId, ReturnT]]) -> Dict[PluginId, ReturnT]: - """Flatten a list of dicts returned by a pm.hook.call() into a single dict""" + """Flatten a list of dicts returned by a pm.hook.call() into a single dict of {plugin_id1: result1, plugin_id2: result2, ...}""" if isinstance(results, (dict, benedict)): results_list = results.values()