Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/134578/?format=api
{ "id": 134578, "url": "https://patches.dpdk.org/api/patches/134578/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/patch/20231123151344.162812-13-juraj.linkes@pantheon.tech/", "project": { "id": 1, "url": "https://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<20231123151344.162812-13-juraj.linkes@pantheon.tech>", "list_archive_url": "https://inbox.dpdk.org/dev/20231123151344.162812-13-juraj.linkes@pantheon.tech", "date": "2023-11-23T15:13:35", "name": "[v8,12/21] dts: interactive remote session docstring update", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "9de8596c9356bae1467e1aacbe952dd2c106fc88", "submitter": { "id": 1626, "url": "https://patches.dpdk.org/api/people/1626/?format=api", "name": "Juraj Linkeš", "email": "juraj.linkes@pantheon.tech" }, "delegate": { "id": 1, "url": "https://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "https://patches.dpdk.org/project/dpdk/patch/20231123151344.162812-13-juraj.linkes@pantheon.tech/mbox/", "series": [ { "id": 30375, "url": "https://patches.dpdk.org/api/series/30375/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/list/?series=30375", "date": "2023-11-23T15:13:23", "name": "dts: docstrings update", "version": 8, "mbox": "https://patches.dpdk.org/series/30375/mbox/" } ], "comments": "https://patches.dpdk.org/api/patches/134578/comments/", "check": "success", "checks": "https://patches.dpdk.org/api/patches/134578/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@inbox.dpdk.org", "Delivered-To": "patchwork@inbox.dpdk.org", "Received": [ "from mails.dpdk.org (mails.dpdk.org [217.70.189.124])\n\tby inbox.dpdk.org (Postfix) with ESMTP id 9E5D7433AC;\n\tThu, 23 Nov 2023 16:15:37 +0100 (CET)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 4FF4B43246;\n\tThu, 23 Nov 2023 16:14:10 +0100 (CET)", "from mail-wm1-f47.google.com (mail-wm1-f47.google.com\n [209.85.128.47]) by mails.dpdk.org (Postfix) with ESMTP id EF1C642FB9\n for <dev@dpdk.org>; Thu, 23 Nov 2023 16:14:02 +0100 (CET)", "by mail-wm1-f47.google.com with SMTP id\n 5b1f17b1804b1-40b27b498c3so6781095e9.0\n for <dev@dpdk.org>; Thu, 23 Nov 2023 07:14:02 -0800 (PST)", "from jlinkes-PT-Latitude-5530.. ([84.245.121.10])\n by smtp.gmail.com with ESMTPSA id\n q4-20020adfea04000000b003296b488961sm1870143wrm.31.2023.11.23.07.14.01\n (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n Thu, 23 Nov 2023 07:14:02 -0800 (PST)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=pantheon.tech; s=google; t=1700752442; x=1701357242; darn=dpdk.org;\n h=content-transfer-encoding:mime-version:references:in-reply-to\n :message-id:date:subject:cc:to:from:from:to:cc:subject:date\n :message-id:reply-to;\n bh=DqZz7e38mO0YfQURv/Wivn7BoETZ8f7mwoH6Gsm/AFI=;\n b=mcEtj3lHkvDC7mq/z6Tp34r6ImOrALzXSuz1nG0MrnYkPA5m3bsOirHsxDEukPa2RF\n hrTgLAvWZocTasgpybk8bqD7+GaKUZsF6vQYmJfuNRD6y/xX9n33wDXcXyHm9CcIhVYA\n Uv2fcDrHWodIbt4SyN5/Bwuxl3kkIvGJVmGJuzL5bx72OUz32ifeUQ7ZHFP5wJ94TixH\n v2J2VS7EmnBJUIvHRKK11Cih9NXSi2jJnpHh2jjU5AZH2RkoJ9NwAt/yWHPGVkWSlplA\n bqwRvH2cV47lKnzwCosnLxX2KwGjSe6OTu7EJ0A54r3csXB0I84SvpNCio3fNtKOTKyP\n aqLg==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20230601; t=1700752442; x=1701357242;\n h=content-transfer-encoding:mime-version:references:in-reply-to\n :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc\n :subject:date:message-id:reply-to;\n bh=DqZz7e38mO0YfQURv/Wivn7BoETZ8f7mwoH6Gsm/AFI=;\n b=vUthiTXFlTpSV2bIdRRUB17uocHTM5bKlnBTH+we7zkAL21fk6HK4ZzA49QaJx5bqT\n RSkgwggmfFsJoUbetichCd+NlkHHL4EtZ3O06S65SXz9qUohvQCEG5KDo4jt9E+dxlkG\n w7BfQkqe0H1MHN1irGJETkA3aGz4n/ZvyXT0MUTGDl7NOaCVdxkK6l+4c57KNtqDY/VQ\n 9pYjwzridd4enVIMmB+SXcAYk2sJ9NAdF/I65Ovmlub5RTSiWRHVWyKbnQjzwKJi4NED\n cTBqFdcREe3vEh4ZpDKlXGHxAEQt2gI4RYYoia/GMikp/KEj15exoFqpEzcrRo5cZ4QV\n aISw==", "X-Gm-Message-State": "AOJu0Yx1KscdwDAbtQ87qPmz7/kfZg4nKRnSbBXiqvRjpFeAeoisyPKd\n dtSVglLmnZSYIzHNQhWXWpjV1g==", "X-Google-Smtp-Source": "\n AGHT+IGkADZ2dT/HZ3vR1OmAjVyA1bWiAdaufAjjBujYFEA5aLsRVKisk0kU32mwVvNThmjDTMpC2Q==", "X-Received": "by 2002:a05:600c:45d3:b0:409:5a92:4711 with SMTP id\n s19-20020a05600c45d300b004095a924711mr3830983wmo.34.1700752442506;\n Thu, 23 Nov 2023 07:14:02 -0800 (PST)", "From": "=?utf-8?q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>", "To": "thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, jspewock@iol.unh.edu,\n probb@iol.unh.edu, paul.szczepanek@arm.com, yoan.picchi@foss.arm.com,\n Luca.Vizzarro@arm.com", "Cc": "dev@dpdk.org, =?utf-8?q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>", "Subject": "[PATCH v8 12/21] dts: interactive remote session docstring update", "Date": "Thu, 23 Nov 2023 16:13:35 +0100", "Message-Id": "<20231123151344.162812-13-juraj.linkes@pantheon.tech>", "X-Mailer": "git-send-email 2.34.1", "In-Reply-To": "<20231123151344.162812-1-juraj.linkes@pantheon.tech>", "References": "<20231115130959.39420-1-juraj.linkes@pantheon.tech>\n <20231123151344.162812-1-juraj.linkes@pantheon.tech>", "MIME-Version": "1.0", "Content-Type": "text/plain; charset=UTF-8", "Content-Transfer-Encoding": "8bit", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://mails.dpdk.org/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org" }, "content": "Format according to the Google format and PEP257, with slight\ndeviations.\n\nSigned-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>\n---\n .../interactive_remote_session.py | 36 +++----\n .../remote_session/interactive_shell.py | 99 +++++++++++--------\n dts/framework/remote_session/python_shell.py | 26 ++++-\n dts/framework/remote_session/testpmd_shell.py | 58 +++++++++--\n 4 files changed, 149 insertions(+), 70 deletions(-)", "diff": "diff --git a/dts/framework/remote_session/interactive_remote_session.py b/dts/framework/remote_session/interactive_remote_session.py\nindex 098ded1bb0..1cc82e3377 100644\n--- a/dts/framework/remote_session/interactive_remote_session.py\n+++ b/dts/framework/remote_session/interactive_remote_session.py\n@@ -22,27 +22,23 @@\n class InteractiveRemoteSession:\n \"\"\"SSH connection dedicated to interactive applications.\n \n- This connection is created using paramiko and is a persistent connection to the\n- host. This class defines methods for connecting to the node and configures this\n- connection to send \"keep alive\" packets every 30 seconds. Because paramiko attempts\n- to use SSH keys to establish a connection first, providing a password is optional.\n- This session is utilized by InteractiveShells and cannot be interacted with\n- directly.\n-\n- Arguments:\n- node_config: Configuration class for the node you are connecting to.\n- _logger: Desired logger for this session to use.\n+ The connection is created using `paramiko <https://docs.paramiko.org/en/latest/>`_\n+ and is a persistent connection to the host. This class defines the methods for connecting\n+ to the node and configures the connection to send \"keep alive\" packets every 30 seconds.\n+ Because paramiko attempts to use SSH keys to establish a connection first, providing\n+ a password is optional. This session is utilized by InteractiveShells\n+ and cannot be interacted with directly.\n \n Attributes:\n- hostname: Hostname that will be used to initialize a connection to the node.\n- ip: A subsection of hostname that removes the port for the connection if there\n+ hostname: The hostname that will be used to initialize a connection to the node.\n+ ip: A subsection of `hostname` that removes the port for the connection if there\n is one. If there is no port, this will be the same as hostname.\n- port: Port to use for the ssh connection. This will be extracted from the\n- hostname if there is a port included, otherwise it will default to 22.\n+ port: Port to use for the ssh connection. This will be extracted from `hostname`\n+ if there is a port included, otherwise it will default to ``22``.\n username: User to connect to the node with.\n password: Password of the user connecting to the host. This will default to an\n empty string if a password is not provided.\n- session: Underlying paramiko connection.\n+ session: The underlying paramiko connection.\n \n Raises:\n SSHConnectionError: There is an error creating the SSH connection.\n@@ -58,9 +54,15 @@ class InteractiveRemoteSession:\n _node_config: NodeConfiguration\n _transport: Transport | None\n \n- def __init__(self, node_config: NodeConfiguration, _logger: DTSLOG) -> None:\n+ def __init__(self, node_config: NodeConfiguration, logger: DTSLOG) -> None:\n+ \"\"\"Connect to the node during initialization.\n+\n+ Args:\n+ node_config: The test run configuration of the node to connect to.\n+ logger: The logger instance this session will use.\n+ \"\"\"\n self._node_config = node_config\n- self._logger = _logger\n+ self._logger = logger\n self.hostname = node_config.hostname\n self.username = node_config.user\n self.password = node_config.password if node_config.password else \"\"\ndiff --git a/dts/framework/remote_session/interactive_shell.py b/dts/framework/remote_session/interactive_shell.py\nindex 4db19fb9b3..b158f963b6 100644\n--- a/dts/framework/remote_session/interactive_shell.py\n+++ b/dts/framework/remote_session/interactive_shell.py\n@@ -3,18 +3,20 @@\n \n \"\"\"Common functionality for interactive shell handling.\n \n-This base class, InteractiveShell, is meant to be extended by other classes that\n-contain functionality specific to that shell type. These derived classes will often\n-modify things like the prompt to expect or the arguments to pass into the application,\n-but still utilize the same method for sending a command and collecting output. How\n-this output is handled however is often application specific. If an application needs\n-elevated privileges to start it is expected that the method for gaining those\n-privileges is provided when initializing the class.\n+The base class, :class:`InteractiveShell`, is meant to be extended by subclasses that contain\n+functionality specific to that shell type. These subclasses will often modify things like\n+the prompt to expect or the arguments to pass into the application, but still utilize\n+the same method for sending a command and collecting output. How this output is handled however\n+is often application specific. If an application needs elevated privileges to start it is expected\n+that the method for gaining those privileges is provided when initializing the class.\n+\n+The :option:`--timeout` command line argument and the :envvar:`DTS_TIMEOUT`\n+environment variable configure the timeout of getting the output from command execution.\n \"\"\"\n \n from abc import ABC\n from pathlib import PurePath\n-from typing import Callable\n+from typing import Callable, ClassVar\n \n from paramiko import Channel, SSHClient, channel # type: ignore[import]\n \n@@ -30,28 +32,6 @@ class InteractiveShell(ABC):\n and collecting input until reaching a certain prompt. All interactive applications\n will use the same SSH connection, but each will create their own channel on that\n session.\n-\n- Arguments:\n- interactive_session: The SSH session dedicated to interactive shells.\n- logger: Logger used for displaying information in the console.\n- get_privileged_command: Method for modifying a command to allow it to use\n- elevated privileges. If this is None, the application will not be started\n- with elevated privileges.\n- app_args: Command line arguments to be passed to the application on startup.\n- timeout: Timeout used for the SSH channel that is dedicated to this interactive\n- shell. This timeout is for collecting output, so if reading from the buffer\n- and no output is gathered within the timeout, an exception is thrown.\n-\n- Attributes\n- _default_prompt: Prompt to expect at the end of output when sending a command.\n- This is often overridden by derived classes.\n- _command_extra_chars: Extra characters to add to the end of every command\n- before sending them. This is often overridden by derived classes and is\n- most commonly an additional newline character.\n- path: Path to the executable to start the interactive application.\n- dpdk_app: Whether this application is a DPDK app. If it is, the build\n- directory for DPDK on the node will be prepended to the path to the\n- executable.\n \"\"\"\n \n _interactive_session: SSHClient\n@@ -61,10 +41,22 @@ class InteractiveShell(ABC):\n _logger: DTSLOG\n _timeout: float\n _app_args: str\n- _default_prompt: str = \"\"\n- _command_extra_chars: str = \"\"\n- path: PurePath\n- dpdk_app: bool = False\n+\n+ #: Prompt to expect at the end of output when sending a command.\n+ #: This is often overridden by subclasses.\n+ _default_prompt: ClassVar[str] = \"\"\n+\n+ #: Extra characters to add to the end of every command\n+ #: before sending them. This is often overridden by subclasses and is\n+ #: most commonly an additional newline character.\n+ _command_extra_chars: ClassVar[str] = \"\"\n+\n+ #: Path to the executable to start the interactive application.\n+ path: ClassVar[PurePath]\n+\n+ #: Whether this application is a DPDK app. If it is, the build directory\n+ #: for DPDK on the node will be prepended to the path to the executable.\n+ dpdk_app: ClassVar[bool] = False\n \n def __init__(\n self,\n@@ -74,6 +66,19 @@ def __init__(\n app_args: str = \"\",\n timeout: float = SETTINGS.timeout,\n ) -> None:\n+ \"\"\"Create an SSH channel during initialization.\n+\n+ Args:\n+ interactive_session: The SSH session dedicated to interactive shells.\n+ logger: The logger instance this session will use.\n+ get_privileged_command: A method for modifying a command to allow it to use\n+ elevated privileges. If :data:`None`, the application will not be started\n+ with elevated privileges.\n+ app_args: The command line arguments to be passed to the application on startup.\n+ timeout: The timeout used for the SSH channel that is dedicated to this interactive\n+ shell. This timeout is for collecting output, so if reading from the buffer\n+ and no output is gathered within the timeout, an exception is thrown.\n+ \"\"\"\n self._interactive_session = interactive_session\n self._ssh_channel = self._interactive_session.invoke_shell()\n self._stdin = self._ssh_channel.makefile_stdin(\"w\")\n@@ -90,6 +95,10 @@ def _start_application(self, get_privileged_command: Callable[[str], str] | None\n \n This method is often overridden by subclasses as their process for\n starting may look different.\n+\n+ Args:\n+ get_privileged_command: A function (but could be any callable) that produces\n+ the version of the command with elevated privileges.\n \"\"\"\n start_command = f\"{self.path} {self._app_args}\"\n if get_privileged_command is not None:\n@@ -97,16 +106,24 @@ def _start_application(self, get_privileged_command: Callable[[str], str] | None\n self.send_command(start_command)\n \n def send_command(self, command: str, prompt: str | None = None) -> str:\n- \"\"\"Send a command and get all output before the expected ending string.\n+ \"\"\"Send `command` and get all output before the expected ending string.\n \n Lines that expect input are not included in the stdout buffer, so they cannot\n- be used for expect. For example, if you were prompted to log into something\n- with a username and password, you cannot expect \"username:\" because it won't\n- yet be in the stdout buffer. A workaround for this could be consuming an\n- extra newline character to force the current prompt into the stdout buffer.\n+ be used for expect.\n+\n+ Example:\n+ If you were prompted to log into something with a username and password,\n+ you cannot expect ``username:`` because it won't yet be in the stdout buffer.\n+ A workaround for this could be consuming an extra newline character to force\n+ the current `prompt` into the stdout buffer.\n+\n+ Args:\n+ command: The command to send.\n+ prompt: After sending the command, `send_command` will be expecting this string.\n+ If :data:`None`, will use the class's default prompt.\n \n Returns:\n- All output in the buffer before expected string\n+ All output in the buffer before expected string.\n \"\"\"\n self._logger.info(f\"Sending: '{command}'\")\n if prompt is None:\n@@ -124,8 +141,10 @@ def send_command(self, command: str, prompt: str | None = None) -> str:\n return out\n \n def close(self) -> None:\n+ \"\"\"Properly free all resources.\"\"\"\n self._stdin.close()\n self._ssh_channel.close()\n \n def __del__(self) -> None:\n+ \"\"\"Make sure the session is properly closed before deleting the object.\"\"\"\n self.close()\ndiff --git a/dts/framework/remote_session/python_shell.py b/dts/framework/remote_session/python_shell.py\nindex cc3ad48a68..ccfd3783e8 100644\n--- a/dts/framework/remote_session/python_shell.py\n+++ b/dts/framework/remote_session/python_shell.py\n@@ -1,12 +1,32 @@\n # SPDX-License-Identifier: BSD-3-Clause\n # Copyright(c) 2023 PANTHEON.tech s.r.o.\n \n+\"\"\"Python interactive shell.\n+\n+Typical usage example in a TestSuite::\n+\n+ from framework.remote_session import PythonShell\n+ python_shell = self.tg_node.create_interactive_shell(\n+ PythonShell, timeout=5, privileged=True\n+ )\n+ python_shell.send_command(\"print('Hello World')\")\n+ python_shell.close()\n+\"\"\"\n+\n from pathlib import PurePath\n+from typing import ClassVar\n \n from .interactive_shell import InteractiveShell\n \n \n class PythonShell(InteractiveShell):\n- _default_prompt: str = \">>>\"\n- _command_extra_chars: str = \"\\n\"\n- path: PurePath = PurePath(\"python3\")\n+ \"\"\"Python interactive shell.\"\"\"\n+\n+ #: Python's prompt.\n+ _default_prompt: ClassVar[str] = \">>>\"\n+\n+ #: This forces the prompt to appear after sending a command.\n+ _command_extra_chars: ClassVar[str] = \"\\n\"\n+\n+ #: The Python executable.\n+ path: ClassVar[PurePath] = PurePath(\"python3\")\ndiff --git a/dts/framework/remote_session/testpmd_shell.py b/dts/framework/remote_session/testpmd_shell.py\nindex 08ac311016..79481e845c 100644\n--- a/dts/framework/remote_session/testpmd_shell.py\n+++ b/dts/framework/remote_session/testpmd_shell.py\n@@ -1,41 +1,79 @@\n # SPDX-License-Identifier: BSD-3-Clause\n # Copyright(c) 2023 University of New Hampshire\n \n+\"\"\"Testpmd interactive shell.\n+\n+Typical usage example in a TestSuite::\n+\n+ testpmd_shell = self.sut_node.create_interactive_shell(\n+ TestPmdShell, privileged=True\n+ )\n+ devices = testpmd_shell.get_devices()\n+ for device in devices:\n+ print(device)\n+ testpmd_shell.close()\n+\"\"\"\n+\n from pathlib import PurePath\n-from typing import Callable\n+from typing import Callable, ClassVar\n \n from .interactive_shell import InteractiveShell\n \n \n class TestPmdDevice(object):\n+ \"\"\"The data of a device that testpmd can recognize.\n+\n+ Attributes:\n+ pci_address: The PCI address of the device.\n+ \"\"\"\n+\n pci_address: str\n \n def __init__(self, pci_address_line: str):\n+ \"\"\"Initialize the device from the testpmd output line string.\n+\n+ Args:\n+ pci_address_line: A line of testpmd output that contains a device.\n+ \"\"\"\n self.pci_address = pci_address_line.strip().split(\": \")[1].strip()\n \n def __str__(self) -> str:\n+ \"\"\"The PCI address captures what the device is.\"\"\"\n return self.pci_address\n \n \n class TestPmdShell(InteractiveShell):\n- path: PurePath = PurePath(\"app\", \"dpdk-testpmd\")\n- dpdk_app: bool = True\n- _default_prompt: str = \"testpmd>\"\n- _command_extra_chars: str = \"\\n\" # We want to append an extra newline to every command\n+ \"\"\"Testpmd interactive shell.\n+\n+ The testpmd shell users should never use\n+ the :meth:`~.interactive_shell.InteractiveShell.send_command` method directly, but rather\n+ call specialized methods. If there isn't one that satisfies a need, it should be added.\n+ \"\"\"\n+\n+ #: The path to the testpmd executable.\n+ path: ClassVar[PurePath] = PurePath(\"app\", \"dpdk-testpmd\")\n+\n+ #: Flag this as a DPDK app so that it's clear this is not a system app and\n+ #: needs to be looked in a specific path.\n+ dpdk_app: ClassVar[bool] = True\n+\n+ #: The testpmd's prompt.\n+ _default_prompt: ClassVar[str] = \"testpmd>\"\n+\n+ #: This forces the prompt to appear after sending a command.\n+ _command_extra_chars: ClassVar[str] = \"\\n\"\n \n def _start_application(self, get_privileged_command: Callable[[str], str] | None) -> None:\n- \"\"\"See \"_start_application\" in InteractiveShell.\"\"\"\n self._app_args += \" -- -i\"\n super()._start_application(get_privileged_command)\n \n def get_devices(self) -> list[TestPmdDevice]:\n- \"\"\"Get a list of device names that are known to testpmd\n+ \"\"\"Get a list of device names that are known to testpmd.\n \n- Uses the device info listed in testpmd and then parses the output to\n- return only the names of the devices.\n+ Uses the device info listed in testpmd and then parses the output.\n \n Returns:\n- A list of strings representing device names (e.g. 0000:14:00.1)\n+ A list of devices.\n \"\"\"\n dev_info: str = self.send_command(\"show device info all\")\n dev_list: list[TestPmdDevice] = []\n", "prefixes": [ "v8", "12/21" ] }