atex 0.13__py3-none-any.whl → 0.15__py3-none-any.whl

atex/__init__.py

@@ -1,7 +1,7 @@
 """
 Ad-hoc Test EXecutor
 
-Some documentation here.
+Some intro documentation here.
 """
 
 import importlib as _importlib

atex/aggregator/__init__.py

@@ -1,3 +1,4 @@
+import abc as _abc
 import importlib as _importlib
 import pkgutil as _pkgutil
 
@@ -7,29 +8,29 @@ class Aggregator:
     TODO: generic description, not JSON-specific
     """
 
+    @_abc.abstractmethod
     def ingest(self, platform, test_name, test_results, test_files):
         """
-        Process 'test_results' (string/Path) for as results reported by a test
-        ran by Executor, along with 'test_files' as files uploaded by that test,
-        aggregating them under 'platform' (string) as 'test_name' (string).
+        Process `test_results` (string/Path) for as results reported by a test
+        ran by Executor, along with `test_files` as files uploaded by that test,
+        aggregating them under `platform` (string) as `test_name` (string).
 
-        This is DESTRUCTIVE, the input results/files are consumed in the
+        This is **destructive**, the input results/files are consumed in the
         process.
         """
-        raise NotImplementedError(f"'ingest' not implemented for {self.__class__.__name__}")
 
+    @_abc.abstractmethod
     def start(self):
         """
         Start the Aggregator instance, opening any files / allocating resources
         as necessary.
         """
-        raise NotImplementedError(f"'start' not implemented for {self.__class__.__name__}")
 
+    @_abc.abstractmethod
     def stop(self):
         """
         Stop the Aggregator instance, freeing all allocated resources.
         """
-        raise NotImplementedError(f"'stop' not implemented for {self.__class__.__name__}")
 
     def __enter__(self):
         try:

atex/aggregator/json.py

@@ -20,30 +20,31 @@ class JSONAggregator(Aggregator):
     Collects reported results in a line-JSON output file and uploaded files
     (logs) from multiple test runs under a shared directory.
 
-    Note that the aggregated JSON file *does not* use the test-based JSON format
-    described by executor/RESULTS.md - both use JSON, but are very different.
+    Note that the aggregated JSON file **does not** use the test-based JSON
+    format described by `executor/RESULTS.md` - both use JSON, but are very
+    different.
 
     This aggergated format uses a top-level array (on each line) with a fixed
     field order:
 
         platform, status, test name, subtest name, files, note
 
-    All these are strings except 'files', which is another (nested) array
+    All these are strings except `files`, which is another (nested) array
     of strings.
 
-    If 'testout' is present in an input test result, it is prepended to
-    the list of 'files'.
-    If a field is missing in the source result, it is translated to a null
+    If `testout` is present in an input test result, it is prepended to
+    the list of `files`.
+    If a field is missing in the source result, it is translated to a `null`
     value.
     """
 
     def __init__(self, target, files):
         """
-        'target' is a string/Path to a .json file for all ingested
-        results to be aggregated (written) to.
+        - `target` is a string/Path to a `.json` file for all ingested
+          results to be aggregated (written) to.
 
-        'files' is a string/Path of the top-level parent for all
-        per-platform / per-test files uploaded by tests.
+        - `files` is a string/Path of the top-level parent for all per-platform
+          / per-test files uploaded by tests.
         """
         self.lock = threading.RLock()
         self.target = Path(target)
@@ -67,7 +68,7 @@ class JSONAggregator(Aggregator):
     def _get_test_files_path(self, platform, test_name):
         """
         Return a directory path to where uploaded files should be stored
-        for a particular 'platform' and 'test_name'.
+        for a particular `platform` and `test_name`.
         """
         platform_files = self.files / platform
         platform_files.mkdir(exist_ok=True)
@@ -81,8 +82,8 @@ class JSONAggregator(Aggregator):
     @staticmethod
     def _move_test_files(test_files, target_dir):
         """
-        Move (or otherwise process) 'test_files' as directory of files uploaded
-        by the test, into the pre-computed 'target_dir' location (inside
+        Move (or otherwise process) `test_files` as directory of files uploaded
+        by the test, into the pre-computed `target_dir` location (inside
         a hierarchy of all files from all tests).
         """
         _verbatim_move(test_files, target_dir)
