catarrh/pysim
1
0
Fork 0
forked from public/pysim
Code Pull Requests Activity

Add more documentation to the classes/methods

Browse Source 
* add type annotations in-line with PEP484
* convert existing documentation to follow the
  "Google Python Style Guide" format understood by
  the sphinx.ext.napoleon' extension
* add much more documentation all over the code base

Change-Id: I6ac88e0662cf3c56ae32d86d50b18a8b4150571a
This commit is contained in:
Harald Welte
2021-04-02 13:00:18 +02:00
parent 082d4e0956
commit ee3501fc62
9 changed files with 635 additions and 185 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
pySim/transport/__init__.py
View File

@@ -24,48 +24,53 @@ from pySim.utils import sw_match
#
class LinkBase(object):
"""Base class for link/transport to card."""
def wait_for_card(self, timeout=None, newcardonly=False):
"""wait_for_card(): Wait for a card and connect to it
def wait_for_card(self, timeout:int=None, newcardonly:bool=False):
"""Wait for a card and connect to it
timeout : Maximum wait time (None=no timeout)
newcardonly : Should we wait for a new card, or an already
inserted one ?
Args:
timeout : Maximum wait time in seconds (None=no timeout)
newcardonly : Should we wait for a new card, or an already inserted one ?
"""
pass
def connect(self):
"""connect(): Connect to a card immediately
"""Connect to a card immediately
"""
pass
def disconnect(self):
"""disconnect(): Disconnect from card
"""Disconnect from card
"""
pass
def reset_card(self):
"""reset_card(): Resets the card (power down/up)
"""Resets the card (power down/up)
"""
pass
def send_apdu_raw(self, pdu):
"""send_apdu_raw(pdu): Sends an APDU with minimal processing
def send_apdu_raw(self, pdu:str):
"""Sends an APDU with minimal processing
pdu : string of hexadecimal characters (ex. "A0A40000023F00")
return : tuple(data, sw), where
data : string (in hex) of returned data (ex. "074F4EFFFF")
sw : string (in hex) of status word (ex. "9000")
Args:
pdu : string of hexadecimal characters (ex. "A0A40000023F00")
Returns:
tuple(data, sw), where
data : string (in hex) of returned data (ex. "074F4EFFFF")
sw : string (in hex) of status word (ex. "9000")
"""
pass
def send_apdu(self, pdu):
"""send_apdu(pdu): Sends an APDU and auto fetch response data
"""Sends an APDU and auto fetch response data
pdu : string of hexadecimal characters (ex. "A0A40000023F00")
return : tuple(data, sw), where
data : string (in hex) of returned data (ex. "074F4EFFFF")
sw : string (in hex) of status word (ex. "9000")
Args:
pdu : string of hexadecimal characters (ex. "A0A40000023F00")
Returns:
tuple(data, sw), where
data : string (in hex) of returned data (ex. "074F4EFFFF")
sw : string (in hex) of status word (ex. "9000")
"""
data, sw = self.send_apdu_raw(pdu)
@@ -82,15 +87,16 @@ class LinkBase(object):
return data, sw
def send_apdu_checksw(self, pdu, sw="9000"):
"""send_apdu_checksw(pdu,sw): Sends an APDU and check returned SW
"""Sends an APDU and check returned SW
pdu : string of hexadecimal characters (ex. "A0A40000023F00")
sw : string of 4 hexadecimal characters (ex. "9000"). The
user may mask out certain digits using a '?' to add some
ambiguity if needed.
return : tuple(data, sw), where
data : string (in hex) of returned data (ex. "074F4EFFFF")
sw : string (in hex) of status word (ex. "9000")
Args:
pdu : string of hexadecimal characters (ex. "A0A40000023F00")
sw : string of 4 hexadecimal characters (ex. "9000"). The user may mask out certain
digits using a '?' to add some ambiguity if needed.
Returns:
tuple(data, sw), where
data : string (in hex) of returned data (ex. "074F4EFFFF")
sw : string (in hex) of status word (ex. "9000")
"""
rv = self.send_apdu(pdu)

8
pySim/transport/calypso.py
View File

@@ -1,9 +1,5 @@
# -*- coding: utf-8 -*-
""" pySim: Transport Link for Calypso bases phones
"""
#
# Copyright (C) 2018 Vadim Yanitskiy <axilirator@gmail.com>
#
# This program is free software: you can redistribute it and/or modify
@@ -73,8 +69,9 @@ class L1CTLMessageSIM(L1CTLMessage):
self.data += pdu
class CalypsoSimLink(LinkBase):
"""Transport Link for Calypso based phones."""
def __init__(self, sock_path = "/tmp/osmocom_l2"):
def __init__(self, sock_path:str = "/tmp/osmocom_l2"):
# Make sure that a given socket path exists
if not os.path.exists(sock_path):
raise ReaderError("There is no such ('%s') UNIX socket" % sock_path)
@@ -119,7 +116,6 @@ class CalypsoSimLink(LinkBase):
pass # Nothing to do really ...
def send_apdu_raw(self, pdu):
"""see LinkBase.send_apdu_raw"""
# Request FULL reset
req_msg = L1CTLMessageSIM(h2b(pdu))

6
pySim/transport/modem_atcmd.py
View File

@@ -1,8 +1,5 @@
# -*- coding: utf-8 -*-
""" pySim: Transport Link for 3GPP TS 27.007 compliant modems
"""
# Copyright (C) 2020 Vadim Yanitskiy <axilirator@gmail.com>
#
# This program is free software: you can redistribute it and/or modify
@@ -31,7 +28,8 @@ from pySim.exceptions import *
# log.root.setLevel(log.DEBUG)
class ModemATCommandLink(LinkBase):
def __init__(self, device='/dev/ttyUSB0', baudrate=115200):
"""Transport Link for 3GPP TS 27.007 compliant modems."""
def __init__(self, device:str='/dev/ttyUSB0', baudrate:int=115200):
self._sl = serial.Serial(device, baudrate, timeout=5)
self._device = device
self._atr = None

10
pySim/transport/pcsc.py
View File

@@ -1,9 +1,5 @@
# -*- coding: utf-8 -*-
""" pySim: PCSC reader transport link
"""
#
# Copyright (C) 2009-2010 Sylvain Munaut <tnt@246tNt.com>
# Copyright (C) 2010 Harald Welte <laforge@gnumonks.org>
#
@@ -32,8 +28,9 @@ from pySim.utils import h2i, i2h
class PcscSimLink(LinkBase):
""" pySim: PCSC reader transport link."""
def __init__(self, reader_number=0):
def __init__(self, reader_number:int=0):
r = readers()
self._reader = r[reader_number]
self._con = self._reader.createConnection()
@@ -46,7 +43,7 @@ class PcscSimLink(LinkBase):
pass
return
def wait_for_card(self, timeout=None, newcardonly=False):
def wait_for_card(self, timeout:int=None, newcardonly:bool=False):
cr = CardRequest(readers=[self._reader], timeout=timeout, newcardonly=newcardonly)
try:
cr.waitforcard()
@@ -75,7 +72,6 @@ class PcscSimLink(LinkBase):
return 1
def send_apdu_raw(self, pdu):
"""see LinkBase.send_apdu_raw"""
apdu = h2i(pdu)

9
pySim/transport/serial.py
View File

@@ -1,9 +1,5 @@
# -*- coding: utf-8 -*-
""" pySim: Transport Link for serial (RS232) based readers included with simcard
"""
#
# Copyright (C) 2009-2010 Sylvain Munaut <tnt@246tNt.com>
#
# This program is free software: you can redistribute it and/or modify
@@ -30,8 +26,10 @@ from pySim.utils import h2b, b2h
class SerialSimLink(LinkBase):
""" pySim: Transport Link for serial (RS232) based readers included with simcard"""
def __init__(self, device='/dev/ttyUSB0', baudrate=9600, rst='-rts', debug=False):
def __init__(self, device:str='/dev/ttyUSB0', baudrate:int=9600, rst:str='-rts',
debug:bool=False):
if not os.path.exists(device):
raise ValueError("device file %s does not exist -- abort" % device)
self._sl = serial.Serial(
@@ -183,7 +181,6 @@ class SerialSimLink(LinkBase):
return self._sl.read()
def send_apdu_raw(self, pdu):
"""see LinkBase.send_apdu_raw"""
pdu = h2b(pdu)
data_len = ord(pdu[4]) # P3