Merge pull request smarthomeNG#970 from Morg42/githubplugin

githubplugin: install and remove plugins from foreign GitHub repos

githubplugin/gperror.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+# vim: set encoding=utf-8 tabstop=4 softtabstop=4 shiftwidth=4 expandtab
+#########################################################################
+#  Copyright 2024-      Sebastian Helms           Morg @ knx-user-forum
+#########################################################################
+#  This file is part of SmartHomeNG.
+#  https://www.smarthomeNG.de
+#  https://knx-user-forum.de/forum/supportforen/smarthome-py
+#
+#  Sample plugin for new plugins to run with SmartHomeNG version 1.10
+#  and up.
+#
+#  SmartHomeNG is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  SmartHomeNG is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with SmartHomeNG. If not, see <http://www.gnu.org/licenses/>.
+#
+#########################################################################
+
+
+class GPError(Exception):
+    """ GithubPlugin-Exception used to signal errors to the webif """
+    pass

githubplugin/plugin.yaml

@@ -0,0 +1,47 @@
+# Metadata for the plugin
+plugin:
+    # Global plugin attributes
+    type: system                   # plugin type (gateway, interface, protocol, system, web)
+    description:
+        de: 'Plugin zur Installation von Plugins aus fremden GitHub-Repositories'
+        en: 'Plugin to install plugins from foreign GitHub repositories'
+    maintainer: Morg42
+#    tester:                         # Who tests this plugin?
+    state: develop                  # Initial 'develop'. change to 'ready' when done with development
+    keywords: git github plugin
+#    documentation: ''              # An url to optional plugin doc - NOT the url to user_doc!!!
+#    support: https://knx-user-forum.de/forum/supportforen/smarthome-py
+
+    version: 1.0.0                  # Plugin version (must match the version specified in __init__.py)
+
+    # these min/max-versions MUST be given in quotes, or e.g. 3.10 will be interpreted as 3.1 (3.1 < 3.9 < 3.10)
+    sh_minversion: '1.10'           # minimum shNG version to use this plugin
+#    sh_maxversion: '1.11'          # maximum shNG version to use this plugin (omit if latest)
+#    py_minversion: '3.10'          # minimum Python version to use for this plugin
+#    py_maxversion: '4.25'          # maximum Python version to use for this plugin (omit if latest)
+
+    multi_instance: false           # plugin supports multi instance
+    restartable: true            # plugin supports stopping and starting again, must be implemented
+    #configuration_needed: False     # False: The plugin will be enabled by the Admin GUI without configuration
+    classname: GithubPlugin         # class containing the plugin
+
+parameters:
+    # Definition of parameters to be configured in etc/plugin.yaml (enter 'parameters: NONE', if section should be empty)
+    app_token:
+        type: str
+        default: ''
+        description:
+            de: 'App-Token zum Zugriff auf GitHub (optional)'
+            en: 'App token for accessing GitHub (optional)'
+
+
+item_attributes: NONE
+
+item_structs: NONE
+    # Definition of item-structure templates for this plugin (enter 'item_structs: NONE', if section should be empty)
+
+plugin_functions: NONE
+    # Definition of plugin functions defined by this plugin (enter 'plugin_functions: NONE', if section should be empty)
+
+logic_parameters: NONE
+    # Definition of logic parameters defined by this plugin (enter 'logic_parameters: NONE', if section should be empty)

githubplugin/requirements.txt

@@ -0,0 +1,2 @@
+GitPython
+PyGithub

githubplugin/user_doc.rst

@@ -0,0 +1,55 @@
+
+.. index:: Plugins; githubplugin
+.. index:: githubplugin
+
+
+============
+githubplugin
+============
+
+.. image:: webif/static/img/plugin_logo.png
+   :alt: plugin logo
+   :width: 300px
+   :height: 300px
+   :scale: 50 %
+   :align: left
+
+
+Beschreibung
+============
+
+Wenn man das Plugin eines anderen Autors ausprobieren oder testen möchte, muss es aus einem fremden Repository von GitHub in die eigene Installation eingebunden werden.
+
+Dieses Plugin ermöglicht es komfortabel, fremde Plugins von GitHub zu installieren und wieder zu deinstallieren. 
+
+Die Bedienung des Plugins und die Übersicht über installierte Plugins erfolgt über das Web-Interface, das über die Admin-UI von SmartHomeNG zugänglich ist.
+
+Dort können Plugins angezeigt, installiert und entfernt  sowie durch einen pull aktualisiert werden. Das Aktualisieren oder Löschen von installierten Plugins ist nur möglich, wenn deren git-Verzeichnisse keine veränderten, gelöschten oder hinzugefügten Dateien enthalten und alle neuen mögliche Commits zu GitHub hochgeladen wurden (push).
+
+Das Plugin legt im Verzeichnis `plugins` das Unterverzeichnis `priv_repos` an, in dem die heruntergeladenen Daten abgelegt werden. Für jedes Plugin werden die folgenden Dateien bzw. Verzeichnisse benötigt:
+
+- ein Repository ("git clone") in `plugins/priv_repos/<Autor>/`; dieser Ordner kann durch mehrere Plugins genutzt werden,
+- ein Ornder mit Worktree-Daten für den jeweiligen Branch in `plugins/priv_repos/<Autor>_wt_<Branch>/`,
+- eine Verknüpfung/Symlink `plugins/priv_<Name>`, die auf den Plugin-Ordner im Worktree verlinkt.
+
+Dabei ist Name ein Bezeichner, der vom Nutzer selbst festgelegt werden kann. Dieser wird dann in der Form `priv_<Name>` auch in der `etc/plugin.yaml` als Bezeichner für das Plugin verwendet.
+
+Im Status-Bereich zeigt das Web-If an, wieviele Zugriffe in der aktuellen Konfiguration pro Stunde möglich und wieviele noch verfügbar sind. Wenn die Zugriffe verbraucht sind, wird die Zeit bis zum nächsten Rücksetzzeitpunkt angezeigt und alle 10 Sekunden aktualisiert.
+
+Anforderungen
+=============
+
+Notwendige Software
+-------------------
+
+Das Plugin benötigt die Python-Pakete GitPython und PyGithub.
+
+Konfiguration
+=============
+
+Das Plugin benötigt keine Konfiguration.
+
+Ohne weiteres Zutun sind 60 Zugriffe pro Stunde möglich. Für normale Nutzer, die gelegentlich neue Plugins zum Testen oder Ausprobieren installieren, reicht das völlig aus. Wenn mehr Zugriffe benötigt werden, kann auf der Seite `GitHub App-Tokens <https://github.com/settings/tokens>` ein Token registriert und in der Plugin-Konfiguration hinterlegt werden. Damit sind bis zu 5000 Zugriffe pro Stunde möglich.
+
+Die Plugin-Parameter sind unter :doc:`/plugins_doc/config/githubplugin` beschrieben.
+