feat: oxidized progress bars

Cargo.toml

@@ -16,6 +16,7 @@ members = ["."]
 pyo3 = "0.27.2"
 
 [dependencies]
+bon = "3.9.1"
 console = "0.16.2"
 dirs = "6.0.0"
 indicatif = { version = "0.18.0", features = ["improved_unicode"] }

craft_cli/_rs/emitter.pyi

@@ -1,6 +1,8 @@
 from enum import Enum
 from pathlib import Path
 
+from craft_cli._rs.progress import Progresser
+
 from .streams import StreamHandle
 
 class Verbosity(Enum):
@@ -132,3 +134,34 @@ class Emitter:
 
     def clear_prefix(self) -> None:
         """Clear the current prefix."""
+
+    def progress_bar(
+        self,
+        text: str,
+        total: int,
+        *,
+        units: str | None = None,
+        show_eta: bool = False,
+        show_progress: bool = False,
+        show_percentage: bool = False,
+    ) -> Progresser:
+        """Render an incremental progress bar.
+
+        This method must be used as a context manager.
+
+        :param text: A brief message to prefix before the progress bar.
+        :param total: The total size of the progress bar. Must be a positive number.
+        :param units: Units to display to the left of the progress bar, like "X/Y
+            units". Implies `show_progress = True`. If set to None, the total count will
+            not be showed at all. If set to "bytes", the total will automatically be
+            adjusted to an appropriate magnitude (e.g., MiB -> GiB). All other values are
+            used as-is. Defaults to None.
+        :param show_eta: Whether or not to display an estimated ETA to the right of the
+            progress bar.
+        :param show_progress: Whether or not to show progress to the right of the progress
+            bar, like "X/Y".
+        :param show_percentage: Whether or not to display a percentage of completion to the
+            right of the progress bar.
+
+        :return: A Progresser context manager.
+        """

craft_cli/_rs/progress.pyi

@@ -0,0 +1,31 @@
+from typing_extensions import Self
+
+class Progresser:
+    def __enter__(self) -> Self: ...
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        _traceback: object,
+    ) -> None: ...
+    def tick(self) -> None:
+        """Increase progress by one."""
+
+    def inc(self, delta: int) -> None:
+        """Increase progress by `delta`.
+
+        Must be a positive number.
+
+        :raises OverflowError: If a negative number is provided.
+        """
+
+    def println(self, text: str) -> None:
+        """Display a message alongside current progress.
+
+        This method must be used instead of any emitting methods from an `Emitter`.
+        It will share verbosity level with the `Emitter` that spawned it, and all
+        messages will be permanent.
+        """
+
+    def progress(self) -> int:
+        """How much progress is complete so far."""