Improve documentation for the pythonizations, test collection subscript return type

doc/python.md

@@ -21,7 +21,8 @@ For reference usage, see the [Python module of EDM4hep](https://github.com/key4h
 
 Python as a language uses different constructions and conventions than C++, perfectly fine C++ code translated one to one to Python could be clunky by Python's standard. cppyy offers a mechanism called [pythonizations](https://cppyy.readthedocs.io/en/latest/pythonizations.html) to make the resulting bindings more pythonic. Some basic pythonizations are included automatically (for instance `operator[]` is translated to `__getitem__`) but others can be specified by a user.
 
-Podio comes with its own set of pythonizations useful for the data models generated with it. To apply all the provided pythonizations to a `model_namespace` namespace:
+Podio comes with its own set of pythonizations useful for the data models generated with it. These pythonizations are available in the submodules of the `podio.pythonizations`. For the full list see the [python API](https://key4hep.web.cern.ch/podio/py_api/podio.pythonizations.html#submodules) documentation.
+To apply all the provided pythonizations to a `model_namespace` namespace:
 
 ```python
 from podio.pythonizations import load_pythonizations

python/podio/pythonizations/collection_subscript.py

@@ -5,18 +5,43 @@
 
 
 class CollectionSubscriptPythonizer(Pythonizer):
-    """Bound-check __getitem__ for classes derived from podio::CollectionBase"""
+    """Bound-check `__getitem__` for classes derived from `podio.CollectionBase`"""
 
     @classmethod
     def priority(cls):
+        """
+        No special requirements for order of applying
+
+        Returns:
+            int: Priority.
+        """
         return 50
 
     @classmethod
     def filter(cls, class_, name):
+        """
+        Filters-out classes non derived from `podio.CollectionBase`.
+
+        Args:
+            class_ (type): Class object.
+            name (str): Name of the class.
+
+        Returns:
+            bool: True if class is derived from `podio.CollectionBase` and should be pythonized.
+        """
         return issubclass(class_, cppyy.gbl.podio.CollectionBase)
 
     @classmethod
     def modify(cls, class_, name):
+        """
+        Raise an `IndexError` exception if an index is invalid.
+        The `__getitem__` will return immutable datatype objects instead of the mutable ones.
+
+        Args:
+            class_ (type): Class object.
+            name (str): Name of the class.
+        """
+
         def get_item(self, i):
             try:
                 return self.at(i)

python/podio/pythonizations/freeze_class.py

@@ -11,16 +11,38 @@ class FreezeClassPythonizer(Pythonizer):
 
     @classmethod
     def priority(cls):
-        """This most likely should be the last pythonization loaded
-        otherwise it may interfere with creating attributes during other pythonizations"""
+        """
+        This most likely should be the last pythonization loaded.
+        Otherwise it may interfere with creating attributes during other pythonizations.
+
+        Returns:
+            int: Priority.
+        """
         return 99
 
     @classmethod
     def filter(cls, class_, name):
+        """
+        Filter passing all the classes
+
+        Args:
+            class_ (type): Class object.
+            name (str): Name of the class.
+
+        Returns:
+            bool: True.
+        """
         return True
 
     @classmethod
     def modify(cls, class_, name):
+        """Raise an `AttributeError` if new attribute would be set
+
+        Args:
+            class_ (type): Class object.
+            name (str): Name of the class.
+        """
+
         def freeze_setattr(self, attr, val):
             object_type = type(self)
             if attr not in object_type.__dict__:

python/podio/test_CodeGen.py

@@ -43,13 +43,21 @@ class CollectionSubscriptTest(unittest.TestCase):
     """Collection subscript test"""
 
     def test_bound_check(self):
+        """Test that bound checking for collection subscript is enabled"""
         collection = nsp.EnergyInNamespaceCollection()
         _ = collection.create()
         self.assertEqual(len(collection), 1)
         with self.assertRaises(IndexError):
             _ = collection[20]
         _ = collection[0]
 
+    def test_getitem_return_type(self):
+        """Test that collection subscript returns an instance of podio immutable datatype"""
+        collection = nsp.EnergyInNamespaceCollection()
+        obj = collection.create()
+        self.assertIsInstance(obj, nsp.MutableEnergyInNamespace)
+        self.assertIsInstance(collection[0], nsp.EnergyInNamespace)
+
 
 class AttributeCreationTest(unittest.TestCase):
     """Setting new attributes test"""