shvcli 0.6.2__tar.gz → 0.8.0__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: shvcli
-Version: 0.6.2
+Version: 0.8.0
 Summary: Silicon Heaven CLI access application
 Author: Elektroline a.s.
 License: MIT License
@@ -27,8 +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
 Classifier: Intended Audience :: End Users/Desktop
@@ -38,10 +36,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.10.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 +101,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,16 +142,16 @@ 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.
-
+* **history_count**: Integer number used for number of records requested at time
+  for ``!history`` builtin.
 
 Example configuration file:
 
@@ -200,6 +205,19 @@ 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.
+
+**history**: is helper to list recorded history of signals by ``.history`` API.
+The listing is incremental in ``history_count`` configured number of records and
+in the order from the newest ones.
+
 
 Special methods ``ls`` and ``dir``
 ----------------------------------
@@ -211,3 +229,21 @@ 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.
+
+You can see ``raw`` option to disable this behavior.
+
+
+OAuth2 login
+------------
+
+SHVCLI supports non-standard login method OAuth2. This is not defined by SHV
+standard. The non-standard URL query ``oauth2=y`` is accepted to perform the
+OAuth2 login. The login is facilitated by web browser. SHVCLI will start server
+on ``tcp://localhost:37719/`` to be able to receive token.
+
+
+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.8.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,16 +97,16 @@ 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.
-
+* **history_count**: Integer number used for number of records requested at time
+  for ``!history`` builtin.
 
 Example configuration file:
 
@@ -155,6 +160,19 @@ 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.
+
+**history**: is helper to list recorded history of signals by ``.history`` API.
+The listing is incremental in ``history_count`` configured number of records and
+in the order from the newest ones.
+
 
 Special methods ``ls`` and ``dir``
 ----------------------------------
@@ -166,3 +184,21 @@ 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.
+
+You can see ``raw`` option to disable this behavior.
+
+
+OAuth2 login
+------------
+
+SHVCLI supports non-standard login method OAuth2. This is not defined by SHV
+standard. The non-standard URL query ``oauth2=y`` is accepted to perform the
+OAuth2 login. The login is facilitated by web browser. SHVCLI will start server
+on ``tcp://localhost:37719/`` to be able to receive token.
+
+
+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.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "shvcli"
-version = "0.6.2"
+version = "0.8.0"
 description = "Silicon Heaven CLI access application"
 readme = "README.rst"
 license = {file = "LICENSE"}
@@ -9,8 +9,6 @@ authors = [
 ]
 classifiers = [
   "Development Status :: 4 - Beta",
-  "License :: OSI Approved :: MIT License",
-  "Programming Language :: Python :: 3",
   "Operating System :: OS Independent",
   "Environment :: Console",
   "Intended Audience :: End Users/Desktop",
@@ -20,10 +18,11 @@ classifiers = [
 ]
 requires-python = ">=3.11"
 dependencies = [
-  "pyshv >= 0.8.0",
+  "pyshv >= 0.10.0",
   "prompt_toolkit",
   "pygments",
   "pyxdg",
+  "more-itertools",
 ]
 
 [project.urls]
@@ -39,6 +38,8 @@ build-backend = "setuptools.build_meta"
 [tool.setuptools.packages.find]
 [tool.setuptools.package-data]
 "*" = ["py.typed"]
+[tool.setuptools.cmdclass]
+build_py = "shvcli.__setuptools__.BuildPy"
 
 [tool.coverage.run]
 branch = true

shvcli-0.8.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.8.0/shvcli/__main__.py

@@ -0,0 +1,35 @@
+"""Implementation of command line application."""
+
+import asyncio
+
+from .afterconn import Afterconn
+from .args import args_apply, args_parse
+from .cli import run
+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 Url(state).connect()
+        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.8.0/shvcli/__setuptools__.py

@@ -0,0 +1,18 @@
+"""Setuptools hook used to replace __version__.py file."""
+
+import pathlib
+
+from setuptools.command.build_py import build_py as _build_py
+
+
+class BuildPy(_build_py):
+    """Custom package build step."""
+
+    def run(self) -> None:  # noqa: D102
+        package = pathlib.Path(__file__).parent.name
+        buildlib = pathlib.Path(self.build_lib) / package
+        buildlib.mkdir(parents=True, exist_ok=True)
+        version = self.distribution.metadata.version
+        (buildlib / "__version__.py").write_text(f'VERSION = "{version}"\n')
+        super().run()
+        (buildlib / "__setuptools__.py").unlink()

shvcli-0.8.0/shvcli/__version__.py

@@ -0,0 +1,24 @@
+"""The loader of the version for source file only installation.
+
+It looks for pyproject.toml file in upper directory and loads version from
+there.
+
+This file is overwritten during distribution build to contain only constant
+VERSION. Please see __setuptools__.py for details.
+"""
+
+import pathlib
+import tomllib
+
+
+def _get_version() -> str:
+    pyproject = pathlib.Path(__file__).parent.parent / "pyproject.toml"
+    if pyproject.exists():
+        with pyproject.open("rb") as f:
+            res = tomllib.load(f)["project"]["version"]
+            if isinstance(res, str):
+                return res
+    return "unknown"
+
+
+VERSION = _get_version()

shvcli-0.8.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.8.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.8.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.8.0/shvcli/builtins/__init__.py

@@ -0,0 +1,29 @@
+"""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 .history import BuiltinHistory
+from .scan import BuiltinScan
+from .set import BuiltinSet
+from .tree import BuiltinTree
+
+__all__ = [
+    "BuiltinCD",
+    "BuiltinDownload",
+    "BuiltinHelp",
+    "BuiltinHistory",
+    "BuiltinScan",
+    "BuiltinSet",
+    "BuiltinSubscribe",
+    "BuiltinSubscriptions",
+    "BuiltinTree",
+    "BuiltinUnsubscribe",
+    "BuiltinUpload",
+    "BuiltinVerify",
+]