chore: create a custom warnings.warn wrapper

JohnVillalovos · JohnVillalovos · commit 75c5089b7d97 · 2022-02-06T10:47:47.000-08:00
Create a custom `warnings.warn` wrapper that will walk the stack trace
to find the first frame outside of the `gitlab/` path to print the
warning against. This will make it easier for users to find where in
their code the error is generated from
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
@@ -93,20 +93,26 @@ Examples:
 .. code-block:: python
 
    # list all the projects
-   projects = gl.projects.list()
+   projects = gl.projects.list(as_list=False)
    for project in projects:
        print(project)
 
    # get the group with id == 2
    group = gl.groups.get(2)
-   for project in group.projects.list():
+   for project in group.projects.list(as_list=False):
        print(project)
 
    # create a new user
    user_data = {'email': 'jen@foo.com', 'username': 'jen', 'name': 'Jen'}
    user = gl.users.create(user_data)
    print(user)
 
+.. warning::
+   Calling `list()` without any arguments will by default not return the complete list
+   of items. Use either the `all=True` or `as_list=False` parameters to get all the
+   items when using listing methods. See the :ref:`pagination` section for more
+   information.
+
 You can list the mandatory and optional attributes for object creation and
 update with the manager's ``get_create_attrs()`` and ``get_update_attrs()``
 methods. They return 2 tuples, the first one is the list of mandatory
@@ -133,7 +139,7 @@ Some objects also provide managers to access related GitLab resources:
 
    # list the issues for a project
    project = gl.projects.get(1)
-   issues = project.issues.list()
+   issues = project.issues.list(all=True)
 
 python-gitlab allows to send any data to the GitLab server when making queries.
 In case of invalid or missing arguments python-gitlab will raise an exception
@@ -150,9 +156,9 @@ conflict with python or python-gitlab when using them as kwargs:
 
 .. code-block:: python
 
-   gl.user_activities.list(from='2019-01-01')  ## invalid
+   gl.user_activities.list(from='2019-01-01', as_list=False)  ## invalid
 
-   gl.user_activities.list(query_parameters={'from': '2019-01-01'})  # OK
+   gl.user_activities.list(query_parameters={'from': '2019-01-01'}, as_list=False)  # OK
 
 Gitlab Objects
 ==============
@@ -222,6 +228,8 @@ a project (the previous example used 2 API calls):
    project = gl.projects.get(1, lazy=True)  # no API call
    project.star()  # API call
 
+.. _pagination:
+
 Pagination
 ==========
 
diff --git a/gitlab/__init__.py b/gitlab/__init__.py
@@ -20,6 +20,7 @@
 from typing import Any
 
 import gitlab.config  # noqa: F401
