shvcli 0.6.2__tar.gz → 0.7.0__tar.gz

{shvcli-0.6.2/shvcli.egg-info → shvcli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: shvcli
-Version: 0.6.2
+Version: 0.7.0
 Summary: Silicon Heaven CLI access application
 Author: Elektroline a.s.
 License: MIT License
@@ -27,7 +27,6 @@ License: MIT License
         
 Project-URL: repository, https://gitlab.com/silicon-heaven/shvcli
 Classifier: Development Status :: 4 - Beta
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
 Classifier: Environment :: Console
@@ -38,10 +37,12 @@ Classifier: Topic :: Terminals
 Requires-Python: >=3.11
 Description-Content-Type: text/x-rst
 License-File: LICENSE
-Requires-Dist: pyshv>=0.8.0
+Requires-Dist: pyshv>=0.9.0
 Requires-Dist: prompt_toolkit
 Requires-Dist: pygments
 Requires-Dist: pyxdg
+Requires-Dist: more-itertools
+Dynamic: license-file
 
 =====================================
 Silicon Heaven CLI access application
@@ -101,20 +102,25 @@ An example of usage:
    .app> /:
    >
 
+.. TIP::
+   The validation that is performed by SHVCLI is best effort and sometimes you
+   might need to submit call that is considered invalid by SHVCLI. For that
+   reason you can use `Ctrl+o` shortcut instead of pressing enter key.
+
 
 Configuration file
 ------------------
 
-Tool reads configuration from files ``/etc/shvcli.ini`` and ``~/.shvcli.ini``.
-They are in INI file format and the following sections are supported:
+Tool reads configuration from files ``/etc/shvcli.toml`` and ``~/.shvcli.toml``.
+They are in TOML file format and the following sections are supported:
 
 **hosts**: That provides mapping from some name to RPC URL.
 
 **hosts-shell**: That is same as **hosts** with exception that URL is passed
 through your local Shell to expand any variables or command substitutions.
 
-**config**: That allows you to set some initial configuration that can be also
-switched in runtime. The following options are available:
+**option**: That allows you to set initial setting for runtime options. The
+following options are available without any plugins:
 
 * **vimode**: If Vi input mode should be used for command line input. The
   default is ``false``.
@@ -137,17 +143,15 @@ switched in runtime. The following options are available:
   be also overwhelming. The default is ``false``. It is beneficial to disable
   the **autobrobe** once you enable debug because otherwise output on CLI will
   be mangled on completion.
-* **cache**: Controls if cache is preserved between invocations. Cache is
-  separated based on the connection URL and stored in files in
-  ``$XDG_CACHE_HOME/shvcli``. The default is ``true``.
-* **call_attempts**: Number of attempts before method call is abandoned and
-  timeout is reported. This makes the total time multiple of **call_timeout**.
-* **call_timeout**: Timeout in seconds before call attempt is abandoned. Based
-  on the **call_attempts** call is attempted again or timeout is reported.
-* **autoget_timeout**: Timeout in seconds before call that is part of autoget
+* **call_query_timeout**: Timeout in seconds for status request query. The
+  shorter time will result in faster request lost detection while very short
+  time will load SHV network too much.
+* **call_retry_timeout**: Timeout in seconds when call request is sent again if
+  no response is received. This is not applied if query is and thus this mostly
+  is used only in case when method doesn't support delayed responses.
+* **autoget_timeout**: Timeout in seconds for call that is part of autoget
   functionality.
 
-
 Example configuration file:
 
 .. code-block:: ini
@@ -200,6 +204,15 @@ disable ``raw`` you use ``noraw``). You can also add ``=true`` or ``=false``.
 The equal sign is also used with integer and floating point options. Without any
 configuration option it simply prints the current configuration.
 
+**upload**: provides a way to copy local file to the RPC File node. The
+parameter must be path to the local file to be uploaded.
+
+**download**: provides a way to copy RPC File node data to local file. The
+parameter must be path to the local file where data will be stored.
+
+**verify**: provides a way to verify RPC File node against local file. The
+parameter must be path to the local file used for the verification.
+
 
 Special methods ``ls`` and ``dir``
 ----------------------------------
