chore: add EncodedId string class to use to hold URL-encoded paths

JohnVillalovos · JohnVillalovos · commit 98961541d36a · 2022-01-09T17:38:12.000-08:00
Add EncodedId string class. This class returns a URL-encoded string
but ensures it will only URL-encode it once even if recursively
called.

Also added some functional tests of 'lazy' objects to make sure they
work.
diff --git a/gitlab/utils.py b/gitlab/utils.py
@@ -56,17 +56,83 @@ def copy_dict(dest: Dict[str, Any], src: Dict[str, Any]) -> None:
             dest[k] = v
 
 
+class EncodedId(str):
+    """A custom `str` class that will return the URL-encoded value of the string.
+
+    Features:
+      * Using it recursively will only url-encode the value once.
+      * Can accept either `str` or `int` as input value.
+      * Can be used in an f-string and output the URL-encoded string.
+
+    Reference to documentation on why this is necessary.
+
+    https://docs.gitlab.com/ee/api/index.html#namespaced-path-encoding
+
+    If using namespaced API requests, make sure that the NAMESPACE/PROJECT_PATH is
+    URL-encoded. For example, / is represented by %2F
+
+    https://docs.gitlab.com/ee/api/index.html#path-parameters
+
+    Path parameters that are required to be URL-encoded must be followed. If not, it
+    doesn’t match an API endpoint and responds with a 404. If there’s something in
+    front of the API (for example, Apache), ensure that it doesn’t decode the
+    URL-encoded path parameters."""
+
+    # `original_str` will contain the original string value that was used to create the
+    # first instance of EncodedId. We will use this original value to generate the
+    # URL-encoded value each time.
+    original_str: str
+
+    def __init__(self, value: Union[int, str]) -> None:
+        # At this point `super().__str__()` returns the URL-encoded value. Which means
+        # when using this as a `str` it will return the URL-encoded value.
+        #
+        # But `value` contains the original value passed in `EncodedId(value)`. We use
+        # this to always keep the original string that was received so that no matter
+        # how many times we recurse we only URL-encode our original string once.
+        if isinstance(value, int):
+            value = str(value)
+        # Make sure isinstance() for `EncodedId` comes before check for `str` as
+        # `EncodedId` is an instance of `str` and would pass that check.
+        elif isinstance(value, EncodedId):
+            # This is the key part as we are always keeping the original string even
+            # through multiple recursions.
+            value = value.original_str
+        elif isinstance(value, str):
+            pass
+        else:
+            raise ValueError(f"Unsupported type received: {type(value)}")
+        self.original_str = value
+        super().__init__()
+
+    def __new__(cls, value: Union[str, int, "EncodedId"]) -> "EncodedId":
+        if isinstance(value, int):
+            value = str(value)
+        # Make sure isinstance() for `EncodedId` comes before check for `str` as
+        # `EncodedId` is an instance of `str` and would pass that check.
+        elif isinstance(value, EncodedId):
+            # We use the original string value to URL-encode
+            value = value.original_str
+        elif isinstance(value, str):
+            pass
+        else:
+            raise ValueError(f"Unsupported type received: {type(value)}")
+        # Set the value our string will return
+        value = urllib.parse.quote(value, safe="")
+        return super().__new__(cls, value)
+
+
 @overload
 def _url_encode(id: int) -> int:
     ...
 
 
 @overload
-def _url_encode(id: str) -> str:
+def _url_encode(id: Union[str, EncodedId]) -> EncodedId:
     ...
 
 
-def _url_encode(id: Union[int, str]) -> Union[int, str]:
+def _url_encode(id: Union[int, str, EncodedId]) -> Union[int, EncodedId]:
     """Encode/quote the characters in the string so that they can be used in a path.
 
     Reference to documentation on why this is necessary.
@@ -84,9 +150,9 @@ def _url_encode(id: Union[int, str]) -> Union[int, str]:
     parameters.
 
     """
-    if isinstance(id, int):
+    if isinstance(id, (int, EncodedId)):
         return id
-    return urllib.parse.quote(id, safe="")
+    return EncodedId(id)
 
 
 def remove_none_from_dict(data: Dict[str, Any]) -> Dict[str, Any]:
diff --git a/tests/functional/api/test_groups.py b/tests/functional/api/test_groups.py
@@ -100,6 +100,7 @@ def test_groups(gl):
     member = group1.members.get(user2.id)
     assert member.access_level == gitlab.const.OWNER_ACCESS
 
+    gl.auth()
     group2.members.delete(gl.user.id)
 
 
diff --git a/tests/functional/api/test_lazy_objects.py b/tests/functional/api/test_lazy_objects.py
@@ -0,0 +1,17 @@
+def test_lazy_objects(gl, group):
+
+    group1 = gl.groups.create({"name": "group1", "path": "group1"})
+    gr1_project = gl.projects.create({"name": "gr1_project", "namespace_id": group1.id})
+
+    lazy_project = gl.projects.get(gr1_project.path_with_namespace, lazy=True)
+    lazy_project.refresh()
+
+    lazy_project = gl.projects.get(gr1_project.path_with_namespace, lazy=True)
+    lazy_project.mergerequests.list()
+
+    lazy_project = gl.projects.get(gr1_project.path_with_namespace, lazy=True)
+    lazy_project.description = "My stuff"
+    lazy_project.save()
+
+    gr1_project.delete()
+    group1.delete()
diff --git a/tests/unit/test_utils.py b/tests/unit/test_utils.py
@@ -15,6 +15,8 @@
 # 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 json
+
 from gitlab import utils
 
 
@@ -35,3 +37,56 @@ def test_url_encode():
     src = "docs/README.md"
     dest = "docs%2FREADME.md"
     assert dest == utils._url_encode(src)
+
+
+class TestEncodedId:
+    def test_init_str(self):
+        obj = utils.EncodedId("Hello")
+        assert "Hello" == str(obj)
+        assert "Hello" == f"{obj}"
+
+        obj = utils.EncodedId("this/is a/path")
+        assert "this%2Fis%20a%2Fpath" == str(obj)
+        assert "this%2Fis%20a%2Fpath" == f"{obj}"
+
+    def test_init_int(self):
+        obj = utils.EncodedId(23)
+        assert "23" == str(obj)
+        assert "23" == f"{obj}"
+
+    def test_init_encodeid_str(self):
+        value = "Goodbye"
+        obj_init = utils.EncodedId(value)
+        obj = utils.EncodedId(obj_init)
+        assert value == str(obj)
+        assert value == f"{obj}"
+        assert value == obj.original_str
+
+        value = "we got/a/path"
+        expected = "we%20got%2Fa%2Fpath"
+        obj_init = utils.EncodedId(value)
+        assert value == obj_init.original_str
+        # Show that no matter how many times we recursively call it we still only
+        # URL-encode it once.
+        obj = utils.EncodedId(
+            utils.EncodedId(utils.EncodedId(utils.EncodedId(utils.EncodedId(obj_init))))
+        )
+        assert expected == str(obj)
+        assert expected == f"{obj}"
+        # We have stored a copy of our original string
+        assert value == obj.original_str
+
+    def test_init_encodeid_int(self):
+        value = 23
+        expected = f"{value}"
+        obj_init = utils.EncodedId(value)
+        obj = utils.EncodedId(obj_init)
+        assert expected == str(obj)
+        assert expected == f"{obj}"
+
+    def test_json_serializable(self):
+        obj = utils.EncodedId("someone")
+        assert '"someone"' == json.dumps(obj)
+
+        obj = utils.EncodedId("we got/a/path")
+        assert '"we%20got%2Fa%2Fpath"' == json.dumps(obj)
