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 24A8A43337; Wed, 15 Nov 2023 11:09:30 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 123DE402EC; Wed, 15 Nov 2023 11:09:30 +0100 (CET) Received: from mail-ed1-f43.google.com (mail-ed1-f43.google.com [209.85.208.43]) by mails.dpdk.org (Postfix) with ESMTP id 46DF0400EF for ; Wed, 15 Nov 2023 11:09:29 +0100 (CET) Received: by mail-ed1-f43.google.com with SMTP id 4fb4d7f45d1cf-544455a4b56so10117929a12.1 for ; Wed, 15 Nov 2023 02:09:29 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1700042969; x=1700647769; darn=dpdk.org; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=msCmtetiOLIV61Nuvk4HE2lqHZaWInKv8MkyXYpp894=; b=KzL8ytqnnmeL22pbPx5LVTiJcCGzXO5kc3YkRx9FF8L5ooLd9NMXOrQA9VhXMCOk7R Ro/UdnWIR5iGqJy2gYESmBXTKYLAGMpxQ6UkGifwho9RvGi/caTDHdfy1dTSVO8iatlX HrH2OdxD1onFLyPkvYfbVmM7jXQ4NZ0RvpWzoEPaAKtJM37MlRsnCAJCm7y0OXeSn2Oj UjlcrUIft4v+w+yCzoAT1hgEVhFqJcqlbjqhR/unkR9uHAH7P8QqCVXzHXC6ADo2D70f /vPlJTN9u8fxEneB7scqkvF0tPPGJEGTHnWI9QgA4T9s4AZL6xxzqr8SyLe0Pz+Ur2e/ ym9g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700042969; x=1700647769; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=msCmtetiOLIV61Nuvk4HE2lqHZaWInKv8MkyXYpp894=; b=qdBfeykpZdEUhmpdHNBXXAE7mWcdN5j97aoCi6IGcM+f0d+I5YRj/meFGj9ZX0m/tY 4HZT4/8XbbtTXntsqx6pfcjLJmQ4tZjvIupRywb0dKbd++PsI469/nhAcCmaEoC/QVyM EbyFeSHeor9/Q0ttOtKniFbocK00UJ81NqrN0vB9xupYc6ZG1cSDVhgSk2/imICVYTuW L3pRPiTmaknUNUktIoI+zVGhYKxghoYKvymQdwnDD3bpzMTk6p1i+FlgZGy/KWQDip4t 7B8YcWM6C+XmhxHVC6e1HjVhAVqZvr/7+Tj6wKTFtv3MZG3UJ4c3lu5hUoKeS2sOeJ+4 WLWA== X-Gm-Message-State: AOJu0YzDaU6yREEDac/FEAntR9u8E0tVlV7ZezHxJkYBmgC1Rtikx3Ey e5hc4BKGACvn2Wnfiak4ZQpkM1G8gtHHZr/VVUKuhA== X-Google-Smtp-Source: AGHT+IFk27OINmjZ8P9sjGJNDSQcSIPe96jAYkVZlcsiHGxwNos3kzbC0qvW+sIhdrT1dXvEyLTwkDVKNcxfXbUdEBw= X-Received: by 2002:a17:906:f116:b0:9e6:f2e3:cdef with SMTP id gv22-20020a170906f11600b009e6f2e3cdefmr7885535ejb.38.1700042968880; Wed, 15 Nov 2023 02:09:28 -0800 (PST) MIME-Version: 1.0 References: <20231106171601.160749-1-juraj.linkes@pantheon.tech> <20231108125324.191005-1-juraj.linkes@pantheon.tech> <20231108125324.191005-5-juraj.linkes@pantheon.tech> <7a5961a6-bf68-41ed-a062-125e58797237@foss.arm.com> In-Reply-To: <7a5961a6-bf68-41ed-a062-125e58797237@foss.arm.com> From: =?UTF-8?Q?Juraj_Linke=C5=A1?= Date: Wed, 15 Nov 2023 11:09:17 +0100 Message-ID: Subject: Re: [PATCH v6 05/23] dts: settings docstring update To: Yoan Picchi Cc: thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, bruce.richardson@intel.com, jspewock@iol.unh.edu, probb@iol.unh.edu, paul.szczepanek@arm.com, dev@dpdk.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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 On Wed, Nov 8, 2023 at 5:17=E2=80=AFPM Yoan Picchi wrote: > > On 11/8/23 12:53, Juraj Linke=C5=A1 wrote: > > Format according to the Google format and PEP257, with slight > > deviations. > > > > Signed-off-by: Juraj Linke=C5=A1 > > --- > > dts/framework/settings.py | 101 +++++++++++++++++++++++++++++++++++++= - > > 1 file changed, 100 insertions(+), 1 deletion(-) > > > > diff --git a/dts/framework/settings.py b/dts/framework/settings.py > > index 7f5841d073..787db7c198 100644 > > --- a/dts/framework/settings.py > > +++ b/dts/framework/settings.py > > @@ -3,6 +3,70 @@ > > # Copyright(c) 2022-2023 PANTHEON.tech s.r.o. > > # Copyright(c) 2022 University of New Hampshire > > > > +"""Environment variables and command line arguments parsing. > > + > > +This is a simple module utilizing the built-in argparse module to pars= e command line arguments, > > +augment them with values from environment variables and make them avai= lable across the framework. > > + > > +The command line value takes precedence, followed by the environment v= ariable value, > > +followed by the default value defined in this module. > > + > > +The command line arguments along with the supported environment variab= les are: > > + > > +.. option:: --config-file > > +.. envvar:: DTS_CFG_FILE > > + > > + The path to the YAML test run configuration file. > > + > > +.. option:: --output-dir, --output > > +.. envvar:: DTS_OUTPUT_DIR > > + > > + The directory where DTS logs and results are saved. > > + > > +.. option:: --compile-timeout > > +.. envvar:: DTS_COMPILE_TIMEOUT > > + > > + The timeout for compiling DPDK. > > + > > +.. option:: -t, --timeout > > +.. envvar:: DTS_TIMEOUT > > + > > + The timeout for all DTS operation except for compiling DPDK. > > + > > +.. option:: -v, --verbose > > +.. envvar:: DTS_VERBOSE > > + > > + Set to any value to enable logging everything to the console. > > + > > +.. option:: -s, --skip-setup > > +.. envvar:: DTS_SKIP_SETUP > > + > > + Set to any value to skip building DPDK. > > + > > +.. option:: --tarball, --snapshot, --git-ref > > +.. envvar:: DTS_DPDK_TARBALL > > + > > + The path to a DPDK tarball, git commit ID, tag ID or tree ID to te= st. > > + > > +.. option:: --test-cases > > +.. envvar:: DTS_TESTCASES > > + > > + A comma-separated list of test cases to execute. Unknown test case= s will be silently ignored. > > + > > +.. option:: --re-run, --re_run > > +.. envvar:: DTS_RERUN > > + > > + Re-run each test case this many times in case of a failure. > > + > > +Attributes: > > + SETTINGS: The module level variable storing framework-wide DTS set= tings. > > In the generated doc, "Attributes" doesn't appear. It ends up looking > like SETTINGS is just another environment variable, with no separation > with the above list. > Yes, the Attributes: section is just a syntactical way to tell the parser to render the attributes in a certain way. We could add some delimiter or an extra paragraph explaining that what comes next are module attributes. I'll try to add something. > > + > > +Typical usage example:: > > + > > + from framework.settings import SETTINGS > > + foo =3D SETTINGS.foo > > +""" > > + > > import argparse > > import os > > from collections.abc import Callable, Iterable, Sequence > > @@ -16,6 +80,23 @@ > > > > > > def _env_arg(env_var: str) -> Any: > > + """A helper method augmenting the argparse Action with environment= variable > > + > > + If the supplied environment variable is defined, then the default = value > > + of the argument is modified. This satisfies the priority order of > > + command line argument > environment variable > default value. > > + > > + Arguments with no values (flags) should be defined using the const= keyword argument > > + (True or False). When the argument is specified, it will be set to= const, if not specified, > > + the default will be stored (possibly modified by the corresponding= environment variable). > > + > > + Other arguments work the same as default argparse arguments, that = is using > > + the default 'store' action. > > + > > + Returns: > > + The modified argparse.Action. > > + """ > > + > > class _EnvironmentArgument(argparse.Action): > > def __init__( > > self, > > @@ -68,14 +149,28 @@ def __call__( > > > > @dataclass(slots=3DTrue) > > class Settings: > > + """Default framework-wide user settings. > > + > > + The defaults may be modified at the start of the run. > > + """ > > + > > + #: > > config_file_path: Path =3D Path(__file__).parent.parent.joinpath(= "conf.yaml") > > + #: > > output_dir: str =3D "output" > > + #: > > timeout: float =3D 15 > > + #: > > verbose: bool =3D False > > + #: > > skip_setup: bool =3D False > > + #: > > dpdk_tarball_path: Path | str =3D "dpdk.tar.xz" > > + #: > > compile_timeout: float =3D 1200 > > + #: > > test_cases: list[str] =3D field(default_factory=3Dlist) > > + #: > > re_run: int =3D 0 > > For some reason in the doc, __init__ also appears : > __init__(config_file_path: ~pathlib.Path =3D PosixPath('/ho... > Yes, the @dataclass decorator adds the constructor so it gets documented. This is useful so that we see the default values. > > > > > > @@ -169,7 +264,7 @@ def _get_parser() -> argparse.ArgumentParser: > > action=3D_env_arg("DTS_RERUN"), > > default=3DSETTINGS.re_run, > > type=3Dint, > > - help=3D"[DTS_RERUN] Re-run each test case the specified amount= of times " > > + help=3D"[DTS_RERUN] Re-run each test case the specified number= of times " > > "if a test failure occurs", > > ) > > > > @@ -177,6 +272,10 @@ def _get_parser() -> argparse.ArgumentParser: > > > > > > def get_settings() -> Settings: > > + """Create new settings with inputs from the user. > > + > > + The inputs are taken from the command line and from environment va= riables. > > + """ > > parsed_args =3D _get_parser().parse_args() > > return Settings( > > config_file_path=3Dparsed_args.config_file, >