@@ -211,3 +224,10 @@ the fullest content.
 Their parameter is also handled in a special way. It is considered to be
 additional path suffix unless it is a valid CPON. This is allowed to match the
 common shells.
+
+
+Plugins
+-------
+
+The support for external plugins is provided. These plugins are discovered using
+Python package metadata using the entry point ``shvcli.plugins``.

{shvcli-0.6.2 → shvcli-0.7.0}/README.rst

@@ -56,20 +56,25 @@ An example of usage:
    .app> /:
    >
 
+.. TIP::
+   The validation that is performed by SHVCLI is best effort and sometimes you
+   might need to submit call that is considered invalid by SHVCLI. For that
+   reason you can use `Ctrl+o` shortcut instead of pressing enter key.
+
 
 Configuration file
 ------------------
 
-Tool reads configuration from files ``/etc/shvcli.ini`` and ``~/.shvcli.ini``.
-They are in INI file format and the following sections are supported:
+Tool reads configuration from files ``/etc/shvcli.toml`` and ``~/.shvcli.toml``.
+They are in TOML file format and the following sections are supported:
 
 **hosts**: That provides mapping from some name to RPC URL.
 
 **hosts-shell**: That is same as **hosts** with exception that URL is passed
 through your local Shell to expand any variables or command substitutions.
 
-**config**: That allows you to set some initial configuration that can be also
-switched in runtime. The following options are available:
+**option**: That allows you to set initial setting for runtime options. The
+following options are available without any plugins:
 
 * **vimode**: If Vi input mode should be used for command line input. The
   default is ``false``.
@@ -92,17 +97,15 @@ switched in runtime. The following options are available:
   be also overwhelming. The default is ``false``. It is beneficial to disable
   the **autobrobe** once you enable debug because otherwise output on CLI will
   be mangled on completion.
-* **cache**: Controls if cache is preserved between invocations. Cache is
-  separated based on the connection URL and stored in files in
-  ``$XDG_CACHE_HOME/shvcli``. The default is ``true``.
-* **call_attempts**: Number of attempts before method call is abandoned and
-  timeout is reported. This makes the total time multiple of **call_timeout**.
-* **call_timeout**: Timeout in seconds before call attempt is abandoned. Based
-  on the **call_attempts** call is attempted again or timeout is reported.
-* **autoget_timeout**: Timeout in seconds before call that is part of autoget
+* **call_query_timeout**: Timeout in seconds for status request query. The
+  shorter time will result in faster request lost detection while very short
+  time will load SHV network too much.
+* **call_retry_timeout**: Timeout in seconds when call request is sent again if
+  no response is received. This is not applied if query is and thus this mostly
+  is used only in case when method doesn't support delayed responses.
+* **autoget_timeout**: Timeout in seconds for call that is part of autoget
   functionality.
 
-
 Example configuration file:
 
 .. code-block:: ini
@@ -155,6 +158,15 @@ disable ``raw`` you use ``noraw``). You can also add ``=true`` or ``=false``.
 The equal sign is also used with integer and floating point options. Without any
 configuration option it simply prints the current configuration.
 
+**upload**: provides a way to copy local file to the RPC File node. The
+parameter must be path to the local file to be uploaded.
+
+**download**: provides a way to copy RPC File node data to local file. The
+parameter must be path to the local file where data will be stored.
+
+**verify**: provides a way to verify RPC File node against local file. The
+parameter must be path to the local file used for the verification.
+
 
 Special methods ``ls`` and ``dir``
 ----------------------------------
@@ -166,3 +178,10 @@ the fullest content.
 Their parameter is also handled in a special way. It is considered to be
 additional path suffix unless it is a valid CPON. This is allowed to match the
 common shells.
+
+
+Plugins
+-------
+
+The support for external plugins is provided. These plugins are discovered using
+Python package metadata using the entry point ``shvcli.plugins``.