@@ -210,25 +211,26 @@ class GzipJSONAggregator(CompressedJSONAggregator):
         compress_files=True, compress_files_suffix=".gz", compress_files_exclude=None,
     ):
         """
-        'target' is a string/Path to a .json.gz file for all ingested
-        results to be aggregated (written) to.
+        - `target` is a string/Path to a `.json.gz` file for all ingested
+          results to be aggregated (written) to.
 
-        'files' is a string/Path of the top-level parent for all
-        per-platform / per-test files uploaded by tests.
+        - `files` is a string/Path of the top-level parent for all per-platform
+          / per-test files uploaded by tests.
 
-        'compress_level' specifies how much effort should be spent compressing,
-        (1 = fast, 9 = slow).
+        - `compress_level` specifies how much effort should be spent compressing,
+          (1 = fast, 9 = slow).
 
-        If 'compress_files' is True, compress also any files uploaded by tests.
+        - If `compress_files` is `True`, compress also any files uploaded by
+          tests.
 
-        The 'compress_files_suffix' is appended to any processed test-uploaded
-        files, and the respective 'files' results array is modified with the
-        new file names (as if the test uploaded compressed files already).
-        Set to "" (empty string) to use original file names and just compress
-        them transparently in-place.
+        - The `compress_files_suffix` is appended to any processed test-uploaded
+          files, and the respective `files` results array is modified with the
+          new file names (as if the test uploaded compressed files already).
+          Set to `""` (empty string) to use original file names and just
+          compress them transparently in-place.
 
-        'compress_files_exclude' is a tuple/list of strings (input 'files'
-        names) to skip when compressing. Their names also won't be modified.
+        - `compress_files_exclude` is a tuple/list of strings (input `files`
+          names) to skip when compressing. Their names also won't be modified.
         """
         super().__init__(target, files)
         self.level = compress_level
@@ -251,26 +253,27 @@ class LZMAJSONAggregator(CompressedJSONAggregator):
         compress_files=True, compress_files_suffix=".xz", compress_files_exclude=None,
     ):
         """
-        'target' is a string/Path to a .json.xz file for all ingested
-        results to be aggregated (written) to.
+        - `target` is a string/Path to a `.json.xz` file for all ingested
+          results to be aggregated (written) to.
 
-        'files' is a string/Path of the top-level parent for all
-        per-platform / per-test files uploaded by tests.
+        - `files` is a string/Path of the top-level parent for all per-platform
+          / per-test files uploaded by tests.
 
-        'compress_preset' specifies how much effort should be spent compressing,
-        (1 = fast, 9 = slow). Optionally ORed with lzma.PRESET_EXTREME to spend
-        even more CPU time compressing.
+        - `compress_preset` specifies how much effort should be spent
+          compressing (1 = fast, 9 = slow). Optionally ORed with
+          `lzma.PRESET_EXTREME` to spend even more CPU time compressing.
 
-        If 'compress_files' is True, compress also any files uploaded by tests.
+        - If `compress_files` is `True`, compress also any files uploaded by
+          tests.
 
-        The 'compress_files_suffix' is appended to any processed test-uploaded
-        files, and the respective 'files' results array is modified with the
-        new file names (as if the test uploaded compressed files already).
-        Set to "" (empty string) to use original file names and just compress
-        them transparently in-place.
+        - The `compress_files_suffix` is appended to any processed test-uploaded
+          files, and the respective `files` results array is modified with the
+          new file names (as if the test uploaded compressed files already).
+          Set to `""` (empty string) to use original file names and just
+          compress them transparently in-place.
 
-        'compress_files_exclude' is a tuple/list of strings (input 'files'
-        names) to skip when compressing. Their names also won't be modified.
+        - `compress_files_exclude` is a tuple/list of strings (input `files`
+          names) to skip when compressing. Their names also won't be modified.
         """
         super().__init__(target, files)
         self.preset = compress_preset

atex/cli/__init__.py

@@ -18,7 +18,7 @@ these keys:
     - function (or other callable) that will be called when invoked by the user,
       gets passed one non-kw argument: argparse-style Namespace
 
