From 3ff4ed67c3e3604290a033988fa37d717ef5a5d4 Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 11 Jan 2022 01:08:09 +0100 Subject: [PATCH] docstrings --- InvenTree/plugin/builtin/action/mixins.py | 12 +--- .../plugin/builtin/integration/mixins.py | 52 ++++++++++---- InvenTree/plugin/helpers.py | 18 ++++- InvenTree/plugin/integration.py | 67 ++++++++++++++----- 4 files changed, 110 insertions(+), 39 deletions(-) diff --git a/InvenTree/plugin/builtin/action/mixins.py b/InvenTree/plugin/builtin/action/mixins.py index 0be19be2ca..ba98738c84 100644 --- a/InvenTree/plugin/builtin/action/mixins.py +++ b/InvenTree/plugin/builtin/action/mixins.py @@ -19,18 +19,12 @@ class ActionMixin: super().__init__() self.add_mixin('action', 'has_action', __class__) - @property - def has_action(self): - """ - Does this plugin have everything needed for an action? - """ - return True - def action_name(self): """ - Return the action name for this plugin. + Action name for this plugin. + If the ACTION_NAME parameter is empty, - look at the PLUGIN_NAME instead. + uses the PLUGIN_NAME instead. """ if self.ACTION_NAME: return self.ACTION_NAME diff --git a/InvenTree/plugin/builtin/integration/mixins.py b/InvenTree/plugin/builtin/integration/mixins.py index 684e100d81..a2087ee879 100644 --- a/InvenTree/plugin/builtin/integration/mixins.py +++ b/InvenTree/plugin/builtin/integration/mixins.py @@ -87,6 +87,9 @@ class ScheduleMixin: SCHEDULED_TASKS = {} class MixinMeta: + """ + Meta options for this mixin + """ MIXIN_NAME = 'Schedule' def __init__(self): @@ -98,6 +101,9 @@ class ScheduleMixin: @property def has_scheduled_tasks(self): + """ + Are tasks defined for this plugin + """ return bool(self.scheduled_tasks) def validate_scheduled_tasks(self): @@ -126,11 +132,17 @@ class ScheduleMixin: raise MixinImplementationError(f"Task '{key}' is missing 'minutes' parameter") def get_task_name(self, key): + """ + Task name for key + """ # Generate a 'unique' task name slug = self.plugin_slug() return f"plugin.{slug}.{key}" def get_task_names(self): + """ + All defined task names + """ # Returns a list of all task names associated with this plugin instance return [self.get_task_name(key) for key in self.scheduled_tasks.keys()] @@ -192,10 +204,17 @@ class EventMixin: """ def process_event(self, event, *args, **kwargs): + """ + Function to handle events + Must be overridden by plugin + """ # Default implementation does not do anything raise MixinNotImplementedError class MixinMeta: + """ + Meta options for this mixin + """ MIXIN_NAME = 'Events' def __init__(self): @@ -209,6 +228,9 @@ class UrlsMixin: """ class MixinMeta: + """ + Meta options for this mixin + """ MIXIN_NAME = 'URLs' def __init__(self): @@ -218,28 +240,28 @@ class UrlsMixin: def setup_urls(self): """ - setup url endpoints for this plugin + Setup url endpoints for this plugin """ return getattr(self, 'URLS', None) @property def base_url(self): """ - returns base url for this plugin + Base url for this plugin """ return f'{PLUGIN_BASE}/{self.slug}/' @property def internal_name(self): """ - returns the internal url pattern name + Internal url pattern name """ return f'plugin:{self.slug}:' @property def urlpatterns(self): """ - returns the urlpatterns for this plugin + Urlpatterns for this plugin """ if self.has_urls: return url(f'^{self.slug}/', include((self.urls, self.slug)), name=self.slug) @@ -248,7 +270,7 @@ class UrlsMixin: @property def has_urls(self): """ - does this plugin use custom urls + Does this plugin use custom urls """ return bool(self.urls) @@ -263,7 +285,7 @@ class NavigationMixin: class MixinMeta: """ - meta options for this mixin + Meta options for this mixin """ MIXIN_NAME = 'Navigation Links' @@ -274,7 +296,7 @@ class NavigationMixin: def setup_navigation(self): """ - setup navigation links for this plugin + Setup navigation links for this plugin """ nav_links = getattr(self, 'NAVIGATION', None) if nav_links: @@ -287,13 +309,15 @@ class NavigationMixin: @property def has_naviation(self): """ - does this plugin define navigation elements + Does this plugin define navigation elements """ return bool(self.navigation) @property def navigation_name(self): - """name for navigation tab""" + """ + Name for navigation tab + """ name = getattr(self, 'NAVIGATION_TAB_NAME', None) if not name: name = self.human_name @@ -301,7 +325,9 @@ class NavigationMixin: @property def navigation_icon(self): - """icon for navigation tab""" + """ + Icon-name for navigation tab + """ return getattr(self, 'NAVIGATION_TAB_ICON', "fas fa-question") @@ -311,7 +337,9 @@ class AppMixin: """ class MixinMeta: - """meta options for this mixin""" + """m + Mta options for this mixin + """ MIXIN_NAME = 'App registration' def __init__(self): @@ -321,7 +349,7 @@ class AppMixin: @property def has_app(self): """ - this plugin is always an app with this plugin + This plugin is always an app with this plugin """ return True diff --git a/InvenTree/plugin/helpers.py b/InvenTree/plugin/helpers.py index 927fd44a7c..e7c7f4a3a8 100644 --- a/InvenTree/plugin/helpers.py +++ b/InvenTree/plugin/helpers.py @@ -10,6 +10,9 @@ from django.conf import settings # region logging / errors def log_plugin_error(error, reference: str = 'general'): + """ + Log an plugin error + """ from plugin import registry # make sure the registry is set up @@ -21,6 +24,9 @@ def log_plugin_error(error, reference: str = 'general'): class IntegrationPluginError(Exception): + """ + Error that encapsulates another error and adds the path / reference of the raising plugin + """ def __init__(self, path, message): self.path = path self.message = message @@ -85,7 +91,9 @@ def handle_plugin_error(error, do_raise: bool = True, do_log: bool = True, do_re # region git-helpers def get_git_log(path): - """get dict with info of the last commit to file named in path""" + """ + Get dict with info of the last commit to file named in path + """ path = path.replace(os.path.dirname(settings.BASE_DIR), '')[1:] command = ['git', 'log', '-n', '1', "--pretty=format:'%H%n%aN%n%aE%n%aI%n%f%n%G?%n%GK'", '--follow', '--', path] try: @@ -100,9 +108,13 @@ def get_git_log(path): class GitStatus: - """class for resolving git gpg singing state""" + """ + Class for resolving git gpg singing state + """ class Definition: - """definition of a git gpg sing state""" + """ + Definition of a git gpg sing state + """ key: str = 'N' status: int = 2 msg: str = '' diff --git a/InvenTree/plugin/integration.py b/InvenTree/plugin/integration.py index c00b81419d..9936fed1fa 100644 --- a/InvenTree/plugin/integration.py +++ b/InvenTree/plugin/integration.py @@ -20,7 +20,7 @@ logger = logging.getLogger("inventree") class MixinBase: """ - General base for mixins + Base set of mixin functions and mechanisms """ def __init__(self) -> None: @@ -87,20 +87,31 @@ class IntegrationPluginBase(MixinBase, plugin.InvenTreePlugin): @property def _is_package(self): + """ + Is the plugin delivered as a package + """ return getattr(self, 'is_package', False) # region properties @property def slug(self): + """ + Slug of plugin + """ return self.plugin_slug() @property def name(self): + """ + Name of plugin + """ return self.plugin_name() @property def human_name(self): - """human readable name for labels etc.""" + """ + Human readable name of plugin + """ human_name = getattr(self, 'PLUGIN_TITLE', None) if not human_name: human_name = self.plugin_name() @@ -108,7 +119,9 @@ class IntegrationPluginBase(MixinBase, plugin.InvenTreePlugin): @property def description(self): - """description of plugin""" + """ + Description of plugin + """ description = getattr(self, 'DESCRIPTION', None) if not description: description = self.plugin_name() @@ -116,7 +129,9 @@ class IntegrationPluginBase(MixinBase, plugin.InvenTreePlugin): @property def author(self): - """returns author of plugin - either from plugin settings or git""" + """ + Author of plugin - either from plugin settings or git + """ author = getattr(self, 'AUTHOR', None) if not author: author = self.package.get('author') @@ -126,7 +141,9 @@ class IntegrationPluginBase(MixinBase, plugin.InvenTreePlugin): @property def pub_date(self): - """returns publishing date of plugin - either from plugin settings or git""" + """ + Publishing date of plugin - either from plugin settings or git + """ pub_date = getattr(self, 'PUBLISH_DATE', None) if not pub_date: pub_date = self.package.get('date') @@ -138,42 +155,56 @@ class IntegrationPluginBase(MixinBase, plugin.InvenTreePlugin): @property def version(self): - """returns version of plugin""" + """ + Version of plugin + """ version = getattr(self, 'VERSION', None) return version @property def website(self): - """returns website of plugin""" + """ + Website of plugin - if set else None + """ website = getattr(self, 'WEBSITE', None) return website @property def license(self): - """returns license of plugin""" + """ + License of plugin + """ license = getattr(self, 'LICENSE', None) return license # endregion @property def package_path(self): - """returns the path to the plugin""" + """ + Path to the plugin + """ if self._is_package: return self.__module__ return pathlib.Path(self.def_path).relative_to(settings.BASE_DIR) @property def settings_url(self): - """returns url to the settings panel""" + """ + URL to the settings panel for this plugin + """ return f'{reverse("settings")}#select-plugin-{self.slug}' # region mixins def mixin(self, key): - """check if mixin is registered""" + """ + Check if mixin is registered + """ return key in self._mixins def mixin_enabled(self, key): - """check if mixin is enabled and ready""" + """ + Check if mixin is registered, enabled and ready + """ if self.mixin(key): fnc_name = self._mixins.get(key) @@ -187,15 +218,21 @@ class IntegrationPluginBase(MixinBase, plugin.InvenTreePlugin): # region package info def get_package_commit(self): - """get last git commit for plugin""" + """ + Get last git commit for the plugin + """ return get_git_log(self.def_path) def get_package_metadata(self): - """get package metadata for plugin""" + """ + Get package metadata for plugin + """ return {} def set_package(self): - """add packaging info of the plugins into plugins context""" + """ + Add package info of the plugin into plugins context + """ package = self.get_package_metadata() if self._is_package else self.get_package_commit() # process date