{shvcli-0.6.2 → shvcli-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "shvcli"
-version = "0.6.2"
+version = "0.7.0"
 description = "Silicon Heaven CLI access application"
 readme = "README.rst"
 license = {file = "LICENSE"}
@@ -9,7 +9,6 @@ authors = [
 ]
 classifiers = [
   "Development Status :: 4 - Beta",
-  "License :: OSI Approved :: MIT License",
   "Programming Language :: Python :: 3",
   "Operating System :: OS Independent",
   "Environment :: Console",
@@ -20,10 +19,11 @@ classifiers = [
 ]
 requires-python = ">=3.11"
 dependencies = [
-  "pyshv >= 0.8.0",
+  "pyshv >= 0.9.0",
   "prompt_toolkit",
   "pygments",
   "pyxdg",
+  "more-itertools",
 ]
 
 [project.urls]

shvcli-0.7.0/shvcli/__init__.py

@@ -0,0 +1,55 @@
+"""Silicon Heaven Command Line Interface."""
+
+import importlib
+
+from .__version__ import VERSION
+from .args import register_argparser
+from .builtin import Builtin, Builtins
+from .client import Client
+from .cliitems import CliItems
+from .config import Config, ConfigError, register_config
+from .option import BoolOption, FloatOption, IntOption, Option
+from .options import (
+    AutoGetOption,
+    AutoGetTimeoutOption,
+    AutoProbeOption,
+    CallDuration,
+    CallQueryTimeout,
+    CallRetryTimeout,
+    DebugOption,
+    RawOption,
+    ViModeOption,
+)
+from .state import State, StateVar
+from .tree import Node, Tree
+
+__all__ = [
+    "VERSION",
+    "AutoGetOption",
+    "AutoGetTimeoutOption",
+    "AutoProbeOption",
+    "BoolOption",
+    "Builtin",
+    "Builtins",
+    "CallDuration",
+    "CallQueryTimeout",
+    "CallRetryTimeout",
+    "CliItems",
+    "Client",
+    "Config",
+    "ConfigError",
+    "DebugOption",
+    "FloatOption",
+    "IntOption",
+    "Node",
+    "Option",
+    "RawOption",
+    "State",
+    "StateVar",
+    "Tree",
+    "ViModeOption",
+    "register_argparser",
+    "register_config",
+]
+
+importlib.import_module(".builtins", package=__package__)

shvcli-0.7.0/shvcli/__main__.py

@@ -0,0 +1,36 @@
+"""Implementation of command line application."""
+
+import asyncio
+
+from .afterconn import Afterconn
+from .args import args_apply, args_parse
+from .cli import run
+from .client import Client
+from .config import load_config
+from .plugins import load_plugins
+from .state import State
+from .url import Url
+
+
+def main() -> None:
+    """Application's entrypoint."""
+    load_plugins()
+    argsgens, args = args_parse()
+    state = State()
+    load_config(args.config, state)
+    args_apply(argsgens, args, state)
+    state.cache_load(Url(state).cache_path())
+
+    async def async_main() -> None:
+        client = await Client.connect(Url(state).url, state=state)
+        await Afterconn(state).run(client)
+        await run(client)
+        if client.client.connected:
+            await client.disconnect()
+
+    asyncio.run(async_main())
+    state.cache_dump(Url(state).cache_path())
+
+
+if __name__ == "__main__":
+    main()

shvcli-0.7.0/shvcli/afterconn.py

@@ -0,0 +1,55 @@
+"""The after connection tasks."""
+
+import argparse
+import collections.abc
+import typing
+
+from .args import ArgsParseFuncGenT, register_argparser
+from .client import Client, SHVPath
+from .cliitems import CliItems
+from .scan import scan_nodes
+from .state import StateVar
+
+AfterConnT: typing.TypeAlias = collections.abc.Callable[
+    [Client], collections.abc.Coroutine[None, None, None]
+]
+
+
+class Afterconn(StateVar, list[AfterConnT]):
+    """The set of operations to be performed right after connection."""
+
+    async def run(self, client: Client) -> None:
+        """Run the steps setup to be performed after connection at startup."""
+        for func in self:
+            await func(client)
+
+
+@register_argparser
+def _argparser(parser: argparse.ArgumentParser) -> ArgsParseFuncGenT:
+    parser.add_argument(
+        "-s",
+        "--subscribe",
+        action="append",
+        default=[],
+        help="Automatic subscription right after connection.",
+    )
+    parser.add_argument(
+        "--scan",
+        action="store_true",
+        help="Perform scan as a first action right after connect.",
+    )
+    parser.add_argument(
+        "--scan-depth",
+        type=int,
+        default=3,
+        help="Depth of the scan performed if --scan is used.",
+    )
+    args, state = yield
+
+    async def afterconn(client: Client) -> None:
+        for ri in args.subscribe:
+            await client.subscribe(CliItems.extend_ri(ri))
+        if args.scan:
+            await scan_nodes(client, SHVPath(""), args.scan_dept)
+
+    Afterconn(state).append(afterconn)

shvcli-0.7.0/shvcli/args.py

@@ -0,0 +1,56 @@
+"""Argument parser wrapper for the SHVCLI."""
+
+import argparse
+import collections.abc
+import contextlib
+import pathlib
+import typing
+
+from .__version__ import VERSION
+from .state import State
+
+ArgsParseFuncGenT: typing.TypeAlias = collections.abc.Generator[
+    None, tuple[argparse.Namespace, State], None
+]
+ArgsparseFuncT: typing.TypeAlias = collections.abc.Callable[
+    [argparse.ArgumentParser], ArgsParseFuncGenT
+]
+
+registered_functions: list[ArgsparseFuncT] = []
+
+
+def register_argparser(func: ArgsparseFuncT) -> None:
+    """Decorate function to register it to be called when arguments are being parsed."""
+    registered_functions.append(func)
+
+
+def args_parse() -> tuple[tuple[ArgsParseFuncGenT, ...], argparse.Namespace]:
+    """Parse passed arguments and return result."""
+    parser = argparse.ArgumentParser(prog="shvcli", description="Silicon Heaven CLI")
+    parser.add_argument("--version", action="version", version="%(prog)s " + VERSION)
+    parser.add_argument(
+        "-c",
+        "--config",
+        action="append",
+        type=pathlib.Path,
+        default=[pathlib.Path("/etc/shvcli.toml"), pathlib.Path("~/.shvcli.toml")],
+    )
+    gens = tuple(func(parser) for func in registered_functions)
+    for gen in gens:
+        next(gen)
+    args = parser.parse_args()
+    return gens, args
+
+
+def args_apply(
+    gens: tuple[ArgsParseFuncGenT, ...], args: argparse.Namespace, state: State
+) -> None:
+    """Apply parsed arguments on the given state.
+
+    The parsed arguments should be applied after configuration but
+    configuration loading needs to be influenced by arguments and thus split
+    arguments parsing to the parsing and application phase.
+    """
+    for gen in gens:
+        with contextlib.suppress(StopIteration):
+            gen.send((args, state))

shvcli-0.7.0/shvcli/builtin.py

@@ -0,0 +1,86 @@
+"""Builtin methods glue code so they can be defined separatelly."""
+
+from __future__ import annotations
+
+import abc
+import collections.abc
+import inspect
+import typing
+
+from prompt_toolkit.completion import Completion
+
+from .client import Client
+from .cliitems import CliItems
+from .state import State, StateVar
+
+
+class Builtin(abc.ABC):
+    """The single builtin definition."""
+
+    builtins: typing.Final[list[type[Builtin]]] = []
+
+    def __init_subclass__(cls, *args: typing.Any, **kwargs: typing.Any) -> None:  # noqa: ANN401
+        super().__init_subclass__(*args, **kwargs)
+        Builtin.builtins.append(cls)
+
+    def __init__(self, builtins: Builtins, state: State) -> None:
+        self.state = state
+
+    @property
+    @abc.abstractmethod
+    def description(self) -> tuple[str, str]:
+        """The provider of the description of this builtin.
+
+        :return: The first string is description of arguments expected by
+          builtin and the second one is the builtin description.
+        """
+
+    def completion(  # noqa: PLR6301
+        self, items: CliItems, client: Client
+    ) -> collections.abc.Iterable[Completion]:
+        """Parameter completion for this builtin."""
+        return tuple()
+
+    async def completion_async(  # noqa: PLR6301
+        self, items: CliItems, client: Client
+    ) -> collections.abc.AsyncGenerator[Completion, None]:
+        """Asynchronous parameter completion for this builtin.
+
+        This is used only if :class:`AutoProbeOption` is enabled.
+
+        It is common that this only fetches the required data with client and
+        the completion is performed in :meth:`completion` only.
+        """
+        return
+        yield  # type: ignore
+
+    def validate(self, items: CliItems, client: Client) -> None:  # noqa: PLR6301
+        """Validate the parameter for this builtin."""
+        return
+
+    async def validate_async(self, items: CliItems, client: Client) -> None:  # noqa: PLR6301
+        """Asynchronously validate the parameter for this builtin.
+
+        This is used only if :class:`AutoProbeOption` is enabled.
+
+        It is common that this only fetches the required data with client and
+        the validation is performed in :meth:`validate` only. SHVCLI also
+        always uses completion and validation together and because completion
+        happens alongside with validation it is rather common to do this
+        probing in the :meth:`completion_async` only.
+        """
+        return
+
+    @abc.abstractmethod
+    async def run(self, items: CliItems, client: Client) -> None:
+        """Run the builtin."""
+
+
+class Builtins(StateVar, dict[str, Builtin]):
+    """All initialized builtins."""
+
+    def __init__(self, state: State) -> None:
+        super().__init__(state)
+        for builtin in Builtin.builtins:
+            if not inspect.isabstract(builtin):
+                builtin(self, state)

shvcli-0.7.0/shvcli/builtins/__init__.py

@@ -0,0 +1,27 @@
+"""All standard builtins.
+
+This module is imported in the top level init and thus all builtins imported
+here are automatically registered.
+"""
+
+from .broker import BuiltinSubscribe, BuiltinSubscriptions, BuiltinUnsubscribe
+from .cd import BuiltinCD
+from .file import BuiltinDownload, BuiltinUpload, BuiltinVerify
+from .help import BuiltinHelp
+from .scan import BuiltinScan
+from .set import BuiltinSet
+from .tree import BuiltinTree
+
+__all__ = [
+    "BuiltinCD",
+    "BuiltinDownload",
+    "BuiltinHelp",
+    "BuiltinScan",
+    "BuiltinSet",
+    "BuiltinSubscribe",
+    "BuiltinSubscriptions",
+    "BuiltinTree",
+    "BuiltinUnsubscribe",
+    "BuiltinUpload",
+    "BuiltinVerify",
+]

shvcli-0.7.0/shvcli/builtins/broker.py

@@ -0,0 +1,100 @@
+"""Broker specific builtins."""
+
+from __future__ import annotations
+
+import collections.abc
+
+from prompt_toolkit.completion import Completion
+from prompt_toolkit.validation import ValidationError
+
+from ..builtin import Builtin, Builtins
+from ..client import Client
+from ..cliitems import CliItems
+from ..state import State
+from ..tools.complet import comp_from, comp_signal_ri
+from ..tools.print import print_flist
+from ..tree import Tree
+
+
+class BuiltinSubscribe(Builtin):
+    """The implementation of ``subscribe`` builtin."""
+
+    def __init__(self, builtins: Builtins, state: State) -> None:
+        super().__init__(builtins, state)
+        builtins["subscribe"] = self
+        builtins["sub"] = self
+
+    @property
+    def description(self) -> tuple[str, str]:  # noqa: D102
+        return "[PATH:METHOD:SIGNAL]...", "Subscribe to given RPC RIs."
+
+    def completion(  # noqa: D102
+        self, items: CliItems, client: Client
+    ) -> collections.abc.Iterable[Completion]:
+        yield from comp_signal_ri(
+            items.param.rpartition(" ")[2], self.state.path, Tree(self.state)
+        )
+
+    async def completion_async(  # noqa: D102
+        self, items: CliItems, client: Client
+    ) -> collections.abc.AsyncGenerator[Completion, None]:
+        last = items.param.rpartition(" ")[2]
+        if ":" not in last:
+            path = items.path / last
+            await client.probe(path if last.endswith("/") else path.parent)
+
+        async for res in super().completion_async(items, client):
+            yield res
+
+    async def run(self, items: CliItems, client: Client) -> None:  # noqa: PLR6301, D102
+        for ri in items.ri_param:
+            await client.subscribe(ri)
+
+
+class BuiltinUnsubscribe(Builtin):
+    """The implementation of ``unsubscribe`` builtin."""
+
+    def __init__(self, builtins: Builtins, state: State) -> None:
+        super().__init__(builtins, state)
+        builtins["unsubscribe"] = self
+        builtins["usub"] = self
+
+    @property
+    def description(self) -> tuple[str, str]:  # noqa: D102
+        return "[PATH:METHOD:SIGNAL]...", "Unsubscribe to given or all RPC RIs."
+
+    def completion(  # noqa: PLR6301, D102
+        self, items: CliItems, client: Client
+    ) -> collections.abc.Iterable[Completion]:
+        yield from comp_from(items.param.rpartition(" ")[2], client.subscriptions())
+
+    def validate(self, items: CliItems, client: Client) -> None:  # noqa: PLR6301, D102
+        if missing := set(items.param.split()) - set(client.subscriptions()):
+            raise ValidationError(message=f"Not subscribed: {' '.join(missing)}")
+
+    async def run(self, items: CliItems, client: Client) -> None:  # noqa: PLR6301, D102
+        for ri in items.ri_param if items.param else client.subscriptions():
+            await client.unsubscribe(ri)
+
+
+class BuiltinSubscriptions(Builtin):
+    """The implementation of ``subscriptions`` builtin."""
+
+    def __init__(self, builtins: Builtins, state: State) -> None:
+        super().__init__(builtins, state)
+        builtins["subscriptions"] = self
+        builtins["subs"] = self
+
+    @property
+    def description(self) -> tuple[str, str]:  # noqa: D102
+        return "", "Display current subscriptions."
+
+    async def run(self, items: CliItems, client: Client) -> None:  # noqa: PLR6301, D102
+        subs = await client.call(".broker/currentClient", "subscriptions")
+        if isinstance(subs, dict):
+            print_flist(
+                ("", sub + (f"?{timeout}secs" if timeout is not None else ""))
+                for sub, timeout in subs.items()
+            )
+        else:
+            print(subs)

shvcli-0.7.0/shvcli/builtins/cd.py

@@ -0,0 +1,37 @@
+"""The cd builtin."""
+
+from __future__ import annotations
+
+import collections.abc
+
+from prompt_toolkit.completion import Completion
+
+from ..builtin import Builtin, Builtins
+from ..client import Client
+from ..cliitems import CliItems
+from ..state import State
+from ..tools.complet import comp_path
+from ..tree import Tree
+
+
+class BuiltinCD(Builtin):
+    """The implementation of ``cd`` builtin that allows change to invalid path."""
+
+    def __init__(self, builtins: Builtins, state: State) -> None:
+        super().__init__(builtins, state)
+        builtins["cd"] = self
+
+    @property
+    def description(self) -> tuple[str, str]:  # noqa: D102
+        return "[PATH]", "Change to given path even if it is invalid."
+
+    def completion(  # noqa: D102
+        self, items: CliItems, client: Client
+    ) -> collections.abc.Iterable[Completion]:
+        yield from comp_path(items.param, self.state.path, Tree(self.state), "")
+
+    async def run(self, items: CliItems, client: Client) -> None:  # noqa: D102
+        try:
+            self.state.path = items.path_param
+        except ValueError as exc:
+            print(exc)