Replace print/verbose with standard logging (#337)

* logging: add NullHandler, replace prints with logging in auth and types

- lyricsgenius/__init__.py: add NullHandler per library logging best practice
- auth.py: replace print() with logger.warning/info
- types/base.py: remove verbose param from save_lyrics(), replace prints with logger.debug
- types/artist.py: deprecate verbose in add_song()/save_lyrics(), replace prints with logger.debug
- types/song.py: deprecate verbose in save_lyrics(), remove pass-through to super()
- types/album.py: deprecate verbose in save_lyrics(), remove pass-through to super()

* logging: replace self.verbose/print with logger in genius.py

- Remove self.verbose attribute entirely
- Deprecate verbose __init__ param with DeprecationWarning shim
- Replace all if self.verbose: print(...) guards with module-level
  logger calls at appropriate levels:
  - INFO: search progress, song count, artist name changes
  - DEBUG: skipped/rejected songs, alternative search attempts
  - WARNING: not-found results, missing lyrics sections

* logging: wire --verbose flag to logging in CLI

- Add module-level logger
- Drop verbose=args.verbose from Genius() constructor call
- --verbose now calls logging.basicConfig(level=DEBUG) so all
  lyricsgenius log records surface to stderr
- Replace guarded print() for 'Saving lyrics' with logger.info()

* tests: remove deprecated verbose= kwargs from all test calls

* chore: bump version to 3.11.0

Replace print/verbose with standard Python logging (minor feature change).

* logging: add enable_logging() convenience helper

One-liner for scripts/notebooks that handles basicConfig with a
sensible default format:

    lyricsgenius.enable_logging()
    lyricsgenius.enable_logging(logging.INFO)
    lyricsgenius.enable_logging(fmt='%(asctime)s %(levelname)s: %(message)s')

Updates README and docs accordingly.

Author: johnwmillr

README.md

@@ -88,12 +88,18 @@ album.save_lyrics()
 There are various options configurable as parameters within the `Genius` class:
 
 ```python
-genius.verbose = False # Turn off status messages
 genius.remove_section_headers = True # Remove section headers (e.g. [Chorus]) from lyrics when searching
 genius.skip_non_songs = False # Include hits thought to be non-songs (e.g. track lists)
 genius.excluded_terms = ["(Remix)", "(Live)"] # Exclude songs with these words in their title
 ```
 
+By default the library is silent. To enable progress logging:
+
+```python
+import lyricsgenius
+lyricsgenius.enable_logging()  # defaults to DEBUG; pass logging.INFO for less output
+```
+
 You can also call the package from the command line:
 
 ```bash

docs/src/usage.rst

@@ -54,9 +54,6 @@ There are various options configurable as parameters within the
 
 .. code:: python
 
-   # Turn off status messages
-   genius.verbose = False 
-
    # Remove section headers (e.g. [Chorus]) from lyrics when searching
    genius.remove_section_headers = True 
 
@@ -66,6 +63,13 @@ There are various options configurable as parameters within the
    # Exclude songs with these words/phrases in their title (case-insensitive)
    genius.excluded_terms = ["(Remix)", "(Live)"]
 
+By default the library is silent. To enable progress logging:
+
+.. code:: python
+
+   import lyricsgenius
+   lyricsgenius.enable_logging()  # defaults to DEBUG; pass logging.INFO for less output
+
 You can also call the package from the command line:
 
 .. code:: bash

lyricsgenius/__init__.py

@@ -3,10 +3,39 @@
 # See LICENSE for details
 """A library that provides a Python interface to the Genius API"""
 
+import logging
 import sys
 
 assert sys.version_info[0] == 3, "LyricsGenius requires Python 3."
 from lyricsgenius.api import API, PublicAPI
 from lyricsgenius.auth import OAuth2
 from lyricsgenius.genius import Genius
 from lyricsgenius.utils import auth_from_environment
+
+# Standard library best practice for packages: add NullHandler so that log
+# records are silently discarded unless the *application* configures logging.
+logging.getLogger("lyricsgenius").addHandler(logging.NullHandler())
+
+_LOG_FORMAT = "%(levelname)s %(name)s: %(message)s"
+
+
+def enable_logging(level: int = logging.DEBUG, fmt: str = _LOG_FORMAT) -> None:
+    """Enable lyricsgenius logging output to stderr.
+
+    A convenience wrapper around :func:`logging.basicConfig` that applies a
+    sensible default format. Call this once near the top of your script before
+    creating a :class:`Genius` instance.
+
+    Args:
+        level: Logging level (default ``logging.DEBUG``). Use
+            ``logging.INFO`` to suppress debug-level messages.
+        fmt: Log format string (default ``"%(levelname)s %(name)s: %(message)s"``).
+
+    Example::
+
+        import lyricsgenius
+        lyricsgenius.enable_logging()
+        lyricsgenius.enable_logging(logging.INFO)
+        lyricsgenius.enable_logging(fmt="%(asctime)s %(levelname)s: %(message)s")
+    """
+    logging.basicConfig(level=level, format=fmt)

lyricsgenius/__main__.py

@@ -1,10 +1,13 @@
 import argparse
+import logging
 import os
 from typing import Callable, Literal
 
 from . import Genius
 from .types import Album, Artist, Song
 
+logger = logging.getLogger(__name__)
+
 SearchResult = Song | Artist | Album
 
 
@@ -37,8 +40,7 @@ def __call__(self, args: argparse.Namespace) -> None:
             if not args.save:
                 print(result.to_text() if format == "txt" else result.to_json())
             else:
-                if args.verbose:
-                    print(f"Saving lyrics in {format.upper()} format.")
+                logger.info("Saving lyrics in %s format.", format.upper())
                 result.save_lyrics(extension=format, overwrite=args.overwrite)
 
 
@@ -99,10 +101,19 @@ def main() -> None:
         help="Specify your Genius API access token (optional). If not provided, it will be read from the GENIUS_ACCESS_TOKEN environment variable.",
     )
     optional.add_argument(
-        "-v", "--verbose", action="store_true", help="Turn on the API verbosity"
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Enable verbose logging output (sets log level to DEBUG)",
     )
     args: argparse.Namespace = parser.parse_args()
 
+    if args.verbose:
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(levelname)s %(name)s: %(message)s",
+        )
+
     # Create an instance of the Genius class
     token: str | None = (
         args.token if args.token else os.environ.get("GENIUS_ACCESS_TOKEN", None)
@@ -112,7 +123,7 @@ def main() -> None:
             "Must provide access token either as an argument or as an environment variable."
         )
 
-    api = Genius(token, verbose=args.verbose, timeout=10)
+    api = Genius(token, timeout=10)
     Searcher(api, args.search_type)(args)
 
 

lyricsgenius/auth.py

@@ -1,3 +1,4 @@
+import logging
 import os
 import webbrowser
 from typing import Any, ClassVar, Self
@@ -8,6 +9,8 @@
 from .types.types import ScopeT
 from .utils import parse_redirected_url
 
+logger = logging.getLogger(__name__)
+
 
 class OAuth2(Sender):
     """Genius OAuth2 authorization flow.
@@ -45,7 +48,7 @@ def __init__(
         if os.environ.get("GENIUS_ACCESS_TOKEN"):
             super().__init__()
         else:
-            print(
+            logger.warning(
                 "GENIUS_ACCESS_TOKEN not found in environment. "
                 "Falling back to the public API (some features may be unavailable)."
             )
@@ -155,7 +158,7 @@ def prompt_user(self) -> str:
 
         """
         url = self.url
-        print("Opening browser for Genius login...")
+        logger.info("Opening browser for Genius login...")
         webbrowser.open(url)
         redirected = input("Please paste redirect URL: ").strip()