lid-cli 0.2__tar.gz → 0.4__tar.gz

lid_cli-0.4/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: lid-cli
+Version: 0.4
+Summary: gio-based volume mounting and unmounting tool.
+Author: Christian Heinze
+License-Expression: MIT
+License-File: LICENSES/MIT.txt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: msgspec>=0.21
+Requires-Dist: rich>=14.3
+Requires-Dist: typer>=0.24
+Requires-Python: >=3.14
+Project-URL: Repository, https://codeberg.org/christianheinze/lid-cli
+Description-Content-Type: text/markdown
+
+# `gio`-based volume handling tool `lid`
+
+## (Un)Install
+
+To install, run
+
+```bash
+uv tool install lid-cli
+```
+
+Then run
+
+```bash
+yd --install-completion
+```
+
+to install auto-completion in your shell.
+
+In `bash`, the completion code is stored in `~/.bash_completions/lid.sh` and that file is sourced from `~/.bashrc`.
+Remove both and call `uv tool uninstall lid-cli` to remove this tool.
+
+## (Un)Mounting
+
+Currently, `lid` allows to (un)mount volumes using `gio`.
+
+To find available volumes, run `lid ls` (add the `--mounted` option to restrict to mounted volumes).
+
+Use `lid mount NAME` to mount a volume wherein name is the name displayed by `lid ls`.
+
+Use `lid umount NAME` to unmount. `lid` will only unmount what it has itself mounted.
+This allows to sandwich another action between a `lid mount` and a `lid umount` call to have the volume mounted during the action and retain the initial state afterwards
+(if the volume was mounted before calling `lid mount` it is still mounted after `lid umount`).

lid_cli-0.4/README.md

@@ -0,0 +1,32 @@
+# `gio`-based volume handling tool `lid`
+
+## (Un)Install
+
+To install, run
+
+```bash
+uv tool install lid-cli
+```
+
+Then run
+
+```bash
+yd --install-completion
+```
+
+to install auto-completion in your shell.
+
+In `bash`, the completion code is stored in `~/.bash_completions/lid.sh` and that file is sourced from `~/.bashrc`.
+Remove both and call `uv tool uninstall lid-cli` to remove this tool.
+
+## (Un)Mounting
+
+Currently, `lid` allows to (un)mount volumes using `gio`.
+
+To find available volumes, run `lid ls` (add the `--mounted` option to restrict to mounted volumes).
+
+Use `lid mount NAME` to mount a volume wherein name is the name displayed by `lid ls`.
+
+Use `lid umount NAME` to unmount. `lid` will only unmount what it has itself mounted.
+This allows to sandwich another action between a `lid mount` and a `lid umount` call to have the volume mounted during the action and retain the initial state afterwards
+(if the volume was mounted before calling `lid mount` it is still mounted after `lid umount`).

{lid_cli-0.2 → lid_cli-0.4}/pyproject.toml

@@ -4,8 +4,8 @@ requires = [ "uv-build>=0.10,<0.11" ]
 
 [project]
 name = "lid-cli"
-version = "0.2"
-description = "Project Lid Cli."
+version = "0.4"
+description = "gio-based volume mounting and unmounting tool."
 readme = "README.md"
 license = "MIT"
 license-files = [ "LICENSES/MIT.txt" ]

{lid_cli-0.2 → lid_cli-0.4}/src/lid/__init__.py

@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: Christian Heinze
 #
 # SPDX-License-Identifier: MIT
-"""lid-cli."""
+"""lid CLI tool."""
 
 from __future__ import annotations
 

{lid_cli-0.2 → lid_cli-0.4}/src/lid/cli.py

@@ -11,6 +11,7 @@ import pathlib as pl
 from typing import Annotated
 
 import rich.console
+import rich.table
 import rich.theme
 import typer
 
@@ -22,7 +23,7 @@ env: lid.types.Environment
 console: rich.console.Console
 
 _HELP = """
-Resource activation and communication helper.
+`gio`-based volume (un)mounter.
 """
 
 app = typer.Typer(help=_HELP, no_args_is_help=True, rich_markup_mode="markdown")
