[tests] pass all PwbTestCase.execute() parameters to utils.execute_pwb()

also make parameters of utils.execute and utils.execute_pwb keyword only
except command/args. Make PwbTestCase._execute() public and add it to the
documentation.

Change-Id: Ibc3ecbdca9abb501b4c8eaf2d58235932a1494fa
---
M tests/aspects.py
M tests/i18n_tests.py
M tests/script_tests.py
M tests/utils.py
4 files changed, 35 insertions(+), 12 deletions(-)

diff --git a/tests/aspects.py b/tests/aspects.py
index efd5616..157210c 100644
--- a/tests/aspects.py
+++ b/tests/aspects.py
@@ -1286,8 +1286,7 @@
 
 class PwbTestCase(TestCase):
 
-    """
-    Test cases use pwb.py to invoke scripts.
+    """Test cases use :mod:`pwb` to invoke scripts.
 
     Test cases which use pwb typically also access a site, and use the network.
     Even during initialisation, scripts may call pywikibot.handle_args, which
@@ -1320,12 +1319,19 @@
         if self.orig_pywikibot_dir:
             os.environ['PYWIKIBOT_DIR'] = self.orig_pywikibot_dir
 
-    def _execute(self, args, data_in=None, timeout=None):
+    def execute(self, args: list[str], **kwargs):
+        """Run :func:`tests.utils.execute_pwb` with default site.
+
+        .. versionchanged:: 9.1
+           pass all arguments to :func:`tests.utils.execute_pwb`; make
+           this method public.
+
+        :param args: :mod:`pwb` warapper script arguments
+        :param kwargs: keyword arguments of :func:`tests.utils.execute_pwb`
+        """
         site = self.get_site()
-
-        args += ['-family:' + site.family.name, '-lang:' + site.code]
-
-        return execute_pwb(args, data_in, timeout)
+        args.append(f'-site:{site.sitename}')
+        return execute_pwb(args, **kwargs)
 
 
 class RecentChangesTestCase(WikimediaDefaultSiteTestCase):
diff --git a/tests/i18n_tests.py b/tests/i18n_tests.py
index 7f4853a..c57a196 100755
--- a/tests/i18n_tests.py
+++ b/tests/i18n_tests.py
@@ -312,8 +312,8 @@
     def test_pagegen_i18n_input(self):
         """Test i18n.input fallback via pwb."""
         expect = i18n.twtranslate(self.alt_code, self.message, fallback=False)
-        result = self._execute(args=['listpages', '-cat'],
-                               data_in='non-existant-category\r\n')
+        result = self.execute(args=['listpages', '-cat'],
+                              data_in='non-existant-category\r\n')
         self.assertIn(expect, result['stderr'])
 
 
diff --git a/tests/script_tests.py b/tests/script_tests.py
index 60dc88b..665479a 100755
--- a/tests/script_tests.py
+++ b/tests/script_tests.py
@@ -224,7 +224,7 @@
                     test_overrides['pywikibot.Site'] = 'lambda *a, **k: None'
 
                 # run the script
-                result = execute_pwb(cmd, data_in, timeout=timeout,
+                result = execute_pwb(cmd, data_in=data_in, timeout=timeout,
                                      overrides=test_overrides)
 
                 err_result = result['stderr']
diff --git a/tests/utils.py b/tests/utils.py
index 9465863..1458c09 100644
--- a/tests/utils.py
+++ b/tests/utils.py
@@ -466,11 +466,13 @@
         """Ignore password changes."""
 
 
-def execute(command: list[str], data_in=None, timeout=None):
+def execute(command: list[str], *, data_in=None, timeout=None):
     """Execute a command and capture outputs.
 
     .. versionchanged:: 8.2
        *error* parameter was removed.
+    .. versionchanged:: 9.1
+       parameters except *command* are keyword only.
 
     :param command: executable to run and arguments to use
     """
@@ -512,7 +514,7 @@
             'stderr': stderr_data.decode(config.console_encoding)}
 
 
-def execute_pwb(args: list[str],
+def execute_pwb(args: list[str], *,
                 data_in: Sequence[str] | None = None,
                 timeout: int | float | None = None,
                 overrides: dict[str, str] | None = None) -> dict[str, Any]:
@@ -520,6 +522,8 @@
 
     .. versionchanged:: 8.2
        the *error* parameter was removed.
+    .. versionchanged:: 9.1
+       parameters except *args* are keyword only.
 
     :param args: list of arguments for pwb.py
     :param overrides: mapping of pywikibot symbols to test replacements

