saip: improve docstrings

Change-Id: I0ca82a434e0bde3dc1b304dfc179d568588631c6

pySim/esim/saip/__init__.py

@@ -30,7 +30,13 @@ from pySim.esim.saip import templates
 asn1 = compile_asn1_subdir('saip')
 
 class File:
-    """Internal representation of a file in a profile filesystem."""
+    """Internal representation of a file in a profile filesystem.
+
+    Parameters:
+        pename: Name string of the profile element
+        l: List of tuples [fileDescriptor, fillFileContent, fillFileOffset profile elements]
+        template: Applicable FileTemplate describing defaults as per SAIP spec
+    """
     def __init__(self, pename: str, l: Optional[List[Tuple]] = None, template: Optional[templates.FileTemplate] = None):
         self.pe_name = pename
         self.template = template
@@ -103,7 +109,7 @@ class File:
 
     @staticmethod
     def linearize_file_content(l: List[Tuple]) -> Optional[io.BytesIO]:
-        """linearize a list of fillFileContent + fillFileOffset tuples."""
+        """linearize a list of fillFileContent / fillFileOffset tuples into a stream of bytes."""
         stream = io.BytesIO()
         for k, v in l:
             if k == 'doNotCreate':
@@ -125,6 +131,7 @@ class File:
         return "File(%s): %s" % (self.pe_name, self.fileDescriptor)
 
 class ProfileElement:
+    """Class representing a Profile Element (PE) within a SAIP Profile."""
     FILE_BEARING = ['mf', 'cd', 'telecom', 'usim', 'opt-usim', 'isim', 'opt-isim', 'phonebook', 'gsm-access',
                     'csim', 'opt-csim', 'eap', 'df-5gs', 'df-saip', 'df-snpn', 'df-5gprose', 'iot', 'opt-iot']
     def _fixup_sqnInit_dec(self) -> None:
@@ -162,6 +169,7 @@ class ProfileElement:
 
     @property
     def header_name(self) -> str:
+        """Return the name of the header field within the profile element."""
         # unneccessarry compliaction by inconsistent naming :(
         if self.type.startswith('opt-'):
             return self.type.replace('-','') + '-header'
@@ -169,10 +177,12 @@ class ProfileElement:
 
     @property
     def header(self):
+        """Return the decoded ProfileHeader."""
         return self.decoded.get(self.header_name, None)
 
     @property
     def templateID(self):
+        """Return the decoded templateID used by this profile element (if any)."""
         return self.decoded.get('templateID', None)
 
     @property
@@ -216,9 +226,12 @@ class ProfileElementSequence:
         self.pes_by_naa: Dict = {}
 
     def get_pes_for_type(self, tname: str) -> List[ProfileElement]:
+        """Return list of profile elements present for given profile element type."""
         return self.pe_by_type.get(tname, [])
 
     def get_pe_for_type(self, tname: str) -> Optional[ProfileElement]:
+        """Return a single profile element for given profile element type. Works only for
+        types of which there is only a signle instance in the PE Sequence!"""
         l = self.get_pes_for_type(tname)
         if len(l) == 0:
             return None

pySim/esim/saip/personalization.py

@@ -32,7 +32,8 @@ def file_replace_content(file: List[Tuple], new_content: bytes):
     return file
 
 class ClassVarMeta(abc.ABCMeta):
-    """Metaclass that puts all additional keyword-args into the class."""
+    """Metaclass that puts all additional keyword-args into the class. We use this to have one
+    class definition for something like a PIN, and then have derived classes for PIN1, PIN2, ..."""
     def __new__(metacls, name, bases, namespace, **kwargs):
         #print("Meta_new_(metacls=%s, name=%s, bases=%s, namespace=%s, kwargs=%s)" % (metacls, name, bases, namespace, kwargs))
         x = super().__new__(metacls, name, bases, namespace)
@@ -78,6 +79,7 @@ def obtain_first_pe_from_pelist(l: List[ProfileElement], wanted_type: str) -> Pr
     return filtered[0]
 
 class Puk(ConfigurableParameter, metaclass=ClassVarMeta):
+    """Configurable PUK (Pin Unblock Code). String ASCII-encoded digits."""
     keyReference = None
     def apply(self, pes: ProfileElementSequence):
         mf_pes = pes.pes_by_naa['mf'][0]
@@ -93,6 +95,7 @@ class Puk2(Puk, keyReference=0x81):
     pass
 
 class Pin(ConfigurableParameter, metaclass=ClassVarMeta):
+    """Configurable PIN (Personal Identification Number).  String of digits."""
     keyReference = None
     def apply(self, pes: ProfileElementSequence):
         mf_pes = pes.pes_by_naa['mf'][0]
@@ -105,6 +108,7 @@ class Pin(ConfigurableParameter, metaclass=ClassVarMeta):
                  return
         raise ValueError('cannot find pinCode')
 class AppPin(ConfigurableParameter, metaclass=ClassVarMeta):
+    """Configurable PIN (Personal Identification Number).  String of digits."""
     keyReference = None
     def _apply_one(self, pe: ProfileElement):
         pinCodes = obtain_first_pe_from_pelist(pe, 'pinCodes')
@@ -134,6 +138,7 @@ class Adm2(Pin, keyReference=0x0B):
 
 
 class AlgoConfig(ConfigurableParameter, metaclass=ClassVarMeta):
+    """Configurable Algorithm parameter.  bytes."""
     key = None
     def apply(self, pes: ProfileElementSequence):
         for pe in pes.get_pes_for_type('akaParameter'):