tgzr.cli 0.1.2__py3-none-any.whl

tgzr/cli/__main__.py

@@ -0,0 +1,7 @@
+import sys
+
+if __name__ == "__main__":
+    # NB: we need a absolute imports here for pyinstaller to work
+    import tgzr.cli.main
+
+    tgzr.cli.main.main()

tgzr/cli/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.2'
+__version_tuple__ = version_tuple = (0, 1, 2)
+
+__commit_id__ = commit_id = None

tgzr/cli/add_plugins.py

@@ -0,0 +1,109 @@
+import os
+import traceback
+import importlib.metadata
+
+import click
+
+
+def add_plugins(group):
+
+    if not isinstance(group, click.Group):
+        raise TypeError(
+            f"plugins can only be attached to an instance of"
+            f" 'click.Group()' not: {repr(group)}"
+        )
+
+    entry_point_group = "tgzr.cli.plugin"
+
+    all_entry_points = importlib.metadata.entry_points(group=entry_point_group)
+
+    for ep in all_entry_points:
+        try:
+            installer = ep.load()
+            installer(group)
+            # group.add_command(ep.load())
+
+        # Catch all exceptions (technically not 'BaseException') and
+        # instead register a special 'BrokenCommand()'. Otherwise, a single
+        # plugin that fails to load and/or register will make the CLI
+        # inoperable. 'BrokenCommand()' explains the situation to users.
+        except Exception as e:
+            group.add_command(BrokenCommand(ep, e))
+
+    return group
+
+
+class BrokenCommand(click.Command):
+    """Represents a plugin ``click.Command()`` that failed to load.
+
+    Can be executed just like a ``click.Command()``, but prints information
+    for debugging and exits with an error code.
+    """
+
+    def __init__(self, entry_point, exception):
+        """
+        :param importlib.metadata.EntryPoint entry_point:
+            Entry point that failed to load.
+        :param Exception exception:
+            Raised when attempting to load the entry point associated with
+            this instance.
+        """
+
+        super().__init__(entry_point.name)
+
+        # There are several ways to get a traceback from an exception, but
+        # 'TracebackException()' seems to be the most portable across actively
+        # supported versions of Python.
+        tbe = traceback.TracebackException.from_exception(exception)
+
+        # A message for '$ cli command --help'. Contains full traceback and a
+        # helpful note. The intention is to nudge users to figure out which
+        # project should get a bug report since users are likely to report the
+        # issue to the developers of the CLI utility they are directly
+        # interacting with. These are not necessarily the right developers.
+        self.help = (
+            "{ls}ERROR: entry point '{module}:{name}' could not be loaded."
+            " Contact its author for help.{ls}{ls}{tb}"
+        ).format(
+            module=entry_point.module,
+            name=entry_point.name,
+            ls=os.linesep,
+            tb="".join(tbe.format()),
+        )
+
+        # Replace the broken command's summary with a warning about how it
+        # was not loaded successfully. The idea is that '$ cli --help' should
+        # include a clear indicator that a subcommand is not functional, and
+        # a little hint for what to do about it. U+2020 is a "dagger", whose
+        # modern use typically indicates a footnote.
+        self.short_help = (
+            f"\u2020 Warning: could not load plugin. Invoke command with"
+            f" '--help' for traceback."
+        )
+
+    def invoke(self, ctx):
+        """Print traceback and debugging message.
+
+        :param click.Context ctx:
+            Active context.
+        """
+
+        click.echo(self.help, color=ctx.color, err=True)
+        ctx.exit(1)
+
+    def parse_args(self, ctx, args):
+        """Pass arguments along without parsing.
+
+        :param click.Context ctx:
+            Active context.
+        :param list args:
+            List of command line arguments.
+        """
+
+        # Do not attempt to parse these arguments. We do not know why the
+        # entry point failed to load, but it is reasonable to assume that
+        # argument parsing will not work. Ultimately the goal is to get the
+        # 'Command.invoke()' method (overloaded in this class) to execute
+        # and provide the user with a bit of debugging information.
+
+        return args

tgzr/cli/install.py

