[S] Change in pysim[master]: saip: improve docstrings

laforge has uploaded this change for review. ( https://gerrit.osmocom.org/c/pysim/+/36013?usp=email ) Change subject: saip: improve docstrings ...................................................................... saip: improve docstrings Change-Id: I0ca82a434e0bde3dc1b304dfc179d568588631c6 --- M pySim/esim/saip/__init__.py M pySim/esim/saip/personalization.py 2 files changed, 30 insertions(+), 3 deletions(-) git pull ssh://gerrit.osmocom.org:29418/pysim refs/changes/13/36013/1 diff --git a/pySim/esim/saip/__init__.py b/pySim/esim/saip/__init__.py index 82ed2b7..b8e41ce 100644 --- a/pySim/esim/saip/__init__.py +++ b/pySim/esim/saip/__init__.py @@ -30,7 +30,13 @@ 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 @@ @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 @@ 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 @@ @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 @@ @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 @@ 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 diff --git a/pySim/esim/saip/personalization.py b/pySim/esim/saip/personalization.py index fd83387..5adaf2e 100644 --- a/pySim/esim/saip/personalization.py +++ b/pySim/esim/saip/personalization.py @@ -32,7 +32,8 @@ 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 @@ 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 @@ 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 @@ 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 AlgoConfig(ConfigurableParameter, metaclass=ClassVarMeta): + """Configurable Algorithm parameter. bytes.""" key = None def apply(self, pes: ProfileElementSequence): for pe in pes.get_pes_for_type('akaParameter'): -- To view, visit https://gerrit.osmocom.org/c/pysim/+/36013?usp=email To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings Gerrit-Project: pysim Gerrit-Branch: master Gerrit-Change-Id: I0ca82a434e0bde3dc1b304dfc179d568588631c6 Gerrit-Change-Number: 36013 Gerrit-PatchSet: 1 Gerrit-Owner: laforge <laforge(a)osmocom.org> Gerrit-MessageType: newchange