Merge pull request #629 from frankieramirez/feat/log-level-names

feat: Accept log level names, and deprecate --verbose

Author: frankieramirez

.changeset/log-levels-have-names.md

@@ -0,0 +1,11 @@
+---
+"comicarr": patch
+---
+
+The log level can now be set by name as well as by number. `warning`, `info`, and `debug` work anywhere the number did — `--log-level debug` on the command line, `COMICARR_LOG_LEVEL=debug` in your compose file, or `LOG_LEVEL = debug` in `config.ini`. Numbers are unchanged, so nothing you already have needs editing, and capitalisation does not matter.
+
+The names describe what each level actually does: level `0` is `warning` because it emits warnings and errors. It was previously described as "quiet", which suggested silence and was never true — turning the dial down has always kept failures visible.
+
+Startup messages now name the level both ways, so it is obvious which setting produced it: `Log level 2 (debug) from startup argument overrides 1 (info) from the config file`.
+
+`--verbose` and `-v` are now deprecated aliases for `--log-level debug`, joining `--quiet` and `-q` (aliases for `--log-level warning`). All four keep working and will continue to — they print a note pointing at `--log-level`, which is the one flag that sets the level directly.

CONTEXT.md

@@ -20,6 +20,10 @@ Who issued a Series' identifier: ComicVine, MangaDex (`md-` prefix), or MyAnimeL
 
 The MangaDex UUID a manga Series polls for new chapters. MangaDex Series carry it in their ComicID; MyAnimeList Series supply metadata from MAL but keep the chapter source in `MangaDexID`, and have none until it is resolved.
 
+## Log level
+
+Comicarr's single verbosity dial, named by the severity it admits: `0` warning, `1` info, `2` debug. Level `0` means warnings and errors, not silence, which is why it is never called "quiet" — `--quiet` and `--verbose` are flag spellings, not level names.
+
 ## Support bundle
 
 A downloadable archive of allowlisted diagnostic data, engineered for public issue attachment after operator review. If its contents appear sensitive, the operator shares it privately with maintainers instead; CarePackage is the legacy implementation name, not the user-facing term.

Comicarr.py

@@ -91,23 +91,26 @@ def main():
     parser.add_argument(
         "--log-level",
         dest="log_level",
-        type=int,
         default=None,
-        metavar="{0,1,2}",
+        metavar="{0,1,2|warning,info,debug}",
         help=(
-            "Logging verbosity: 0 warnings and errors, 1 normal, 2 everything. "
+            "Logging verbosity: 0/warning warnings and errors, 1/info normal, 2/debug everything. "
             "Overrides COMICARR_LOG_LEVEL and the config file; omit it and those apply."
         ),
     )
     parser.add_argument(
-        "-v", "--verbose", action="store_true", default=False, help="Increase console logging verbosity"
+        "-v",
+        "--verbose",
+        action="store_true",
+        default=False,
+        help="Deprecated alias for --log-level debug (everything)",
     )
     parser.add_argument(
         "-q",
         "--quiet",
         action="store_true",
         default=False,
-        help="Deprecated alias for --log-level 0 (warnings and errors only)",
+        help="Deprecated alias for --log-level warning (warnings and errors only)",
     )
     parser.add_argument("-d", "--daemon", action="store_true", default=False, help="Run as a daemon")
     parser.add_argument("-p", "--port", type=int, default=0, help="Force Comicarr to run on a specified port")
@@ -300,15 +303,25 @@ def main():
     # Startup args are the top of the precedence chain (args > COMICARR_LOG_LEVEL
     # > config), but only when one was actually passed: leaving this None is what
     # lets the environment and the config file be heard at all.
+    #
+    # `--log-level` accepts a number or a name; an unusable value supplies
+    # nothing, so it falls through to the aliases and then to the layers below
+    # rather than blocking the boot over a typo.
     comicarr.LOG_LEVEL = None
     if args_log_level is not None:
-        comicarr.LOG_LEVEL = log_level_source.clamp_level(args_log_level)
-        print("Log level set to %s by startup argument." % comicarr.LOG_LEVEL)
-    elif args_verbose:
-        print("Verbose/Debugging mode enabled...")
+        argument_level, argument_notices = log_level_source.parse_level(
+            args_log_level, log_level_source.SOURCE_ARGUMENT
+        )
+        for notice in argument_notices:
+            print(notice)
+        if argument_level is not None:
+            comicarr.LOG_LEVEL = argument_level
+            print("Log level set to %s by startup argument." % log_level_source.describe_level(argument_level))
+    if comicarr.LOG_LEVEL is None and args_verbose:
+        print("--verbose is deprecated; use --log-level debug. Log level set to 2 (debug).")
         comicarr.LOG_LEVEL = 2
