socx-cli 0.1.0__py3-none-any.whl

src/socx/cli.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from types import CodeType
+
+import click
+from trogon import tui
+
+from .log import logger
+from .console import console
+from .config import settings
+from .config import USER_CONFIG_DIR
+
+
+_CONTEXT_SETTINGS = dict(
+    help_option_names=[
+        "?",
+        "-h",
+        "--help",
+    ],
+)
+
+
+class RichHelp:
+    def get_help(self, ctx: click.Context) -> None:
+        return self._header(ctx) + super().get_help(ctx) + self._footer()
+
+    def _header(self, ctx: click.Context) -> str:
+        path_text = "->".join(ctx.command_path.split())
+        with console.capture() as header:
+            console.line(1)
+            console.rule("")
+            console.print("[b]Help & Usage", justify="center")
+            console.print(f"[b][u]({path_text})", justify="center")
+        return header.get()
+
+    def _footer(self) -> str:
+        with console.capture() as footer:
+            console.line(1)
+            console.rule("")
+        return footer.get()
+
+
+class RichCommand(RichHelp, click.Command):
+    pass
+
+
+class RichGroup(RichHelp, click.Group):
+    def group(self, *args, **kwargs) -> click.RichGroup:
+        kwargs["cls"] = RichGroup
+        return super().group(*args, **kwargs)
+
+    def command(self, *args, **kwargs) -> click.RichCommand:
+        kwargs["cls"] = RichCommand
+        return super().command(*args, **kwargs)
+
+
+class CmdLine(RichGroup, click.Group):
+    def __init__(self, *args, **kwargs):
+        kwargs["context_settings"] = _CONTEXT_SETTINGS
+        super().__init__(*args, **kwargs)
+        self._plugins = None
+
+    @property
+    def plugins(self) -> list[click.Command]:
+        if self._plugins is None:
+            self._load_plugins()
+        return self._plugins
+
+    @property
+    def plugin_names(self) -> list[str]:
+        return [cmd.name for cmd in self.plugins.values()]
+
+    def get_command(self, ctx: click.Context, name: str) -> CodeType:
+        logger.debug(f"get_command({ctx=}, {name=}) was called...")
+        if name in self.plugins and self.plugins[name] is not None:
+            rv = self.plugins[name]
+            logger.debug(
+                f"get_command({ctx=}, {name=}) returning plugin {rv=}."
+            )
+            return rv
+        rv = super().get_command(ctx, name)
+        logger.debug(f"get_command({ctx=}, {name=}) returning command {rv=}.")
+        return rv
+
+    def list_commands(self, ctx) -> list[str]:
+        logger.debug(f"list_commands({ctx=}) was called...")
+        rv = list(self.plugins.values())
+        rv += super().list_commands(ctx)
+        logger.debug(f"list_commands({ctx=}) returning {rv=}.")
+        return rv
+
+    @classmethod
+    def _listify(cls, args: str | list | tuple | set | dict) -> list:
+        logger.debug(f"{cls.__name__}._listify called with {args=}")
+        if isinstance(args, list):
+            rv = args
+        elif isinstance(args, dict):
+            rv = list(args.values())
+        elif isinstance(args, set | tuple):
+            rv = list(args)
+        else:
+            rv = [args]
+        logger.debug(f"{cls.__name__}._listify returning value '{rv=}'")
+        return rv
+
+    @classmethod
+    def _unique(cls, args: str | list | tuple | set) -> list:
+        logger.debug(f"{cls.__name__}._unique called with {args=}")
+        lookup = set()
+        args = cls._listify(args)
+        args = [
+            x for x in args if args not in lookup and lookup.add(x) is None
+        ]
+        logger.debug(f"{cls.__name__}._unique returning {args=}")
+
+    @classmethod
+    def _compile(cls, file, name):
+        logger.debug(f"{cls.__name__}._compile called with {file=}, {name=}")
+        ns = {}
+        logger.debug(f"compiling '{name}' (plugin: {file})...")
+        code = compile(file.read_text(), name, "exec")
+        logger.debug(f"'{name}' compiled.")
+        eval(code, ns, ns)
+        logger.debug(f"'{name}' evaluated.")
+        plugin = ns.get("cli")
+        if plugin:
+            logger.debug(f"'{name}' loaded.")
+            logger.debug(f"{cls.__name__}._compile returning {plugin=}")
+            return plugin
+        cls._missing_cli_err(name)
+        return None
+
+    def _load_plugins(self) -> None:
+        if self._plugins is None:
+            self._plugins = {}
+        else:
+            self._plugins.clear()
+        for name, path in settings.plugins.items():
+            cmd = self._compile(path, name)
+            self._plugins[name] = cmd
+        for name, cmd in self._plugins.items():
+            self.add_command(cmd, name)
+
+    @classmethod
+    def _missing_cli_err(cls, name) -> None:
+        err = (
+            f"failed to load '{name}' (plugin).\n"
+            "please make ensure that function 'cli' is defined and has "
+            "either @group or @command decorator applied."
+        )
+        exc = ValueError(err)
+        logger.exception(err, exc_info=exc)
+        logger.debug(f"'{name}' (plugin) unloaded", exc_info=exc)
+
+
+@tui()
+@click.group("socx", cls=CmdLine)
+@click.option(
+    "--configure/--no-configure",
+    default=True,
+    show_default=True,
+    help="load/dont-load user configurations at startup.",
+)
+def cli(configure: bool) -> None:
+    """SoC team tool executer and plugin manager."""
+    if configure:
+        from .config._config import _load_settings
+
+        _load_settings(USER_CONFIG_DIR)