@@ -0,0 +1,147 @@
+from typing import Callable
+
+import os
+import sys
+from pathlib import Path
+import tempfile
+import platform
+
+import uv
+
+
+def install(
+    home: Path | str,
+    studio_name: str,
+    python_version: str | None = "3.12",
+    default_index: str | None = None,
+    find_links: str | None = None,
+    allow_prerelease: bool = False,
+    echo: Callable[[str], None] | None = None,
+):
+    """
+    Install TGZR by creating a tmp venv with tgzr.shell, then
+    using this tgzr.cli to create a Studio at the requested location.
+
+    May raise: FileExistsError, ChildProcessError.
+    """
+    if echo is None:
+        echo = lambda message: print(message)
+
+    home = Path(home)
+    studio_path = home / "Workspace" / studio_name
+    if studio_path.exists():
+        raise FileExistsError(f"The Studio {studio_path} already exists. Aborting.")
+
+    echo(f"Installing tgzr at {home}, creating Studio {studio_name}")
+
+    # We need to create the `.tgzr` file at requested home first, or
+    # the cli may discover existing locations and create the Studio
+    # in an existing installation:
+    home.mkdir(exist_ok=True, parents=True)
+    (home / ".tgzr").touch()
+
+    venv_path = tempfile.mkdtemp(prefix="tgzr_install_tmp_venv")
+    echo(f"Creating temp venv: {venv_path}")
+
+    # Clean up PATH
+    # (we've seen situations where things in the PATH would mess up the installation )
+    PATH = os.environ.get("PATH", "")
+    path = PATH.split(os.pathsep)
+    banned_words = ["python", ".poetry"]
+    clean_path = []
+    for i in path:
+        keep = True
+        for word in banned_words:
+            if word in i.lower():
+                keep = False
+                break
+        if keep:
+            clean_path.append(i)
+    os.environ["PATH"] = os.pathsep.join(clean_path)
+
+    if 0:
+        # This does not work as pyinstaller script: sys.executable is wrong so venv is messed up
+        print(sys.executable)
+        cmd = f"{sys.executable} -m uv venv --prompt TGZR_installer {venv_path}"
+        echo(f"EXEC: {cmd}")
+        ret = os.system(cmd)
+        print("--->", ret)
+    elif 0:
+        # This does not work as pyinstaller script: sys.executable is wrong so venv is messed up
+        import venv
+
+        try:
+            venv.main(["--without-pip", "--prompt", "TGZR-Installer", venv_path])
+        except Exception:
+            raise
+    else:
+        # This does work as pyinstaller script: we are delegating everything to uv
+
+        # Use this to inspect the content of the pyinstaller archive when
+        # we run as a pysintaller script:
+        # if getattr(sys, "frozen", False) and hasattr(sys, "_MEIPASS"):
+        #     ROOT = sys._MEIPASS
+        #     print("FROZEN CONTENT:", os.listdir(ROOT))
+
+        try:
+            # NOTE: this also works when we're a pysintaller script thanks to the
+            # data arg of the Analysis in the pyinstall spec file:
+            # it keeps the uv executable installed in your current venv
+            # (it exists because we have uv in the project requirement)
+            # and place it in a "bin" folder inside the pysintaller archive.
+            # This bin folder is looked up by uv.find_uv_bin() so we're
+            # good.
+            uv_exe = uv.find_uv_bin()
+        except Exception as err:
+            # This should not occur ¯\\_(ツ)_/¯
+            echo(f"Oops, could not find uv: {err}")
+        else:
+            cmd = (
+                f"{uv_exe} venv -p {python_version} --prompt TGZR-Installer {venv_path}"
+            )
+            echo(f"EXEC: {cmd}")
+            ret = os.system(cmd)
+            if ret:
+                raise Exception("Error creating venv with cmd: {cmd}")
+
+        default_index_options = ""
+        if default_index:
+            default_index_options = f"--default-index {default_index}"
+
+        find_links_options = ""
+        if find_links:
+            find_links_options = f"--find-links {find_links}"
+
+        prerelease_options = ""
+        if allow_prerelease:
+            prerelease_options = "--prerelease=allow"
+
+        # Install tgzr.shell in the temp venv:
+        cmd = f"{uv_exe} pip install {default_index_options} {find_links_options} {prerelease_options} --python {venv_path} tgzr.shell"
+        echo(f"EXEC: {cmd}")
+        ret = os.system(cmd)
+        if ret:
+            raise ChildProcessError("Error installing packages in venv with cmd: {cmd}")
+
+        # Use tgzr.cli from the temp venv to create the Studio
+        # ! Don't forget to pass the index related options there !
+        index_options = ""
+        if default_index:
+            index_options += f" --default-index {default_index}"
+        if find_links:
+            index_options += f" --find-links {find_links}"
+        if allow_prerelease:
+            index_options += " --allow-prerelease"
+        if 0:
+            # IDKW but this does not work, it runs the orignal tgzr cmd instead of the venv one :[
+            cmd = f"{uv_exe} run --python {venv_path} tgzr --home {home} studio create {index_options} {studio_name}"
+        else:
+            if platform.system() == "Windows":
+                tgzr_exe = f"{venv_path}/Scripts/tgzr"
+            else:
+                tgzr_exe = f"{venv_path}/bin/tgzr"
+        cmd = f"{tgzr_exe} --home {home} studio create {index_options}  {studio_name}"
+        ret = os.system(cmd)
+        echo(f"EXEC: {cmd}")
+        if ret:
+            raise ChildProcessError(f"Error creating Studio with cmd: {cmd}")