+from gitlab import utils as _utils
 from gitlab._version import (  # noqa: F401
     __author__,
     __copyright__,
@@ -40,11 +41,13 @@
 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,
+        _utils.warn(
+            message=(
+                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."
+            ),
+            category=DeprecationWarning,
         )
         return getattr(gitlab.const, name)
     raise AttributeError(f"module {__name__} has no attribute {name}")
diff --git a/gitlab/utils.py b/gitlab/utils.py
@@ -15,8 +15,11 @@
 # 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 pathlib
+import traceback
 import urllib.parse
-from typing import Any, Callable, Dict, Optional, Union
+import warnings
+from typing import Any, Callable, Dict, Optional, Type, Union
 
 import requests
 
@@ -90,3 +93,36 @@ def __new__(  # type: ignore
 
 def remove_none_from_dict(data: Dict[str, Any]) -> Dict[str, Any]:
     return {k: v for k, v in data.items() if v is not None}
+
+
+def warn(
+    message: str,
+    *,
+    category: Optional[Type] = None,
+    source: Optional[Any] = None,
+) -> None:
+    """This `warnings.warn` wrapper function attempts to show the location causing the
+    warning in the user code that called the library.
+
+    It does this by walking up the stack trace to find the first frame located outside
+    the `gitlab/` directory. This is helpful to users as it shows them their code that
+    is causing the warning.
+    """
+    # Get `stacklevel` for user code so we indicate where issue is in
+    # their code.
+    pg_dir = pathlib.Path(__file__).parent.resolve()
+    stack = traceback.extract_stack()
+    stacklevel = 1
+    warning_from = ""
+    for stacklevel, frame in enumerate(reversed(stack), start=1):
+        if stacklevel == 2:
+            warning_from = f" (python-gitlab: {frame.filename}:{frame.lineno})"
+        frame_dir = str(pathlib.Path(frame.filename).parent.resolve())
+        if not frame_dir.startswith(str(pg_dir)):
+            break
+    warnings.warn(
+        message=message + warning_from,
+        category=category,
+        stacklevel=stacklevel,
+        source=source,
+    )
diff --git a/gitlab/v4/objects/artifacts.py b/gitlab/v4/objects/artifacts.py
@@ -2,7 +2,6 @@
 GitLab API:
 https://docs.gitlab.com/ee/api/job_artifacts.html
 """
-import warnings
 from typing import Any, Callable, Optional, TYPE_CHECKING
 
 import requests
@@ -34,10 +33,12 @@ def __call__(
         *args: Any,
         **kwargs: Any,
     ) -> Optional[bytes]:
-        warnings.warn(
-            "The project.artifacts() method is deprecated and will be "
-            "removed in a future version. Use project.artifacts.download() instead.\n",
-            DeprecationWarning,
+        utils.warn(
+            message=(
+                "The project.artifacts() method is deprecated and will be removed in a "
+                "future version. Use project.artifacts.download() instead.\n"
+            ),
+            category=DeprecationWarning,
         )
         return self.download(
             *args,
diff --git a/gitlab/v4/objects/projects.py b/gitlab/v4/objects/projects.py
@@ -1,4 +1,3 @@
-import warnings
 from typing import Any, Callable, cast, Dict, List, Optional, TYPE_CHECKING, Union
 
 import requests
@@ -548,10 +547,12 @@ def transfer(self, to_namespace: Union[int, str], **kwargs: Any) -> None:
 
     @cli.register_custom_action("Project", ("to_namespace",))
     def transfer_project(self, *args: Any, **kwargs: Any) -> None:
-        warnings.warn(
-            "The project.transfer_project() method is deprecated and will be "
-            "removed in a future version. Use project.transfer() instead.",
-            DeprecationWarning,
+        utils.warn(
+            message=(
+                "The project.transfer_project() method is deprecated and will be "
+                "removed in a future version. Use project.transfer() instead."
+            ),
+            category=DeprecationWarning,
         )
         return self.transfer(*args, **kwargs)
 
@@ -562,10 +563,12 @@ def artifact(
         *args: Any,
         **kwargs: Any,
     ) -> Optional[bytes]:
-        warnings.warn(
-            "The project.artifact() method is deprecated and will be "
-            "removed in a future version. Use project.artifacts.raw() instead.",
-            DeprecationWarning,
+        utils.warn(
+            message=(
+                "The project.artifact() method is deprecated and will be "
+                "removed in a future version. Use project.artifacts.raw() instead."
+            ),
+            category=DeprecationWarning,
         )
         return self.artifacts.raw(*args, **kwargs)
 
diff --git a/tests/unit/test_utils.py b/tests/unit/test_utils.py
@@ -16,6 +16,7 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 import json
+import warnings
 
 from gitlab import utils
 
@@ -76,3 +77,21 @@ def test_json_serializable(self):
 
         obj = utils.EncodedId("we got/a/path")
         assert '"we%20got%2Fa%2Fpath"' == json.dumps(obj)
+
+
+class TestWarningsWrapper:
+    def test_warn(self):
+        warn_message = "short and stout"
+        warn_source = "teapot"
+
+        with warnings.catch_warnings(record=True) as caught_warnings:
+            utils.warn(message=warn_message, category=UserWarning, source=warn_source)
+        assert len(caught_warnings) == 1
+        warning = caught_warnings[0]
+        # File name is this file as it is the first file outside of the `gitlab/` path.
+        assert __file__ == warning.filename
+        assert warning.category == UserWarning
+        assert isinstance(warning.message, UserWarning)
+        assert warn_message in str(warning.message)
+        assert __file__ in str(warning.message)
+        assert warn_source == warning.source
