implemented verbosity tiers 'low, default, high'

Author: bitdruid

README.md

@@ -178,8 +178,13 @@ Parameters will change the download behavior for snapshots.
 - **`-m`**, **`--metadata`**<br>
   Folder where metadata will be saved (`cdx`/`db`/`csv`/`log`). If you are downloading into a network share, you SHOULD set this to a local path because sqlite locking mechanism may cause issues with network shares.
 
-- **`--verbose`**:<br>
-  Increase output verbosity.
+- **`-v`**, **`--verbose`** `[level]`:<br>
+  Set verbosity level. Available levels:
+  - `low` (or `quiet`, `minimal`, `min`): Essential output only (same as no flag)
+  - `default` (or `normal`, `verbose`): Standard verbose output (default when flag is set)
+  - `high` (or `debug`, `detailed`, `max`): Detailed verbose output
+  
+  Examples: `--verbose`, `--verbose default`, `--verbose high`, `-v high`
 
 - **`--log`** <!-- `<path>` -->:<br>
   Saves a log file into the output-dir. `waybackup_<sanitized_url>.log`.
@@ -199,6 +204,9 @@ Parameters will change the download behavior for snapshots.
 - **`--delay`** `<seconds>`:<br>
   Delay between download requests in seconds. Default is no delay (0).
 
+- **`--wait`** `<seconds>`:<br>
+  Seconds to wait before renewing connection after HTTP errors or snapshot download errors. Default is 15 seconds.
+
 #### Job Handling:
 
 - **`--reset`**:  

pyproject.toml

@@ -18,7 +18,7 @@ dependencies = [
     "python-magic-bin==0.4.14; sys_platform == 'win32' or sys_platform == 'darwin'",
 ]
 name = "pywaybackup"
-version = "4.1.3"
+version = "4.1.4"
 description = "Query and download archive.org as simple as possible."
 authors = [{ name = "bitdruid", email = "bitdruid@outlook.com" }]
 license = { file = "LICENSE" }

pywaybackup/Arguments.py

@@ -33,14 +33,27 @@ def __init__(self):
         behavior = parser.add_argument_group("manipulate behavior")
         behavior.add_argument("-o", "--output", type=str, metavar="", help="output for all files - defaults to current directory")
         behavior.add_argument("-m", "--metadata", type=str, metavar="", help="change directory for db/cdx/csv/log files")
-        behavior.add_argument("-v", "--verbose", action="store_true", help="overwritten by progress - gives detailed output")
+        behavior.add_argument(
+            "-v", "--verbose",
+            type=str,
+            nargs="?",
+            const="default",
+            metavar="",
+            help="verbosity level: low, default, high (default if flag set without value)",
+        )
         behavior.add_argument("--log", action="store_true", help="save a log file into the output folder")
         behavior.add_argument("--progress", action="store_true", help="show a progress bar")
         behavior.add_argument("--no-redirect", action="store_true", help="do not follow redirects by archive.org")
         behavior.add_argument("--retry", type=int, default=0, metavar="", help="retry failed downloads (opt tries as int, else infinite)")
         behavior.add_argument("--workers", type=int, default=1, metavar="", help="number of workers (simultaneous downloads)")
         behavior.add_argument("--delay", type=int, default=0, metavar="", help="delay between each download in seconds")
-        behavior.add_argument("--wait", type=int, default=15, metavar="", help="seconds to wait before renewing connection after HTTP errors or snapshot download errors (default: 15)",)
+        behavior.add_argument(
+            "--wait",
+            type=int,
+            default=15,
+            metavar="",
+            help="seconds to wait before renewing connection after HTTP errors or snapshot download errors (default: 15)",
+        )
 
         special = parser.add_argument_group("special")
         special.add_argument("--reset", action="store_true", help="reset the job and ignore existing cdx/db/csv files")

pywaybackup/PyWayBackup.py

@@ -4,6 +4,7 @@
 import sys
 import time
 from importlib.metadata import version
+from typing import Union
 
 import pywaybackup.archive_save as archive_save
 from pywaybackup.archive_download import DownloadArchive