@@ -90,11 +91,14 @@ def _complete_mount_kw(incomplete: str) -> list[str]:
     import asyncio
 
     env = lid.io.capture_environment()
-    return asyncio.run(
-        lid.gio.find_device_names(
-            incomplete, mounted_only=False, env=env, runner=lid.subprocess.run
+    try:
+        return asyncio.run(
+            lid.gio.find_volume_names(
+                incomplete, mounted_only=False, env=env, runner=lid.subprocess.run
+            )
         )
-    )
+    except lid.types.GioError:
+        return []
 
 
 def _require_nonempty(param: typer.CallbackParam, v: str | None) -> str | None:
@@ -103,12 +107,13 @@ def _require_nonempty(param: typer.CallbackParam, v: str | None) -> str | None:
     raise typer.BadParameter(f"parameter `{param.name}` must not be an empty string")
 
 
-@app.command()
+@app.command(help="Mount volume.")
 def mount(
     kw: Annotated[
         str,
         typer.Argument(
-            help="Device keyword.",
+            help="Volume name as displayed by `lid ls` (partial names"
+            " are sufficient as long as they uniquely identify a single volume name).",
             autocompletion=_complete_mount_kw,
             callback=_require_nonempty,
         ),
@@ -124,8 +129,8 @@ def mount(
             mt = runner.run(lid.gio.mount(kw, env=env, runner=lid.subprocess.run))
         except lid.types.GioNotFoundError as err:
             log.exception("Failed to mount for keyword `%s`.", kw)
-            raise typer.BadParameter(f"Device not determined: {err}.") from None
-        except lid.types.GioMountError as err:
+            raise typer.BadParameter(f"Volume not determined: {err}.") from None
+        except lid.types.GioError as err:
             log.exception("Failed to mount for keyword `%s`.", kw)
             console.print(f"Mount failure: {err}.", style="error")
             raise typer.Exit(2) from None
@@ -138,11 +143,13 @@ def mount(
                 env.runtime_dir.joinpath(str(uuid.uuid4())).write_bytes(mt_info)
             except OSError, PermissionError:
                 log.exception("Failed to create mount marker file.")
+                log.debug("Attempting unmount.")
                 try:
                     runner.run(
                         lid.gio.umount(mount=mt, env=env, runner=lid.subprocess.run)
                     )
-                except lid.types.GioMountError as err:
+                except lid.types.GioError as err:
+                    log.exception("Unmounting failed.")
                     console.print(
                         f"Failed to create marker file, then failed to umount: {err}.",
                         style="error",
@@ -154,26 +161,80 @@ def mount(
     return 0
 
 
+@app.command("ls", help="List available volumes.")
+def list_volumes(
+    mounted: Annotated[
+        bool,
+        typer.Option(
+            "--mounted",
+            help="Only list mounted volumes.",
+        ),
+    ] = False,
+) -> int:
+    import asyncio
+
+    try:
+        names = asyncio.run(
+            lid.gio.find_volume_names(
+                "", mounted_only=mounted, env=env, runner=lid.subprocess.run
+            )
+        )
+    except lid.types.GioError as err:
+        log.exception("Failed to list volumes.")
+        console.print(f"Volume discovery failure: {err}.", style="error")
+        raise typer.Exit(2) from None
+
+    if not names:
+        console.print("No volumes found.", style="warning")
+        return 0
+
+    table = rich.table.Table(title="Volumes")
+    table.add_column("Name", overflow="fold")
+    for name in names:
+        table.add_row(name)
+    console.print(table)
+    return 0
+
+
 def _complete_umount_kw(incomplete: str) -> list[str]:
     import asyncio
 
     env = lid.io.capture_environment()
-    return asyncio.run(
-        lid.gio.find_device_names(
-            incomplete, mounted_only=True, env=env, runner=lid.subprocess.run
+    try:
+        return asyncio.run(
+            lid.gio.find_volume_names(
+                incomplete, mounted_only=True, env=env, runner=lid.subprocess.run
+            )
         )
-    )
+    except lid.types.GioError:
+        return []
 
 
 async def _umount(kw: str, /, env: lid.types.Environment) -> int:
     import asyncio
 
-    names, markers = await asyncio.gather(
-        lid.gio.find_device_names(
-            kw, mounted_only=True, env=env, runner=lid.subprocess.run
-        ),
-        asyncio.to_thread(lid.io.read_mount_markers, env),
-    )
+    async with asyncio.TaskGroup() as tg:
+        names_task = tg.create_task(
+            lid.gio.find_volume_names(
+                kw, mounted_only=True, env=env, runner=lid.subprocess.run
+            )
+        )
+        markers_task = tg.create_task(
+            asyncio.to_thread(lid.io.read_mount_markers, env),
+        )
+        try:
+            names, markers = await names_task, await markers_task
+        except* (OSError, PermissionError) as err:
+            log.exception(
+                "Failed to access mount marker files in `%s`.", env.runtime_dir
+            )
+            console.print("Failed to access marker files.", style="error")
+            raise typer.Exit(2) from err
+        except* lid.types.GioError as err:
+            log.exception("Failed to gather volume information for keyword `%s`.", kw)
+            console.print(f"Unmount failure: {err}.", style="error")
+            raise typer.Exit(2) from err
+
     match [(p, m) for n, (p, m) in it.product(names, markers) if n == m.name]:
         case []:
             log.info("Found no matching marker file. Exiting.")
@@ -181,10 +242,7 @@ async def _umount(kw: str, /, env: lid.types.Environment) -> int:
         case [[pl.Path() as f, lid.types.Mount() as mt]]:
             try:
                 await lid.gio.umount(mount=mt, env=env, runner=lid.subprocess.run)
-            except lid.types.GioNotFoundError as err:
-                log.exception("Failed to mount for keyword `%s` (match: `%s`.", kw, mt)
-                raise typer.BadParameter(f"Device not determined: {err}.") from None
-            except lid.types.GioMountError as err:
+            except lid.types.GioError as err:
                 log.exception(
                     "Failed to unmount for keyword `%s` (match: `%s`).", kw, mt
                 )
@@ -218,7 +276,8 @@ def umount(
     kw: Annotated[
         str,
         typer.Argument(
-            help="Device keyword.",
+            help="Volume name as displayed by `lid ls` (partial names"
+            " are sufficient as long as they uniquely identify a single volume name).",
             autocompletion=_complete_umount_kw,
             callback=_require_nonempty,
         ),

{lid_cli-0.2 → lid_cli-0.4}/src/lid/gio.py

@@ -38,54 +38,54 @@ if TYPE_CHECKING:
     ) -> None: ...
 
 
-__all__ = ["find_device_names", "mount", "umount"]
+__all__ = ["find_volume_names", "mount", "umount"]
 
 log = logging.getLogger(__name__)
 
 
 # Return type dictated by use a completion suggester.
-async def find_device_names(
+async def find_volume_names(
     kw: str, /, mounted_only: bool, env: types.Environment, runner: AsyncRunner
 ) -> list[str]:
-    device_info = await _query_matching_device_info(
+    volume_info = await _query_matching_volume_info(
         kw, include_details=False, env=env, runner=runner
     )
     if not mounted_only:
-        return [d["__name__"] for d in device_info]
-    return [d["__name__"] for d in device_info if any(k.startswith("Mount") for k in d)]
+        return [d["__name__"] for d in volume_info]
+    return [d["__name__"] for d in volume_info if any(k.startswith("Mount") for k in d)]
 
 
 async def mount(kw: str, /, env: types.Environment, runner: AsyncRunner) -> types.Mount:
-    """Mount device.
+    """Mount volume.
 
     Parameters
     ----------
     kw
-        (Partial) name of device as given in the top line of the gio output section.
+        (Partial) name of volume as given in the top line of the gio output section.
     """
-    device_info = await _query_matching_device_info(
+    volume_info = await _query_matching_volume_info(
         kw, include_details=True, env=env, runner=runner
     )
-    device = _extract_device(kw, device_info=device_info)
+    volume = _extract_volume(kw, volume_info=volume_info)
 
-    name, mount_id, is_mounted = device.name, device.id_, device.is_mounted
+    name, mount_id, is_mounted = volume.name, volume.id_, volume.is_mounted
     if is_mounted:
-        log.info("Device `%s` already mounted.", name)
+        log.info("Volume `%s` already mounted.", name)
     else:
-        log.info("Mounting device `%s`.", name)
+        log.info("Mounting volume `%s`.", name)
         try:
             await runner(env.gio_bin, "mount", "--device", mount_id)
         except types.SubprocessError as err:
-            log.exception("Failed to mount device ID `%s`.", mount_id)
-            raise types.GioMountError(
-                f"failed to mount device with ID`{mount_id}`"
-            ) from err
+            log.exception("Failed to mount volume ID `%s`.", mount_id)
+            raise types.GioError(f"failed to mount volume with ID`{mount_id}`") from err
 
     try:
-        mp = await _find_mountpoint(mount_id, env=env, runner=runner)
-    except types.GioMountError as err:
+        mp = await _find_mountpoint(
+            volume.data["activation_root"], env=env, runner=runner
+        )
+    except types.GioError as err:
         log.exception("Found no mount point for `%s`.", name)
-        raise types.GioMountError(f"found no mount point for `{name}`") from err
+        raise types.GioError(f"found no mount point for `{name}`") from err
 
     return types.Mount(name=name, mountpoint=mp, triggered=mount_id is not None)
 
@@ -98,23 +98,25 @@ async def umount(
     env: types.Environment,
     runner: AsyncRunner,
 ) -> None:
-    """Unmount device."""
+    """Unmount volume."""
     if kw is not None:
-        device_info = await _query_matching_device_info(
+        volume_info = await _query_matching_volume_info(
             kw, include_details=True, env=env, runner=runner
         )
-        device = _extract_device(kw, device_info=device_info)
+        volume = _extract_volume(kw, volume_info=volume_info)
 
-        if not device.is_mounted:
-            log.info("Device `%s` not mounted.")
+        if not volume.is_mounted:
+            log.info("Volume `%s` not mounted.")
             return
-        name, mount_id = device.name, device.id_
+        name = volume.name
 
         try:
-            mountpoint = await _find_mountpoint(mount_id, env=env, runner=runner)
-        except types.GioMountError as err:
+            mountpoint = await _find_mountpoint(
+                volume.data["activation_root"], env=env, runner=runner
+            )
+        except types.GioError as err:
             log.exception("Found no mount point for `%s`.", name)
-            raise types.GioMountError(f"found no mount point for `{name}`") from err
+            raise types.GioError(f"found no mount point for `{name}`") from err
     else:
         if TYPE_CHECKING:
             mount = cast("types.Mount", mount)
@@ -123,23 +125,26 @@ async def umount(
     try:
         await runner(env.gio_bin, "mount", "--unmount", mountpoint)
     except types.SubprocessError as err:
-        raise types.GioMountError(f"failed to unmount `{mountpoint}`") from err
+        raise types.GioError(f"failed to unmount `{mountpoint}`") from err
 
 
 @dataclass(slots=True, kw_only=True)
-class _Device:
+class _Volume:
     name: str
     id_: str
+
     is_mounted: bool
     data: dict[str, Any]
 
 
-async def _query_matching_device_info(
+async def _query_matching_volume_info(
     kw: str, /, include_details: bool, env: types.Environment, runner: AsyncRunner
 ) -> Sequence[dict[str, Any]]:
-    if not kw:
-        raise ValueError("empty keyword cannot be used for device identification")
+    """Query volume information.
 
+    Only volumes with names containing `kw` (interpreted as a regular expression)
+    are returned.
+    """
     if include_details:
         gio_args = ("mount", "--list", "--detail")
     else:
@@ -147,30 +152,28 @@ async def _query_matching_device_info(
     try:
         gio_out = await runner(env.gio_bin, *gio_args)
     except types.SubprocessError as err:
-        raise types.GioMountError(
-            "failed to collect gio output for device discovery"
+        raise types.GioError(
+            "failed to collect gio output for volume discovery"
         ) from err
     try:
         info = _parse_output(gio_out)
-    except types.GioParseError as err:
-        raise types.GioMountError(
-            "failed to parse gio output for device discovery"
-        ) from err
+    except types.GioError as err:
+        raise types.GioError("failed to parse gio output for volume discovery") from err
 
     pattern = re.compile(kw, re.IGNORECASE)
     return [
         v
         for k, v in info.items()
-        if k.startswith(("Volume", "Drive"))
+        if k.startswith("Volume")
         and isinstance(v, dict)
         and pattern.search(v.get("__name__", "")) is not None
     ]
 
 
-def _extract_device(kw: str, /, device_info: Sequence[dict[str, Any]]) -> _Device:
-    match device_info:
+def _extract_volume(kw: str, /, volume_info: Sequence[dict[str, Any]]) -> _Volume:
+    match volume_info:
         case []:
-            raise types.GioNotFoundError(f"found no device matching for `{kw}`")
+            raise types.GioNotFoundError(f"found no volume matching for `{kw}`")
         case [{"__name__": name} as v]:
             log.debug("Matched `%s` to full name `%s`.", kw, name)
 
@@ -183,35 +186,33 @@ def _extract_device(kw: str, /, device_info: Sequence[dict[str, Any]]) -> _Devic
                 case _:
                     log.error("Failed to find mount ID in `%s`.", v)
                     raise types.GioNotFoundError(f"failed to find ID for `{name}`")
-            return _Device(name=name, id_=mount_id, is_mounted=is_mounted, data=v)
+            return _Volume(name=name, id_=mount_id, is_mounted=is_mounted, data=v)
         case [f, s, *ms]:
             fn, sn, lms = f["__name__"], s["__name__"], len(ms)
             raise types.GioNotFoundError(
                 f"found multiple matches for `{kw}`: `{fn}`, `{sn}`, and {lms} more."
             )
         case _:
-            raise types.GioNotFoundError("unsupported gio output structure")
+            raise types.GioError("unsupported gio output structure")
 
 
 async def _find_mountpoint(
     id_: str, /, env: types.Environment, runner: AsyncRunner
 ) -> str:
     try:
-        # Requires device to be mounted.
+        # Requires volume to be mounted.
         # Need to the US locale as the output key are adapted to that setting.
         gio_out = await runner(
             env.gio_bin, "info", "-a", "local", id_, env_mods={"LANG": "en_US-UTF-8"}
         )
     except types.SubprocessError as err:
-        raise types.GioMountError(
+        raise types.GioError(
             "failed to collect gio output for mountpoint discovery"
         ) from err
     try:
         gio_out = _parse_output(gio_out)
-    except types.GioParseError as err:
-        raise types.GioMountError(
-            "failed to parse gio output for path discovery"
-        ) from err
+    except types.GioError as err:
+        raise types.GioError("failed to parse gio output for path discovery") from err
 
     return gio_out["local path"]
 
@@ -233,7 +234,7 @@ def _parse_output(text: str, /, header_name: str = "__name__") -> dict[str, Any]
             stack.pop()
         current = stack[-1]
         if line.indent < current.indent:
-            raise types.GioParseError(
+            raise types.GioError(
                 f"indent {line.indent} does not match any previous level"
             )
 
@@ -293,7 +294,7 @@ def _parse_line(
     log.debug("Extracted content: `%s` (indent: %s).", content, indent)
 
     if (spec_match := _SPEC.fullmatch(content)) is None:
-        raise types.GioParseError("line not matching expected pattern: `%s`", content)
+        raise types.GioError("line not matching expected pattern: `%s`", content)
 
     key, value = spec_match.group("key"), spec_match.group("val") or None
     log.debug("Found key/value: `%s`=`%s`.", key, value)

{lid_cli-0.2 → lid_cli-0.4}/src/lid/subprocess.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import asyncio
 import contextvars
+import logging
 import os
 
 from lid import types
@@ -18,6 +19,8 @@ if TYPE_CHECKING:
 
 __all__ = ["raise_on_stderr", "run"]
 
+log = logging.getLogger()
+
 RUNNING = contextvars.ContextVar[str]("_RUNNING")
 
 
@@ -46,7 +49,8 @@ async def run(
         stderr=asyncio.subprocess.PIPE,
         **proc_kwargs,
     )
-    token = RUNNING.set(f"`{bin_} {' '.join(args)}`")
+    token = RUNNING.set(running := f"`{bin_} {' '.join(args)}`")
+    log.debug("Running %s.", running)
     try:
         stdout, stderr = await proc.communicate()
     except asyncio.CancelledError:
@@ -55,7 +59,7 @@ async def run(
         raise
 
     if proc.returncode != 0:
-        running = RUNNING.get()
+        log.error("Running %s failed (error code %s).", running, proc.returncode)
         RUNNING.reset(token)
         raise types.SubprocessError(
             f"{running} exited with return code {proc.returncode}:"
@@ -63,6 +67,8 @@ async def run(
         )
     try:
         if stderr:
+            log.warning("Found STDERR output: `%s`.", stderr)
+
             handle_stderr(stderr)
         stdout = stdout.decode("utf-8")
     finally:

{lid_cli-0.2 → lid_cli-0.4}/src/lid/types.py

@@ -26,16 +26,16 @@ class EnvCaptureError(LidError):
     """Exception raised when capturing the environment fails."""
 
 
-class GioParseError(LidError):
-    """Raised when gio CLI output cannot be parsed."""
+class GioError(LidError):
+    """Exception raised when interaction with `gio` failes.
 
-
-class GioMountError(LidError):
-    """Exception raised when (un)mounting device fails."""
+    This includes all issues not related to user input, e.g., unsupported formats
+    int the `gio` output.
+    """
 
 
-class GioNotFoundError(GioMountError):
-    """Exception raised when (un)mounting device fails due to missing device."""
+class GioNotFoundError(LidError):
+    """Exception raised when no matching volume can be found."""
 
 
 @dataclass(slots=True)
@@ -55,11 +55,11 @@ class Mount(msgspec.Struct, forbid_unknown_fields=True, kw_only=True):
     Parameters
     ----------
     name
-        Device ID as displayed by `gio mount --list`.
+        Volume ID as displayed by `gio mount --list`.
     mountpoint
-        Mountpoint (local directory logically linked to device file system).
+        Mountpoint (local directory logically linked to volume file system).
     triggered
-        True if the attempt actually mounted the device.
+        True if the attempt actually mounted the volume.
     """
 
     name: str

lid_cli-0.2/PKG-INFO

@@ -1,31 +0,0 @@
-Metadata-Version: 2.4
-Name: lid-cli
-Version: 0.2
-Summary: Project Lid Cli.
-Author: Christian Heinze
-License-Expression: MIT
-License-File: LICENSES/MIT.txt
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: End Users/Desktop
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Utilities
-Classifier: Typing :: Typed
-Requires-Dist: msgspec>=0.21
-Requires-Dist: rich>=14.3
-Requires-Dist: typer>=0.24
-Requires-Python: >=3.14
-Project-URL: Repository, https://codeberg.org/christianheinze/lid-cli
-Description-Content-Type: text/markdown
-
-# lid-cli
-
-To find device, run `gio mount --list --detail` and select ID in the first line.
-
-## TODO
-
-- More error handling and testing.
-- Build CLI with mount and umount commands.
-- Possibly write target to disk in a small file for umount to read from.

lid_cli-0.2/README.md

@@ -1,9 +0,0 @@
-# lid-cli
-
-To find device, run `gio mount --list --detail` and select ID in the first line.
-
-## TODO
-
-- More error handling and testing.
-- Build CLI with mount and umount commands.
-- Possibly write target to disk in a small file for umount to read from.