From b476afe9928c6e844b86b56f9316ae1a1fe254f2 Mon Sep 17 00:00:00 2001
From: "John L. Villalovos" <john@sodarock.com>
Date: Mon, 3 Oct 2022 21:29:54 -0700
Subject: [PATCH] chore: add bare-minimum logging support

Follow the Python documentation guidelines for "Configuring Logging
for a Library" [1]

Which is basically adding these two lines:
  import logging
  logging.getLogger(__name__).addHandler(logging.NullHandler())

Setup a very basic usage of logging in `gitlab/client.py`

By using the NullHandler it means that by default any log messages
output will not be displayed. It is up to the client application to do
a `logging.basicConfig()` call to get log messages to display.

[1] https://docs.python.org/3/howto/logging.html#configuring-logging-for-a-library
Related: #2080
---
 gitlab/__init__.py          |  1 +
 gitlab/_logging.py          | 31 +++++++++++++++++++++++++++++++
 gitlab/client.py            |  5 ++++-
 tests/unit/test__logging.py | 24 ++++++++++++++++++++++++
 4 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 gitlab/_logging.py
 create mode 100644 tests/unit/test__logging.py

diff --git a/gitlab/__init__.py b/gitlab/__init__.py
index e7aafdae8..889a52cf7 100644
--- a/gitlab/__init__.py
+++ b/gitlab/__init__.py
@@ -19,6 +19,7 @@
 import warnings
 from typing import Any
 
+import gitlab._logging
 import gitlab.config  # noqa: F401
 from gitlab import utils as _utils
 from gitlab._version import (  # noqa: F401
diff --git a/gitlab/_logging.py b/gitlab/_logging.py
new file mode 100644
index 000000000..207e8747c
--- /dev/null
+++ b/gitlab/_logging.py
@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+"""
+The initialization of the logging module is intentionaly done here in the
+_logging.py module so that it will be initialized before any other of our
+python-gitlab modules are loaded. So if they do logging upon being loaded it
+will allow them to do it safely.
+"""
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import logging
+from typing import List
+
+__all__: List[str] = []
+
+# Using the `NullHandler` means that any log messages generated will not be
+# output unless the client application configures logging. For example by
+# calling `logging.basicConfig()`
+_module_root_logger_name = __name__.split(".", maxsplit=1)[0]
+logging.getLogger(_module_root_logger_name).addHandler(logging.NullHandler())
diff --git a/gitlab/client.py b/gitlab/client.py
index 94fb66a4a..3b1e49bda 100644
--- a/gitlab/client.py
+++ b/gitlab/client.py
@@ -1,5 +1,6 @@
 """Wrapper for the GitLab API."""
 
+import logging
 import os
 import re
 import time
@@ -14,6 +15,8 @@
 import gitlab.exceptions
 from gitlab import _backends, utils
 
+LOG = logging.getLogger(__name__)
+
 REDIRECT_MSG = (
     "python-gitlab detected a {status_code} ({reason!r}) redirection. You must update "
     "your GitLab URL to the correct URL to avoid issues. The redirection was from: "
@@ -540,7 +543,6 @@ def _set_auth_info(self) -> None:
 
     @staticmethod
     def enable_debug() -> None:
-        import logging
         from http.client import HTTPConnection  # noqa
 
         HTTPConnection.debuglevel = 1
@@ -549,6 +551,7 @@ def enable_debug() -> None:
         requests_log = logging.getLogger("requests.packages.urllib3")
         requests_log.setLevel(logging.DEBUG)
         requests_log.propagate = True
+        LOG.debug("Enabled debug mode for python-gitlab")
 
     def _get_session_opts(self) -> Dict[str, Any]:
         return {
diff --git a/tests/unit/test__logging.py b/tests/unit/test__logging.py
new file mode 100644
index 000000000..9248f861c
--- /dev/null
+++ b/tests/unit/test__logging.py
@@ -0,0 +1,24 @@
+import logging
+
+import pytest
+
+from gitlab import _logging
+
+
+@pytest.fixture
+def LOG():
+    return logging.getLogger(_logging._module_root_logger_name)
+
+
+def test_module_root_logger_name():
+    assert _logging._module_root_logger_name == "gitlab"
+
+
+def test_module_name(LOG):
+    assert LOG.name == "gitlab"
+
+
+def test_logger_null_handler(LOG):
+    assert len(LOG.handlers) == 1
+    handler = LOG.handlers[0]
+    assert isinstance(handler, logging.NullHandler)