core: add generator and Python stub file for WeeChat API (issue #1377)

.github/workflows/ci.yml

@@ -41,6 +41,7 @@ jobs:
     - name: Check Python scripts
       run: |
         pylint --additional-builtins=_ doc/docgen.py
+        pylint doc/python_stub.py
         pylint tests/scripts/python/testapigen.py
         pylint tests/scripts/python/testapi.py
         pylint tests/scripts/python/unparse.py

ChangeLog.adoc

@@ -35,6 +35,7 @@ New features::
   * fifo: change default value of option fifo.file.path to "${weechat_runtime_dir}/weechat_fifo_${info:pid}"
   * irc: evaluate server options "sasl_key" and "ssl_cert"
   * logger: change default value of option logger.file.path to "${weechat_data_dir}/logs"
+  * python: add stub for WeeChat API (issue #1377)
   * relay: evaluate option relay.network.ssl_cert_key, change default value to "${weechat_config_dir}/ssl/relay.pem"
   * script: change default value of option script.scripts.path to "${weechat_cache_dir}/script"
   * trigger: add variables "${tg_shell_argc}" and "${tg_shell_argvN}" in command trigger evaluated strings (issue #1624)

doc/python_stub.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+#
+# Copyright (C) 2019 Simmo Saan <simmo.saan@gmail.com>
+# Copyright (C) 2021 Sébastien Helleu <flashcode@flashtux.org>
+#
+# This program 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.
+#
+# This program 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 this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+"""
+Generate Python stub: API constants and functions, with type annotations.
+
+This script requires Python 3.6+.
+"""
+
+from pathlib import Path
+from typing import TextIO
+
+import re
+
+DOC_DIR = Path(__file__).resolve().parent / 'en'
+
+STUB_HEADER = """\
+#
+# WeeChat Python stub file, auto-generated by python_stub.py.
+# DO NOT EDIT BY HAND!
+#
+
+from typing import Dict
+
+"""
+
+CONSTANT_RE = r"""\
+  `(?P<constant>WEECHAT_[A-Z0-9_]+)` \((?P<type>(string|integer))\)(?: \+)?\
+"""
+
+FUNCTION_RE = r"""\
+\[source,python\]
+----
+# prototype
+def (?P<function>\w+)(?P<args>[^)]*)(?P<return>\) -> [^:]+:) \.\.\.\
+"""
+
+
+def write_stub_constants(stub_file: TextIO) -> None:
+    """
+    Write constants in the stub file, extracted from the Scripting guide.
+    """
+    types = {
+        'integer': 'int',
+        'string': 'str',
+    }
+    constant_pattern = re.compile(CONSTANT_RE)
+    with open(DOC_DIR / 'weechat_scripting.en.adoc') as scripting_file:
+        scripting = scripting_file.read()
+        for match in constant_pattern.finditer(scripting):
+            stub_file.write(f'{match["constant"]}: {types[match["type"]]}\n')
+
+
+def write_stub_functions(stub_file: TextIO) -> None:
+    """
+    Write function prototypes in the stub file, extracted from the
+    Plugin API reference.
+    """
+    function_pattern = re.compile(FUNCTION_RE, re.DOTALL)
+    with open(DOC_DIR / 'weechat_plugin_api.en.adoc') as api_doc_file:
+        api_doc = api_doc_file.read()
+        for match in function_pattern.finditer(api_doc):
+            url = f'https://weechat.org/doc/api#_{match["function"]}'
+            stub_file.write(f"""\n
+def {match["function"]}{match["args"]}{match["return"]}
+    \"""`{match["function"]} in WeeChat plugin API reference <{url}>`_\"""
+    ...
+""")
+
+
+def stub_api() -> None:
+    """Write Python stub file."""
+    with open('weechat.pyi', 'w') as stub_file:
+        stub_file.write(STUB_HEADER)
+        write_stub_constants(stub_file)
+        write_stub_functions(stub_file)
+
+
+if __name__ == '__main__':
+    stub_api()