src/socx/config/__init__.py

@@ -0,0 +1,88 @@
+"""
+Management of application configuration settings.
+
+Configurations are defined in .toml files located inside the 'config'
+directory.
+
+The default configurations are under settings.toml and can be used as a
+reference.
+
+Local configurations may be defined in 'settings.local.toml'.
+
+Any local configration have priority over the defaults and will either
+override the default, or be merged with it if dynaconf_merge is true,
+and the keys do not conflict.
+
+Reference the settings.toml file for an example of how configurations are
+defined.
+
+For additional information regarding the internals of this module, reference
+dynaconf documentation on its official-site/github-repository.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.tree import Tree
+from rich.table import Table
+from dynaconf import Dynaconf
+from dynaconf.utils.boxing import DynaBox
+
+from ._config import _to_tree
+from ._config import _get_settings
+
+__all__ = (
+    # API
+    "settings",
+    "settings_tree",
+    # Metadata
+    "APP_NAME",
+    "APP_AUTHOR",
+    "APP_VERSION",
+    # Directories
+    "USER_LOG_DIR",
+    "USER_DATA_DIR",
+    "USER_CACHE_DIR",
+    "USER_STATE_DIR",
+    "USER_CONFIG_DIR",
+    "USER_RUNTIME_DIR",
+)
+
+
+from ._config import APP_NAME as APP_NAME
+from ._config import APP_AUTHOR as APP_AUTHOR
+from ._config import APP_VERSION as APP_VERSION
+from ._config import USER_LOG_DIR as USER_LOG_DIR
+from ._config import USER_DATA_DIR as USER_DATA_DIR
+from ._config import USER_CACHE_DIR as USER_CACHE_DIR
+from ._config import USER_STATE_DIR as USER_STATE_DIR
+from ._config import USER_CONFIG_DIR as USER_CONFIG_DIR
+from ._config import USER_RUNTIME_DIR as USER_RUNTIME_DIR
+
+
+settings = _get_settings()
+"""
+Global settings instance.
+
+Any attribute/key accesses to this instance trigger a lazy loading operation
+which will attempt to find and read the value of the attribute from any of the
+.toml configuration files under the 'settings' directory.
+"""
+
+
+def reconfigure(path: Path) -> Dynaconf:
+    from ._config import _load_settings
+    _load_settings(path)
+
+
+def settings_tree(
+    root: Dynaconf | DynaBox | dict,
+    label: str = "Settings",
+) -> Tree | Table:
+    """Get a tree representation of a dynaconf settings instance."""
+    if isinstance(root, Dynaconf):
+        root = root.as_dict()
+    if not isinstance(root, dict | list | tuple | set):
+        root = str(root)
+    return _to_tree(label, root)

src/socx/config/_config.py

@@ -0,0 +1,357 @@
+from __future__ import annotations
+
+import sys
+from typing import Any
+from typing import Final
+from pathlib import Path
+from importlib.metadata import version
+from importlib.metadata import metadata
+from importlib.metadata import PackageMetadata
+from collections.abc import Iterable
+
+from click import open_file
+from rich.tree import Tree
+from rich.table import Table
+from rich.console import Group
+from rich.console import Console
+from rich.logging import RichHandler
+from dynaconf import Dynaconf
+from dynaconf import ValidationError
+from dynaconf import add_converter
+from dynaconf.validator import empty
+from dynaconf.validator import Validator
+from platformdirs import site_data_dir
+from platformdirs import site_cache_dir
+from platformdirs import site_config_dir
+from platformdirs import site_runtime_dir
+from platformdirs import user_log_dir
+from platformdirs import user_data_dir
+from platformdirs import user_state_dir
+from platformdirs import user_cache_dir
+from platformdirs import user_config_dir
+from platformdirs import user_runtime_dir
+
+from ..log import logger
+from ..log import add_handler
+from ..log import DEFAULT_LEVEL
+from ..log import DEFAULT_TIME_FORMAT
+from ..validators import PathValidator
+
+
+__author__ = "Sagi Kimhi <sagi.kim5@gmail.com>"
+
+__version__ = version(__package__.partition(".")[0])
+
+__metadata__ = metadata(__package__.partition(".")[0])
+
+
+PACKAGE_NAME: Final[str] = __package__.partition(".")[0]
+"""Package name."""
+
+PACKAGE_PATH: Final[Path] = Path(sys.modules[PACKAGE_NAME].__file__).parent
+"""Absolute path to package."""
+
+PACKAGE_AUTHOR: Final[str] = __author__
+"""Package author."""
+
+PACKAGE_VERSION: Final[str] = __version__
+"""Package version."""
+
+PACKAGE_METADATA: Final[PackageMetadata] = __metadata__
+"""Package metadata."""
+
+APP_NAME: Final[str] = PACKAGE_NAME
+"""Application name."""
+
+APP_AUTHOR: Final[str] = PACKAGE_METADATA
+"""Application author"""
+
+APP_VERSION: Final[str] = PACKAGE_VERSION
+"""Application version."""
+
+SITE_DATA_DIR: Final[Path] = Path(
+    site_data_dir(
+        appname=APP_NAME,
+        version=APP_VERSION,
+        appauthor=APP_AUTHOR,
+        ensure_exists=False,
+    )
+).resolve()
+"""Absolute path to platform's native application data directory."""
+
+SITE_CACHE_DIR: Final[Path] = Path(
+    site_cache_dir(
+        appname=APP_NAME,
+        version=APP_VERSION,
+        appauthor=APP_AUTHOR,
+        ensure_exists=False,
+    )
+).resolve()
+"""Absolute path to platform's native application cache directory."""
+
+SITE_CONFIG_DIR: Final[Path] = Path(
+    site_config_dir(
+        appname=APP_NAME,
+        version=APP_VERSION,
+        appauthor=APP_AUTHOR,
+        ensure_exists=False,
+    )
+).resolve()
+"""Absolute path to platform's native application config directory."""
+
+SITE_RUNTIME_DIR: Final[Path] = Path(
+    site_runtime_dir(
+        appname=APP_NAME,
+        version=APP_VERSION,
+        appauthor=APP_AUTHOR,
+        ensure_exists=False,
+    )
+).resolve()
+"""Absolute path to platform's native application runtime directory."""
+
+USER_LOG_DIR: Final[Path] = Path(
+    user_log_dir(
+        appname=APP_NAME,
+        version=APP_VERSION,
+        appauthor=APP_AUTHOR,
+        ensure_exists=True,
+    )
+)
+"""Absolute path to platform's native application logs directory."""
+
+USER_DATA_DIR: Final[Path] = Path(
+    user_data_dir(
+        appname=APP_NAME,
+        version=APP_VERSION,
+        appauthor=APP_AUTHOR,
+        ensure_exists=True,
+    )
+).resolve()
+"""Absolute path to platform's native application data directory."""
+
+USER_CACHE_DIR: Final[Path] = Path(
+    user_cache_dir(
+        appname=APP_NAME,
+        version=APP_VERSION,
+        appauthor=APP_AUTHOR,
+        ensure_exists=True,
+    )
+).resolve()
+"""Absolute path to platform's native application cache directory."""
+
+USER_STATE_DIR: Final[Path] = Path(
+    user_state_dir(
+        appname=APP_NAME,
+        version=APP_VERSION,
+        appauthor=APP_AUTHOR,
+        ensure_exists=True,
+    )
+).resolve()
+"""Absolute path to platform's native application state directory."""
+
+USER_CONFIG_DIR: Final[Path] = Path(
+    user_config_dir(
+        appname=APP_NAME,
+        version=APP_VERSION,
+        appauthor=APP_AUTHOR,
+        ensure_exists=True,
+    )
+).resolve()
+"""Absolute path to platform's native application config directory."""
+
+USER_RUNTIME_DIR: Final[Path] = Path(
+    user_runtime_dir(
+        appname=APP_NAME,
+        version=APP_VERSION,
+        appauthor=APP_AUTHOR,
+        ensure_exists=True,
+    )
+).resolve()
+"""Absolute path to platform's native application runtime directory."""
+
+_init_done: bool = False
+
+_settings: Dynaconf | dict = {
+    name: value for name, value in vars().items() if not name.startswith("_")
+}
+
+_user_log: Path = USER_LOG_DIR / "run.log"
+
+_static_dir: Path = Path(PACKAGE_PATH) / "static" / "toml"
+
+_static_file: Path = "settings.toml"
+
+_user_settings: Path = Path(USER_CONFIG_DIR) / "settings.toml"
+
+_static_settings: Path = Path(_static_dir) / _static_file
+
+_settings_kwargs = dict(
+    encoding="utf-8",
+    lowercase_read=True,
+    envvar_prefix=APP_NAME.upper(),
+    load_dotenv=True,
+    environments=False,
+    dotenv_override=True,
+    sysenv_fallback=True,
+    validate_on_update="all",
+    validators=[Validator(r"convert.*", ne=empty)],
+)
+
+
+def _init_module() -> None:
+    global _init_done
+    logger.debug("initializing module.")
+    _init_logger()
+    _init_converters()
+    _load_settings()
+    _validate_settings()
+    _init_done = True
+    logger.debug("module initialized.")
+
+
+def _init_logger() -> None:
+    global logger
+    logger.debug("initializing logger.")
+    add_handler(
+        RichHandler(
+            level=DEFAULT_LEVEL,
+            console=Console(
+                file=open_file(
+                    filename=str(_user_log),
+                    mode="w",
+                    encoding="utf-8",
+                    lazy=True,
+                ),
+                tab_size=4,
+                width=110,
+            ),
+            markup=False,
+            show_time=True,
+            show_level=True,
+            rich_tracebacks=True,
+            locals_max_string=None,
+            locals_max_length=None,
+            tracebacks_theme="monokai",
+            omit_repeated_times=False,
+            tracebacks_word_wrap=False,
+            tracebacks_show_locals=True,
+            log_time_format=DEFAULT_TIME_FORMAT,
+        )
+    )
+    logger.info("logging initialized.")
+    logger.info(f"logging at path: {_user_log}")
+
+
+def _init_converters() -> None:
+    logger.debug("initializing settings converters.")
+    add_converter("path", lambda x: Path(str(x)).resolve())
+    add_converter("glob", lambda x: next(Path().glob(x)).resolve())
+    logger.debug("settings converters initialized.")
+
+
+def _load_settings(
+    path: Path | None = None,
+    preload: Iterable[str] | None = None,
+    includes: Iterable[str] | None = None,
+) -> Dynaconf:
+    global _settings
+    path = path if path else _static_settings
+    preload = preload if preload else []
+    includes = includes if includes else []
+    logger.debug(f"loading settings from {path}.")
+    settings = Dynaconf(
+        root_path=path.parent,
+        preload=preload,
+        settings_files=[str(path)],
+        includes=includes,
+        **_settings_kwargs,
+        **_settings.as_dict()
+        if isinstance(_settings, Dynaconf)
+        else _settings,
+    )
+    settings.update(_settings)
+    _settings = settings
+    logger.debug("settings loaded.")
+    return _settings
+
+
+def _validate_settings() -> None:
+    global _settings
+    logger.debug("Validating settings.")
+    for lang in _settings.convert:
+        _settings.validators.register(_get_convert_validators(lang))
+    accumulative_errors = ""
+    try:
+        _settings.validators.validate_all()
+    except ValidationError as e:
+        accumulative_errors = e.details
+        logger.debug("Settings validation failed.")
+    else:
+        logger.debug("Settings validation passed.")
+    finally:
+        if accumulative_errors:
+            errors = ValidationError(accumulative_errors)
+            logger.exception(accumulative_errors, exc_info=errors)
+
+
+def _get_settings() -> Dynaconf:
+    if not _init_done:
+        _init_module()
+    return _settings
+
+
+def _get_convert_validators(lang: str) -> list[Validator]:
+    (
+        Validator(
+            f"convert.{lang}.source",
+            condition=PathValidator.source_validator,
+            must_exist=True,
+            ne=empty,
+        ),
+    )
+    (
+        Validator(
+            f"convert.{lang}.target",
+            condition=PathValidator.target_validator,
+            must_exist=True,
+            ne=empty,
+        ),
+    )
+
+
+def _to_tree(key: str, val: Any) -> Tree | Table:
+    if isinstance(val, list | set | tuple):
+        node = Tree(key)
+        for i, v in enumerate(val):
+            k = f"{key}[{i}]"
+            if isinstance(v, dict):
+                node.add(Group(k, _to_table("", v)))
+            else:
+                node.add(_to_table(k, v))
+    elif isinstance(val, dict):
+        node = Tree(key)
+        for k, v in val.items():
+            node.add(_to_tree(k, v))
+    else:
+        node = _to_table(key, str(val))
+    return node
+
+
+def _to_table(key: str, val: Any) -> Table:
+    node = Table()
+    node.show_lines = True
+    node.show_header = True
+    node.show_footer = False
+    if isinstance(val, list | tuple | set):
+        node.add_column("index")
+        node.add_column(key)
+        for i, v in enumerate(val):
+            node.add_row(str(i), str(v))
+    elif isinstance(val, dict):
+        for k in val:
+            node.add_column(k)
+        node.add_row(*[str(v) for v in val.values()])
+    else:
+        node.add_column(str(key))
+        node.add_row(str(val))
+    return node

