Verbosity (#1296)

* Verbosity

 - Implementing VerticaPy verbosity.

[Only Part1 is implemented]

* PART2

 - multiple corrections

* correction 3

* Correction 3

* PART 4

* PART5

 - should be the last part of this change.

* final correction

Author: oualib

verticapy/__init__.py

@@ -37,8 +37,8 @@
 __url__: str = "https://github.com/vertica/verticapy/"
 __license__: str = "Apache License, Version 2.0"
 __version__: str = "1.0.5"
-__iteration__: int = 2
-__date__: str = "01102024"
+__iteration__: int = 1
+__date__: str = "02102024"
 __last_commit__: str = "c4fa73aaaf54051fb35b325a5dd77573ba9b3f4c"
 __long_version__: str = f"{__version__}-{__iteration__}—{__date__}-{__last_commit__}"
 __codecov__: float = 0.84

verticapy/_config/config.py

@@ -379,6 +379,10 @@ def set_option(key: str, value: Any = None) -> None:
             [bool]
             If set to ``True``, a loading bar is displayed
             when using iterative functions.
+        - verbosity
+            [int]
+            API Verbosity, must be a value between 0 and 3.
+            0 (silent) | 1 (warning) | 2 (info) | 3 (debug)
 
     value: object, optional
         New value of the option.
@@ -758,3 +762,11 @@ def set_option(key: str, value: Any = None) -> None:
 
 # Verbosity
 register_option(Option("print_info", True, "", bool_validator))
+register_option(
+    Option(
+        "verbosity",
+        2,
+        "",
+        in_validator([0, 1, 2, 3]),
+    )
+)

verticapy/_utils/_display.py

@@ -16,7 +16,7 @@
 """
 import html
 import shutil
-from typing import Optional
+from typing import Literal, Optional
 
 import verticapy._config.config as conf
 from verticapy._typing import NoneType

verticapy/_utils/_parsers.py

@@ -17,18 +17,15 @@
 import io
 import os
 from typing import List
-import warnings
 
 import verticapy._config.config as conf
+from verticapy._utils._print import print_message
 from verticapy._utils._sql._format import list_strip
 
 if conf.get_import_success("graphviz"):
     import graphviz
     from graphviz import Source
 
-if conf.get_import_success("IPython"):
-    from IPython.display import display
-
 # CSV
 
 
@@ -104,7 +101,7 @@ def get_header_names(
                     "to CSV while retaining its indexes.\nTip: Use "
                     "index=False when exporting with pandas.DataFrame.to_csv."
                 )
-            warnings.warn(warning_message, Warning)
+            print_message(warning_message, "warning")
     return list_strip(file_header)
 
 
@@ -329,8 +326,5 @@ def parse_explain_graphviz(rows: list[str], display_trees: bool = True) -> list:
             result += [row]
     if display_trees:
         for row in result:
-            if isinstance(row, str) or not (conf.get_import_success("IPython")):
-                print(row)
-            else:
-                display(row)
+            print_message(row, "display")
     return result

verticapy/_utils/_print.py

@@ -0,0 +1,57 @@
+"""
+Copyright  (c)  2018-2024 Open Text  or  one  of its
+affiliates.  Licensed  under  the   Apache  License,
+Version 2.0 (the  "License"); You  may  not use this
+file except in compliance with the License.
+
+You may obtain a copy of the License at:
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless  required  by applicable  law or  agreed to in
+writing, software  distributed  under the  License is
+distributed on an  "AS IS" BASIS,  WITHOUT WARRANTIES
+OR CONDITIONS OF ANY KIND, either express or implied.
+See the  License for the specific  language governing
+permissions and limitations under the License.
+"""
+from typing import Literal
+import warnings
+
+import verticapy._config.config as conf
+
+if conf.get_import_success("IPython"):
+    from IPython.display import display, HTML, Markdown
+
+
+def print_message(
+    message: str, mtype: Literal["print", "warning", "display", "markdown"] = "print"
+) -> None:
+    """
+    Prints the input message or warning.
+    This function is used to manage the
+    verbosity.
+    """
+    mtype = mtype.lower().strip()
+    if mtype == "warning" and conf.get_option("verbosity") >= 1:
+        warnings.warn(message, Warning)
+    elif (
+        mtype == "print"
+        and conf.get_option("print_info")
+        and conf.get_option("verbosity") >= 2
+    ):
+        print(message)
+    elif (
+        mtype in ("display", "markdown")
+        and conf.get_option("print_info")
+        and conf.get_option("verbosity") >= 2
+    ):
+        if conf.get_import_success("IPython"):
+            try:
+                if mtype == "markdown":
+                    display(Markdown(message))
+                else:
+                    display(HTML(message))
+            except:
+                display(message)
+        else:
+            print(message)

verticapy/_utils/_sql/_display.py

@@ -18,11 +18,9 @@
 from typing import Optional
 
 import verticapy._config.config as conf
+from verticapy._utils._print import print_message
 from verticapy._utils._sql._format import clean_query, indent_vpy_sql
 
-if conf.get_import_success("IPython"):
-    from IPython.display import HTML, display
-
 
 def print_query(query: str, title: Optional[str] = None) -> None:
     """
@@ -64,13 +62,13 @@ def print_query(query: str, title: Optional[str] = None) -> None:
     query_print = clean_query(query)
     query_print = indent_vpy_sql(query)
     if conf.get_import_success("IPython"):
-        display(HTML(f"<h4>{title}</h4>"))
+        print_message(f"<h4>{title}</h4>", "display")
         query_print = query_print.replace("\n", " <br>").replace("  ", " &emsp; ")
-        display(HTML(query_print))
+        print_message(query_print, "display")
     else:
-        print(f"$ {title} $\n")
-        print(query_print)
-        print("-" * int(screen_columns) + "\n")
+        print_message(f"$ {title} $\n")
+        print_message(query_print)
+        print_message("-" * int(screen_columns) + "\n")
 
 
 def print_time(elapsed_time: float) -> None:
@@ -103,7 +101,9 @@ def print_time(elapsed_time: float) -> None:
     """
     screen_columns = shutil.get_terminal_size().columns
     if conf.get_import_success("IPython"):
-        display(HTML(f"<div><b>Execution: </b> {round(elapsed_time, 3)}s</div>"))
+        print_message(
+            f"<div><b>Execution: </b> {round(elapsed_time, 3)}s</div>", "display"
+        )
     else:
-        print(f"Execution: {round(elapsed_time, 3)}s")
-        print("-" * int(screen_columns) + "\n")
+        print_message(f"Execution: {round(elapsed_time, 3)}s")
+        print_message("-" * int(screen_columns) + "\n")

verticapy/_utils/_sql/_format.py

@@ -15,7 +15,6 @@
 permissions and limitations under the License.
 """
 import re
-import warnings
 from typing import Any, Iterable, Literal, Optional
 
 import numpy as np
@@ -24,13 +23,11 @@
 
 import verticapy._config.config as conf
 from verticapy._utils._object import read_pd
+from verticapy._utils._print import print_message
 from verticapy._utils._sql._cast import to_dtype_category
 from verticapy._typing import NoneType, SQLColumns, SQLExpression
 from verticapy.errors import ParsingError
 
-if conf.get_import_success("IPython"):
-    from IPython.display import display, Markdown
-
 """
 SQL KEYWORDS
 """
@@ -640,7 +637,6 @@ def format_query(
         construct others, simplifying the overall
         code.
     """
-    display_success = print_sql and conf.get_import_success("IPython")
     res = clean_query(query)
     html_res = res
 
@@ -695,15 +691,13 @@ def format_query(
             .replace("\n", "<br>")
             .replace("    ", "&nbsp;&nbsp;&nbsp;&nbsp;")
         )
-    if display_success:
-        display(Markdown(html_res))
     if indent_sql:
         res = indent_vpy_sql(res)
     if print_sql:
-        print(res)
+        print_message(res, "markdown")
     if only_html:
         return html_res
-    elif display_success:
+    elif print_sql:
         return res, html_res
     return res, None
 
@@ -1574,7 +1568,7 @@ def replace_vars_in_query(query: SQLExpression, locals_dict: dict) -> SQLExpress
                 warning_message = (
                     f"Failed to replace variables in the query.\nError: {e}"
                 )
-                warnings.warn(warning_message, Warning)
+                print_message(warning_message, "warning")
                 fail = True
         if not fail:
             object_type = None

verticapy/_utils/_sql/_sys.py

@@ -172,7 +172,9 @@ def _executeSQL(
         query = clean_query(query)
 
     cursor = current_cursor()
-    if conf.get_option("sql_on") and print_time_sql:
+    if (
+        conf.get_option("sql_on") or (conf.get_option("verbosity") == 3)
+    ) and print_time_sql:
         print_query(query, title)
     start_time = time.time()
     if data:
@@ -183,7 +185,9 @@ def _executeSQL(
     else:
         cursor.execute(query)
     elapsed_time = time.time() - start_time
-    if conf.get_option("time_on") and print_time_sql:
+    if (
+        conf.get_option("time_on") or (conf.get_option("verbosity") == 3)
+    ) and print_time_sql:
         print_time(elapsed_time)
     if method == "fetchrow":
         return cursor.fetchone()

verticapy/connection/connect.py

@@ -21,7 +21,8 @@
 from vertica_python.vertica.cursor import Cursor
 from vertica_python.vertica.connection import Connection
 
-import verticapy._config.config as conf
+from verticapy._utils._print import print_message
+
 from verticapy.connection.errors import ConnectionError, OAuthTokenRefreshError
 from verticapy.connection.global_connection import (
     get_global_connection,
@@ -142,10 +143,9 @@ def connect(section: str, dsn: Optional[str] = None) -> None:
             gb_conn.set_connection(
                 vertica_connection(section, dsn, config=None), section, dsn
             )
-        if conf.get_option("print_info"):
-            print("Connected Successfully!")
+        print_message("Connected Successfully!")
     except OAuthTokenRefreshError as error:
-        print(
+        print_message(
             "Access Denied: Your authentication credentials are incorrect or have expired. Please retry"
         )
         new_connection(
@@ -155,13 +155,12 @@ def connect(section: str, dsn: Optional[str] = None) -> None:
             gb_conn.set_connection(
                 vertica_connection(section, dsn, config=None), section, dsn
             )
-            if conf.get_option("print_info"):
-                print("Connected Successfully!")
+            print_message("Connected Successfully!")
         except OAuthTokenRefreshError as error:
-            print("Error persists:")
+            print_message("Error persists:")
             raise error
     except ConnectionError as error:
-        print(
+        print_message(
             "A connection error occured. Common reasons may be an invalid host, port, or, if requiring "
             "OAuth and token refresh, this may be due to an incorrect or malformed token url."
         )

verticapy/connection/oauth_manager.py

@@ -18,12 +18,11 @@
 from __future__ import print_function, division, absolute_import, annotations
 
 import requests
-import warnings
 
-from urllib3.poolmanager import PoolManager
 from requests.adapters import HTTPAdapter
+from urllib3.poolmanager import PoolManager
 
-
+from verticapy._utils._print import print_message
 from verticapy.connection.errors import (
     OAuthTokenRefreshError,
     OAuthConfigurationError,
@@ -66,7 +65,7 @@ def set_config(self, configs) -> None:
             for k, v in configs.items():
                 if k not in valid_keys:
                     invalid_key = f"Unrecognized OAuth config property: {k}"
-                    warnings.warn(invalid_key)
+                    print_message(invalid_key, "warning")
                     continue
                 if v is None or v == "":  # ignore empty value
                     continue