From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 872274415E; Wed, 5 Jun 2024 16:45:35 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 6A4A84113D; Wed, 5 Jun 2024 16:45:21 +0200 (CEST) Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by mails.dpdk.org (Postfix) with ESMTP id 9184341133 for ; Wed, 5 Jun 2024 16:45:19 +0200 (CEST) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 69D5CDA7; Wed, 5 Jun 2024 07:45:43 -0700 (PDT) Received: from localhost.localdomain (unknown [10.57.40.142]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPA id E7BFF3F792; Wed, 5 Jun 2024 07:45:17 -0700 (PDT) From: Luca Vizzarro To: dev@dpdk.org Cc: Jeremy Spewock , =?UTF-8?q?Juraj=20Linke=C5=A1?= , Luca Vizzarro , Paul Szczepanek Subject: [PATCH v3 3/5] dts: add parsing utility module Date: Wed, 5 Jun 2024 15:45:02 +0100 Message-Id: <20240605144504.361438-4-luca.vizzarro@arm.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240605144504.361438-1-luca.vizzarro@arm.com> References: <20240412111136.3470304-1-luca.vizzarro@arm.com> <20240605144504.361438-1-luca.vizzarro@arm.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Adds parsing text into a custom dataclass. It provides a new `TextParser` dataclass to be inherited. This implements the `parse` method, which combined with the parser functions, it can automatically parse the value for each field. This new utility will facilitate and simplify the parsing of complex command outputs, while ensuring that the codebase does not get bloated and stays flexible. Signed-off-by: Luca Vizzarro Reviewed-by: Paul Szczepanek --- dts/framework/exception.py | 9 ++ dts/framework/parser.py | 228 +++++++++++++++++++++++++++++++++++++ 2 files changed, 237 insertions(+) create mode 100644 dts/framework/parser.py diff --git a/dts/framework/exception.py b/dts/framework/exception.py index cce1e0231a..d9d690037d 100644 --- a/dts/framework/exception.py +++ b/dts/framework/exception.py @@ -31,6 +31,8 @@ class ErrorSeverity(IntEnum): #: SSH_ERR = 4 #: + INTERNAL_ERR = 5 + #: DPDK_BUILD_ERR = 10 #: TESTCASE_VERIFY_ERR = 20 @@ -192,3 +194,10 @@ def __init__(self, suite_name: str) -> None: def __str__(self) -> str: """Add some context to the string representation.""" return f"Blocking suite {self._suite_name} failed." + + +class InternalError(DTSError): + """An internal error or bug has occurred in DTS.""" + + #: + severity: ClassVar[ErrorSeverity] = ErrorSeverity.INTERNAL_ERR diff --git a/dts/framework/parser.py b/dts/framework/parser.py new file mode 100644 index 0000000000..a260b45c91 --- /dev/null +++ b/dts/framework/parser.py @@ -0,0 +1,228 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright(c) 2024 Arm Limited + +"""Parsing utility module. + +This module provides :class:`~TextParser` which can be used to model any dataclass to a block of +text. +""" + +import re +from abc import ABC +from dataclasses import MISSING, dataclass, fields +from functools import partial +from typing import Any, Callable, TypedDict, cast + +from typing_extensions import Self + +from framework.exception import InternalError + + +class ParserFn(TypedDict): + """Parser function in a dict compatible with the :func:`dataclasses.field` metadata param.""" + + #: + TextParser_fn: Callable[[str], Any] + + +@dataclass +class TextParser(ABC): + r"""Helper abstract dataclass that parses a text according to the fields' rules. + + In order to enable text parsing in a dataclass, subclass it with this class. + + So that a new instance of the dataclass can be created from text, the method `parse` is + provided. This takes text as an argument and for each field in the dataclass, the field's parser + function is run against the whole text. The returned value is then assigned to the field of the + new instance. If the field does not have a parser function its default value or factory is used + instead. If no default is available either, an exception is raised. + + This class provides a selection of parser functions and a function to wrap parser functions with + generic functions. Parser functions are designed to be passed to the fields' metadata param. + The most commonly used parser function is expected to be the method `find`, which runs a regular + expression against the text to find matches. + + Example: + The following example makes use of and demonstrates every parser function available: + + ..code:: python + + from dataclasses import dataclass, field + from enum import Enum + from framework.parser import TextParser + + class Colour(Enum): + BLACK = 1 + WHITE = 2 + + @classmethod + def from_str(cls, text: str): + match text: + case "black": + return cls.BLACK + case "white": + return cls.WHITE + case _: + return None # unsupported colour + + @classmethod + def make_parser(cls): + # make a parser function that finds a match and + # then makes it a Colour object through Colour.from_str + return TextParser.wrap(cls.from_str, TextParser.find(r"is a (\w+)")) + + @dataclass + class Animal(TextParser): + kind: str = field(metadata=TextParser.find(r"is a \w+ (\w+)")) + name: str = field(metadata=TextParser.find(r"^(\w+)")) + colour: Colour = field(metadata=Colour.make_parser()) + age: int = field(metadata=TextParser.find_int(r"aged (\d+)")) + + steph = Animal.parse("Stephanie is a white cat aged 10") + print(steph) # Animal(kind='cat', name='Stephanie', colour=, age=10) + """ + + """============ BEGIN PARSER FUNCTIONS ============""" + + @staticmethod + def wrap(parser_fn: ParserFn, wrapper_fn: Callable) -> ParserFn: + """Makes a wrapped parser function. + + `parser_fn` is called and if a non-None value is returned, `wrapper_function` is called with + it. Otherwise the function returns early with None. In pseudo-code: + + intermediate_value := parser_fn(input) + if intermediary_value is None then + output := None + else + output := wrapper_fn(intermediate_value) + + Args: + parser_fn: The dictionary storing the parser function to be wrapped. + wrapper_fn: The function that wraps `parser_fn`. + + Returns: + ParserFn: A dictionary for the `dataclasses.field` metadata argument containing the + newly wrapped parser function. + """ + inner_fn = parser_fn["TextParser_fn"] + + def _composite_parser_fn(text: str) -> Any: + intermediate_value = inner_fn(text) + if intermediate_value is None: + return None + return wrapper_fn(intermediate_value) + + return ParserFn(TextParser_fn=_composite_parser_fn) + + @staticmethod + def find( + pattern: str | re.Pattern[str], + flags: re.RegexFlag = re.RegexFlag(0), + named: bool = False, + ) -> ParserFn: + """Makes a parser function that finds a regular expression match in the text. + + If the pattern has any capturing groups, it returns None if no match was found, otherwise a + tuple containing the values per each group is returned.. If the pattern has only one + capturing group and a match was found, its value is returned. If the pattern has no + capturing groups then either True or False is returned if the pattern had a match or not. + + Args: + pattern: The regular expression pattern. + flags: The regular expression flags. Ignored if the given pattern is already compiled. + named: If set to True only the named capturing groups will be returned, as a dictionary. + + Returns: + ParserFn: A dictionary for the `dataclasses.field` metadata argument containing the find + parser function. + """ + if isinstance(pattern, str): + pattern = re.compile(pattern, flags) + + def _find(text: str) -> Any: + m = pattern.search(text) + if m is None: + return None if pattern.groups > 0 else False + + if pattern.groups == 0: + return True + + if named: + return m.groupdict() + + matches = m.groups() + if len(matches) == 1: + return matches[0] + + return matches + + return ParserFn(TextParser_fn=_find) + + @staticmethod + def find_int( + pattern: str | re.Pattern[str], + flags: re.RegexFlag = re.RegexFlag(0), + int_base: int = 0, + ) -> ParserFn: + """Makes a parser function that converts the match of :meth:`~find` to int. + + This function is compatible only with a pattern containing one capturing group. + + Args: + pattern: The regular expression pattern. + flags: The regular expression flags. Ignored if the given pattern is already compiled. + int_base: The base of the number to convert from. + + Raises: + InternalError: If the pattern does not have exactly one capturing group. + + Returns: + ParserFn: A dictionary for the `dataclasses.field` metadata argument containing the + :meth:`~find` parser function wrapped by the int built-in. + """ + if isinstance(pattern, str): + pattern = re.compile(pattern, flags) + + if pattern.groups != 1: + raise InternalError("only one capturing group is allowed with this parser function") + + return TextParser.wrap(TextParser.find(pattern), partial(int, base=int_base)) + + """============ END PARSER FUNCTIONS ============""" + + @classmethod + def parse(cls, text: str) -> Self: + """Creates a new instance of the class from the given text. + + A new class instance is created with all the fields that have a parser function in their + metadata. Fields without one are ignored and are expected to have a default value, otherwise + the class initialization will fail. + + A field is populated with the value returned by its corresponding parser function. + + Args: + text: the text to parse + + Raises: + InternalError: if the parser did not find a match and the field does not have a default + value or default factory. + + Returns: + A new instance of the class. + """ + fields_values = {} + for field in fields(cls): + parse = cast(ParserFn, field.metadata).get("TextParser_fn") + if parse is None: + continue + + value = parse(text) + if value is not None: + fields_values[field.name] = value + elif field.default is MISSING and field.default_factory is MISSING: + raise InternalError( + f"parser for field {field.name} returned None, but the field has no default" + ) + + return cls(**fields_values) -- 2.34.1