@@ -122,7 +123,7 @@ def __init__(
         statuscode: str = None,
         output: str = None,
         metadata: str = None,
-        verbose: bool = False,
+        verbose: Union[bool, str, int] = None,
         log: bool = False,
         progress: bool = False,
         no_redirect: bool = False,

pywaybackup/Verbosity.py

@@ -1,23 +1,99 @@
+from enum import IntEnum
 from tqdm import tqdm
 from typing import Union
 
 
+# outside enum to avoid cls membership
+_VERBOSITY_ALIASES = {
+    "NORMAL": "DEFAULT",
+    "VERBOSE": "DEFAULT",
+    "DETAIL": "HIGH",
+    "DETAILED": "HIGH",
+    "MAX": "HIGH",
+    "QUIET": "LOW",
+    "MINIMAL": "LOW",
+    "MIN": "LOW",
+}
+
+
+class VerbosityLevel(IntEnum):
+    """
+    Verbosity levels for output control.
+
+    - LOW: Essential output only (no verbose flag)
+    - DEFAULT: Standard verbose output (--verbose or --verbose default)
+    - HIGH: Detailed verbose output (--verbose high)
+    """
+
+    LOW = 0
+    DEFAULT = 1
+    HIGH = 2
+
+    @classmethod
+    def from_value(cls, value) -> "VerbosityLevel":
+        """
+        Convert various input types to VerbosityLevel.
+
+        Args:
+            value: Can be:
+                - None/False: LOW
+                - True: DEFAULT
+                - str: "low", "default", "high" (+ aliases: normal, info, debug, quiet, etc.)
+                - int: 0, 1, 2
+                - VerbosityLevel: returned as-is
+
+        Returns:
+            VerbosityLevel enum value
+
+        Raises:
+            ValueError: If string value is not a valid level or alias
+        """
+        if value is None or value is False:
+            return cls.LOW
+        if value is True:
+            return cls.DEFAULT
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, int):
+            try:
+                return cls(value)
+            except ValueError:
+                raise ValueError(f"Invalid verbosity level: {value}. Valid levels: 0 (low), 1 (default), 2 (high)")
+        if isinstance(value, str):
+            upper_value = value.upper()
+            # check for aliases first
+            if upper_value in _VERBOSITY_ALIASES:
+                upper_value = _VERBOSITY_ALIASES[upper_value]
+            # try to get the enum member
+            try:
+                return cls[upper_value]
+            except KeyError:
+                valid = ", ".join([m.name.lower() for m in cls] + list(set(a.lower() for a in _VERBOSITY_ALIASES)))
+                raise ValueError(f"Invalid verbosity level: '{value}'. Valid levels: {valid}")
+        return cls.LOW
+
+
 class Verbosity:
     """
     A class to manage verbosity levels, logging, progress and output.
+
+    Verbosity tiers:
+    - LOW (0): Essential output only - no verbose flag set
+    - DEFAULT (1): Standard verbose - --verbose or --verbose default
+    - HIGH (2): Detailed verbose - --verbose high
     """
 
-    verbose = False
+    level = VerbosityLevel.LOW
 
     PROGRESS = None
     pbar = None
 
     log = None
 
     @classmethod
-    def init(cls, logfile=None, silent: bool = False, verbose: bool = False, progress=None):
+    def init(cls, logfile=None, silent: bool = False, verbose: Union[bool, str, int] = False, progress=None):
         cls.silent = silent
-        cls.verbose = verbose
+        cls.level = VerbosityLevel.from_value(verbose)
         cls.logfile = open(logfile, "w", encoding="utf-8") if logfile else None
         cls.PROGRESS = progress
 
@@ -30,17 +106,19 @@ def fini(cls):
             cls.logfile.close()
 
     @classmethod
-    def write(cls, verbose: bool = None, content: Union[str, list] = None):
+    def write(cls, verbose: Union[bool, str, int, None] = None, content: Union[str, list] = None):
         """
         Writes log entries to stdout or logfile based on verbosity level and progress-bar status.
 
         Determines if the message should be printed based on verbosity level.
-        - If None, the message is always printed.
 
-        Content is a list and is filtered and concatenated to a single block of loglines.
-        It should contain dictionaries with keys:
-        - 'verbose': The verbosity level of the message (True/False).
-        - 'content': The actual message to be logged.
+        Args:
+            verbose: The required verbosity level for this message:
+                - None: Always printed (essential output)
+                - False/0/"low": Printed at LOW level and above
+                - True/1/"default": Printed at DEFAULT level and above
+                - 2/"high": Printed at HIGH level only
+            content: The message string or list of message dicts to log.
         """
         if not cls.silent:
             if isinstance(content, str):
@@ -80,16 +158,23 @@ def filter_verbosity(cls, message: list):
         """
         Removes messages from the list that do not match the verbosity level.
 
-        - True if message is verbose None (print always)
-        - True if message has same verbosity as configured
+        Messages are printed if:
+        - verbose is None (always print - essential output)
+        - The message's required level <= configured level
 
         Returns a string containing the filtered messages, joined by newlines.
         """
         filtered_message = []
         for msg in message:
-            verbose = msg.get("verbose", None)
-            if verbose is None or verbose == cls.verbose:
+            msg_verbose = msg.get("verbose", None)
+            if msg_verbose is None:
+                # NONE is always printed
                 filtered_message.append(msg["content"])
+            else:
+                # convert message verbosity and compare
+                msg_level = VerbosityLevel.from_value(msg_verbose)
+                if msg_level <= cls.level:
+                    filtered_message.append(msg["content"])
         return "\n".join(filtered_message)
 
 

pywaybackup/archive_download.py

@@ -156,9 +156,11 @@ def _download_loop(self, worker: Worker):
                 while worker.attempt <= retry_max_attempt:  # retry as given by user
                     worker.message.store(
                         verbose=True,
-                        content=f"\n-----> Worker: {worker.id} \
-                            - Attempt: [{worker.attempt}/{retry_max_attempt}] \
-                            Snapshot ID: [{worker.snapshot.counter}/{self.sc._snapshot_total}]",
+                        content=(
+                            f"\n-----> Worker: {worker.id}"
+                            f" - Attempt: [{worker.attempt}/{retry_max_attempt}]"
+                            f" Snapshot ID: [{worker.snapshot.counter}/{self.sc._snapshot_total}]"
+                        ),
                     )
                     download_attempt = 1
                     download_max_attempt = 3