-    elif args_quiet:
-        print("--quiet is deprecated; use --log-level 0. Logging warnings and errors only...")
+    if comicarr.LOG_LEVEL is None and args_quiet:
+        print("--quiet is deprecated; use --log-level warning. Log level set to 0 (warning).")
         comicarr.LOG_LEVEL = 0
 
     if args_ignoreupdate:

comicarr/app/config/log_level.py

@@ -16,6 +16,10 @@
 2. the `COMICARR_LOG_LEVEL` environment variable
 3. `LOG_LEVEL` in the config file (the Settings UI writes this one)
 
+Each of them accepts the level in either notation -- `0`/`1`/`2` or
+`warning`/`info`/`debug` -- and the integer is what gets stored, whichever form
+was typed.
+
 A source only counts when it *explicitly supplies* a value. That qualifier is
 the whole point: Docker used to pass `--quiet` on every start, which pinned the
 escape hatch permanently open and left an operator with no way to raise
@@ -38,6 +42,19 @@
 MIN_LEVEL = 0
 MAX_LEVEL = 2
 
+# One name per level, and the threshold picks it: level 0 is `WARNING`, so it is
+# called `warning`. The tempting `quiet`/`normal`/`verbose` triple is not here on
+# purpose -- level 0 emits warnings and errors, and a dial labelled "quiet" is
+# the same lie #610 was about. `warn`, `error`, and `critical` are rejected too:
+# the first is a second name for one level, and the last two name a severity no
+# level can deliver on its own.
+LEVEL_NAMES = {"warning": 0, "info": 1, "debug": 2}
+NAME_FOR_LEVEL = {level: name for name, level in LEVEL_NAMES.items()}
+
+# Every source accepts both notations, so every rejection describes both. One
+# string because the CLI notice and the Settings HTTP error must not drift.
+ACCEPTED_FORMS = "%s-%s or one of %s" % (MIN_LEVEL, MAX_LEVEL, ", ".join(LEVEL_NAMES))
+
 # Named for the source, not the mechanism, because these strings are echoed to
 # the operator when the level is decided.
 SOURCE_ARGUMENT = "startup argument"
@@ -65,9 +82,24 @@ def clamp_level(level: int) -> int:
     return max(MIN_LEVEL, min(MAX_LEVEL, level))
 
 
