core: add configuration version, add API function config_set_version

src/plugins/python/weechat-python-api.c

@@ -869,6 +869,64 @@ API_FUNC(config_new)
     API_RETURN_STRING(result);
 }
 
+struct t_hashtable *
+weechat_python_api_config_update_cb (const void *pointer, void *data,
+                                     struct t_config_file *config_file,
+                                     int version_read,
+                                     struct t_hashtable *data_read)
+{
+    struct t_plugin_script *script;
+    void *func_argv[4];
+    char empty_arg[1] = { '\0' };
+    const char *ptr_function, *ptr_data;
+    struct t_hashtable *ret_hashtable;
+
+    script = (struct t_plugin_script *)pointer;
+    plugin_script_get_function_and_data (data, &ptr_function, &ptr_data);
+
+    if (ptr_function && ptr_function[0])
+    {
+        func_argv[0] = (ptr_data) ? (char *)ptr_data : empty_arg;
+        func_argv[1] = (char *)API_PTR2STR(config_file);
+        func_argv[2] = &version_read;
+        func_argv[3] = data_read;
+
+        ret_hashtable = weechat_python_exec (script,
+                                             WEECHAT_SCRIPT_EXEC_HASHTABLE,
+                                             ptr_function,
+                                             "ssih", func_argv);
+
+        return ret_hashtable;
+    }
+
+    return NULL;
+}
+
+API_FUNC(config_set_version)
+{
+    char *config_file, *function, *data;
+    int rc, version;
+
+    API_INIT_FUNC(1, "config_set_version", API_RETURN_INT(0));
+    config_file = NULL;
+    version = 0;
+    function = NULL;
+    data = NULL;
+    if (!PyArg_ParseTuple (args, "siss", &config_file, &version, &function, &data))
+        API_WRONG_ARGS(API_RETURN_INT(0));
+
+    rc = plugin_script_api_config_set_version (
+        weechat_python_plugin,
+        python_current_script,
+        API_STR2PTR(config_file),
+        version,
+        &weechat_python_api_config_update_cb,
+        function,
+        data);
+
+    API_RETURN_INT(rc);
+}
+
 int
 weechat_python_api_config_read_cb (const void *pointer, void *data,
                                    struct t_config_file *config_file,
@@ -5315,6 +5373,7 @@ PyMethodDef weechat_python_funcs[] =
     API_DEF_FUNC(list_remove_all),
     API_DEF_FUNC(list_free),
     API_DEF_FUNC(config_new),
+    API_DEF_FUNC(config_set_version),
     API_DEF_FUNC(config_new_section),
     API_DEF_FUNC(config_search_section),
     API_DEF_FUNC(config_new_option),

src/plugins/python/weechat.pyi

@@ -481,6 +481,53 @@ def config_new(name: str, callback_reload: str, callback_reload_data: str) -> st
     ...
 
 
+def config_set_version(config_file: str, version: int, callback_update: str, callback_update_data: str) -> int:
+    """`config_set_version in WeeChat plugin API reference <https://weechat.org/doc/api/#_config_set_version>`_
+    ::
+
+        # example
+        def my_config_update_cb(data: str, config_file: str, version_read: int, data_read: Dict[str, str]) -> Dict[str, str]:
+            # return now if version is already up-to-date
+            if version_read >= 2:
+                return {}
+
+            section = data_read.get("section")
+            option = data_read.get("option")
+
+            # rename section "abc" to "def"
+            if section and not option and section == "abc":
+                data_read["section"] = "def"
+                return data_read
+
+            # limit other changes to section "test"
+            if not section or not option or section != "test":
+                return {}
+
+            # rename option "test1" to "test2"
+            if option == "test1":
+                data_read["option"] = "test2"
+                return data_read
+
+            # set value to "xxx" for option "test"
+            if option == "test":
+                data_read["value"] = "xxx"
+                return data_read
+
+            # set value to NULL for option "test_null"
+            if option == "test_null":
+                data_read["value_null"] = "1"
+                return data_read
+
+            # no changes
+            return {}
+
+        config_file = weechat.config_new("test", "", "")
+        weechat.config_set_version(config_file, 2, "my_config_update_cb", "")
+        weechat.config_read(config_file)
+    """
+    ...
+
+
 def config_new_section(config_file: str, name: str,
                        user_can_add_options: int, user_can_delete_options: int,
                        callback_read: str, callback_read_data: str,