Merge pull request #1694 from python-gitlab/jlvillal/const_explicit

refactor: explicitly import gitlab.const values into top-level namespace

3 files changed, 53 insertions, 2 deletions

diff --git a/gitlab/__init__.py b/gitlab/__init__.py
index 7b79f22..824f177 100644
--- a/gitlab/__init__.py
+++ b/gitlab/__init__.py
@@ -17,6 +17,7 @@
 """Wrapper for the GitLab API."""
 
 import warnings
+from typing import Any
 
 import gitlab.config  # noqa: F401
 from gitlab.__version__ import (  # noqa: F401
@@ -28,7 +29,22 @@ from gitlab.__version__ import (  # noqa: F401
     __version__,
 )
 from gitlab.client import Gitlab, GitlabList  # noqa: F401
-from gitlab.const import *  # noqa: F401,F403
 from gitlab.exceptions import *  # noqa: F401,F403
 
 warnings.filterwarnings("default", category=DeprecationWarning, module="^gitlab")
+
+
+# NOTE(jlvillal): We are deprecating access to the gitlab.const values which
+# were previously imported into this namespace by the
+# 'from gitlab.const import *' statement.
+def __getattr__(name: str) -> Any:
+    # Deprecate direct access to constants without namespace
+    if name in gitlab.const._DEPRECATED:
+        warnings.warn(
+            f"\nDirect access to 'gitlab.{name}' is deprecated and will be "
+            f"removed in a future major python-gitlab release. Please "
+            f"use 'gitlab.const.{name}' instead.",
+            DeprecationWarning,
+        )
+        return getattr(gitlab.const, name)
+    raise AttributeError(f"module {__name__} has no attribute {name}")
diff --git a/gitlab/const.py b/gitlab/const.py
index 12faf88..48aa96d 100644
--- a/gitlab/const.py
+++ b/gitlab/const.py
@@ -17,6 +17,41 @@
 
 from gitlab.__version__ import __title__, __version__
 
+# NOTE(jlvillal): '_DEPRECATED' only affects users accessing constants via the
+# top-level gitlab.* namespace. See 'gitlab/__init__.py:__getattr__()' for the
+# consumer of '_DEPRECATED' For example 'x = gitlab.NO_ACCESS'.  We want users
+# to instead use constants by doing code like: gitlab.const.NO_ACCESS.
+_DEPRECATED = [
+    "DEFAULT_URL",
+    "DEVELOPER_ACCESS",
+    "GUEST_ACCESS",
+    "MAINTAINER_ACCESS",
+    "MINIMAL_ACCESS",
+    "NO_ACCESS",
+    "NOTIFICATION_LEVEL_CUSTOM",
+    "NOTIFICATION_LEVEL_DISABLED",
+    "NOTIFICATION_LEVEL_GLOBAL",
+    "NOTIFICATION_LEVEL_MENTION",
+    "NOTIFICATION_LEVEL_PARTICIPATING",
+    "NOTIFICATION_LEVEL_WATCH",
+    "OWNER_ACCESS",
+    "REPORTER_ACCESS",
+    "SEARCH_SCOPE_BLOBS",
+    "SEARCH_SCOPE_COMMITS",
+    "SEARCH_SCOPE_GLOBAL_SNIPPET_TITLES",
+    "SEARCH_SCOPE_ISSUES",
+    "SEARCH_SCOPE_MERGE_REQUESTS",
+    "SEARCH_SCOPE_MILESTONES",
+    "SEARCH_SCOPE_PROJECT_NOTES",
+    "SEARCH_SCOPE_PROJECTS",
+    "SEARCH_SCOPE_USERS",
+    "SEARCH_SCOPE_WIKI_BLOBS",
+    "USER_AGENT",
+    "VISIBILITY_INTERNAL",
+    "VISIBILITY_PRIVATE",
+    "VISIBILITY_PUBLIC",
+]
+
 DEFAULT_URL: str = "https://gitlab.com"
 
 NO_ACCESS: int = 0
diff --git a/gitlab/mixins.py b/gitlab/mixins.py
index 0159ecd..916da3c 100644
--- a/gitlab/mixins.py
+++ b/gitlab/mixins.py
@@ -618,7 +618,7 @@ class AccessRequestMixin(_RestObjectBase):
     )
     @exc.on_http_error(exc.GitlabUpdateError)
     def approve(
-        self, access_level: int = gitlab.DEVELOPER_ACCESS, **kwargs: Any
+        self, access_level: int = gitlab.const.DEVELOPER_ACCESS, **kwargs: Any
     ) -> None:
         """Approve an access request.