tgzr/cli/install_cli.py

@@ -0,0 +1,143 @@
+from pathlib import Path
+
+import click
+
+from ._version import __version__
+from .install import install
+
+
+@click.command("install")
+@click.option(
+    "-S",
+    "--studio",
+    default=None,
+    help="Name of the Studio to create.",
+)
+@click.option(
+    "-H",
+    "--home",
+    help="Path to install to. Default to current dir. Created if needed.",
+)
+@click.option(
+    "-p",
+    "--python-version",
+    default="3.12",
+    help="The python version to use. Defaults to 3.12 which in the minmum (3.14 is know to cause issue with nicegui on windows)",
+)
+@click.option(
+    "--default-index",
+    help="The URL of the default package index (by default: <https://pypi.org/simple>).",
+)
+@click.option(
+    "-f",
+    "--find-links",
+    help="path a folder containing packages to install. Usefull in no-internet situations.",
+)
+@click.option(
+    "--allow-prerelease",
+    is_flag=True,
+    help="Allow installing tgzr using pre-release packages. Default is False.",
+)
+@click.option(
+    "-i",
+    "--info",
+    is_flag=True,
+    help="Show info about this installer.",
+)
+def install_cmd(
+    studio: str | None,
+    home: str | None,
+    python_version,
+    default_index,
+    find_links,
+    allow_prerelease,
+    info,
+):
+    """
+    Install a new tgzr environment.
+    """
+    if info:
+        import tgzr.cli
+        import sys
+        import uv
+
+        click.echo("TGZR Installer:")
+        click.echo(f"{tgzr.cli._version.__version__=}")
+        click.echo(f"{sys.version=}")
+        click.echo(f"{sys.executable=}")
+        click.echo(f"{uv.find_uv_bin()=}")
+        return
+
+    if studio is None:
+        studio = str(click.prompt(f"Studio name", default="MyStudio"))
+    studio = studio.strip().replace(" ", "_")  # overall better + avoids code injection
+
+    if home is None:
+        cwd = Path.cwd().resolve()
+        home = str(
+            click.prompt(f"Install path (can be relative to current dir)", default=cwd)
+        )
+        home = home.strip()
+        if not Path(home).is_absolute():
+            home = str((cwd / home).resolve())
+
+    try:
+        install(
+            home,
+            studio,
+            python_version,
+            default_index,
+            find_links,
+            allow_prerelease,
+            click.echo,
+        )
+    except (FileExistsError, ChildProcessError) as err:
+        click.echo(f"\nInstallation failed: {err}\nPlease contact your adminitrator.")
+        return
+
+    # Some shell won't allow unicodes :/ so:
+    try:
+        click.echo("\n\n✨ tgzr successfully installed ✨")
+    except:
+        click.echo("\n\n tgzr successfully installed!")
+
+
+@click.command("install")
+def install_help():
+    click.echo("# Installing TGZR with `tgzr install`")
+    click.echo(
+        """
+    TGZR installs itself in a folder called "home".
+    This folder will contain:
+        - System : a folder with technical bits managed by TGZR.
+        - Workspace: a folder for everything work related.
+        - `.tgzr` : a configuration file for the installation.
+
+    Everything you will do with TGZR will be related to a Studio.
+    Your Studios are located in the Workspace folder.
+
+    When installing TGZR, you need to know:
+    - Where you want your "home" to be
+    - The name of you studio
+
+    The easiest way to install TGZR with the command line
+    is to go into the folder you chose as "home" and enter:
+        `tgzr install`
+    You will be prompter for a Studio name, and you will
+    be prompter for an install path with a default value of the
+    current folder.
+
+    You can also specify the home path and the studio name 
+    with arguments:
+        `tgzr install --home /path/to/tgzr/home --studio MyStudioName`
+
+# Advanced
+
+    During installation, tgzr will fetch packages from PyPI.
+    If you need to use custom packages instead of official ones, 
+    you can override the default package index with 
+    `--default-index` and/or specify an local folder containing
+    packages with `--find-links`.
+
+    """
+    )