-This module-level dict must be named 'CLI_SPEC'.
+This module-level dict must be named `CLI_SPEC`.
 """
 
 import sys
@@ -27,21 +27,16 @@ import pkgutil
 import argparse
 import logging
 
-from .. import util
-
 
 def setup_logging(level):
-    if level <= util.EXTRADEBUG:
-        fmt = "%(asctime)s %(name)s: %(filename)s:%(lineno)s: %(funcName)s(): %(message)s"
-        # also print urllib3 headers
+    # also print urllib3 headers
+    if level <= logging.DEBUG:
         import http.client  # noqa: PLC0415
         http.client.HTTPConnection.debuglevel = 5
-    else:
-        fmt = "%(asctime)s %(name)s: %(message)s"
     logging.basicConfig(
         level=level,
         stream=sys.stderr,
-        format=fmt,
+        format="%(asctime)s %(name)s: %(message)s",
         datefmt="%Y-%m-%d %H:%M:%S",
     )
 
@@ -59,16 +54,16 @@ def main():
 
     log_grp = parser.add_mutually_exclusive_group()
     log_grp.add_argument(
-        "--debug", "-d", action="store_const", dest="loglevel", const=logging.DEBUG,
-        help="enable extra debugging (logging.DEBUG)",
+        "--debug", "-d", action="append", dest="debug_loggers", metavar="LOGGER", default=[],
+        help="set logging.DEBUG for a given logger name",
     )
     log_grp.add_argument(
-        "--extra-debug", "-D", action="store_const", dest="loglevel", const=util.EXTRADEBUG,
-        help="enable extra debugging (atex.util.EXTRADEBUG)",
+        "--debug-all", "-D", action="store_const", dest="loglevel", const=logging.DEBUG,
+        help="set logging.DEBUG globally",
     )
     log_grp.add_argument(
         "--quiet", "-q", action="store_const", dest="loglevel", const=logging.WARNING,
-        help="be quiet during normal operation (logging.WARNING)",
+        help="set logging.WARNING globally (suppress INFO)",
     )
     parser.set_defaults(loglevel=logging.INFO)
 
@@ -89,6 +84,9 @@ def main():
     args = parser.parse_args()
 
     setup_logging(args.loglevel)
+    # per-logger overrides
+    for logger in args.debug_loggers:
+        logging.getLogger(logger).setLevel(logging.DEBUG)
 
     try:
         mains[args._module](args)

atex/cli/testingfarm.py

@@ -169,7 +169,7 @@ def stats(args):
 
 
 def reserve(args):
-    util.info(f"Reserving {args.compose} on {args.arch} for {args.timeout} minutes")
+    print(f"Reserving {args.compose} on {args.arch} for {args.timeout} minutes")
 
     if args.hvm:
         hardware = {"virtualization": {"is-supported": True}}
@@ -192,7 +192,7 @@ def reserve(args):
         api=api,
     )
     with res as m:
-        util.info(f"Got machine: {m}")
+        print(f"Got machine: {m}")
         while True:
             try:
                 res.request.assert_alive()
@@ -223,20 +223,20 @@ def watch_pipeline(args):
     api = _get_api(args)
     request = tf.Request(id=args.request_id, api=api)
 
-    util.info(f"Waiting for {args.request_id} to be 'running'")
+    print(f"Waiting for {args.request_id} to be 'running'")
     try:
         request.wait_for_state("running")
     except tf.GoneAwayError:
-        util.info(f"Request {args.request_id} already finished")
+        print(f"Request {args.request_id} already finished")
         return
 
-    util.info("Querying pipeline.log")
+    print("Querying pipeline.log")
     try:
         for line in tf.PipelineLogStreamer(request):
             sys.stdout.write(line)
             sys.stdout.write("\n")
     except tf.GoneAwayError:
-        util.info(f"Request {args.request_id} finished, exiting")
+        print(f"Request {args.request_id} finished, exiting")
 
 
 def parse_args(parser):

atex/connection/__init__.py

@@ -1,3 +1,4 @@
+import abc as _abc
 import importlib as _importlib
 import pkgutil as _pkgutil
 
@@ -30,9 +31,9 @@ class Connection:
             ...
 
     Note that internal connection handling must be implemented as thread-aware,
-    ie. disconnect() might be called from a different thread while connect()
-    or cmd() are still running.
-    Similarly, multiple threads may run cmd() or rsync() independently.
+    ie. `disconnect()` might be called from a different thread while `connect()`
+    or `cmd()` are still running.
+    Similarly, multiple threads may run `cmd()` or `rsync()` independently.
 
     TODO: document that any exceptions raised by a Connection should be children
     of ConnectionError
@@ -52,52 +53,53 @@ class Connection:
     def __exit__(self, exc_type, exc_value, traceback):
         self.disconnect()
 
+    @_abc.abstractmethod
     def connect(self, block=True):
         """
         Establish a persistent connection to the remote.
 