+def describe_level(level: int) -> str:
+    """Render a level the way every operator-facing surface says it: `2 (debug)`.
+
+    The number is what an operator's `config.ini` and compose file contain; the
+    name is what `--help` and the Settings dial show them. Saying both keeps the
+    two notations from drifting apart in anyone's head.
+    """
+    return "%s (%s)" % (level, NAME_FOR_LEVEL[clamp_level(level)])
+
+
 def parse_level(raw, origin: str) -> tuple[int | None, list[str]]:
     """Read one source's value into a usable level.
 
+    Both notations are accepted from every source -- `2` and `debug` are the same
+    instruction, so an operator who reads `Debug` on the Settings dial can type
+    `--log-level debug` and have it work. Names are matched case-insensitively
+    and never need clamping; a number does.
+
     Returns `(None, notices)` when the source supplied nothing usable, so the
     caller falls through to the next layer rather than starting at a level
     nobody asked for. Out-of-range numbers are clamped rather than rejected: a
@@ -85,13 +117,16 @@ def parse_level(raw, origin: str) -> tuple[int | None, list[str]]:
         text = str(raw).strip()
         if not text:
             return None, notices
+        named = LEVEL_NAMES.get(text.casefold())
+        if named is not None:
+            return named, notices
         try:
             parsed = int(text)
         except ValueError:
-            return None, [f"Ignoring {origin}: {text!r} is not a number. Expected {MIN_LEVEL}-{MAX_LEVEL}."]
+            return None, [f"Ignoring {origin}: {text!r} is not a log level. Expected {ACCEPTED_FORMS}."]
     clamped = clamp_level(parsed)
     if clamped != parsed:
-        notices.append(f"Log level {parsed} from {origin} is out of range; using {clamped}.")
+        notices.append(f"Log level {parsed} from {origin} is out of range; using {describe_level(clamped)}.")
     return clamped, notices
 
 
@@ -124,8 +159,10 @@ def resolve_startup_log_level(
     # Say what lost, so an operator who edits the Settings dial and sees nothing
     # change has the reason in front of them rather than in the source.
     overridden = [
-        f"{other_level} from {other_source}" for other_level, other_source in supplied[1:] if other_level != level
+        f"{describe_level(other_level)} from {other_source}"
+        for other_level, other_source in supplied[1:]
+        if other_level != level
     ]
     if overridden:
-        notices.append(f"Log level {level} from {source} overrides {', '.join(overridden)}.")
+        notices.append(f"Log level {describe_level(level)} from {source} overrides {', '.join(overridden)}.")
     return LogLevelResolution(level=level, source=source, notices=notices)

comicarr/app/system/service.py

@@ -44,7 +44,7 @@
 from comicarr.app.acquisition.models import DispatchState
 from comicarr.app.common.dates import normalize_utc_datetime
 from comicarr.app.common.redaction import redact_sensitive_text
-from comicarr.app.config.log_level import MAX_LEVEL, MIN_LEVEL, SOURCE_SETTINGS, parse_level
+from comicarr.app.config.log_level import ACCEPTED_FORMS, SOURCE_SETTINGS, parse_level
 from comicarr.app.config.registry import (
     readable_keys,
     scheduler_job_intervals,
@@ -407,16 +407,18 @@ def update_config(ctx, key_values):
     level_notices = []
     if "LOG_LEVEL" in filtered:
         # Read by the same rules as every other source of the level, so a value
-        # typed into Settings behaves like one passed on the command line:
-        # out of range clamps, non-numeric is refused. A startup source is
-        # clamped rather than rejected because refusing to boot helps nobody;
-        # an HTTP request can simply be told it was wrong, and persisting
-        # garbage would leave the level silently ignored at the next start.
+        # typed into Settings behaves like one passed on the command line: both
+        # notations are accepted, out of range clamps, and anything else is
+        # refused. A startup source is clamped rather than rejected because
+        # refusing to boot helps nobody; an HTTP request can simply be told it
+        # was wrong, and persisting garbage would leave the level silently
+        # ignored at the next start. Whichever form arrives, an integer is what
+        # gets stored.
         level, level_notices = parse_level(filtered["LOG_LEVEL"], SOURCE_SETTINGS)
         if level is None:
             return {
                 "success": False,
-                "error": "LOG_LEVEL must be a number between %s and %s" % (MIN_LEVEL, MAX_LEVEL),
+                "error": "LOG_LEVEL must be %s" % ACCEPTED_FORMS,
             }
         filtered["LOG_LEVEL"] = level
 

docs/architecture/logging-levels.md

@@ -8,12 +8,31 @@ the logger and to every sink it feeds. There is no second dial.
 
 | Level | Threshold | Console | `comicarr.log` | Web UI log list |
 | --- | --- | --- | --- | --- |
-| `0` — quiet | `WARNING` | warnings and errors | warnings and errors | warnings and errors |
-| `1` — normal (default) | `INFO` | info and above | info and above | info and above |
-| `2` — verbose | `DEBUG` | everything | everything | everything |
+| `0` — `warning` | `WARNING` | warnings and errors | warnings and errors | warnings and errors |
+| `1` — `info` (default) | `INFO` | info and above | info and above | info and above |
+| `2` — `debug` | `DEBUG` | everything | everything | everything |
 
 Levels below `0` clamp to `WARNING`; above `2` clamp to `DEBUG`.
 
+### The names are determined, not chosen
+
+Each level *is* a stdlib threshold, so the threshold names it. That rules out
+the obvious `quiet` / `normal` / `verbose` triple, which this document used
+until #620: level `0` emits warnings and errors, and calling it "quiet" is the
+same class of lie as #610 — a control describing behaviour the process does not
+have. An operator who reads "quiet" and hears "silence" will turn the dial down
+and believe failures stopped.
+
+There is exactly one name per level. `warn` is refused as a second spelling of
+one level; `error` and `critical` are refused because no level delivers them —
+`--log-level error` could only mean "warnings and errors", which is level `0`
+under a name that promises something narrower.
+
+`quiet` and `verbose` survive only as the flag spellings `--quiet` and
+`--verbose`, which is a different thing from a level name and is covered below.
+Neither is accepted as a *value*: `--log-level` was `type=int` before #620, so
+nobody could ever have typed them and there is no back-compatibility to keep.
+
 `logger.threshold_for_level()` is the only place this mapping lives, and
 `logger.current_log_level()` is the only supported way to ask what the dial is
 currently set to. Nothing else may branch on verbosity.
@@ -31,6 +50,18 @@ Three sources, highest priority first:
 
 If none of them supplies a value, the level is `1`.
 
+**Every source accepts both notations.** `--log-level debug`,
+`COMICARR_LOG_LEVEL=debug`, `LOG_LEVEL = debug` in `config.ini`, and a `"debug"`
+sent to the Settings endpoint all mean level `2`. Matching is
+case-insensitive and tolerates surrounding whitespace. One grammar everywhere is
+the point: an operator who reads `Debug` on the Settings dial and types
+`--log-level debug` must not meet an error, and a source that quietly accepted
+less than its neighbours would only ever be discovered by tripping over it.
+
+**The stored value is always the integer.** A name is normalised by
+`parse_level` at the boundary and never reaches `config.ini`, so `LOG_LEVEL`
+stays the `int` the registry declares and the generated frontend types expect.
+
 **A source counts only when it explicitly supplies a value.** That qualifier is
 the whole rule, and it is what #610 got wrong: the Docker entrypoint passed
 `--quiet` on every start, so the top of the chain was permanently occupied and
@@ -46,7 +77,13 @@ overrode.
 
 Values outside `0`–`2` are clamped rather than rejected: a compose file asking
 for `3` wants maximum verbosity, and refusing to boot over it helps nobody. A
-non-numeric value is ignored with a notice, and the next source down is used.
+value that is neither a number nor one of the three names is ignored with a
+notice, and the next source down is used.
+
+Operator-facing text names the level in both notations — `Log level 2 (debug)
+from startup argument overrides 1 (info) from the config file`. The number is
+what an operator's config and compose files contain; the name is what `--help`
+and the Settings dial show them. `describe_level()` is the single renderer.
 
 `COMICARR_LOG_LEVEL` is a deliberate one-off for this one key. Comicarr does not
 read the environment for any other setting, and a general `COMICARR_<KEY>`
@@ -69,22 +106,37 @@ is the realistic case), the save still reports success and the failure is
 logged; the level applies at the next start.
 
 The value is read by `parse_level`, exactly as the three startup sources are,
-so a level typed into Settings clamps to range the same way. It differs on one
-point: a non-numeric value is *refused* with an error rather than ignored. A
-startup source has a layer beneath it to fall through to, and an HTTP request
-has somewhere to put the complaint — persisting `"verbose"` would leave the
-operator's setting silently discarded at the next start.
+so a level typed into Settings clamps to range the same way and accepts the same
+two notations. It differs on one point: an unrecognised value is *refused* with
+an error rather than ignored. A startup source has a layer beneath it to fall
+through to, and an HTTP request has somewhere to put the complaint — persisting
+`"loud"` would leave the operator's setting silently discarded at the next
+start. The rejection names both accepted forms, from the same `ACCEPTED_FORMS`
+string the startup notice uses, so the two can never describe different rules.
 
 On the next start the chain runs again, so a startup argument or
 `COMICARR_LOG_LEVEL` will override what Settings saved. That is the documented
 precedence, and it is why the winning source announces what it overrode.
 
+The dial itself shows number, name, and consequence together — `0 · Warning —
+warnings and errors` — rather than a bare one-word label. The number is what the
+operator's config file contains, the name is what the CLI accepts, and the
+consequence is what stops the next "I set it to 0 and expected silence". This
+supersedes the `quiet / normal / verbose` labels locked while designing the
+surface; the layout of that design is unaffected.
+
 ### `--quiet` and `--verbose`
 
-`--quiet` is a deprecated alias for `--log-level 0` and prints a notice saying
-so. It stays because it is in existing compose files and systemd units; deleting
-it would break them for a cosmetic gain. `--verbose` maps to level `2`. When
-more than one is passed, `--log-level` wins, then `--verbose`, then `--quiet`.
+Both are deprecated aliases — `--quiet` for `--log-level warning`, `--verbose`
+for `--log-level debug` — and both print a notice saying so. Both keep their
+short forms `-q` and `-v`, and neither has a removal date: they are in existing
+compose files and systemd units, and deleting them would break those for a
+cosmetic gain. `--log-level` is the only flag that sets the dial directly.
+
+When more than one is passed, `--log-level` wins, then `--verbose`, then
+`--quiet`. A `--log-level` whose value is unusable supplies *nothing*, so it
+loses to an alias that was also passed — same rule as the precedence chain, one
+level down.
 
 ### The two helpers disagree about `None`, on purpose
 

frontend/package-lock.json

@@ -109,4 +109,3 @@ export function PrototypeSwitcher({
     </div>
   );
 }
-