feat: add an asdict() method to the Gitlab Objects

JohnVillalovos · JohnVillalovos · commit 7220c55caa21 · 2022-02-02T14:08:30.000-08:00
Add an `asdict()` method that returns a dictionary representation copy
of the Gitlab Object. This is a copy and changes made to it will have
no impact on the Gitlab Object.

The `asdict()` method name was chosen as both the `dataclasses` and
`attrs` libraries have an `asdict()` function which has the similar
purpose of creating a dictionary represenation of an object.
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
@@ -192,6 +192,35 @@ You can print a Gitlab Object. For example:
    # Or explicitly via `pformat()`. This is equivalent to the above.
    print(project.pformat())
 
+You can get a dictionary representation copy of the Gitlab Object. Modifications made to
+the dictionary will have no impact on the GitLab Object. This can also be used
+to create a JSON representation of the object. There are two ways to retrieve a
+dictionary representation of the Gitlab Object.
+
+ * `asdict()` method. Returns a dictionary with updated attributes having precedence.
+ * `attributes` property. Returns a dictionary with original attributes having
+   precedence and then updated attributes. Also returns any relevant parent object
+   attributes.
+
+.. note::
+
+   `attributes` returns the parent object attributes that are defined in
+   `object._from_parent_attrs`. What this can mean is that for example a `ProjectIssue`
+   object will have a `project_id` key in the dictionary returned from `attributes` but
+   `asdict()` will not.
+
+
+.. code-block:: python
+
+   project = gl.projects.get(1)
+   project_dict = project.asdict()
+   # Do a JSON dump of the object
+   print(json.dumps(project.asdict()))
+
+   # Or a dictionary representation also containing some of the parent attributes
+   issue = project.issues.get(1)
+   attribute_dict = issue.attributes
+
 
 Base types
 ==========
diff --git a/gitlab/base.py b/gitlab/base.py
@@ -15,6 +15,7 @@
 # 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 copy
 import importlib
 import pprint
 import textwrap
@@ -144,15 +145,16 @@ def __getattr__(self, name: str) -> Any:
     def __setattr__(self, name: str, value: Any) -> None:
         self.__dict__["_updated_attrs"][name] = value
 
+    def asdict(self) -> Dict[str, Any]:
+        data = copy.deepcopy(self._attrs)
+        data.update(copy.deepcopy(self._updated_attrs))
+        return data
+
     def __str__(self) -> str:
-        data = self._attrs.copy()
-        data.update(self._updated_attrs)
-        return f"{type(self)} => {data}"
+        return f"{type(self)} => {self.asdict()}"
 
     def pformat(self) -> str:
-        data = self._attrs.copy()
-        data.update(self._updated_attrs)
-        return f"{type(self)} => \n{pprint.pformat(data)}"
+        return f"{type(self)} => \n{pprint.pformat(self.asdict())}"
 
     def pprint(self) -> None:
         print(self.pformat())
diff --git a/tests/unit/test_base.py b/tests/unit/test_base.py
@@ -249,3 +249,71 @@ def test_pprint(self, capfd, fake_manager):
             " 'ham': 'eggseggseggseggseggseggseggseggseggseggseggseggseggseggseggs'}\n"
         )
         assert stderr == ""
+
+    def test_asdict(self, fake_manager):
+        fake_object = FakeObject(fake_manager, {"attr1": "foo", "alist": [1, 2, 3]})
+        assert fake_object.attr1 == "foo"
+        result = fake_object.asdict()
+        assert result == {"attr1": "foo", "alist": [1, 2, 3]}
+        # Demonstrate modifying the dictionary does not modify the object
+        result["attr1"] = "testing"
+        result["alist"].append(4)
+        assert result == {"attr1": "testing", "alist": [1, 2, 3, 4]}
+        assert fake_object.attr1 == "foo"
+        assert fake_object.alist == [1, 2, 3]
+        # asdict() returns the updated value
+        fake_object.attr1 = "spam"
+        assert fake_object.asdict() == {"attr1": "spam", "alist": [1, 2, 3]}
+        # Modify attribute and then ensure modifying a list in the returned dict won't
+        # modify the list in the object.
+        fake_object.attr1 = [9, 7, 8]
+        assert fake_object.asdict() == {
+            "attr1": [9, 7, 8],
+            "alist": [1, 2, 3],
+        }
+        result = fake_object.asdict()
+        result["attr1"].append(1)
+        assert fake_object.asdict() == {
+            "attr1": [9, 7, 8],
+            "alist": [1, 2, 3],
+        }
+
+    def test_attributes(self, fake_manager):
+        fake_object = FakeObject(fake_manager, {"attr1": [1, 2, 3]})
+        assert fake_object.attr1 == [1, 2, 3]
+        result = fake_object.attributes
+        assert result == {"attr1": [1, 2, 3]}
+
+        # Updated attribute value is not reflected in `attributes`
+        fake_object.attr1 = "hello"
+        assert fake_object.attributes == {"attr1": [1, 2, 3]}
+        assert fake_object.attr1 == "hello"
+        # New attribute is in `attributes`
+        fake_object.new_attrib = "spam"
+        assert fake_object.attributes == {"attr1": [1, 2, 3], "new_attrib": "spam"}
+
+        # Modifying the dictionary can cause modification to the object :(
+        result = fake_object.attributes
+        result["attr1"].append(10)
+        assert result == {"attr1": [1, 2, 3, 10], "new_attrib": "spam"}
+        assert fake_object.attributes == {"attr1": [1, 2, 3, 10], "new_attrib": "spam"}
+        assert fake_object.attr1 == "hello"
+
+
+    def test_asdict_vs_attributes(self, fake_manager):
+        fake_object = FakeObject(fake_manager, {"attr1": "foo"})
+        assert fake_object.attr1 == "foo"
+        result = fake_object.asdict()
+        assert result == {"attr1": "foo"}
+
+        # New attribute added, return same result
+        assert fake_object.attributes == fake_object.asdict()
+        fake_object.attr2 = "eggs"
+        assert fake_object.attributes == fake_object.asdict()
+        # Update attribute, return different result
+        fake_object.attr1 = "hello"
+        assert fake_object.attributes != fake_object.asdict()
+        # asdict() returns the updated value
+        assert fake_object.asdict() == {"attr1": "hello", "attr2": "eggs"}
+        # `attributes` returns original value
+        assert fake_object.attributes == {"attr1": "foo", "attr2": "eggs"}
