<p>laforge has uploaded this change for <strong>review</strong>.</p><p><a href="https://gerrit.osmocom.org/c/pysim/+/23577">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">Add more documentation to the classes/methods<br><br>* add type annotations in-line with PEP484<br>* convert existing documentation to follow the<br> "Google Python Style Guide" format understood by<br> the sphinx.ext.napoleon' extension<br>* add much more documentation all over the code base<br><br>Change-Id: I6ac88e0662cf3c56ae32d86d50b18a8b4150571a<br>---<br>M pySim/commands.py<br>M pySim/exceptions.py<br>M pySim/filesystem.py<br>M pySim/transport/__init__.py<br>M pySim/transport/calypso.py<br>M pySim/transport/modem_atcmd.py<br>M pySim/transport/pcsc.py<br>M pySim/transport/serial.py<br>M pySim/utils.py<br>9 files changed, 600 insertions(+), 155 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://gerrit.osmocom.org:29418/pysim refs/changes/77/23577/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/pySim/commands.py b/pySim/commands.py</span><br><span>index 9aed588..9f4d450 100644</span><br><span>--- a/pySim/commands.py</span><br><span>+++ b/pySim/commands.py</span><br><span>@@ -64,7 +64,7 @@</span><br><span> # from what SIMs responds. See also:</span><br><span> # USIM: ETSI TS 102 221, chapter 11.1.1.3 Response Data</span><br><span> # SIM: GSM 11.11, chapter 9.2.1 SELECT</span><br><span style="color: hsl(0, 100%, 40%);">- def __record_len(self, r):</span><br><span style="color: hsl(120, 100%, 40%);">+ def __record_len(self, r) -> int:</span><br><span> if self.sel_ctrl == "0004":</span><br><span> tlv_parsed = self.__parse_fcp(r[-1])</span><br><span> file_descriptor = tlv_parsed['82']</span><br><span>@@ -75,14 +75,15 @@</span><br><span> </span><br><span> # Tell the length of a binary file. See also comment</span><br><span> # above.</span><br><span style="color: hsl(0, 100%, 40%);">- def __len(self, r):</span><br><span style="color: hsl(120, 100%, 40%);">+ def __len(self, r) -> int:</span><br><span> if self.sel_ctrl == "0004":</span><br><span> tlv_parsed = self.__parse_fcp(r[-1])</span><br><span> return int(tlv_parsed['80'], 16)</span><br><span> else:</span><br><span> return int(r[-1][4:8], 16)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def get_atr(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ def get_atr(self) -> str:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Return the ATR of the currently inserted card."""</span><br><span> return self._tp.get_atr()</span><br><span> </span><br><span> @property</span><br><span>@@ -100,6 +101,7 @@</span><br><span> self._sel_ctrl = value</span><br><span> </span><br><span> def try_select_path(self, dir_list):</span><br><span style="color: hsl(120, 100%, 40%);">+ """ Try to select a specified path given as list of hex-string FIDs"""</span><br><span> rv = []</span><br><span> if type(dir_list) is not list:</span><br><span> dir_list = [dir_list]</span><br><span>@@ -111,6 +113,14 @@</span><br><span> return rv</span><br><span> </span><br><span> def select_path(self, dir_list):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Execute SELECT for an entire list/path of FIDs.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ dir_list: list of FIDs representing the path to select</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ list of return values (FCP in hex encoding) for each element of the path</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> rv = []</span><br><span> if type(dir_list) is not list:</span><br><span> dir_list = [dir_list]</span><br><span>@@ -119,14 +129,23 @@</span><br><span> rv.append(data)</span><br><span> return rv</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def select_file(self, fid):</span><br><span style="color: hsl(120, 100%, 40%);">+ def select_file(self, fid:str):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Execute SELECT a given file by FID."""</span><br><span> return self._tp.send_apdu_checksw(self.cla_byte + "a4" + self.sel_ctrl + "02" + fid)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def select_adf(self, aid):</span><br><span style="color: hsl(120, 100%, 40%);">+ def select_adf(self, aid:str):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Execute SELECT a given Applicaiton ADF."""</span><br><span> aidlen = ("0" + format(len(aid) // 2, 'x'))[-2:]</span><br><span> return self._tp.send_apdu_checksw(self.cla_byte + "a4" + "0404" + aidlen + aid)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def read_binary(self, ef, length=None, offset=0):</span><br><span style="color: hsl(120, 100%, 40%);">+ def read_binary(self, ef, length:int=None, offset:int=0):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Execute READD BINARY.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ ef : string or list of strings indicating name or path of transparent EF</span><br><span style="color: hsl(120, 100%, 40%);">+ length : number of bytes to read</span><br><span style="color: hsl(120, 100%, 40%);">+ offset : byte offset in file from which to start reading</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> r = self.select_path(ef)</span><br><span> if len(r[-1]) == 0:</span><br><span> return (None, None)</span><br><span>@@ -144,7 +163,15 @@</span><br><span> raise ValueError('Failed to read (offset %d)' % (offset))</span><br><span> return total_data, sw</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def update_binary(self, ef, data, offset=0, verify=False):</span><br><span style="color: hsl(120, 100%, 40%);">+ def update_binary(self, ef, data:str, offset:int=0, verify:bool=False):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Execute UPDATE BINARY.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ ef : string or list of strings indicating name or path of transparent EF</span><br><span style="color: hsl(120, 100%, 40%);">+ data : hex string of data to be written</span><br><span style="color: hsl(120, 100%, 40%);">+ offset : byte offset in file from which to start writing</span><br><span style="color: hsl(120, 100%, 40%);">+ verify : Whether or not to verify data after write</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> self.select_path(ef)</span><br><span> pdu = self.cla_byte + 'd6%04x%02x' % (offset, len(data) // 2) + data</span><br><span> res = self._tp.send_apdu_checksw(pdu)</span><br><span>@@ -152,18 +179,31 @@</span><br><span> self.verify_binary(ef, data, offset)</span><br><span> return res</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def verify_binary(self, ef, data, offset=0):</span><br><span style="color: hsl(120, 100%, 40%);">+ def verify_binary(self, ef, data:str, offset:int=0):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Verify contents of transparent EF.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ ef : string or list of strings indicating name or path of transparent EF</span><br><span style="color: hsl(120, 100%, 40%);">+ data : hex string of expected data</span><br><span style="color: hsl(120, 100%, 40%);">+ offset : byte offset in file from which to start verifying</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> res = self.read_binary(ef, len(data) // 2, offset)</span><br><span> if res[0].lower() != data.lower():</span><br><span> raise ValueError('Binary verification failed (expected %s, got %s)' % (data.lower(), res[0].lower()))</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def read_record(self, ef, rec_no):</span><br><span style="color: hsl(120, 100%, 40%);">+ def read_record(self, ef, rec_no:int):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Execute READ RECORD.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ ef : string or list of strings indicating name or path of linear fixed EF</span><br><span style="color: hsl(120, 100%, 40%);">+ rec_no : record number to read</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> r = self.select_path(ef)</span><br><span> rec_length = self.__record_len(r)</span><br><span> pdu = self.cla_byte + 'b2%02x04%02x' % (rec_no, rec_length)</span><br><span> return self._tp.send_apdu(pdu)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def update_record(self, ef, rec_no, data, force_len=False, verify=False):</span><br><span style="color: hsl(120, 100%, 40%);">+ def update_record(self, ef, rec_no:int, data:str, force_len:bool=False, verify:bool=False):</span><br><span> r = self.select_path(ef)</span><br><span> if not force_len:</span><br><span> rec_length = self.__record_len(r)</span><br><span>@@ -177,33 +217,51 @@</span><br><span> self.verify_record(ef, rec_no, data)</span><br><span> return res</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def verify_record(self, ef, rec_no, data):</span><br><span style="color: hsl(120, 100%, 40%);">+ def verify_record(self, ef, rec_no:int, data:str):</span><br><span> res = self.read_record(ef, rec_no)</span><br><span> if res[0].lower() != data.lower():</span><br><span> raise ValueError('Record verification failed (expected %s, got %s)' % (data.lower(), res[0].lower()))</span><br><span> </span><br><span> def record_size(self, ef):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Determine the record size of given file.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ ef : string or list of strings indicating name or path of linear fixed EF</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> r = self.select_path(ef)</span><br><span> return self.__record_len(r)</span><br><span> </span><br><span> def record_count(self, ef):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Determine the number of records in given file.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ ef : string or list of strings indicating name or path of linear fixed EF</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> r = self.select_path(ef)</span><br><span> return self.__len(r) // self.__record_len(r)</span><br><span> </span><br><span> def binary_size(self, ef):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Determine the size of given transparent file.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ ef : string or list of strings indicating name or path of transparent EF</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> r = self.select_path(ef)</span><br><span> return self.__len(r)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def run_gsm(self, rand):</span><br><span style="color: hsl(120, 100%, 40%);">+ def run_gsm(self, rand:str):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Execute RUN GSM ALGORITHM."""</span><br><span> if len(rand) != 32:</span><br><span> raise ValueError('Invalid rand')</span><br><span> self.select_path(['3f00', '7f20'])</span><br><span> return self._tp.send_apdu(self.cla_byte + '88000010' + rand)</span><br><span> </span><br><span> def reset_card(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Physically reset the card"""</span><br><span> return self._tp.reset_card()</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def verify_chv(self, chv_no, code):</span><br><span style="color: hsl(120, 100%, 40%);">+ def verify_chv(self, chv_no:int, code:str):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Verify a given CHV (Card Holder Verification == PIN)"""</span><br><span> fc = rpad(b2h(code), 16)</span><br><span> data, sw = self._tp.send_apdu(self.cla_byte + '2000' + ('%02X' % chv_no) + '08' + fc)</span><br><span> if (sw != '9000'):</span><br><span>diff --git a/pySim/exceptions.py b/pySim/exceptions.py</span><br><span>index 4fb8f72..f1d1a18 100644</span><br><span>--- a/pySim/exceptions.py</span><br><span>+++ b/pySim/exceptions.py</span><br><span>@@ -22,18 +22,27 @@</span><br><span> #</span><br><span> </span><br><span> class NoCardError(Exception):</span><br><span style="color: hsl(120, 100%, 40%);">+ """No card was found in the reader."""</span><br><span> pass</span><br><span> </span><br><span> class ProtocolError(Exception):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Some kind of protocol level error interfacing with the card."""</span><br><span> pass</span><br><span> </span><br><span> class ReaderError(Exception):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Some kind of general error with the card reader."""</span><br><span> pass</span><br><span> </span><br><span> class SwMatchError(Exception):</span><br><span> """Raised when an operation specifies an expected SW but the actual SW from</span><br><span> the card doesn't match."""</span><br><span style="color: hsl(0, 100%, 40%);">- def __init__(self, sw_actual, sw_expected, rs=None):</span><br><span style="color: hsl(120, 100%, 40%);">+ def __init__(self, sw_actual:str, sw_expected:str, rs=None):</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ sw_actual : the SW we actually received from the card (4 hex digits)</span><br><span style="color: hsl(120, 100%, 40%);">+ sw_expected : the SW we expected to receive from the card (4 hex digits)</span><br><span style="color: hsl(120, 100%, 40%);">+ rs : interpreter class to convert SW to string</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> self.sw_actual = sw_actual</span><br><span> self.sw_expected = sw_expected</span><br><span> self.rs = rs</span><br><span>diff --git a/pySim/filesystem.py b/pySim/filesystem.py</span><br><span>index cb39b94..ead21f9 100644</span><br><span>--- a/pySim/filesystem.py</span><br><span>+++ b/pySim/filesystem.py</span><br><span>@@ -41,7 +41,16 @@</span><br><span> RESERVED_NAMES = ['..', '.', '/', 'MF']</span><br><span> RESERVED_FIDS = ['3f00']</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def __init__(self, fid=None, sfid=None, name=None, desc=None, parent=None):</span><br><span style="color: hsl(120, 100%, 40%);">+ def __init__(self, fid:str=None, sfid:str=None, name:str=None, desc:str=None,</span><br><span style="color: hsl(120, 100%, 40%);">+ parent=None):</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ fid : File Identifier (4 hex digits)</span><br><span style="color: hsl(120, 100%, 40%);">+ sfid : Short File Identifier (2 hex digits, optional)</span><br><span style="color: hsl(120, 100%, 40%);">+ name : Brief name of the file, lik EF_ICCID</span><br><span style="color: hsl(120, 100%, 40%);">+ desc : Descriptoin of the file</span><br><span style="color: hsl(120, 100%, 40%);">+ parent : Parent CardFile object within filesystem hierarchy</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> if not isinstance(self, CardADF) and fid == None:</span><br><span> raise ValueError("fid is mandatory")</span><br><span> if fid:</span><br><span>@@ -72,7 +81,11 @@</span><br><span> return self.fid</span><br><span> </span><br><span> def fully_qualified_path(self, prefer_name=True):</span><br><span style="color: hsl(0, 100%, 40%);">- """Return fully qualified path to file as list of FID or name strings."""</span><br><span style="color: hsl(120, 100%, 40%);">+ """Return fully qualified path to file as list of FID or name strings.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ prefer_name : Preferably build path of names; fall-back to FIDs as required</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> if self.parent != self:</span><br><span> ret = self.parent.fully_qualified_path(prefer_name)</span><br><span> else:</span><br><span>@@ -90,8 +103,16 @@</span><br><span> node = node.parent</span><br><span> return node</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def _get_self_selectables(self, alias=None, flags = []):</span><br><span style="color: hsl(0, 100%, 40%);">- """Return a dict of {'identifier': self} tuples"""</span><br><span style="color: hsl(120, 100%, 40%);">+ def _get_self_selectables(self, alias:str=None, flags = []):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Return a dict of {'identifier': self} tuples.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ alias : Add an alias with given name to 'self' </span><br><span style="color: hsl(120, 100%, 40%);">+ flags : Specify which selectables to return 'FIDS' and/or 'NAMES';</span><br><span style="color: hsl(120, 100%, 40%);">+ If not specified, all selectables will be returned.</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ dict containing reference to 'self' for all identifiers.</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> sels = {}</span><br><span> if alias:</span><br><span> sels.update({alias: self})</span><br><span>@@ -102,7 +123,15 @@</span><br><span> return sels</span><br><span> </span><br><span> def get_selectables(self, flags = []):</span><br><span style="color: hsl(0, 100%, 40%);">- """Return a dict of {'identifier': File} that is selectable from the current file."""</span><br><span style="color: hsl(120, 100%, 40%);">+ """Return a dict of {'identifier': File} that is selectable from the current file.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ flags : Specify which selectables to return 'FIDS' and/or 'NAMES';</span><br><span style="color: hsl(120, 100%, 40%);">+ If not specified, all selectables will be returned.</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ dict containing all selectable items. Key is identifier (string), value</span><br><span style="color: hsl(120, 100%, 40%);">+ a reference to a CardFile (or derived class) instance.</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> sels = {}</span><br><span> # we can always select ourself</span><br><span> if flags == [] or 'SELF' in flags:</span><br><span>@@ -119,7 +148,15 @@</span><br><span> return sels</span><br><span> </span><br><span> def get_selectable_names(self, flags = []):</span><br><span style="color: hsl(0, 100%, 40%);">- """Return a list of strings for all identifiers that are selectable from the current file."""</span><br><span style="color: hsl(120, 100%, 40%);">+ """Return a dict of {'identifier': File} that is selectable from the current file.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ flags : Specify which selectables to return 'FIDS' and/or 'NAMES';</span><br><span style="color: hsl(120, 100%, 40%);">+ If not specified, all selectables will be returned.</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ dict containing all selectable items. Key is identifier (string), value</span><br><span style="color: hsl(120, 100%, 40%);">+ a reference to a CardFile (or derived class) instance.</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> sels = self.get_selectables(flags)</span><br><span> return sels.keys()</span><br><span> </span><br><span>@@ -140,8 +177,12 @@</span><br><span> def __str__(self):</span><br><span> return "DF(%s)" % (super().__str__())</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def add_file(self, child, ignore_existing=False):</span><br><span style="color: hsl(0, 100%, 40%);">- """Add a child (DF/EF) to this DF"""</span><br><span style="color: hsl(120, 100%, 40%);">+ def add_file(self, child:CardFile, ignore_existing:bool=False):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Add a child (DF/EF) to this DF.</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ child: The new DF/EF to be added</span><br><span style="color: hsl(120, 100%, 40%);">+ ignore_existing: Ignore, if file with given FID already exists. Old one will be kept.</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> if not isinstance(child, CardFile):</span><br><span> raise TypeError("Expected a File instance")</span><br><span> if not is_hex(child.fid, minlen = 4, maxlen = 4):</span><br><span>@@ -164,12 +205,25 @@</span><br><span> child.parent = self</span><br><span> </span><br><span> def add_files(self, children, ignore_existing=False):</span><br><span style="color: hsl(0, 100%, 40%);">- """Add a list of child (DF/EF) to this DF"""</span><br><span style="color: hsl(120, 100%, 40%);">+ """Add a list of child (DF/EF) to this DF</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ children: List of new DF/EFs to be added</span><br><span style="color: hsl(120, 100%, 40%);">+ ignore_existing: Ignore, if file[s] with given FID already exists. Old one[s] will be kept.</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> for child in children:</span><br><span> self.add_file(child, ignore_existing)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def get_selectables(self, flags = []):</span><br><span style="color: hsl(0, 100%, 40%);">- """Get selectable (DF/EF names) from current DF"""</span><br><span style="color: hsl(120, 100%, 40%);">+ def get_selectables(self, flags = []) -> dict:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Return a dict of {'identifier': File} that is selectable from the current DF.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ flags : Specify which selectables to return 'FIDS' and/or 'NAMES';</span><br><span style="color: hsl(120, 100%, 40%);">+ If not specified, all selectables will be returned.</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ dict containing all selectable items. Key is identifier (string), value</span><br><span style="color: hsl(120, 100%, 40%);">+ a reference to a CardFile (or derived class) instance.</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> # global selectables + our children</span><br><span> sels = super().get_selectables(flags)</span><br><span> if flags == [] or 'FIDS' in flags:</span><br><span>@@ -178,7 +232,8 @@</span><br><span> sels.update({x.name: x for x in self.children.values() if x.name})</span><br><span> return sels</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def lookup_file_by_name(self, name):</span><br><span style="color: hsl(120, 100%, 40%);">+ def lookup_file_by_name(self, name:str) -> CardFile:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Find a file with given name within current DF."""</span><br><span> if name == None:</span><br><span> return None</span><br><span> for i in self.children.values():</span><br><span>@@ -186,7 +241,8 @@</span><br><span> return i</span><br><span> return None</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def lookup_file_by_sfid(self, sfid):</span><br><span style="color: hsl(120, 100%, 40%);">+ def lookup_file_by_sfid(self, sfid:str) -> CardFile:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Find a file with given short file ID within current DF."""</span><br><span> if sfid == None:</span><br><span> return None</span><br><span> for i in self.children.values():</span><br><span>@@ -194,7 +250,8 @@</span><br><span> return i</span><br><span> return None</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def lookup_file_by_fid(self, fid):</span><br><span style="color: hsl(120, 100%, 40%);">+ def lookup_file_by_fid(self, fid:str) -> CardFile:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Find a file with given file ID within current DF."""</span><br><span> if fid in self.children:</span><br><span> return self.children[fid]</span><br><span> return None</span><br><span>@@ -228,13 +285,21 @@</span><br><span> """Get list of completions (AID names)"""</span><br><span> return [x.name for x in self.applications]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def get_selectables(self, flags = []):</span><br><span style="color: hsl(0, 100%, 40%);">- """Get list of completions (DF/EF/ADF names) from current DF"""</span><br><span style="color: hsl(120, 100%, 40%);">+ def get_selectables(self, flags = []) -> dict:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Return a dict of {'identifier': File} that is selectable from the current DF.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ flags : Specify which selectables to return 'FIDS' and/or 'NAMES';</span><br><span style="color: hsl(120, 100%, 40%);">+ If not specified, all selectables will be returned.</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ dict containing all selectable items. Key is identifier (string), value</span><br><span style="color: hsl(120, 100%, 40%);">+ a reference to a CardFile (or derived class) instance.</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> sels = super().get_selectables(flags)</span><br><span> sels.update(self.get_app_selectables(flags))</span><br><span> return sels</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def get_app_selectables(self, flags = []):</span><br><span style="color: hsl(120, 100%, 40%);">+ def get_app_selectables(self, flags = []) -> dict:</span><br><span> """Get applications by AID + name"""</span><br><span> sels = {}</span><br><span> if flags == [] or 'AIDS' in flags:</span><br><span>@@ -243,15 +308,19 @@</span><br><span> sels.update({x.name: x for x in self.applications.values() if x.name})</span><br><span> return sels</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def decode_select_response(self, data_hex):</span><br><span style="color: hsl(0, 100%, 40%);">- """Decode the response to a SELECT command."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def decode_select_response(self, data_hex:str) -> str:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Decode the response to a SELECT command.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ This is the fall-back method which doesn't perform any decoding. It mostly</span><br><span style="color: hsl(120, 100%, 40%);">+ exists so specific derived classes can overload it for actual decoding.</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> return data_hex</span><br><span> </span><br><span> </span><br><span> </span><br><span> class CardADF(CardDF):</span><br><span> """ADF (Application Dedicated File) in the smart card filesystem"""</span><br><span style="color: hsl(0, 100%, 40%);">- def __init__(self, aid, **kwargs):</span><br><span style="color: hsl(120, 100%, 40%);">+ def __init__(self, aid:str, **kwargs):</span><br><span> super().__init__(**kwargs)</span><br><span> self.aid = aid # Application Identifier</span><br><span> if self.parent:</span><br><span>@@ -276,8 +345,16 @@</span><br><span> def __str__(self):</span><br><span> return "EF(%s)" % (super().__str__())</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def get_selectables(self, flags = []):</span><br><span style="color: hsl(0, 100%, 40%);">- """Get list of completions (EF names) from current DF"""</span><br><span style="color: hsl(120, 100%, 40%);">+ def get_selectables(self, flags = []) -> dict:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Return a dict of {'identifier': File} that is selectable from the current DF.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ flags : Specify which selectables to return 'FIDS' and/or 'NAMES';</span><br><span style="color: hsl(120, 100%, 40%);">+ If not specified, all selectables will be returned.</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ dict containing all selectable items. Key is identifier (string), value</span><br><span style="color: hsl(120, 100%, 40%);">+ a reference to a CardFile (or derived class) instance.</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> #global selectable names + those of the parent DF</span><br><span> sels = super().get_selectables(flags)</span><br><span> sels.update({x.name:x for x in self.parent.children.values() if x != self})</span><br><span>@@ -285,10 +362,14 @@</span><br><span> </span><br><span> </span><br><span> class TransparentEF(CardEF):</span><br><span style="color: hsl(0, 100%, 40%);">- """Transparent EF (Entry File) in the smart card filesystem"""</span><br><span style="color: hsl(120, 100%, 40%);">+ """Transparent EF (Entry File) in the smart card filesystem.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ A Transparent EF is a binary file with no formal structure. This is contrary to</span><br><span style="color: hsl(120, 100%, 40%);">+ Record based EFs which have [fixed size] records that can be individually read/updated."""</span><br><span> </span><br><span> @with_default_category('Transparent EF Commands')</span><br><span> class ShellCommands(CommandSet):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Shell commands specific for Trransparent EFs."""</span><br><span> def __init__(self):</span><br><span> super().__init__()</span><br><span> </span><br><span>@@ -326,13 +407,33 @@</span><br><span> if data:</span><br><span> self._cmd.poutput(json.dumps(data, indent=4))</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def __init__(self, fid, sfid=None, name=None, desc=None, parent=None, size={1,None}):</span><br><span style="color: hsl(120, 100%, 40%);">+ def __init__(self, fid:str, sfid:str=None, name:str=None, desc:str=None, parent:CardDF=None,</span><br><span style="color: hsl(120, 100%, 40%);">+ size={1,None}):</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ fid : File Identifier (4 hex digits)</span><br><span style="color: hsl(120, 100%, 40%);">+ sfid : Short File Identifier (2 hex digits, optional)</span><br><span style="color: hsl(120, 100%, 40%);">+ name : Brief name of the file, lik EF_ICCID</span><br><span style="color: hsl(120, 100%, 40%);">+ desc : Descriptoin of the file</span><br><span style="color: hsl(120, 100%, 40%);">+ parent : Parent CardFile object within filesystem hierarchy</span><br><span style="color: hsl(120, 100%, 40%);">+ size : tuple of (minimum_size, recommended_size)</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> super().__init__(fid=fid, sfid=sfid, name=name, desc=desc, parent=parent)</span><br><span> self.size = size</span><br><span> self.shell_commands = [self.ShellCommands()]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def decode_bin(self, raw_bin_data):</span><br><span style="color: hsl(0, 100%, 40%);">- """Decode raw (binary) data into abstract representation. Overloaded by specific classes."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def decode_bin(self, raw_bin_data:bytearray):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Decode raw (binary) data into abstract representation.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ A derived class would typically provide a _decode_bin() or _decode_hex() method</span><br><span style="color: hsl(120, 100%, 40%);">+ for implementing this specifically for the given file. This function checks which</span><br><span style="color: hsl(120, 100%, 40%);">+ of the method exists, add calls them (with conversion, as needed).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ raw_bin_data : binary encoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ abstract_data; dict representing the decoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> method = getattr(self, '_decode_bin', None)</span><br><span> if callable(method):</span><br><span> return method(raw_bin_data)</span><br><span>@@ -341,8 +442,18 @@</span><br><span> return method(b2h(raw_bin_data))</span><br><span> return {'raw': raw_bin_data.hex()}</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def decode_hex(self, raw_hex_data):</span><br><span style="color: hsl(0, 100%, 40%);">- """Decode raw (hex string) data into abstract representation. Overloaded by specific classes."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def decode_hex(self, raw_hex_data:str):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Decode raw (hex string) data into abstract representation.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ A derived class would typically provide a _decode_bin() or _decode_hex() method</span><br><span style="color: hsl(120, 100%, 40%);">+ for implementing this specifically for the given file. This function checks which</span><br><span style="color: hsl(120, 100%, 40%);">+ of the method exists, add calls them (with conversion, as needed).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ raw_hex_data : hex-encoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ abstract_data; dict representing the decoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> method = getattr(self, '_decode_hex', None)</span><br><span> if callable(method):</span><br><span> return method(raw_hex_data)</span><br><span>@@ -352,8 +463,18 @@</span><br><span> return method(raw_bin_data)</span><br><span> return {'raw': raw_bin_data.hex()}</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def encode_bin(self, abstract_data):</span><br><span style="color: hsl(0, 100%, 40%);">- """Encode abstract representation into raw (binary) data. Overloaded by specific classes."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def encode_bin(self, abstract_data) -> bytearray:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Encode abstract representation into raw (binary) data.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ A derived class would typically provide an _encode_bin() or _encode_hex() method</span><br><span style="color: hsl(120, 100%, 40%);">+ for implementing this specifically for the given file. This function checks which</span><br><span style="color: hsl(120, 100%, 40%);">+ of the method exists, add calls them (with conversion, as needed).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ abstract_data : dict representing the decoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ binary encoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> method = getattr(self, '_encode_bin', None)</span><br><span> if callable(method):</span><br><span> return method(abstract_data)</span><br><span>@@ -362,8 +483,18 @@</span><br><span> return h2b(method(abstract_data))</span><br><span> raise NotImplementedError</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def encode_hex(self, abstract_data):</span><br><span style="color: hsl(0, 100%, 40%);">- """Encode abstract representation into raw (hex string) data. Overloaded by specific classes."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def encode_hex(self, abstract_data) -> str:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Encode abstract representation into raw (hex string) data.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ A derived class would typically provide an _encode_bin() or _encode_hex() method</span><br><span style="color: hsl(120, 100%, 40%);">+ for implementing this specifically for the given file. This function checks which</span><br><span style="color: hsl(120, 100%, 40%);">+ of the method exists, add calls them (with conversion, as needed).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ abstract_data : dict representing the decoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ hex string encoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> method = getattr(self, '_encode_hex', None)</span><br><span> if callable(method):</span><br><span> return method(abstract_data)</span><br><span>@@ -375,10 +506,14 @@</span><br><span> </span><br><span> </span><br><span> class LinFixedEF(CardEF):</span><br><span style="color: hsl(0, 100%, 40%);">- """Linear Fixed EF (Entry File) in the smart card filesystem"""</span><br><span style="color: hsl(120, 100%, 40%);">+ """Linear Fixed EF (Entry File) in the smart card filesystem.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Linear Fixed EFs are record oriented files. They consist of a number of fixed-size</span><br><span style="color: hsl(120, 100%, 40%);">+ records. The records can be individually read/updated."""</span><br><span> </span><br><span> @with_default_category('Linear Fixed EF Commands')</span><br><span> class ShellCommands(CommandSet):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Shell commands specific for Linear Fixed EFs."""</span><br><span> def __init__(self):</span><br><span> super().__init__()</span><br><span> </span><br><span>@@ -425,13 +560,33 @@</span><br><span> if data:</span><br><span> self._cmd.poutput(data)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def __init__(self, fid, sfid=None, name=None, desc=None, parent=None, rec_len={1,None}):</span><br><span style="color: hsl(120, 100%, 40%);">+ def __init__(self, fid:str, sfid:str=None, name:str=None, desc:str=None, parent:CardDF=None,</span><br><span style="color: hsl(120, 100%, 40%);">+ rec_len={1,None}):</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ fid : File Identifier (4 hex digits)</span><br><span style="color: hsl(120, 100%, 40%);">+ sfid : Short File Identifier (2 hex digits, optional)</span><br><span style="color: hsl(120, 100%, 40%);">+ name : Brief name of the file, lik EF_ICCID</span><br><span style="color: hsl(120, 100%, 40%);">+ desc : Descriptoin of the file</span><br><span style="color: hsl(120, 100%, 40%);">+ parent : Parent CardFile object within filesystem hierarchy</span><br><span style="color: hsl(120, 100%, 40%);">+ rec_len : tuple of (minimum_length, recommended_length)</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> super().__init__(fid=fid, sfid=sfid, name=name, desc=desc, parent=parent)</span><br><span> self.rec_len = rec_len</span><br><span> self.shell_commands = [self.ShellCommands()]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def decode_record_hex(self, raw_hex_data):</span><br><span style="color: hsl(0, 100%, 40%);">- """Decode raw (hex string) data into abstract representation. Overloaded by specific classes."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def decode_record_hex(self, raw_hex_data:str):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Decode raw (hex string) data into abstract representation.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ A derived class would typically provide a _decode_record_bin() or _decode_record_hex()</span><br><span style="color: hsl(120, 100%, 40%);">+ method for implementing this specifically for the given file. This function checks which</span><br><span style="color: hsl(120, 100%, 40%);">+ of the method exists, add calls them (with conversion, as needed).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ raw_hex_data : hex-encoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ abstract_data; dict representing the decoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> method = getattr(self, '_decode_record_hex', None)</span><br><span> if callable(method):</span><br><span> return method(raw_hex_data)</span><br><span>@@ -441,8 +596,18 @@</span><br><span> return method(raw_bin_data)</span><br><span> return {'raw': raw_bin_data.hex()}</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def decode_record_bin(self, raw_bin_data):</span><br><span style="color: hsl(0, 100%, 40%);">- """Decode raw (binary) data into abstract representation. Overloaded by specific classes."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def decode_record_bin(self, raw_bin_data:bytearray):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Decode raw (binary) data into abstract representation.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ A derived class would typically provide a _decode_record_bin() or _decode_record_hex()</span><br><span style="color: hsl(120, 100%, 40%);">+ method for implementing this specifically for the given file. This function checks which</span><br><span style="color: hsl(120, 100%, 40%);">+ of the method exists, add calls them (with conversion, as needed).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ raw_bin_data : binary encoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ abstract_data; dict representing the decoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> method = getattr(self, '_decode_record_bin', None)</span><br><span> if callable(method):</span><br><span> return method(raw_bin_data)</span><br><span>@@ -452,8 +617,18 @@</span><br><span> return method(raw_hex_data)</span><br><span> return {'raw': raw_hex_data}</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def encode_record_hex(self, abstract_data):</span><br><span style="color: hsl(0, 100%, 40%);">- """Encode abstract representation into raw (hex string) data. Overloaded by specific classes."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def encode_record_hex(self, abstract_data) -> str:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Encode abstract representation into raw (hex string) data.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ A derived class would typically provide an _encode_record_bin() or _encode_record_hex()</span><br><span style="color: hsl(120, 100%, 40%);">+ method for implementing this specifically for the given file. This function checks which</span><br><span style="color: hsl(120, 100%, 40%);">+ of the method exists, add calls them (with conversion, as needed).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ abstract_data : dict representing the decoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ hex string encoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> method = getattr(self, '_encode_record_hex', None)</span><br><span> if callable(method):</span><br><span> return method(abstract_data)</span><br><span>@@ -463,8 +638,18 @@</span><br><span> return b2h(raww_bin_data)</span><br><span> raise NotImplementedError</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def encode_record_bin(self, abstract_data):</span><br><span style="color: hsl(0, 100%, 40%);">- """Encode abstract representation into raw (binary) data. Overloaded by specific classes."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def encode_record_bin(self, abstract_data) -> bytearray:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Encode abstract representation into raw (binary) data.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ A derived class would typically provide an _encode_record_bin() or _encode_record_hex()</span><br><span style="color: hsl(120, 100%, 40%);">+ method for implementing this specifically for the given file. This function checks which</span><br><span style="color: hsl(120, 100%, 40%);">+ of the method exists, add calls them (with conversion, as needed).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ abstract_data : dict representing the decoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ binary encoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> method = getattr(self, '_encode_record_bin', None)</span><br><span> if callable(method):</span><br><span> return method(abstract_data)</span><br><span>@@ -476,23 +661,46 @@</span><br><span> class CyclicEF(LinFixedEF):</span><br><span> """Cyclic EF (Entry File) in the smart card filesystem"""</span><br><span> # we don't really have any special support for those; just recycling LinFixedEF here</span><br><span style="color: hsl(0, 100%, 40%);">- def __init__(self, fid, sfid=None, name=None, desc=None, parent=None, rec_len={1,None}):</span><br><span style="color: hsl(120, 100%, 40%);">+ def __init__(self, fid:str, sfid:str=None, name:str=None, desc:str=None, parent:CardDF=None,</span><br><span style="color: hsl(120, 100%, 40%);">+ rec_len={1,None}):</span><br><span> super().__init__(fid=fid, sfid=sfid, name=name, desc=desc, parent=parent, rec_len=rec_len)</span><br><span> </span><br><span> class TransRecEF(TransparentEF):</span><br><span> """Transparent EF (Entry File) containing fixed-size records.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> These are the real odd-balls and mostly look like mistakes in the specification:</span><br><span> Specified as 'transparent' EF, but actually containing several fixed-length records</span><br><span> inside.</span><br><span> We add a special class for those, so the user only has to provide encoder/decoder functions</span><br><span> for a record, while this class takes care of split / merge of records.</span><br><span> """</span><br><span style="color: hsl(0, 100%, 40%);">- def __init__(self, fid, sfid=None, name=None, desc=None, parent=None, rec_len=None, size={1,None}):</span><br><span style="color: hsl(120, 100%, 40%);">+ def __init__(self, fid:str, sfid:str=None, name:str=None, desc:str=None, parent:CardDF=None,</span><br><span style="color: hsl(120, 100%, 40%);">+ rec_len=None, size={1,None}):</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ fid : File Identifier (4 hex digits)</span><br><span style="color: hsl(120, 100%, 40%);">+ sfid : Short File Identifier (2 hex digits, optional)</span><br><span style="color: hsl(120, 100%, 40%);">+ name : Brief name of the file, lik EF_ICCID</span><br><span style="color: hsl(120, 100%, 40%);">+ desc : Descriptoin of the file</span><br><span style="color: hsl(120, 100%, 40%);">+ parent : Parent CardFile object within filesystem hierarchy</span><br><span style="color: hsl(120, 100%, 40%);">+ rec_len : Length of the fixed-length records within transparent EF</span><br><span style="color: hsl(120, 100%, 40%);">+ size : tuple of (minimum_size, recommended_size)</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> super().__init__(fid=fid, sfid=sfid, name=name, desc=desc, parent=parent, size=size)</span><br><span> self.rec_len = rec_len</span><br><span> </span><br><span> def decode_record_hex(self, raw_hex_data):</span><br><span style="color: hsl(0, 100%, 40%);">- """Decode raw (hex string) data into abstract representation. Overloaded by specific classes."""</span><br><span style="color: hsl(120, 100%, 40%);">+ """Decode raw (hex string) data into abstract representation.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ A derived class would typically provide a _decode_record_bin() or _decode_record_hex()</span><br><span style="color: hsl(120, 100%, 40%);">+ method for implementing this specifically for the given file. This function checks which</span><br><span style="color: hsl(120, 100%, 40%);">+ of the method exists, add calls them (with conversion, as needed).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ raw_hex_data : hex-encoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ abstract_data; dict representing the decoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> method = getattr(self, '_decode_record_hex', None)</span><br><span> if callable(method):</span><br><span> return method(raw_hex_data)</span><br><span>@@ -502,8 +710,18 @@</span><br><span> return method(raw_bin_data)</span><br><span> return {'raw': raw_hex_data}</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def decode_record_bin(self, raw_bin_data):</span><br><span style="color: hsl(0, 100%, 40%);">- """Decode raw (hex string) data into abstract representation. Overloaded by specific classes."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def decode_record_bin(self, raw_bin_data:bytearray):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Decode raw (binary) data into abstract representation.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ A derived class would typically provide a _decode_record_bin() or _decode_record_hex()</span><br><span style="color: hsl(120, 100%, 40%);">+ method for implementing this specifically for the given file. This function checks which</span><br><span style="color: hsl(120, 100%, 40%);">+ of the method exists, add calls them (with conversion, as needed).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ raw_bin_data : binary encoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ abstract_data; dict representing the decoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> method = getattr(self, '_decode_record_bin', None)</span><br><span> if callable(method):</span><br><span> return method(raw_bin_data)</span><br><span>@@ -513,8 +731,18 @@</span><br><span> return method(raw_hex_data)</span><br><span> return {'raw': raw_hex_data}</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def encode_record_hex(self, abstract_data):</span><br><span style="color: hsl(0, 100%, 40%);">- """Encode abstract representation into raw (hex string) data. Overloaded by specific classes."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def encode_record_hex(self, abstract_data) -> str:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Encode abstract representation into raw (hex string) data.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ A derived class would typically provide an _encode_record_bin() or _encode_record_hex()</span><br><span style="color: hsl(120, 100%, 40%);">+ method for implementing this specifically for the given file. This function checks which</span><br><span style="color: hsl(120, 100%, 40%);">+ of the method exists, add calls them (with conversion, as needed).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ abstract_data : dict representing the decoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ hex string encoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> method = getattr(self, '_encode_record_hex', None)</span><br><span> if callable(method):</span><br><span> return method(abstract_data)</span><br><span>@@ -523,8 +751,18 @@</span><br><span> return h2b(method(abstract_data))</span><br><span> raise NotImplementedError</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def encode_record_bin(self, abstract_data):</span><br><span style="color: hsl(0, 100%, 40%);">- """Encode abstract representation into raw (binary) data. Overloaded by specific classes."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def encode_record_bin(self, abstract_data) -> bytearray:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Encode abstract representation into raw (binary) data.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ A derived class would typically provide an _encode_record_bin() or _encode_record_hex()</span><br><span style="color: hsl(120, 100%, 40%);">+ method for implementing this specifically for the given file. This function checks which</span><br><span style="color: hsl(120, 100%, 40%);">+ of the method exists, add calls them (with conversion, as needed).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ abstract_data : dict representing the decoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ binary encoded data</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> method = getattr(self, '_encode_record_bin', None)</span><br><span> if callable(method):</span><br><span> return method(abstract_data)</span><br><span>@@ -549,6 +787,11 @@</span><br><span> class RuntimeState(object):</span><br><span> """Represent the runtime state of a session with a card."""</span><br><span> def __init__(self, card, profile):</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ card : pysim.cards.Card instance</span><br><span style="color: hsl(120, 100%, 40%);">+ profile : CardProfile instance</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> self.mf = CardMF()</span><br><span> self.card = card</span><br><span> self.selected_file = self.mf</span><br><span>@@ -581,15 +824,22 @@</span><br><span> print("error: could not determine card applications")</span><br><span> return apps_taken</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def get_cwd(self):</span><br><span style="color: hsl(0, 100%, 40%);">- """Obtain the current working directory."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def get_cwd(self) -> CardDF:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Obtain the current working directory.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ CardDF instance</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> if isinstance(self.selected_file, CardDF):</span><br><span> return self.selected_file</span><br><span> else:</span><br><span> return self.selected_file.parent</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def get_application(self):</span><br><span style="color: hsl(0, 100%, 40%);">- """Obtain the currently selected application (if any)."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def get_application(self) -> CardADF:</span><br><span style="color: hsl(120, 100%, 40%);">+ """Obtain the currently selected application (if any).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ CardADF() instance or None"""</span><br><span> # iterate upwards from selected file; check if any is an ADF</span><br><span> node = self.selected_file</span><br><span> while node.parent != node:</span><br><span>@@ -598,9 +848,16 @@</span><br><span> node = node.parent</span><br><span> return None</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def interpret_sw(self, sw):</span><br><span style="color: hsl(0, 100%, 40%);">- """Interpret the given SW relative to the currently selected Application</span><br><span style="color: hsl(0, 100%, 40%);">- or the underlying profile."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def interpret_sw(self, sw:str):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Interpret a given status word relative to the currently selected application</span><br><span style="color: hsl(120, 100%, 40%);">+ or the underlying card profile.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ sw : Status word as string of 4 hexd digits</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ Tuple of two strings</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> app = self.get_application()</span><br><span> if app:</span><br><span> # The application either comes with its own interpret_sw</span><br><span>@@ -614,8 +871,13 @@</span><br><span> else:</span><br><span> return self.profile.interpret_sw(sw)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def select(self, name, cmd_app=None):</span><br><span style="color: hsl(0, 100%, 40%);">- """Change current directory"""</span><br><span style="color: hsl(120, 100%, 40%);">+ def select(self, name:str, cmd_app=None):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Select a file (EF, DF, ADF, MF, ...).</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ name : Name of file to select</span><br><span style="color: hsl(120, 100%, 40%);">+ cmd_app : Command Application State (for unregistering old file commands)</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> sels = self.selected_file.get_selectables()</span><br><span> if is_hex(name):</span><br><span> name = name.lower()</span><br><span>@@ -645,43 +907,98 @@</span><br><span> else:</span><br><span> raise ValueError("Cannot select unknown %s" % (name))</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def read_binary(self, length=None, offset=0):</span><br><span style="color: hsl(120, 100%, 40%);">+ def read_binary(self, length:int=None, offset:int=0):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Read [part of] a transparent EF binary data.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ length : Amount of data to read (None: as much as possible)</span><br><span style="color: hsl(120, 100%, 40%);">+ offset : Offset into the file from which to read 'length' bytes</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ binary data read from the file</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> if not isinstance(self.selected_file, TransparentEF):</span><br><span> raise TypeError("Only works with TransparentEF")</span><br><span> return self.card._scc.read_binary(self.selected_file.fid, length, offset)</span><br><span> </span><br><span> def read_binary_dec(self):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Read [part of] a transparent EF binary data and decode it.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ length : Amount of data to read (None: as much as possible)</span><br><span style="color: hsl(120, 100%, 40%);">+ offset : Offset into the file from which to read 'length' bytes</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ abstract decode data read from the file</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> (data, sw) = self.read_binary()</span><br><span> dec_data = self.selected_file.decode_hex(data)</span><br><span> print("%s: %s -> %s" % (sw, data, dec_data))</span><br><span> return (dec_data, sw)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def update_binary(self, data_hex, offset=0):</span><br><span style="color: hsl(120, 100%, 40%);">+ def update_binary(self, data_hex:str, offset:int=0):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Update transparent EF binary data.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ data_hex : hex string of data to be written</span><br><span style="color: hsl(120, 100%, 40%);">+ offset : Offset into the file from which to write 'data_hex'</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> if not isinstance(self.selected_file, TransparentEF):</span><br><span> raise TypeError("Only works with TransparentEF")</span><br><span> return self.card._scc.update_binary(self.selected_file.fid, data_hex, offset)</span><br><span> </span><br><span> def update_binary_dec(self, data):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Update transparent EF from abstract data. Encodes the data to binary and</span><br><span style="color: hsl(120, 100%, 40%);">+ then updates the EF with it.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ data : abstract data which is to be encoded and written</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> data_hex = self.selected_file.encode_hex(data)</span><br><span> print("%s -> %s" % (data, data_hex))</span><br><span> return self.update_binary(data_hex)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def read_record(self, rec_nr=0):</span><br><span style="color: hsl(120, 100%, 40%);">+ def read_record(self, rec_nr:int=0):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Read a record as binary data.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ rec_nr : Record number to read</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ hex string of binary data contained in record</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> if not isinstance(self.selected_file, LinFixedEF):</span><br><span> raise TypeError("Only works with Linear Fixed EF")</span><br><span> # returns a string of hex nibbles</span><br><span> return self.card._scc.read_record(self.selected_file.fid, rec_nr)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def read_record_dec(self, rec_nr=0):</span><br><span style="color: hsl(120, 100%, 40%);">+ def read_record_dec(self, rec_nr:int=0):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Read a record and decode it to abstract data.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ rec_nr : Record number to read</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ abstract data contained in record</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> (data, sw) = self.read_record(rec_nr)</span><br><span> return (self.selected_file.decode_record_hex(data), sw)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def update_record(self, rec_nr, data_hex):</span><br><span style="color: hsl(120, 100%, 40%);">+ def update_record(self, rec_nr:int, data_hex):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Update a record with given binary data</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ rec_nr : Record number to read</span><br><span style="color: hsl(120, 100%, 40%);">+ data_hex : Hex string binary data to be written</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> if not isinstance(self.selected_file, LinFixedEF):</span><br><span> raise TypeError("Only works with Linear Fixed EF")</span><br><span> return self.card._scc.update_record(self.selected_file.fid, rec_nr, data_hex)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def update_record_dec(self, rec_nr, data):</span><br><span style="color: hsl(120, 100%, 40%);">+ def update_record_dec(self, rec_nr:int, data):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Update a record with given abstract data. Will encode abstract to binary data</span><br><span style="color: hsl(120, 100%, 40%);">+ and then write it to the given record on the card.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ rec_nr : Record number to read</span><br><span style="color: hsl(120, 100%, 40%);">+ data_hex : Abstract data to be written</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> hex_data = self.selected_file.encode_record_hex(data)</span><br><span> return self.update_record(self, rec_nr, data_hex)</span><br><span> </span><br><span>@@ -694,9 +1011,15 @@</span><br><span> self.fcp = None</span><br><span> </span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-def interpret_sw(sw_data, sw):</span><br><span style="color: hsl(0, 100%, 40%);">- """Interpret a given status word within the profile. Returns tuple of</span><br><span style="color: hsl(0, 100%, 40%);">- two strings"""</span><br><span style="color: hsl(120, 100%, 40%);">+def interpret_sw(sw_data:dict, sw:str):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Interpret a given status word.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ sw_data : Hierarchical dict of status word matches</span><br><span style="color: hsl(120, 100%, 40%);">+ sw : status word to match (string of 4 hex digits)</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ tuple of two strings (class_string, description)</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> for class_str, swdict in sw_data.items():</span><br><span> # first try direct match</span><br><span> if sw in swdict:</span><br><span>@@ -710,7 +1033,12 @@</span><br><span> class CardApplication(object):</span><br><span> """A card application is represented by an ADF (with contained hierarchy) and optionally</span><br><span> some SW definitions."""</span><br><span style="color: hsl(0, 100%, 40%);">- def __init__(self, name, adf=None, sw=None):</span><br><span style="color: hsl(120, 100%, 40%);">+ def __init__(self, name, adf:str=None, sw:dict=None):</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ adf : ADF name</span><br><span style="color: hsl(120, 100%, 40%);">+ sw : Dict of status word conversions</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> self.name = name</span><br><span> self.adf = adf</span><br><span> self.sw = sw or dict()</span><br><span>@@ -719,8 +1047,14 @@</span><br><span> return "APP(%s)" % (self.name)</span><br><span> </span><br><span> def interpret_sw(self, sw):</span><br><span style="color: hsl(0, 100%, 40%);">- """Interpret a given status word within the application. Returns tuple of</span><br><span style="color: hsl(0, 100%, 40%);">- two strings"""</span><br><span style="color: hsl(120, 100%, 40%);">+ """Interpret a given status word within the application.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ sw : Status word as string of 4 hexd digits</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ Tuple of two strings</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> return interpret_sw(self.sw, sw)</span><br><span> </span><br><span> class CardProfile(object):</span><br><span>@@ -728,6 +1062,14 @@</span><br><span> applications as well as profile-specific SW and shell commands. Every card has</span><br><span> one card profile, but there may be multiple applications within that profile."""</span><br><span> def __init__(self, name, **kw):</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ desc (str) : Description</span><br><span style="color: hsl(120, 100%, 40%);">+ files_in_mf : List of CardEF instances present in MF</span><br><span style="color: hsl(120, 100%, 40%);">+ applications : List of CardApplications present on card</span><br><span style="color: hsl(120, 100%, 40%);">+ sw : List of status word definitions</span><br><span style="color: hsl(120, 100%, 40%);">+ shell_cmdsets : List of cmd2 shell command sets of profile-specific commands</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> self.name = name</span><br><span> self.desc = kw.get("desc", None)</span><br><span> self.files_in_mf = kw.get("files_in_mf", [])</span><br><span>@@ -739,9 +1081,20 @@</span><br><span> return self.name</span><br><span> </span><br><span> def add_application(self, app):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Add an application to a card profile.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ app : CardApplication instance to be added to profile</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> self.applications.append(app)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def interpret_sw(self, sw):</span><br><span style="color: hsl(0, 100%, 40%);">- """Interpret a given status word within the profile. Returns tuple of</span><br><span style="color: hsl(0, 100%, 40%);">- two strings"""</span><br><span style="color: hsl(120, 100%, 40%);">+ def interpret_sw(self, sw:str):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Interpret a given status word within the profile.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ sw : Status word as string of 4 hexd digits</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ Tuple of two strings</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> return interpret_sw(self.sw, sw)</span><br><span>diff --git a/pySim/transport/__init__.py b/pySim/transport/__init__.py</span><br><span>index d720259..f946af8 100644</span><br><span>--- a/pySim/transport/__init__.py</span><br><span>+++ b/pySim/transport/__init__.py</span><br><span>@@ -24,48 +24,53 @@</span><br><span> #</span><br><span> </span><br><span> class LinkBase(object):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Base class for link/transport to card."""</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def wait_for_card(self, timeout=None, newcardonly=False):</span><br><span style="color: hsl(0, 100%, 40%);">- """wait_for_card(): Wait for a card and connect to it</span><br><span style="color: hsl(120, 100%, 40%);">+ def wait_for_card(self, timeout:int=None, newcardonly:bool=False):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Wait for a card and connect to it</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- timeout : Maximum wait time (None=no timeout)</span><br><span style="color: hsl(0, 100%, 40%);">- newcardonly : Should we wait for a new card, or an already</span><br><span style="color: hsl(0, 100%, 40%);">- inserted one ?</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ timeout : Maximum wait time in seconds (None=no timeout)</span><br><span style="color: hsl(120, 100%, 40%);">+ newcardonly : Should we wait for a new card, or an already inserted one ?</span><br><span> """</span><br><span> pass</span><br><span> </span><br><span> def connect(self):</span><br><span style="color: hsl(0, 100%, 40%);">- """connect(): Connect to a card immediately</span><br><span style="color: hsl(120, 100%, 40%);">+ """Connect to a card immediately</span><br><span> """</span><br><span> pass</span><br><span> </span><br><span> def disconnect(self):</span><br><span style="color: hsl(0, 100%, 40%);">- """disconnect(): Disconnect from card</span><br><span style="color: hsl(120, 100%, 40%);">+ """Disconnect from card</span><br><span> """</span><br><span> pass</span><br><span> </span><br><span> def reset_card(self):</span><br><span style="color: hsl(0, 100%, 40%);">- """reset_card(): Resets the card (power down/up)</span><br><span style="color: hsl(120, 100%, 40%);">+ """Resets the card (power down/up)</span><br><span> """</span><br><span> pass</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def send_apdu_raw(self, pdu):</span><br><span style="color: hsl(0, 100%, 40%);">- """send_apdu_raw(pdu): Sends an APDU with minimal processing</span><br><span style="color: hsl(120, 100%, 40%);">+ def send_apdu_raw(self, pdu:str):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Sends an APDU with minimal processing</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- pdu : string of hexadecimal characters (ex. "A0A40000023F00")</span><br><span style="color: hsl(0, 100%, 40%);">- return : tuple(data, sw), where</span><br><span style="color: hsl(0, 100%, 40%);">- data : string (in hex) of returned data (ex. "074F4EFFFF")</span><br><span style="color: hsl(0, 100%, 40%);">- sw : string (in hex) of status word (ex. "9000")</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ pdu : string of hexadecimal characters (ex. "A0A40000023F00")</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ tuple(data, sw), where</span><br><span style="color: hsl(120, 100%, 40%);">+ data : string (in hex) of returned data (ex. "074F4EFFFF")</span><br><span style="color: hsl(120, 100%, 40%);">+ sw : string (in hex) of status word (ex. "9000")</span><br><span> """</span><br><span> pass</span><br><span> </span><br><span> def send_apdu(self, pdu):</span><br><span style="color: hsl(0, 100%, 40%);">- """send_apdu(pdu): Sends an APDU and auto fetch response data</span><br><span style="color: hsl(120, 100%, 40%);">+ """Sends an APDU and auto fetch response data</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- pdu : string of hexadecimal characters (ex. "A0A40000023F00")</span><br><span style="color: hsl(0, 100%, 40%);">- return : tuple(data, sw), where</span><br><span style="color: hsl(0, 100%, 40%);">- data : string (in hex) of returned data (ex. "074F4EFFFF")</span><br><span style="color: hsl(0, 100%, 40%);">- sw : string (in hex) of status word (ex. "9000")</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ pdu : string of hexadecimal characters (ex. "A0A40000023F00")</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ tuple(data, sw), where</span><br><span style="color: hsl(120, 100%, 40%);">+ data : string (in hex) of returned data (ex. "074F4EFFFF")</span><br><span style="color: hsl(120, 100%, 40%);">+ sw : string (in hex) of status word (ex. "9000")</span><br><span> """</span><br><span> data, sw = self.send_apdu_raw(pdu)</span><br><span> </span><br><span>@@ -82,15 +87,16 @@</span><br><span> return data, sw</span><br><span> </span><br><span> def send_apdu_checksw(self, pdu, sw="9000"):</span><br><span style="color: hsl(0, 100%, 40%);">- """send_apdu_checksw(pdu,sw): Sends an APDU and check returned SW</span><br><span style="color: hsl(120, 100%, 40%);">+ """Sends an APDU and check returned SW</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- pdu : string of hexadecimal characters (ex. "A0A40000023F00")</span><br><span style="color: hsl(0, 100%, 40%);">- sw : string of 4 hexadecimal characters (ex. "9000"). The</span><br><span style="color: hsl(0, 100%, 40%);">- user may mask out certain digits using a '?' to add some</span><br><span style="color: hsl(0, 100%, 40%);">- ambiguity if needed.</span><br><span style="color: hsl(0, 100%, 40%);">- return : tuple(data, sw), where</span><br><span style="color: hsl(0, 100%, 40%);">- data : string (in hex) of returned data (ex. "074F4EFFFF")</span><br><span style="color: hsl(0, 100%, 40%);">- sw : string (in hex) of status word (ex. "9000")</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ pdu : string of hexadecimal characters (ex. "A0A40000023F00")</span><br><span style="color: hsl(120, 100%, 40%);">+ sw : string of 4 hexadecimal characters (ex. "9000"). The user may mask out certain</span><br><span style="color: hsl(120, 100%, 40%);">+ digits using a '?' to add some ambiguity if needed.</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ tuple(data, sw), where</span><br><span style="color: hsl(120, 100%, 40%);">+ data : string (in hex) of returned data (ex. "074F4EFFFF")</span><br><span style="color: hsl(120, 100%, 40%);">+ sw : string (in hex) of status word (ex. "9000")</span><br><span> """</span><br><span> rv = self.send_apdu(pdu)</span><br><span> </span><br><span>diff --git a/pySim/transport/calypso.py b/pySim/transport/calypso.py</span><br><span>index 7f99d21..467d5ee 100644</span><br><span>--- a/pySim/transport/calypso.py</span><br><span>+++ b/pySim/transport/calypso.py</span><br><span>@@ -1,9 +1,5 @@</span><br><span> # -*- coding: utf-8 -*-</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-""" pySim: Transport Link for Calypso bases phones</span><br><span style="color: hsl(0, 100%, 40%);">-"""</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-#</span><br><span> # Copyright (C) 2018 Vadim Yanitskiy <axilirator@gmail.com></span><br><span> #</span><br><span> # This program is free software: you can redistribute it and/or modify</span><br><span>@@ -73,8 +69,9 @@</span><br><span> self.data += pdu</span><br><span> </span><br><span> class CalypsoSimLink(LinkBase):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Transport Link for Calypso based phones."""</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def __init__(self, sock_path = "/tmp/osmocom_l2"):</span><br><span style="color: hsl(120, 100%, 40%);">+ def __init__(self, sock_path:str = "/tmp/osmocom_l2"):</span><br><span> # Make sure that a given socket path exists</span><br><span> if not os.path.exists(sock_path):</span><br><span> raise ReaderError("There is no such ('%s') UNIX socket" % sock_path)</span><br><span>@@ -119,7 +116,6 @@</span><br><span> pass # Nothing to do really ...</span><br><span> </span><br><span> def send_apdu_raw(self, pdu):</span><br><span style="color: hsl(0, 100%, 40%);">- """see LinkBase.send_apdu_raw"""</span><br><span> </span><br><span> # Request FULL reset</span><br><span> req_msg = L1CTLMessageSIM(h2b(pdu))</span><br><span>diff --git a/pySim/transport/modem_atcmd.py b/pySim/transport/modem_atcmd.py</span><br><span>index 86d4443..fccd388 100644</span><br><span>--- a/pySim/transport/modem_atcmd.py</span><br><span>+++ b/pySim/transport/modem_atcmd.py</span><br><span>@@ -1,8 +1,5 @@</span><br><span> # -*- coding: utf-8 -*-</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-""" pySim: Transport Link for 3GPP TS 27.007 compliant modems</span><br><span style="color: hsl(0, 100%, 40%);">-"""</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span> # Copyright (C) 2020 Vadim Yanitskiy <axilirator@gmail.com></span><br><span> #</span><br><span> # This program is free software: you can redistribute it and/or modify</span><br><span>@@ -31,7 +28,8 @@</span><br><span> # log.root.setLevel(log.DEBUG)</span><br><span> </span><br><span> class ModemATCommandLink(LinkBase):</span><br><span style="color: hsl(0, 100%, 40%);">- def __init__(self, device='/dev/ttyUSB0', baudrate=115200):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Transport Link for 3GPP TS 27.007 compliant modems."""</span><br><span style="color: hsl(120, 100%, 40%);">+ def __init__(self, device:str='/dev/ttyUSB0', baudrate:int=115200):</span><br><span> self._sl = serial.Serial(device, baudrate, timeout=5)</span><br><span> self._device = device</span><br><span> self._atr = None</span><br><span>diff --git a/pySim/transport/pcsc.py b/pySim/transport/pcsc.py</span><br><span>index 2c2cbb9..f08f71a 100644</span><br><span>--- a/pySim/transport/pcsc.py</span><br><span>+++ b/pySim/transport/pcsc.py</span><br><span>@@ -1,9 +1,5 @@</span><br><span> # -*- coding: utf-8 -*-</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-""" pySim: PCSC reader transport link</span><br><span style="color: hsl(0, 100%, 40%);">-"""</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-#</span><br><span> # Copyright (C) 2009-2010 Sylvain Munaut <tnt@246tNt.com></span><br><span> # Copyright (C) 2010 Harald Welte <laforge@gnumonks.org></span><br><span> #</span><br><span>@@ -32,8 +28,9 @@</span><br><span> </span><br><span> </span><br><span> class PcscSimLink(LinkBase):</span><br><span style="color: hsl(120, 100%, 40%);">+ """ pySim: PCSC reader transport link."""</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def __init__(self, reader_number=0):</span><br><span style="color: hsl(120, 100%, 40%);">+ def __init__(self, reader_number:int=0):</span><br><span> r = readers()</span><br><span> self._reader = r[reader_number]</span><br><span> self._con = self._reader.createConnection()</span><br><span>@@ -46,7 +43,7 @@</span><br><span> pass</span><br><span> return</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def wait_for_card(self, timeout=None, newcardonly=False):</span><br><span style="color: hsl(120, 100%, 40%);">+ def wait_for_card(self, timeout:int=None, newcardonly:bool=False):</span><br><span> cr = CardRequest(readers=[self._reader], timeout=timeout, newcardonly=newcardonly)</span><br><span> try:</span><br><span> cr.waitforcard()</span><br><span>@@ -75,7 +72,6 @@</span><br><span> return 1</span><br><span> </span><br><span> def send_apdu_raw(self, pdu):</span><br><span style="color: hsl(0, 100%, 40%);">- """see LinkBase.send_apdu_raw"""</span><br><span> </span><br><span> apdu = h2i(pdu)</span><br><span> </span><br><span>diff --git a/pySim/transport/serial.py b/pySim/transport/serial.py</span><br><span>index 03d3f38..6d39303 100644</span><br><span>--- a/pySim/transport/serial.py</span><br><span>+++ b/pySim/transport/serial.py</span><br><span>@@ -1,9 +1,5 @@</span><br><span> # -*- coding: utf-8 -*-</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-""" pySim: Transport Link for serial (RS232) based readers included with simcard</span><br><span style="color: hsl(0, 100%, 40%);">-"""</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">-#</span><br><span> # Copyright (C) 2009-2010 Sylvain Munaut <tnt@246tNt.com></span><br><span> #</span><br><span> # This program is free software: you can redistribute it and/or modify</span><br><span>@@ -30,8 +26,10 @@</span><br><span> </span><br><span> </span><br><span> class SerialSimLink(LinkBase):</span><br><span style="color: hsl(120, 100%, 40%);">+ """ pySim: Transport Link for serial (RS232) based readers included with simcard"""</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- def __init__(self, device='/dev/ttyUSB0', baudrate=9600, rst='-rts', debug=False):</span><br><span style="color: hsl(120, 100%, 40%);">+ def __init__(self, device:str='/dev/ttyUSB0', baudrate:int=9600, rst:str='-rts',</span><br><span style="color: hsl(120, 100%, 40%);">+ debug:bool=False):</span><br><span> if not os.path.exists(device):</span><br><span> raise ValueError("device file %s does not exist -- abort" % device)</span><br><span> self._sl = serial.Serial(</span><br><span>@@ -183,7 +181,6 @@</span><br><span> return self._sl.read()</span><br><span> </span><br><span> def send_apdu_raw(self, pdu):</span><br><span style="color: hsl(0, 100%, 40%);">- """see LinkBase.send_apdu_raw"""</span><br><span> </span><br><span> pdu = h2b(pdu)</span><br><span> data_len = ord(pdu[4]) # P3</span><br><span>diff --git a/pySim/utils.py b/pySim/utils.py</span><br><span>index 0848b01..607526c 100644</span><br><span>--- a/pySim/utils.py</span><br><span>+++ b/pySim/utils.py</span><br><span>@@ -21,43 +21,65 @@</span><br><span> #</span><br><span> </span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-def h2b(s):</span><br><span style="color: hsl(120, 100%, 40%);">+def h2b(s: str) -> bytearray:</span><br><span> """convert from a string of hex nibbles to a sequence of bytes"""</span><br><span> return bytearray.fromhex(s)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-def b2h(b):</span><br><span style="color: hsl(120, 100%, 40%);">+def b2h(b: bytearray) -> str:</span><br><span> """convert from a sequence of bytes to a string of hex nibbles"""</span><br><span> return ''.join(['%02x'%(x) for x in b])</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-def h2i(s):</span><br><span style="color: hsl(120, 100%, 40%);">+def h2i(s:str):</span><br><span style="color: hsl(120, 100%, 40%);">+ """convert from a string of hex nibbles to a list of integers"""</span><br><span> return [(int(x,16)<<4)+int(y,16) for x,y in zip(s[0::2], s[1::2])]</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-def i2h(s):</span><br><span style="color: hsl(120, 100%, 40%);">+def i2h(s) -> str:</span><br><span style="color: hsl(120, 100%, 40%);">+ """convert from a list of integers to a string of hex nibbles"""</span><br><span> return ''.join(['%02x'%(x) for x in s])</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-def h2s(s):</span><br><span style="color: hsl(120, 100%, 40%);">+def h2s(s:str) -> str:</span><br><span style="color: hsl(120, 100%, 40%);">+ """convert from a string of hex nibbles to an ASCII string"""</span><br><span> return ''.join([chr((int(x,16)<<4)+int(y,16)) for x,y in zip(s[0::2], s[1::2])</span><br><span> if int(x + y, 16) != 0xff])</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-def s2h(s):</span><br><span style="color: hsl(120, 100%, 40%);">+def s2h(s:str) -> str:</span><br><span style="color: hsl(120, 100%, 40%);">+ """convert from an ASCII string to a string of hex nibbles"""</span><br><span> b = bytearray()</span><br><span> b.extend(map(ord, s))</span><br><span> return b2h(b)</span><br><span> </span><br><span> # List of bytes to string</span><br><span style="color: hsl(0, 100%, 40%);">-def i2s(s):</span><br><span style="color: hsl(120, 100%, 40%);">+def i2s(s) -> str:</span><br><span style="color: hsl(120, 100%, 40%);">+ """convert from a list of integers to an ASCII string"""</span><br><span> return ''.join([chr(x) for x in s])</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-def swap_nibbles(s):</span><br><span style="color: hsl(120, 100%, 40%);">+def swap_nibbles(s:str) -> str:</span><br><span style="color: hsl(120, 100%, 40%);">+ """swap the nibbles in a hex string"""</span><br><span> return ''.join([x+y for x,y in zip(s[1::2], s[0::2])])</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-def rpad(s, l, c='f'):</span><br><span style="color: hsl(120, 100%, 40%);">+def rpad(s:str, l:int, c='f') -> str:</span><br><span style="color: hsl(120, 100%, 40%);">+ """pad string on the right side.</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ s : string to pad</span><br><span style="color: hsl(120, 100%, 40%);">+ l : total length to pad to</span><br><span style="color: hsl(120, 100%, 40%);">+ c : padding character</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ String 's' padded with as many 'c' as needed to reach total length of 'l'</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> return s + c * (l - len(s))</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-def lpad(s, l, c='f'):</span><br><span style="color: hsl(120, 100%, 40%);">+def lpad(s:str, l:int, c='f') -> str:</span><br><span style="color: hsl(120, 100%, 40%);">+ """pad string on the left side.</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ s : string to pad</span><br><span style="color: hsl(120, 100%, 40%);">+ l : total length to pad to</span><br><span style="color: hsl(120, 100%, 40%);">+ c : padding character</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ String 's' padded with as many 'c' as needed to reach total length of 'l'</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> return c * (l - len(s)) + s</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-def half_round_up(n):</span><br><span style="color: hsl(120, 100%, 40%);">+def half_round_up(n:int) -> int:</span><br><span> return (n + 1)//2</span><br><span> </span><br><span> # IMSI encoded format:</span><br><span>@@ -75,8 +97,8 @@</span><br><span> # Because of this, an odd length IMSI fits exactly into len(imsi) + 1 // 2 bytes, whereas an</span><br><span> # even length IMSI only uses half of the last byte.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-def enc_imsi(imsi):</span><br><span style="color: hsl(0, 100%, 40%);">- """Converts a string imsi into the value of the EF"""</span><br><span style="color: hsl(120, 100%, 40%);">+def enc_imsi(imsi:str):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Converts a string IMSI into the encoded value of the EF"""</span><br><span> l = half_round_up(len(imsi) + 1) # Required bytes - include space for odd/even indicator</span><br><span> oe = len(imsi) & 1 # Odd (1) / Even (0)</span><br><span> ei = '%02x' % l + swap_nibbles('%01x%s' % ((oe<<3)|1, rpad(imsi, 15)))</span><br><span>@@ -781,7 +803,7 @@</span><br><span> </span><br><span> return None</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-def sw_match(sw, pattern):</span><br><span style="color: hsl(120, 100%, 40%);">+def sw_match(sw:str, pattern:str) -> str:</span><br><span> """Match given SW against given pattern."""</span><br><span> # Create a masked version of the returned status word</span><br><span> sw_lower = sw.lower()</span><br><span>@@ -796,8 +818,18 @@</span><br><span> # Compare the masked version against the pattern</span><br><span> return sw_masked == pattern</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-def tabulate_str_list(str_list, width = 79, hspace = 2, lspace = 1, align_left = True):</span><br><span style="color: hsl(0, 100%, 40%);">- """Pretty print a list of strings into a tabulated form"""</span><br><span style="color: hsl(120, 100%, 40%);">+def tabulate_str_list(str_list, width:int = 79, hspace:int = 2, lspace:int = 1,</span><br><span style="color: hsl(120, 100%, 40%);">+ align_left:bool = True):</span><br><span style="color: hsl(120, 100%, 40%);">+ """Pretty print a list of strings into a tabulated form.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Args:</span><br><span style="color: hsl(120, 100%, 40%);">+ width : total width in characters per line</span><br><span style="color: hsl(120, 100%, 40%);">+ space : horizontal space between cells</span><br><span style="color: hsl(120, 100%, 40%);">+ lspace : number of spaces before row</span><br><span style="color: hsl(120, 100%, 40%);">+ align_lef : Align text to the left side</span><br><span style="color: hsl(120, 100%, 40%);">+ Returns:</span><br><span style="color: hsl(120, 100%, 40%);">+ multi-line string containing formatted table</span><br><span style="color: hsl(120, 100%, 40%);">+ """</span><br><span> if str_list == None:</span><br><span> return ""</span><br><span> if len(str_list) <= 0:</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/pysim/+/23577">change 23577</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/pysim/+/23577"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: pysim </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: I6ac88e0662cf3c56ae32d86d50b18a8b4150571a </div>
<div style="display:none"> Gerrit-Change-Number: 23577 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: laforge <laforge@osmocom.org> </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>