Add docstrings and remove some duplicate code

gramps/gen/lib/baseobj.py

@@ -2,6 +2,7 @@
 # Gramps - a GTK+/GNOME based genealogy program
 #
 # Copyright (C) 2000-2006  Donald N. Allingham
+# Copyright (C) 2024       Nick Hall
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -58,13 +59,42 @@ def unserialize(self, data):
         """
 
     def get_object_state(self):
+        """
+        Get the current object state as a dictionary.
+
+        By default this returns the public attributes of the instance.  This
+        method can be overridden if the class requires other attributes or
+        properties to be saved.
+
+        This method is called to provide the information required to serialize
+        the object.
+
+        :returns: Returns a dictionary of attributes that represent the state
+                  of the object.
+        :rtype: dict
+        """
         attr_dict = {"_class": self.__class__.__name__}
         for key, value in self.__dict__.items():
             if not key.startswith("_"):
                 attr_dict[key] = value
         return attr_dict
 
     def set_object_state(self, attr_dict):
+        """
+        Set the current object state using information provided in the given
+        dictionary.
+
+        By default this sets the state of the object assuming that all items in
+        the dictionary map to public attributes.  This method can be overridden
+        to set the state using custom functionality.  For performance reasons
+        it is useful to set a property without calling its setter function.  As
+        JSON provides no distinction between tuples and lists, this method can
+        also be use to convert lists into tuples where required.
+
+        :param attr_dict: A dictionary of attributes that represent the state of
+                          the object.
+        :type attr_dict: dict
+        """
         for key, value in attr_dict.items():
             if key != "_class":
                 setattr(self, key, value)

gramps/gen/lib/date.py

@@ -5,7 +5,7 @@
 # Copyright (C) 2009-2013  Douglas S. Blank
 # Copyright (C) 2013       Paul Franklin
 # Copyright (C) 2013-2014  Vassilii Khachaturov
-# Copyright (C) 2017       Nick Hall
+# Copyright (C) 2017,2024  Nick Hall
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -750,19 +750,16 @@ def unserialize(self, data):
             raise DateError("Invalid date to unserialize")
         return self
 
-    def get_object_state(self):
-        attr_dict = {"_class": self.__class__.__name__}
-        for key, value in self.__dict__.items():
-            if not key.startswith("_"):
-                attr_dict[key] = value
-        return attr_dict
-
     def set_object_state(self, attr_dict):
-        for key, value in attr_dict.items():
-            if key == "dateval":
-                value = tuple(value)
-            if key != "_class":
-                setattr(self, key, value)
+        """
+        Set the current object state using information provided in the given
+        dictionary.
+
+        We override this method to convert `dateval` into a tuple.
+        """
+        if "dateval" in attr_dict:
+            attr_dict["dateval"] = tuple(attr_dict["dateval"])
+        super().set_object_state(attr_dict)
 
     @classmethod
     def get_schema(cls):

gramps/gen/lib/event.py

@@ -4,7 +4,7 @@
 # Copyright (C) 2000-2007  Donald N. Allingham
 # Copyright (C) 2010       Michiel D. Nauta
 # Copyright (C) 2011       Tim G L Lyons
-# Copyright (C) 2017       Nick Hall
+# Copyright (C) 2017,2024  Nick Hall
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -137,12 +137,23 @@ def serialize(self, no_text_date=False):
         )
 
     def get_object_state(self):
+        """
+        Get the current object state as a dictionary.
+
+        We override this method to handle the `type` and `description` properties.
+        """
         attr_dict = super().get_object_state()
         attr_dict["type"] = self.__type
         attr_dict["description"] = self.__description
         return attr_dict
 
     def set_object_state(self, attr_dict):
+        """
+        Set the current object state using information provided in the given
+        dictionary.
+
+        We override this method to handle the `type` and `description` properties.
+        """
         if "type" in attr_dict:
             self.__type = attr_dict["type"]
             del attr_dict["type"]

gramps/gen/lib/eventref.py

@@ -5,7 +5,7 @@
 # Copyright (C) 2010       Michiel D. Nauta
 # Copyright (C) 2011       Tim G L Lyons
 # Copyright (C) 2013       Doug Blank <[email protected]>
-# Copyright (C) 2017       Nick Hall
+# Copyright (C) 2017,2024  Nick Hall
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -87,11 +87,22 @@ def serialize(self):
         )
 
     def get_object_state(self):
+        """
+        Get the current object state as a dictionary.
+
+        We override this method to handle the `role` property.
+        """
         attr_dict = super().get_object_state()
         attr_dict["role"] = self.__role
         return attr_dict
 
     def set_object_state(self, attr_dict):
+        """
+        Set the current object state using information provided in the given
+        dictionary.
+
+        We override this method to handle the `role` property.
+        """
         self.__role = attr_dict["role"]
         del attr_dict["role"]
         super().set_object_state(attr_dict)

gramps/gen/lib/mediaref.py

@@ -5,7 +5,7 @@
 # Copyright (C) 2010       Michiel D. Nauta
 # Copyright (C) 2011       Tim G L Lyons
 # Copyright (C) 2013       Doug Blank <[email protected]>
-# Copyright (C) 2017       Nick Hall
+# Copyright (C) 2017,2024  Nick Hall
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -152,6 +152,12 @@ def unserialize(self, data):
         return self
 
     def set_object_state(self, attr_dict):
+        """
+        Set the current object state using information provided in the given
+        dictionary.
+
+        We override this method to convert `rect` into a tuple.
+        """
         rect = attr_dict["rect"]
         if rect is not None:
             attr_dict["rect"] = tuple(rect)

gramps/gen/lib/person.py

@@ -1,10 +1,10 @@
 #
 # Gramps - a GTK+/GNOME based genealogy program
 #
-# Copyright (C) 2000-2007  Donald N. Allingham
-# Copyright (C) 2010       Michiel D. Nauta
-# Copyright (C) 2010,2017  Nick Hall
-# Copyright (C) 2011       Tim G L Lyons
+# Copyright (C) 2000-2007       Donald N. Allingham
+# Copyright (C) 2010            Michiel D. Nauta
+# Copyright (C) 2010,2017,2024  Nick Hall
+# Copyright (C) 2011            Tim G L Lyons
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -323,11 +323,22 @@ def unserialize(self, data):
         return self
 
     def get_object_state(self):
+        """
+        Get the current object state as a dictionary.
+
+        We override this method to handle the `gender` property.
+        """
         attr_dict = super().get_object_state()
         attr_dict["gender"] = self.__gender
         return attr_dict
 
     def set_object_state(self, attr_dict):
+        """
+        Set the current object state using information provided in the given
+        dictionary.
+
+        We override this method to handle the `gender` property.
+        """
         if "gender" in attr_dict:
             self.__gender = attr_dict["gender"]
             del attr_dict["gender"]

gramps/gen/lib/styledtext.py

@@ -3,7 +3,7 @@
 #
 # Copyright (C) 2008       Zsolt Foldvari
 # Copyright (C) 2013       Doug Blank <[email protected]>
-# Copyright (C) 2017       Nick Hall
+# Copyright (C) 2017,2024  Nick Hall
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -103,12 +103,23 @@ def __init__(self, text="", tags=None):
             self._tags = []
 
     def get_object_state(self):
+        """
+        Get the current object state as a dictionary.
+
+        We override this method to handle the `tags` and `string` properties.
+        """
         attr_dict = {"_class": self.__class__.__name__}
         attr_dict["tags"] = self._tags
         attr_dict["string"] = self._string
         return attr_dict
 
     def set_object_state(self, attr_dict):
+        """
+        Set the current object state using information provided in the given
+        dictionary.
+
+        We override this method to handle the `tags` and `string` properties.
+        """
         self._tags = attr_dict["tags"]
         self._string = attr_dict["string"]
 

gramps/gen/lib/styledtexttag.py

@@ -1,9 +1,9 @@
 #
 # Gramps - a GTK+/GNOME based genealogy program
 #
-# Copyright (C) 2008  Zsolt Foldvari
-# Copyright (C) 2013  Doug Blank <[email protected]>
-# Copyright (C) 2017  Nick Hall
+# Copyright (C) 2008       Zsolt Foldvari
+# Copyright (C) 2013       Doug Blank <[email protected]>
+# Copyright (C) 2017,2024  Nick Hall
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -70,17 +70,15 @@ def __init__(self, name=None, value=None, ranges=None):
             # Current use of StyledTextTag is such that a shallow copy suffices.
             self.ranges = ranges
 
-    def get_object_state(self):
-        attr_dict = {"_class": self.__class__.__name__}
-        attr_dict["name"] = self.name
-        attr_dict["value"] = self.value
-        attr_dict["ranges"] = self.ranges
-        return attr_dict
-
     def set_object_state(self, attr_dict):
-        self.name = attr_dict["name"]
-        self.value = attr_dict["value"]
-        self.ranges = [tuple(item) for item in attr_dict["ranges"]]
+        """
+        Set the current object state using information provided in the given
+        dictionary.
+
+        We override this method to convert the elements of `ranges` into tuples.
+        """
+        attr_dict["ranges"] = [tuple(item) for item in attr_dict["ranges"]]
+        super().set_object_state(attr_dict)
 
     def serialize(self):
         """Convert the object to a serialized tuple of data.

gramps/gen/lib/tag.py

@@ -1,8 +1,8 @@
 #
 # Gramps - a GTK+/GNOME based genealogy program
 #
-# Copyright (C) 2010,2017 Nick Hall
-# Copyright (C) 2013      Doug Blank <[email protected]>
+# Copyright (C) 2010,2017,2024  Nick Hall
+# Copyright (C) 2013            Doug Blank <[email protected]>
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -109,13 +109,26 @@ def unserialize(self, data):
         return self
 
     def get_object_state(self):
+        """
+        Get the current object state as a dictionary.
+
+        We override this method to handle the `name`, `color` and `priority`
+        properties.
+        """
         attr_dict = super().get_object_state()
         attr_dict["name"] = self.__name
         attr_dict["color"] = self.__color
         attr_dict["priority"] = self.__priority
         return attr_dict
 
     def set_object_state(self, attr_dict):
+        """
+        Set the current object state using information provided in the given
+        dictionary.
+
+        We override this method to handle the `name`, `color` and `priority`
+        properties.
+        """
         if "name" in attr_dict:
             self.__name = attr_dict["name"]
             del attr_dict["name"]