src/socx/console.py

@@ -0,0 +1,8 @@
+from rich import pretty
+from rich.console import Console
+
+__all__ = ("console",)
+
+_console: Console = Console(record=True, tab_size=4, force_terminal=True)
+pretty.install(_console, overflow="ignore", indent_guides=True, max_length=78)
+console = _console

src/socx/converter.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import abc
+from typing import override
+from dataclasses import dataclass
+
+from dynaconf.utils.boxing import DynaBox
+
+from .log import logger
+from .config import settings
+from .reader import Reader
+from .reader import FileReader
+from .writer import Writer
+from .writer import FileWriter
+from .parser import Parser
+from .parser import LstParser
+from .tokenizer import Tokenizer
+from .tokenizer import LstTokenizer
+from .formatter import Formatter
+from .formatter import SystemVerilogFormatter
+
+
+@dataclass(unsafe_hash=True)
+class Converter(abc.ABC):
+    reader: Reader | None = None
+    writer: Writer | None = None
+    parser: Parser | None = None
+    tokenizer: Tokenizer | None = None
+    formatter: Formatter | None = None
+
+    @property
+    def cfg(self) -> DynaBox:
+        return settings.convert[self.lang]
+
+    @property
+    @abc.abstractmethod
+    def lang(self) -> DynaBox: ...
+
+    @abc.abstractmethod
+    def convert(self) -> None: ...
+
+
+@dataclass
+class LstConverter(Converter):
+    def __post_init__(self) -> None:
+        self.parser = LstParser()
+        self.reader = FileReader(
+            self.cfg.source, self.cfg.includes, self.cfg.excludes
+        )
+        self.writer = FileWriter(self.cfg.target)
+        self.tokenizer = LstTokenizer()
+        self.formatter = SystemVerilogFormatter()
+
+    @override
+    @property
+    def lang(self) -> DynaBox:
+        return "lst"
+
+    def convert(self) -> None:
+        inputs = self.reader.read()
+        outputs = {path: "" for path in inputs}
+        self.parser.parse()
+        for path, input_text in inputs.items():
+            matches = self.tokenizer.tokenize(input_text)
+            outputs[path] = self.formatter.format(
+                self.tokenizer.token_map, matches, self.parser.sym_table
+            )
+            logger.debug(f"{input_text=}")
+            logger.debug(f"{outputs[path]=}")
+            logger.debug(f"{self.parser.sym_table=}")
+            self.writer.write(outputs[path], path.with_suffix(".svh").name)

src/socx/core/__init__.py

@@ -0,0 +1,2 @@
+from .mixins import TypedPtrMixin as TypedPtrMixin
+from .mixins import UIDMixin as UIDMixin