tgzr/cli/main.py

@@ -0,0 +1,7 @@
+import sys
+
+
+def main():
+    from tgzr.cli.main_cli import tgzr_cli
+
+    sys.exit(tgzr_cli())

tgzr/cli/main_cli.py

@@ -0,0 +1,31 @@
+import click
+
+
+from ._version import __version__
+from .add_plugins import add_plugins
+from .install_cli import install_cmd, install_help
+
+from .utils import TGZRCliGroup
+
+
+@click.group(
+    cls=TGZRCliGroup,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.version_option(version=__version__, prog_name="tgzr")
+def tgzr_cli(
+    **kwargs,  # needed for plugin installing custom options
+):
+    pass
+
+
+@tgzr_cli.group(cls=TGZRCliGroup, help="Documentations and tooltips.")
+def help():
+    pass
+
+
+tgzr_cli.add_command(install_cmd)
+help.add_command(install_help)
+tgzr_cli.set_default_command(install_cmd)
+
+add_plugins(tgzr_cli)

tgzr/cli/utils.py

@@ -0,0 +1,99 @@
+import inspect
+
+import click
+
+
+class TGZRCliGroup(click.Group):
+    """
+    This Group recognizes commands with less
+    than their full name when there is no ambiguity.
+    For example: 'wo'->'workspace' if no other command
+    starts with 'wo'
+
+    This Group can be configured with a default command.
+    This command will be invoked if no command is provided.
+
+    This Group can find a sub-group for you with
+    `find_group(group_name)`, which may be used by cli plugins
+    to install their commands and groups where they want
+    to.
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        kwargs["result_callback"] = self.__result_callback
+        super().__init__(*args, **kwargs)
+        self.no_args_is_help = True
+        self.invoke_without_command = False
+        self._looked_up_cmds: list[str] = []
+
+        self._default_command: click.Command | None = None
+        self._default_command_kwargs: dict | None = None
+        self._default_command_setter_module: str | None = None
+
+    def set_default_command(self, cmd: click.Command | None, **kwargs) -> None:
+        frame: inspect.FrameInfo = inspect.stack()[1]
+        setter_module = inspect.getmodule(frame[0])
+        self._default_command_setter_module = (
+            setter_module and setter_module.__name__ or None
+        )
+
+        if cmd is None:
+            self.no_args_is_help = True
+            self.invoke_without_command = False
+            self._default_command = None
+            self._default_command_kwargs = None
+            return
+        else:
+            self.no_args_is_help = False
+            self.invoke_without_command = True
+            self._default_command = cmd
+            self._default_command_kwargs = kwargs
+
+    def get_default_command(
+        self,
+    ) -> tuple[click.Command | None, dict | None, str | None]:
+        return (
+            self._default_command,
+            self._default_command_kwargs,
+            self._default_command_setter_module,
+        )
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        self._looked_up_cmds.append(cmd_name)
+        known_commands = self.list_commands(ctx)
+        if cmd_name not in known_commands:
+            found = [name for name in known_commands if name.startswith(cmd_name)]
+            if len(found) > 1:
+                raise click.UsageError(
+                    f'Ambiuous command "{cmd_name}" (could be {' or '.join(found)}).'
+                )
+            elif found:
+                cmd_name = found[0]
+
+        return super().get_command(ctx, cmd_name)
+
+    def find_group(self, named: str) -> click.Group | None:
+        """
+        Find a click group under this group.
+        Usefull to install plugin under sub commands.
+        """
+        for name, value in self.commands.items():
+            if not isinstance(value, click.Group):
+                continue
+            if name == named:
+                return value
+        return None
+
+    @click.pass_context
+    @staticmethod
+    def __result_callback(ctx: click.Context, self, *result, **kwargs):
+        # See that "self" arg on a staticmethod ? Don't ask!!!! :p
+
+        if self._looked_up_cmds:
+            # Only invoke default command when no other command
+            # was specified. We use self._looked_up_cmds to
+            # find out if a command was given.
+            return
+
+        if self._default_command is not None:
+            ctx.invoke(self._default_command, **self._default_command_kwargs)