-        If 'block' is True, wait for the connection to be up,
+        If `block` is True, wait for the connection to be up,
         otherwise raise BlockingIOError if the connection is still down.
         """
-        raise NotImplementedError(f"'connect' not implemented for {self.__class__.__name__}")
 
+    @_abc.abstractmethod
     def disconnect(self):
         """
         Destroy the persistent connection to the remote.
         """
-        raise NotImplementedError(f"'disconnect' not implemented for {self.__class__.__name__}")
 
+    @_abc.abstractmethod
     def cmd(self, command, *, func=_util.subprocess_run, **func_args):
         """
         Execute a single command on the remote, using subprocess-like semantics.
 
-        'command' is the command with arguments, as a tuple/list.
+        - `command` is the command with arguments, as a tuple/list.
 
-        'func' is the subprocess function to use (.run(), .Popen, etc.).
+        - `func` is the subprocess function to use (`.run()`, `.Popen()`, etc.).
 
-        'func_args' are further keyword arguments to pass to 'func'.
+        - `func_args` are further keyword arguments to pass to `func`.
         """
-        raise NotImplementedError(f"'cmd' not implemented for {self.__class__.__name__}")
 
+    @_abc.abstractmethod
     def rsync(self, *args, func=_util.subprocess_run, **func_args):
         """
-        Synchronize local/remote files/directories via 'rsync'.
+        Synchronize local/remote files/directories via `rsync`.
+
+        Pass `*args` like `rsync(1)` CLI arguments, incl. option arguments, ie.
 
-        Pass *args like rsync(1) CLI arguments, incl. option arguments, ie.
             .rsync("-vr", "local_path/", "remote:remote_path")
             .rsync("-z", "remote:remote_file" ".")
 
         To indicate remote path, use any string followed by a colon, the remote
-        name does not matter as an internally-handled '-e' option dictates all
+        name does not matter as an internally-handled `-e` option dictates all
         the connection details.
 
-        'func' is a subprocess function to use (.run(), .Popen, etc.).
+        - `func` is a subprocess function to use (`.run()`, `.Popen()`, etc.).
 
-        'func_args' are further keyword arguments to pass to 'func'.
+        - `func_args` are further keyword arguments to pass to `func`.
 
-        The remote must have rsync(1) already installed.
+        The remote must have the `rsync` command already installed.
         """
-        raise NotImplementedError(f"'rsync' not implemented for {self.__class__.__name__}")
 
 
 _submodules = [

atex/connection/podman.py

@@ -1,5 +1,5 @@
 """
-Connection API implementation using the 'podman' CLI client.
+Connection API implementation using the `podman` CLI client.
 """
 
 import subprocess
@@ -14,21 +14,10 @@ class PodmanConnectionError(ConnectionError):
 
 class PodmanConnection(Connection):
     """
-    Implements the Connection API via 'podman container exec' on an
+    Implements the Connection API via `podman container exec` on an
     already-running container, it does not handle any image pulling,
     container creation, starting or stopping.
     """
-
-#    def __init__(self, container, *, user=None, workdir=None):
-#        """
-#        'container' is a string with either the full or partial podman
-#        container ID, or a container name, as recognized by podman CLI.
-#
-#        'user' is a string with a username or UID, possibly including a GID,
-#        passed to the podman CLI as --user.
-#
-#        'workdir' is a string specifying the CWD inside the container.
-#        """
     def __init__(self, container):
         self.container = container
 

atex/connection/ssh.py

@@ -1,15 +1,15 @@
 """
-Connection API implementation using the OpenSSH ssh(1) client.
+Connection API implementation using the OpenSSH `ssh(1)` client.
 
 Any SSH options are passed via dictionaries of options, and later translated
-to '-o' client CLI options, incl. Hostname, User, Port, IdentityFile, etc.
+to `-o` client CLI options, incl. Hostname, User, Port, IdentityFile, etc.
 No "typical" ssh CLI switches are used.
 
 This allows for a nice flexibility from Python code - this module provides
 some sensible option defaults (for scripted use), but you are free to
 overwrite any options via class or function arguments (where appropriate).
 
-Note that .cmd() quotes arguments to really execute individual arguments
+Note that `.cmd()` quotes arguments to really execute individual arguments
 as individual arguments in the remote shell, so you need to give it a proper
 iterable (like for other Connections), not a single string with spaces.
 """
