Adding upstream version 2.1.2~dev0+20240219.upstream/2.1.2_dev0+20240219upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

3 files changed, 345 insertions, 0 deletions

diff --git a/docs/source/devguide/how-to/curl-jsonrpc.md b/docs/source/devguide/how-to/curl-jsonrpc.md
new file mode 100644
index 0000000..9bb559d
--- /dev/null
+++ b/docs/source/devguide/how-to/curl-jsonrpc.md
@@ -0,0 +1,162 @@
+# How to connect to JSON-RPC with curl
+
+Before continuing make sure `deluge-web` or Web UI plugin is running.
+
+## Create a curl configuration file
+
+To save a lot of typing and to keep the curl command short we shall create
+a `curl.cfg` files and put the following contents in it:
+
+    request = "POST"
+    compressed
+    cookie = "cookie_deluge.txt"
+    cookie-jar = "cookie_deluge.txt"
+    header = "Content-Type: application/json"
+    header = "Accept: application/json"
+    url = "http://localhost:8112/json"
+    write-out = "\n"
+
+To pretty-print the JSON result see: <https://stackoverflow.com/q/352098/175584>
+
+## Log in to Web UI
+
+Log in to the Web UI and get session cookie:
+
+    curl -d '{"method": "auth.login", "params": ["deluge"], "id": 1}' -K curl.cfg
+
+Result is `true` to signify that login was successful:
+
+    {
+        "error": null,
+        "id": 1,
+        "result": true
+    }
+
+Check the contents of the cookie file to verify session ID created.
+
+    cat cookie_deluge.txt
+    # Netscape HTTP Cookie File
+    # http://curl.haxx.se/docs/http-cookies.html
+    # This file was generated by libcurl! Edit at your own risk.
+
+    localhost	FALSE	/json	FALSE	1540061203	_session_id	<session_id>
+
+## Check connected to deluged
+
+Use the `web.connected` method to get a boolean response if the Web UI is
+connected to a deluged host:
+
+    curl -d '{"method": "web.connected", "params": [], "id": 1}' -K curl.cfg
+
+Result is `false` because Web UI is not yet connected to the daemon:
+
+    {
+        "error": null,
+        "id": 1,
+        "result": false
+    }
+
+## Get list of deluged hosts
+
+Use the `web.get_hosts` method:
+
+    curl -d '{"method": "web.get_hosts", "params": [], "id": 1}' -K curl.cfg
+
+The result contains the `<hostID>` for using in request `params` field.
+
+    {
+        "error": null,
+        "id": 1,
+        "result": [
+            [
+                "<hostID>",
+                "127.0.0.1",
+                58846,
+                "localclient"
+            ]
+        ]
+    }
+
+## Get the deluged host status
+
+    curl -d '{"method": "web.get_host_status", \
+    "params": ["<hostID>"], "id": 1}' -K curl.cfg
+
+The result shows the version and status; _online_, _offline_ or _connected_.
+
+    {
+        "error": null,
+        "id": 1,
+        "result": [
+            "<hostID>",
+            "Online",
+            "2.0.0"
+        ]
+    }
+
+## Connect to deluged host
+
+To connect to deluged with `<hostID>`:
+
+    curl -d '{"method": "web.connect", \
+    "params": ["<hostID>"], "id": 1}' -K curl.cfg
+
+The result contains the full list of available host methods:
+
+    {
+        "error": null,
+        "id": 1,
+        "result": [
+            "core.add_torrent_url",
+            ...
+            "core.upload_plugin"
+        ]
+    }
+
+## Disconnect from host
+
+    curl -d '{"method": "web.disconnect", "params": [], "id": 1}' -K curl.cfg
+
+A successful result:
+
+    {
+        "error": null,
+        "id": 1,
+        "result": "Connection was closed cleanly."
+    }
+
+## Add a torrent
+
+    curl -d '{"method": "web.add_torrents", "params": \
+    [[{"path":"/tmp/ubuntu-12.04.1-desktop-amd64.iso.torrent", \
+    "options":null}]], "id": 1}' -K curl.cfg
+
+## Add a magnet URI
+
+    curl-d '{"method": "core.add_torrent_magnet", \
+    "params": ["<magnet_uri>", {}], "id": 1}' -K curl.cfg
+
+## Get list of files for a torrent
+
+    curl -d '{"method": "web.get_torrent_files", \
+    "params": ["<torrentid>"], "id": 1}' -K curl.cfg
+
+## Set a core config option
+
+    curl -d '{"method": "core.set_config", \
+    "params":[{"max_upload_slots_global":"200"}], "id": 1}' -K curl.cfg
+
+    {"error": null, "result": null, "id": 1}
+
+## Useful curl configuration options
+
+For full list of options see man page `man curl` or help `curl --help`:
+
+    --cookie (-b) # Load cookie file with session id
+    --cookie-jar (-c) # Save cookie file with session id
+    --compressed # responses are gzipped
+    --include (-i) # Include the HTTP header in output (optional)
+    --header (-H) # HTTP header
+    --request (-X) # custom request method
+    --data (-d) # data to send in POST request '{"method": "", "params": [], "id": ""}'
+    --insecure (-k) # use with self-signed certs https
diff --git a/docs/source/devguide/how-to/index.md b/docs/source/devguide/how-to/index.md
new file mode 100644
index 0000000..e63c771
--- /dev/null
+++ b/docs/source/devguide/how-to/index.md
@@ -0,0 +1,23 @@
+# How-to guides
+
+A collection of guides for specific issues or to cover more detail than the tutorials.
+
+## Web JSON-RPC
+
+```{toctree}
+:titlesonly:
+
+Connect to JSON-RPC using curl <curl-jsonrpc>
+```
+
+## Plugins
+
+<!--
+- [Create a plugin](create-plugin.md)
+-->
+
+```{toctree}
+:titlesonly:
+
+Update 1.3 plugin for 2.0 <update-1.3-plugin>
+```
diff --git a/docs/source/devguide/how-to/update-1.3-plugin.md b/docs/source/devguide/how-to/update-1.3-plugin.md
new file mode 100644
index 0000000..9ce6ae1
--- /dev/null
+++ b/docs/source/devguide/how-to/update-1.3-plugin.md
@@ -0,0 +1,160 @@
+# How to update a Deluge 1.3 plugin for 2.0
+
+With the new code in Deluge 2.0 there are changes that require authors of
+existing plugins to update their plugins to work on Deluge 2.0.
+
+The main changes are with Python 3 support and the new GTK3 user interface with
+the dropping of GTK2. However it is still possible for a 1.3 plugin to be made
+compatible with 2.0 and this guide aims to helps with that process.
+
+## Python
+
+### Python version matching
+
+Ensure your code is Python >=3.6 compatible.
+
+In `1.3-stable` the plugins that were built with a specific version of Python
+would only be loaded if the system Python also matched.
+
+This has change in Deluge 2.0 and it will load any Python version of plugin
+eggs so compatibility is essential for end-users not to encounter issues.
+
+## GTK 3 addition
+
+In order to support both Deluge 1.3 and 2.0 all existing plugin GTK UI files
+must be copied and then converted to contain only GTK3 code with the old files
+still using PyGTK e.g.:
+
+    cp gtkui.py gtk3ui.py
+
+### Convert from libglade to GtkBuilder
+
+With PyGTK there were two library options for creating the user interface from
+XML files by default Deluge plugins used libglade but that has been deprecated
+and removed in GTK3. So the libglade `.glade` files will need converted to
+GtkBuilder `.ui` files and the Python code updated.
+
+See the official [Migrating to GtkBuilder][migrate-gtkbuilder] document for more details.
+
+#### GtkBuilder conversion script
+
+Install the `gtk-builder-convert` converter on Ubuntu with:
+
+    sudo apt install libgtk2.0-dev
+
+To convert your GTK run it like so:
+
+    gtk-builder-convert data/config.glade data/config.ui
+
+#### Glade UI designer for GTK2
+
+The above conversion can also be done in Glade UI designer (version <=3.8).
+
+In the preferences select `GtkBuilder` as the project file format. Ensure
+that the minimum Gtk version is set to 2.24 and fix any deprecated widgets.
+
+The updated file should be saved with file extension `.ui`.
+
+#### Python code changes
+
+The code needs to replace `gtk.glade` references with `gtk.Builder` and the
+first step is updating how the files are loaded:
+
+```diff
+- glade = gtk.glade.XML(get_resource("config.glade"))
++ builder = Gtk.Builder.new_from_file(get_resource("config.ui"))
+```
+
+Replace signals method:
+
+```diff
+- glade.signal_autoconnect(self)
++ builder.connect_signals(self)
+```
+
+Replace `get_widget` with `get_object`:
+
+```diff
+- glade.get_widget
++ builder.get_object
+```
+
+Check for any remaining `glade` methods and replace with the `builder` equivalents.
+
+### Migrate XML files to GTK3
+
+If you open and save the file it will update with the new requirement header:
+
+    <!-- Generated with glade 3.18.3 -->
+    <interface>
+      <requires lib="gtk+" version="3.10"/>
+
+You can fix deprecated widgets but keep the minimum GTK version to <= 3.10 for
+desktop compatibility.
+
+An example of migrating a Deluge plugin to GtkBuilder: [AutoAdd GtkBuilder]
+
+### Gtk import rename
+
+Move from PyGTK to GTK3 using Python bindings.
+
+<https://pygobject.readthedocs.io/en/latest/guide/porting.html>
+
+    wget https://gitlab.gnome.org/GNOME/pygobject/raw/master/tools/pygi-convert.sh
+    cp gtkui.py gtk3ui.py
+    sh pygi-convert.sh gtk3ui.py
+
+```diff
+-import gtk
++from gi.repository import Gtk
+```
+
+```diff
+- self.builder = gtk.Builder()
++ self.builder = Gtk.Builder()
+```
+
+### Deluge GTK3
+
+#### Imports
+
+Imports will need renamed from `deluge.ui.gtkui` to `deluge.ui.gtk3`.
+
+There is also a new PluginBase for Gtk3 UI:
+
+```diff
+-from deluge.plugins.pluginbase import GtkPluginBase
++from deluge.plugins.pluginbase import Gtk3PluginBase
+-class GtkUI(GtkPluginBase):
++class Gtk3UI(Gtk3PluginBase):
+```
+
+#### Entry points
+
+To enable the GTK3 UI to find the plugin the entry points requires updating too.
+
+In the plugin `__init__.py` file add a new `Gtk3UIPlugin` class:
+
+```
+class Gtk3UIPlugin(PluginInitBase):
+    def __init__(self, plugin_name):
+        from .gtk3ui import Gtk3UI as _plugin_cls
+        self._plugin_cls = _plugin_cls
+        super(Gtk3UIPlugin, self).__init__(plugin_name)
+```
+
+A new entry for GTK3 UI can then be added to `setup.py`:
+
+```diff
+     [deluge.plugin.gtkui]
+     %s = %s:GtkUIPlugin
++    [deluge.plugin.gtk3ui]
++    %s = deluge_%s:Gtk3UIPlugin
+     [deluge.plugin.webui]
+     %s = %s:WebUIPlugin
+-    """ % ((__plugin_name__, __plugin_name__.lower())*3)
++    """ % ((__plugin_name__, __plugin_name__.lower())*4)
+```
+
+[migrate-gtkbuilder]: https://developer.gnome.org/gtk2/stable/gtk-migrating-GtkBuilder.html
+[autoadd gtkbuilder]: https://git.deluge-torrent.org/deluge/commit/?h=develop&id=510a8b50b213cab804d693a5f122f9c0d9dd1fb3