From 92ef4e4970c88484e6a13543a8d7cf4c551ea3a7 Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Sun, 16 Jan 2022 23:58:38 +0100 Subject: [PATCH 01/18] first guide section --- docs/extend/how_to_plugin.md | 27 +++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 28 insertions(+) create mode 100644 docs/extend/how_to_plugin.md diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md new file mode 100644 index 0000000..659eb3e --- /dev/null +++ b/docs/extend/how_to_plugin.md @@ -0,0 +1,27 @@ +--- +title: How to plugin +--- + +## How to write a plugin +A short introductory guide for plugin beginners. + +### Should it be a plugin? +First of all figure out what you function / code should do. +If you want to change how InvenTree base mechanics and business logic work a plugin will not be sufficient. Maybe fork the project or better start a discussion on GitHub. + +If you want to remove parts of the user interface -> remove the permissions for that part and the users will not see them. + +If you add a lot of code (over ~1000 LOC) maybe spilt it into multiple plugins to make upgrading specific parts and testing simpler. + +### It will be a plugin! Now pick your mixins +Great. Now please read the plugin documentation to figure out the basic way it works. It is rather short as a the (builtin) mixins come with extensive docstrings. + +Consider the usecase for your plugin and define the exact function of the plugin, maybe even in a short readme. The pick the mixins you need. They help reduce custom code and keep the system reliable if internal calls change. + +- Is it just a simple REST-endpoint that runs a function (ActionMixin) or a parser for a custom barcode format (BarcodeMixin)? +- How does the user interact with the plugin? Is it a UI separate from the main InvenTree UI (UrlsMixin), does it need multiple pages with navigation-links (NavigationMixin). +- Will it make calls to external APIs (APICallMixin helps there)? +- Do you need to run in the background (ScheduleMixin) or when things in InvenTree change (EventMixin)? +- Does the plugin need configuration that should be user changeable (SettingsMixin) or static (just use a yaml in the config dir)? +- You want to receive webhooks? Do not code your own untested function – use the WebhookEndpoint model as a base and override the perform_action method. +- Do you need the full power of Django with custom models and all the complexity that comes with that – welcome to the danger zone and AppMixin. diff --git a/mkdocs.yml b/mkdocs.yml index 192a789..a07f4b4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -111,6 +111,7 @@ nav: - Python Interface: extend/python.md - Plugins: - Overview: extend/plugins.md + - How to plugin: extend/how_to_plugin.md - Action Mixin: extend/plugins/action.md - API Mixin: extend/plugins/api.md - App Mixin: extend/plugins/app.md From 7bb65a2e77b0f5d47b19f56b23e27d6fd13647a8 Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Mon, 17 Jan 2022 00:05:22 +0100 Subject: [PATCH 02/18] fix small mistakes --- docs/extend/how_to_plugin.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index 659eb3e..b76c76f 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -6,17 +6,17 @@ title: How to plugin A short introductory guide for plugin beginners. ### Should it be a plugin? -First of all figure out what you function / code should do. -If you want to change how InvenTree base mechanics and business logic work a plugin will not be sufficient. Maybe fork the project or better start a discussion on GitHub. +First of all figure out what your plugin / code should do. +If you want to change how InvenTree base mechanics and business logic work, a plugin will not be sufficient. Maybe fork the project or better start a discussion on GitHub. There might be an easier / established way to do what you want. -If you want to remove parts of the user interface -> remove the permissions for that part and the users will not see them. +If you want to remove parts of the user interface -> remove the permissions for those objects / actions and the users will not see them. -If you add a lot of code (over ~1000 LOC) maybe spilt it into multiple plugins to make upgrading specific parts and testing simpler. +If you add a lot of code (over ~1000 LOC) maybe split it into multiple plugins to make upgrading and testing simpler. -### It will be a plugin! Now pick your mixins -Great. Now please read the plugin documentation to figure out the basic way it works. It is rather short as a the (builtin) mixins come with extensive docstrings. +### It will be a plugin! Pick your building blocks +Great. Now please read the plugin documentation to get an overview of the architecture. It is rather short as a the (builtin) mixins come with extensive docstrings. -Consider the usecase for your plugin and define the exact function of the plugin, maybe even in a short readme. The pick the mixins you need. They help reduce custom code and keep the system reliable if internal calls change. +Consider the usecase for your plugin and define the exact function of the plugin, maybe wrtie it down in a short readme. Then pick the mixins you need (they help reduce custom code and keep the system reliable if internal calls change). - Is it just a simple REST-endpoint that runs a function (ActionMixin) or a parser for a custom barcode format (BarcodeMixin)? - How does the user interact with the plugin? Is it a UI separate from the main InvenTree UI (UrlsMixin), does it need multiple pages with navigation-links (NavigationMixin). From 7a90f81db5a839be08ee7cfccafc179f29ce568a Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Mon, 17 Jan 2022 00:13:56 +0100 Subject: [PATCH 03/18] add links --- docs/extend/how_to_plugin.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index b76c76f..9fd84fc 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -7,21 +7,21 @@ A short introductory guide for plugin beginners. ### Should it be a plugin? First of all figure out what your plugin / code should do. -If you want to change how InvenTree base mechanics and business logic work, a plugin will not be sufficient. Maybe fork the project or better start a discussion on GitHub. There might be an easier / established way to do what you want. +If you want to change how InvenTree base mechanics and business logic work, a plugin will not be sufficient. Maybe fork the project or better [start a discussion](https://github.com/inventree/InvenTree/discussions) on GitHub. There might be an easier / established way to do what you want. If you want to remove parts of the user interface -> remove the permissions for those objects / actions and the users will not see them. If you add a lot of code (over ~1000 LOC) maybe split it into multiple plugins to make upgrading and testing simpler. ### It will be a plugin! Pick your building blocks -Great. Now please read the plugin documentation to get an overview of the architecture. It is rather short as a the (builtin) mixins come with extensive docstrings. +Great. Now please read the [plugin documentation](./plugins.md) to get an overview of the architecture. It is rather short as a the (builtin) mixins come with extensive docstrings. Consider the usecase for your plugin and define the exact function of the plugin, maybe wrtie it down in a short readme. Then pick the mixins you need (they help reduce custom code and keep the system reliable if internal calls change). -- Is it just a simple REST-endpoint that runs a function (ActionMixin) or a parser for a custom barcode format (BarcodeMixin)? -- How does the user interact with the plugin? Is it a UI separate from the main InvenTree UI (UrlsMixin), does it need multiple pages with navigation-links (NavigationMixin). -- Will it make calls to external APIs (APICallMixin helps there)? -- Do you need to run in the background (ScheduleMixin) or when things in InvenTree change (EventMixin)? -- Does the plugin need configuration that should be user changeable (SettingsMixin) or static (just use a yaml in the config dir)? -- You want to receive webhooks? Do not code your own untested function – use the WebhookEndpoint model as a base and override the perform_action method. -- Do you need the full power of Django with custom models and all the complexity that comes with that – welcome to the danger zone and AppMixin. +- Is it just a simple REST-endpoint that runs a function ([ActionMixin](./plugins/action.md)) or a parser for a custom barcode format ([BarcodeMixin](./plugins/barcode.md))? +- How does the user interact with the plugin? Is it a UI separate from the main InvenTree UI ([UrlsMixin](./plugins/urls.md)), does it need multiple pages with navigation-links ([NavigationMixin](./plugins/navigation.md)). +- Will it make calls to external APIs ([APICallMixin](./plugins/api.md) helps there)? +- Do you need to run in the background ([ScheduleMixin](./plugins/schedule.md)) or when things in InvenTree change ([EventMixin](./plugins/event.md))? +- Does the plugin need configuration that should be user changeable ([SettingsMixin](./plugins/settings.md)) or static (just use a yaml in the config dir)? +- You want to receive webhooks? Do not code your own untested function, use the WebhookEndpoint model as a base and override the perform_action method. +- Do you need the full power of Django with custom models and all the complexity that comes with that – welcome to the danger zone and [AppMixin](./plugins/app.md). The plugin will be treated as a app by django and can maybe rack the whole instance. From b7519ccb34dfa8cb94b373598fbc29efa1b18f8a Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Mon, 17 Jan 2022 00:21:46 +0100 Subject: [PATCH 04/18] smaller section --- docs/extend/how_to_plugin.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index 9fd84fc..d2f1892 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -13,9 +13,10 @@ If you want to remove parts of the user interface -> remove the permissions for If you add a lot of code (over ~1000 LOC) maybe split it into multiple plugins to make upgrading and testing simpler. -### It will be a plugin! Pick your building blocks +### It will be a plugin! Great. Now please read the [plugin documentation](./plugins.md) to get an overview of the architecture. It is rather short as a the (builtin) mixins come with extensive docstrings. +### Pick your building blocks Consider the usecase for your plugin and define the exact function of the plugin, maybe wrtie it down in a short readme. Then pick the mixins you need (they help reduce custom code and keep the system reliable if internal calls change). - Is it just a simple REST-endpoint that runs a function ([ActionMixin](./plugins/action.md)) or a parser for a custom barcode format ([BarcodeMixin](./plugins/barcode.md))? From acbb238fa8b0ea5f99ce475fda89bab1d52cc964 Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Mon, 17 Jan 2022 01:41:31 +0100 Subject: [PATCH 05/18] add guidelines --- docs/extend/how_to_plugin.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index d2f1892..2531553 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -26,3 +26,19 @@ Consider the usecase for your plugin and define the exact function of the plugin - Does the plugin need configuration that should be user changeable ([SettingsMixin](./plugins/settings.md)) or static (just use a yaml in the config dir)? - You want to receive webhooks? Do not code your own untested function, use the WebhookEndpoint model as a base and override the perform_action method. - Do you need the full power of Django with custom models and all the complexity that comes with that – welcome to the danger zone and [AppMixin](./plugins/app.md). The plugin will be treated as a app by django and can maybe rack the whole instance. + +### Development guidelines +If you want to make your life easier, try to follow these guidelines; break where it makes sense for your use case. +- keep it simple - more that 1000 LOC are normally to much for a plugin +- use mixins where possible - we try to keep coverage high for them so they are not likely to break +- do not use internal functions - if a functions name starts with `_` it is internal and might change at any time +- keep you imports clean - the APIs for plugins and mixins are young and evolving. Use +``` +from plugin import IntegrationPluginBase, registry +from plugin.mixins import APICallMixin, SettingsMixin, ScheduleMixin, BarcodeMixin + +``` +- deliver as a package - pip is great for dependency management and pypi can serve as a transparent and reliable delivery infrastructure +- tag your GitHub repo with 'inventree' and 'inventreeplugins' to make discovery easier +- use GitHub actions to test your plugin regularly (you can [schedule actions](https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows#schedule)) against the 'latest' [docker-build]https://hub.docker.com/r/inventree/inventree of InvenTree +- if you use the AppMixin pin your plugin against the stable branch of InvenTree, your migrations might get messed up otherwise From 7c469bba105ee45ee4e4d93cf2d3e188d9e022de Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Mon, 17 Jan 2022 01:44:24 +0100 Subject: [PATCH 06/18] format fix --- docs/extend/how_to_plugin.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index 2531553..3998365 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -29,6 +29,7 @@ Consider the usecase for your plugin and define the exact function of the plugin ### Development guidelines If you want to make your life easier, try to follow these guidelines; break where it makes sense for your use case. + - keep it simple - more that 1000 LOC are normally to much for a plugin - use mixins where possible - we try to keep coverage high for them so they are not likely to break - do not use internal functions - if a functions name starts with `_` it is internal and might change at any time From e3d23540693d0f3f8c490f7d1b44b78b994040a0 Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Mon, 17 Jan 2022 01:55:30 +0100 Subject: [PATCH 07/18] add info on private releases --- docs/extend/how_to_plugin.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index 3998365..0f655d5 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -40,6 +40,7 @@ from plugin.mixins import APICallMixin, SettingsMixin, ScheduleMixin, BarcodeMix ``` - deliver as a package - pip is great for dependency management and pypi can serve as a transparent and reliable delivery infrastructure +- if you need to use a private infrastructure, use the 'Releases' functions in GitHub or Gitlab. Point to the 'latest' release endpoint when installing to make sure the update function works - tag your GitHub repo with 'inventree' and 'inventreeplugins' to make discovery easier - use GitHub actions to test your plugin regularly (you can [schedule actions](https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows#schedule)) against the 'latest' [docker-build]https://hub.docker.com/r/inventree/inventree of InvenTree - if you use the AppMixin pin your plugin against the stable branch of InvenTree, your migrations might get messed up otherwise From 26daa4120ef4d278214ba0063e399bee9e7d71dd Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Mon, 17 Jan 2022 01:57:03 +0100 Subject: [PATCH 08/18] fix link --- docs/extend/how_to_plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index 0f655d5..5c2181d 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -42,5 +42,5 @@ from plugin.mixins import APICallMixin, SettingsMixin, ScheduleMixin, BarcodeMix - deliver as a package - pip is great for dependency management and pypi can serve as a transparent and reliable delivery infrastructure - if you need to use a private infrastructure, use the 'Releases' functions in GitHub or Gitlab. Point to the 'latest' release endpoint when installing to make sure the update function works - tag your GitHub repo with 'inventree' and 'inventreeplugins' to make discovery easier -- use GitHub actions to test your plugin regularly (you can [schedule actions](https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows#schedule)) against the 'latest' [docker-build]https://hub.docker.com/r/inventree/inventree of InvenTree +- use GitHub actions to test your plugin regularly (you can [schedule actions](https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows#schedule)) against the 'latest' [docker-build](https://hub.docker.com/r/inventree/inventree) of InvenTree - if you use the AppMixin pin your plugin against the stable branch of InvenTree, your migrations might get messed up otherwise From d6d76398b1c566ff6e4a50b17f85085db451c71e Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Tue, 18 Jan 2022 23:57:47 +0100 Subject: [PATCH 09/18] metadata --- docs/extend/how_to_plugin.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index 5c2181d..3811dc4 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -27,6 +27,9 @@ Consider the usecase for your plugin and define the exact function of the plugin - You want to receive webhooks? Do not code your own untested function, use the WebhookEndpoint model as a base and override the perform_action method. - Do you need the full power of Django with custom models and all the complexity that comes with that – welcome to the danger zone and [AppMixin](./plugins/app.md). The plugin will be treated as a app by django and can maybe rack the whole instance. +### Define the metadata +Do not forget to declare the metadata for your plugin, it will be used in the setttings. + ### Development guidelines If you want to make your life easier, try to follow these guidelines; break where it makes sense for your use case. From ea0016ba2f58f9e0ebd521ce1798b332f2e6deb2 Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Tue, 18 Jan 2022 23:58:06 +0100 Subject: [PATCH 10/18] fix spacing --- docs/extend/how_to_plugin.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index 3811dc4..5263a71 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -40,7 +40,6 @@ If you want to make your life easier, try to follow these guidelines; break wher ``` from plugin import IntegrationPluginBase, registry from plugin.mixins import APICallMixin, SettingsMixin, ScheduleMixin, BarcodeMixin - ``` - deliver as a package - pip is great for dependency management and pypi can serve as a transparent and reliable delivery infrastructure - if you need to use a private infrastructure, use the 'Releases' functions in GitHub or Gitlab. Point to the 'latest' release endpoint when installing to make sure the update function works From 20d4bea8b46d7d68ed4e34b5c3440485a6ecda7c Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Wed, 19 Jan 2022 00:01:01 +0100 Subject: [PATCH 11/18] make metadata clearer --- docs/extend/how_to_plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index 5263a71..df97539 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -28,7 +28,7 @@ Consider the usecase for your plugin and define the exact function of the plugin - Do you need the full power of Django with custom models and all the complexity that comes with that – welcome to the danger zone and [AppMixin](./plugins/app.md). The plugin will be treated as a app by django and can maybe rack the whole instance. ### Define the metadata -Do not forget to declare the metadata for your plugin, it will be used in the setttings. +Do not forget to [declare the metadata](./plugins.md#plugin-options) for your plugin, those will be used in the settings. At least provide a weblink so users can file issues / reach you. ### Development guidelines If you want to make your life easier, try to follow these guidelines; break where it makes sense for your use case. From 11ac217f7d4397a909be66503a2aa7098e4aee74 Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Wed, 19 Jan 2022 00:16:53 +0100 Subject: [PATCH 12/18] add sample code --- docs/extend/how_to_plugin.md | 39 ++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index df97539..2228746 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -46,3 +46,42 @@ from plugin.mixins import APICallMixin, SettingsMixin, ScheduleMixin, BarcodeMix - tag your GitHub repo with 'inventree' and 'inventreeplugins' to make discovery easier - use GitHub actions to test your plugin regularly (you can [schedule actions](https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows#schedule)) against the 'latest' [docker-build](https://hub.docker.com/r/inventree/inventree) of InvenTree - if you use the AppMixin pin your plugin against the stable branch of InvenTree, your migrations might get messed up otherwise + +### A simple example +This example adds a new action under `/api/action/sample` using the ActionMixin. +``` python +# -*- coding: utf-8 -*- +"""sample implementation for ActionPlugin""" +from plugin import IntegrationPluginBase +from plugin.mixins import ActionMixin + + +class SampleActionPlugin(ActionMixin, IntegrationPluginBase): + """ + Use docstrings for everything... pls + """ + + PLUGIN_NAME = "SampleActionPlugin" + ACTION_NAME = "sample" + + # metadata + AUTHOR = "Sample Author" + DESCRIPTION = "A very basic plugin with one mixin" + PUBLISH_DATE = "22.02.2222" + VERSION = "1.2.3" # We recommend semver and increase the major version with each new major release of InvenTree + WEBSITE = "https://example.com/" + LICENSE = "MIT" # use what you want - OSI approved is ♥ + + # Everything form here is for the ActionMixin + def perform_action(self): + print("Action plugin in action!") + + def get_info(self): + return { + "user": self.user.username, + "hello": "world", + } + + def get_result(self): + return True # This is returned to the client +``` From 85d3c6e8a91b9bfa62e7ce82ba7391c0e412c0ea Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Wed, 19 Jan 2022 00:22:22 +0100 Subject: [PATCH 13/18] add footnotes --- docs/extend/how_to_plugin.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index 2228746..74d413c 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -50,15 +50,15 @@ from plugin.mixins import APICallMixin, SettingsMixin, ScheduleMixin, BarcodeMix ### A simple example This example adds a new action under `/api/action/sample` using the ActionMixin. ``` python -# -*- coding: utf-8 -*- -"""sample implementation for ActionPlugin""" +# -*- coding: utf-8 -*- # (1) +"""sample implementation for ActionPlugin""" # (2) from plugin import IntegrationPluginBase from plugin.mixins import ActionMixin class SampleActionPlugin(ActionMixin, IntegrationPluginBase): """ - Use docstrings for everything... pls + Use docstrings for everything... pls # (2) """ PLUGIN_NAME = "SampleActionPlugin" @@ -85,3 +85,7 @@ class SampleActionPlugin(ActionMixin, IntegrationPluginBase): def get_result(self): return True # This is returned to the client ``` + + +1. It is recommended to put each plugin into it's own file, this is not required +2. Please document you functions and classes - following PEP8 or black is recommended From 463cb72c4f5a4a9a4c963e773ab70a1c380fb572 Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Wed, 19 Jan 2022 00:26:47 +0100 Subject: [PATCH 14/18] add title --- docs/extend/how_to_plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index 74d413c..66e2a8d 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -49,7 +49,7 @@ from plugin.mixins import APICallMixin, SettingsMixin, ScheduleMixin, BarcodeMix ### A simple example This example adds a new action under `/api/action/sample` using the ActionMixin. -``` python +``` python title="sampleactionplugin.py" # -*- coding: utf-8 -*- # (1) """sample implementation for ActionPlugin""" # (2) from plugin import IntegrationPluginBase From f69435db7c62a840057cc13351a5335ec7df622e Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Wed, 19 Jan 2022 00:39:49 +0100 Subject: [PATCH 15/18] fix format --- docs/extend/how_to_plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index 66e2a8d..c57b908 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -49,7 +49,7 @@ from plugin.mixins import APICallMixin, SettingsMixin, ScheduleMixin, BarcodeMix ### A simple example This example adds a new action under `/api/action/sample` using the ActionMixin. -``` python title="sampleactionplugin.py" +``` py title="sampleactionplugin.py" # -*- coding: utf-8 -*- # (1) """sample implementation for ActionPlugin""" # (2) from plugin import IntegrationPluginBase From f847108af63821f8ee68fc44024c932325081c19 Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Wed, 19 Jan 2022 00:43:51 +0100 Subject: [PATCH 16/18] remove title --- docs/extend/how_to_plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index c57b908..a991acb 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -49,7 +49,7 @@ from plugin.mixins import APICallMixin, SettingsMixin, ScheduleMixin, BarcodeMix ### A simple example This example adds a new action under `/api/action/sample` using the ActionMixin. -``` py title="sampleactionplugin.py" +``` py # -*- coding: utf-8 -*- # (1) """sample implementation for ActionPlugin""" # (2) from plugin import IntegrationPluginBase From 3beb1f0734f8e389123a6c846041c9d4febccf16 Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Wed, 19 Jan 2022 00:47:43 +0100 Subject: [PATCH 17/18] move annotation markers --- docs/extend/how_to_plugin.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index a991acb..86249a9 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -50,16 +50,19 @@ from plugin.mixins import APICallMixin, SettingsMixin, ScheduleMixin, BarcodeMix ### A simple example This example adds a new action under `/api/action/sample` using the ActionMixin. ``` py -# -*- coding: utf-8 -*- # (1) -"""sample implementation for ActionPlugin""" # (2) +# -*- coding: utf-8 -*- +# (1) +"""sample implementation for ActionPlugin""" +# (2) from plugin import IntegrationPluginBase from plugin.mixins import ActionMixin class SampleActionPlugin(ActionMixin, IntegrationPluginBase): """ - Use docstrings for everything... pls # (2) + Use docstrings for everything... pls """ + # (2) PLUGIN_NAME = "SampleActionPlugin" ACTION_NAME = "sample" From b8ae520f04a6a6009cc30446342a97f311d0f0ad Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Wed, 19 Jan 2022 00:58:50 +0100 Subject: [PATCH 18/18] remove annotations, we would need to sponsor to use it --- docs/extend/how_to_plugin.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index 86249a9..d2a9fc8 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -51,9 +51,7 @@ from plugin.mixins import APICallMixin, SettingsMixin, ScheduleMixin, BarcodeMix This example adds a new action under `/api/action/sample` using the ActionMixin. ``` py # -*- coding: utf-8 -*- -# (1) """sample implementation for ActionPlugin""" -# (2) from plugin import IntegrationPluginBase from plugin.mixins import ActionMixin @@ -62,7 +60,6 @@ class SampleActionPlugin(ActionMixin, IntegrationPluginBase): """ Use docstrings for everything... pls """ - # (2) PLUGIN_NAME = "SampleActionPlugin" ACTION_NAME = "sample" @@ -88,7 +85,3 @@ class SampleActionPlugin(ActionMixin, IntegrationPluginBase): def get_result(self): return True # This is returned to the client ``` - - -1. It is recommended to put each plugin into it's own file, this is not required -2. Please document you functions and classes - following PEP8 or black is recommended