@@ -17,6 +17,7 @@ iterable (like for other Connections), not a single string with spaces.
 import os
 import time
 import shlex
+import logging
 import tempfile
 import threading
 import subprocess
@@ -25,6 +26,8 @@ from pathlib import Path
 from .. import util
 from . import Connection
 
+logger = logging.getLogger("atex.connection.ssh")
+
 
 DEFAULT_OPTIONS = {
     "LogLevel": "ERROR",
@@ -48,7 +51,6 @@ class DisconnectedError(SSHError):
     """
     Raised when an already-connected ssh session goes away (breaks connection).
     """
-    pass
 
 
 class NotConnectedError(SSHError):
@@ -56,19 +58,17 @@ class NotConnectedError(SSHError):
     Raised when an operation on ssh connection is requested, but the connection
     is not yet open (or has been closed/disconnected).
     """
-    pass
 
 
 class ConnectError(SSHError):
     """
     Raised when a to-be-opened ssh connection fails to open.
     """
-    pass
 
 
 def _shell_cmd(command, sudo=None):
     """
-    Make a command line for running 'command' on the target system.
+    Make a command line for running `command` on the target system.
     """
     quoted_args = (shlex.quote(str(arg)) for arg in command)
     if sudo:
@@ -81,7 +81,7 @@ def _shell_cmd(command, sudo=None):
 
 def _options_to_cli(options):
     """
-    Assemble an ssh(1) or sshpass(1) command line with -o options.
+    Assemble an `ssh(1)` or `sshpass(1)` command line with `-o` options.
     """
     list_opts = []
     for key, value in options.items():
@@ -94,7 +94,7 @@ def _options_to_cli(options):
 
 def _options_to_ssh(options, password=None, extra_cli_flags=()):
     """
-    Assemble an ssh(1) or sshpass(1) command line with -o options.
+    Prefix `sshpass(1)` if password was specified.
     """
     cli_opts = _options_to_cli(options)
     if password:
@@ -111,7 +111,7 @@ def _options_to_ssh(options, password=None, extra_cli_flags=()):
 # return a string usable for rsync -e
 def _options_to_rsync_e(options, password=None):
     """
-    Return a string usable for the rsync -e argument.
+    Return a string usable for the rsync `-e` argument.
     """
     cli_opts = _options_to_cli(options)
     batch_mode = "-oBatchMode=no" if password else "-oBatchMode=yes"
@@ -121,9 +121,10 @@ def _options_to_rsync_e(options, password=None):
 def _rsync_host_cmd(*args, options, password=None, sudo=None):
     """
     Assemble a rsync command line, noting that
-      - 'sshpass' must be before 'rsync', not inside the '-e' argument
-      - 'ignored_arg' must be passed by user as destination, not inside '-e'
-      - 'sudo' is part of '--rsync-path', yet another argument
+
+    - `sshpass` must be before `rsync`, not inside the `-e` argument
+    - `ignored_arg` must be passed by user as destination, not inside `-e`
+    - `sudo` is part of `--rsync-path`, yet another argument
     """
     return (
         *(("sshpass", "-p", password) if password else ()),
@@ -136,25 +137,25 @@ def _rsync_host_cmd(*args, options, password=None, sudo=None):
 
 class StatelessSSHConnection(Connection):
     """
-    Implements the Connection API using a ssh(1) client using "standalone"
-    (stateless) logic - connect() and disconnect() are no-op, .cmd() simply
-    executes the ssh client and .rsync() executes 'rsync -e ssh'.
+    Implements the Connection API using a `ssh(1)` client using "standalone"
+    (stateless) logic - `connect()` and `disconnect()` are no-op, `.cmd()`
+    simply executes the ssh client and `.rsync()` executes `rsync -e ssh`.
 
-    Compared to ManagedSSHConnection, this may be slow for many .cmd() calls,
+    Compared to ManagedSSHConnection, this may be slow for many `.cmd()` calls,
     but every call is stateless, there is no persistent connection.
 
-    If you need only one .cmd(), this will be faster than ManagedSSHConnection.
+    For only one `.cmd()`, this class is faster than ManagedSSHConnection.
     """
 
     def __init__(self, options, *, password=None, sudo=None):
         """
-        Prepare to connect to an SSH server specified in 'options'.
+        Prepare to connect to an SSH server specified in `options`.
 
-        If 'password' is given, spawn the ssh(1) command via 'sshpass' and
-        pass the password to it.
+        - If `password` is given, spawn the `ssh` command via `sshpass` and
+          pass the password to it.
 
-        If 'sudo' specifies a username, call sudo(8) on the remote shell
-        to run under a different user on the remote host.
+        - If `sudo` specifies a username, call `sudo(8)` on the remote shell
+          to run under a different user on the remote host.
         """
         self.options = DEFAULT_OPTIONS.copy()
         self.options.update(options)
@@ -164,11 +165,6 @@ class StatelessSSHConnection(Connection):
         self._master_proc = None
 
     def connect(self, block=True):
-        """
-        Optional, .cmd() and .rsync() work without it, but it is provided here
-        for compatibility with the Connection API.
-        """
-        # TODO: just wait until .cmd(['true']) starts responding ?
         pass
 
     def disconnect(self):
@@ -217,9 +213,9 @@ class StatelessSSHConnection(Connection):
 
 class ManagedSSHConnection(Connection):
     """
-    Implements the Connection API using one persistently-running ssh(1) client
-    started in a 'ControlMaster' mode, with additional ssh clients using that
-    session to execute remote commands. Similarly, .rsync() uses it too.
+    Implements the Connection API using one persistently-running `ssh(1)` client
+    started in a ControlMaster mode, with additional ssh clients using that
+    session to execute remote commands. Similarly, `.rsync()` uses it too.
 
     This is much faster than StatelessSSHConnection when executing multiple
     commands, but contains a complex internal state (what if ControlMaster
@@ -230,13 +226,13 @@ class ManagedSSHConnection(Connection):
 
     def __init__(self, options, *, password=None, sudo=None):
         """
-        Prepare to connect to an SSH server specified in 'options'.
+        Prepare to connect to an SSH server specified in `options`.
 
-        If 'password' is given, spawn the ssh(1) command via 'sshpass' and
-        pass the password to it.
+        - If `password` is given, spawn the `ssh` command via `sshpass`
+        and pass the password to it.
 
-        If 'sudo' specifies a username, call sudo(8) on the remote shell
-        to run under a different user on the remote host.
+        - If `sudo` specifies a username, call `sudo(8)` on the remote shell
+          to run under a different user on the remote host.
         """
         self.lock = threading.RLock()
         self.options = DEFAULT_OPTIONS.copy()
@@ -265,7 +261,7 @@ class ManagedSSHConnection(Connection):
         proc = self._master_proc
         if not proc:
             return
-        util.debug(f"disconnecting: {self.options}")
+        logger.info(f"disconnecting: {self.options}")
         proc.kill()
         # don't zombie forever, return EPIPE on any attempts to write to us
         proc.stdout.close()
@@ -285,7 +281,7 @@ class ManagedSSHConnection(Connection):
         sock = self._tmpdir / "control.sock"
 
         if not self._master_proc:
-            util.debug(f"connecting: {self.options}")
+            logger.info(f"connecting: {self.options}")
             options = self.options.copy()
             options["SessionType"] = "none"
             options["ControlMaster"] = "yes"
@@ -331,14 +327,14 @@ class ManagedSSHConnection(Connection):
 
     def forward(self, forward_type, *spec, cancel=False):
         """
-        Add (one or more) ssh forwarding specifications as 'spec' to an
+        Add (one or more) ssh forwarding specifications as `spec` to an
         already-connected instance. Each specification has to follow the
-        format of LocalForward or RemoteForward (see ssh_config(5)).
-        Ie. "1234 1.2.3.4:22" or "0.0.0.0:1234 1.2.3.4:22".
+        format of LocalForward or RemoteForward (see `ssh_config(5)`).
+        Ie. `1234 1.2.3.4:22` or `0.0.0.0:1234 1.2.3.4:22`.
 
-        'forward_type' must be either LocalForward or RemoteForward.
+        - `forward_type` must be either LocalForward or RemoteForward.
 
-        If 'cancel' is True, cancel the forwarding instead of adding it.
+        - If `cancel` is `True`, cancel the forwarding instead of adding it.
         """
         assert forward_type in ("LocalForward", "RemoteForward")
         self.assert_master()