Documentation: improve doc

LudovicRousseau · May 1, 2023 · 807fae5 · 807fae5
1 parent df11194
commit 807fae5
Show file tree

Hide file tree

Showing 4 changed files with 66 additions and 45 deletions.
diff --git a/smartcard/CardConnection.py b/smartcard/CardConnection.py
@@ -31,9 +31,16 @@ class CardConnection(Observable):
     """Card connection abstract class.
     """
     T0_protocol = 0x00000001
+    """ protocol T=0 """
+
     T1_protocol = 0x00000002
+    """ protocol T=1 """
+
     RAW_protocol = 0x00010000
+    """ protocol RAW (direct access to the reader) """
+
     T15_protocol = 0x00000008
+    """ protocol T=15 """
 
     def __init__(self, reader):
         """Construct a new card connection.
@@ -43,9 +50,12 @@ def __init__(self, reader):
         """
         Observable.__init__(self)
         self.reader = reader
+        """ reader name """
         self.errorcheckingchain = None
+        """ see L{setErrorCheckingChain} """
         self.defaultprotocol = CardConnection.T0_protocol |\
             CardConnection.T1_protocol
+        """ see L{setProtocol} and L{getProtocol} """
 
     def __del__(self):
         """Connect to card."""
@@ -76,11 +86,14 @@ def connect(self, protocol=None, mode=None, disposition=None):
         L{CardConnection.T0_protocol}, L{CardConnection.T1_protocol},
         L{CardConnection.RAW_protocol}, L{CardConnection.T15_protocol}
 
-        @param mode: SCARD_SHARE_SHARED (default), SCARD_SHARE_EXCLUSIVE or
-        SCARD_SHARE_DIRECT
+        @param mode: C{smartcard.scard.SCARD_SHARE_SHARED} (default),
+        C{smartcard.scard.SCARD_SHARE_EXCLUSIVE} or
+        C{smartcard.scard.SCARD_SHARE_DIRECT}
 
-        @param disposition: SCARD_LEAVE_CARD (default), SCARD_RESET_CARD,
-        SCARD_UNPOWER_CARD or SCARD_EJECT_CARD
+        @param disposition: C{smartcard.scard.SCARD_LEAVE_CARD}
+        (default), C{smartcard.scard.SCARD_RESET_CARD},
+        C{smartcard.scard.SCARD_UNPOWER_CARD} or
+        C{smartcard.scard.SCARD_EJECT_CARD}
         """
         Observable.setChanged(self)
         Observable.notifyObservers(self, CardConnectionEvent('connect'))
@@ -91,11 +104,14 @@ def reconnect(self, protocol=None, mode=None, disposition=None):
         L{CardConnection.T0_protocol}, L{CardConnection.T1_protocol},
         L{CardConnection.RAW_protocol}, L{CardConnection.T15_protocol}
 
-        @param mode: SCARD_SHARE_SHARED (default), SCARD_SHARE_EXCLUSIVE or
-        SCARD_SHARE_DIRECT
+        @param mode: C{smartcard.scard.SCARD_SHARE_SHARED} (default),
+        C{smartcard.scard.SCARD_SHARE_EXCLUSIVE} or
+        C{smartcard.scard.SCARD_SHARE_DIRECT}
 
-        @param disposition: SCARD_LEAVE_CARD, SCARD_RESET_CARD (default),
-        SCARD_UNPOWER_CARD or SCARD_EJECT_CARD
+        @param disposition: C{smartcard.scard.SCARD_LEAVE_CARD},
+        C{smartcard.scard.SCARD_RESET_CARD} (default),
+        C{smartcard.scard.SCARD_UNPOWER_CARD} or
+        C{smartcard.scard.SCARD_EJECT_CARD}
         """
         Observable.setChanged(self)
         Observable.notifyObservers(self, CardConnectionEvent('reconnect'))
@@ -112,8 +128,8 @@ def getATR(self):
     def getProtocol(self):
         """Return bit mask for the protocol of connection, or None if no
         protocol set.  The return value is a bit mask of
-        CardConnection.T0_protocol, CardConnection.T1_protocol,
-        CardConnection.RAW_protocol, CardConnection.T15_protocol
+        L{CardConnection.T0_protocol}, L{CardConnection.T1_protocol},
+        L{CardConnection.RAW_protocol}, L{CardConnection.T15_protocol}
         """
         return self.defaultprotocol
 
@@ -123,33 +139,34 @@ def getReader(self):
 
     def setErrorCheckingChain(self, errorcheckingchain):
         """Add an error checking chain.
-        @param errorcheckingchain: a smartcard.sw.ErrorCheckingChain object The
-        error checking strategies in errorchecking chain will be tested
-        with each received response APDU, and a
-        smartcard.sw.SWException.SWException will be raised upon
+        @param errorcheckingchain: a L{smartcard.sw.ErrorCheckingChain}
+        object The error checking strategies in errorchecking chain will
+        be tested with each received response APDU, and a
+        L{smartcard.sw.SWExceptions.SWException} will be raised upon
         error."""
         self.errorcheckingchain = errorcheckingchain
 
     def setProtocol(self, protocol):
         """Set protocol for card connection.
-        @param protocol: a bit mask of CardConnection.T0_protocol,
-        CardConnection.T1_protocol, CardConnection.RAW_protocol,
-        CardConnection.T15_protocol e.g.
-        setProtocol(CardConnection.T1_protocol |
-        CardConnection.T0_protocol) """
+        @param protocol: a bit mask of L{CardConnection.T0_protocol},
+        L{CardConnection.T1_protocol}, L{CardConnection.RAW_protocol},
+        L{CardConnection.T15_protocol}
+
+        >>> setProtocol(CardConnection.T1_protocol | CardConnection.T0_protocol)
+        """
         self.defaultprotocol = protocol
 
     def transmit(self, bytes, protocol=None):
-        """Transmit an apdu. Internally calls doTransmit() class method
+        """Transmit an apdu. Internally calls L{doTransmit()} class method
         and notify observers upon command/response APDU events.
-        Subclasses must override the doTransmit() class method.
+        Subclasses must override the L{doTransmit()} class method.
 
         @param bytes:      list of bytes to transmit
 
         @param protocol:   the transmission protocol, from
-                    CardConnection.T0_protocol,
-                    CardConnection.T1_protocol, or
-                    CardConnection.RAW_protocol
+                    L{CardConnection.T0_protocol},
+                    L{CardConnection.T1_protocol}, or
+                    L{CardConnection.RAW_protocol}
         """
         Observable.setChanged(self)
         Observable.notifyObservers(self,
@@ -207,7 +224,8 @@ def doControl(self, controlCode, bytes):
     def getAttrib(self, attribId):
         """return the requested attribute
 
-        @param attribId: attribute id like SCARD_ATTR_VENDOR_NAME
+        @param attribId: attribute id like
+        C{smartcard.scard.SCARD_ATTR_VENDOR_NAME}
         """
         Observable.setChanged(self)
         Observable.notifyObservers(self,

diff --git a/smartcard/pcsc/PCSCCardConnection.py b/smartcard/pcsc/PCSCCardConnection.py
@@ -30,7 +30,7 @@
 
 
 def translateprotocolmask(protocol):
-    """Translate CardConnection protocol mask into PCSC protocol mask."""
+    """Translate L{CardConnection} protocol mask into PCSC protocol mask."""
     pcscprotocol = 0
     if protocol is not None:
         if CardConnection.T0_protocol & protocol:
@@ -98,7 +98,8 @@ def connect(self, protocol=None, mode=None, disposition=None):
         If protocol is not specified, connect with the default
         connection protocol.
 
-        If mode is not specified, connect with SCARD_SHARE_SHARED."""
+        If mode is not specified, connect with
+        C{smartcard.scard.SCARD_SHARE_SHARED}."""
         CardConnection.connect(self, protocol)
         pcscprotocol = translateprotocolmask(protocol)
         if 0 == pcscprotocol:
@@ -142,9 +143,11 @@ def reconnect(self, protocol=None, mode=None, disposition=None):
         If protocol is not specified, connect with the default
         connection protocol.
 
-        If mode is not specified, connect with SCARD_SHARE_SHARED.
+        If mode is not specified, connect with
+        C{smartcard.scard.SCARD_SHARE_SHARED}.
 
-        If disposition is not specified, do a warm reset (SCARD_RESET_CARD)"""
+        If disposition is not specified, do a warm reset
+        (C{smartcard.scard.SCARD_RESET_CARD})"""
         CardConnection.reconnect(self, protocol)
         if self.hcard is None:
             raise CardConnectionException('Card not connected',
@@ -223,13 +226,13 @@ def doTransmit(self, bytes, protocol=None):
         @param bytes:    command apdu to transmit (list of bytes)
 
         @param protocol: the transmission protocol, from
-            CardConnection.T0_protocol, CardConnection.T1_protocol, or
-            CardConnection.RAW_protocol
+            L{CardConnection.T0_protocol}, L{CardConnection.T1_protocol}, or
+            L{CardConnection.RAW_protocol}
 
         @return:     a tuple (response, sw1, sw2) where
-                    sw1 is status word 1, e.g. 0x90
-                    sw2 is status word 2, e.g. 0x1A
-                    response are the response bytes excluding status words
+                    - response are the response bytes excluding status words
+                    - sw1 is status word 1, e.g. 0x90
+                    - sw2 is status word 2, e.g. 0x1A
         """
         if protocol is None:
             protocol = self.getProtocol()

diff --git a/smartcard/pcsc/PCSCCardRequest.py b/smartcard/pcsc/PCSCCardRequest.py
@@ -47,23 +47,23 @@ def __init__(self, newcardonly=False, readers=None,
                  cardType=None, cardServiceClass=None, timeout=1):
         """Construct new PCSCCardRequest.
 
-        @param newcardonly: if True, request a new card default is
-        False, i.e. accepts cards already inserted
+        @param newcardonly: if C{True}, request a new card. default is
+        C{False}, i.e. accepts cards already inserted
 
         @param readers: the list of readers to consider for requesting a
         card default is to consider all readers
 
-        @param cardType: the CardType class to wait for; default is
-        AnyCardType, i.e.  the request will returns with new or already
+        @param cardType: the L{CardType} class to wait for; default is
+        L{AnyCardType}, i.e.  the request will returns with new or already
         inserted cards
 
         @param cardServiceClass: the specific card service class to
         create and bind to the card default is to create and bind a
-        PassThruCardService
+        L{PassThruCardService}
 
         @param timeout: the time in seconds we are ready to wait for
         connecting to the requested card.  default is to wait one second
-        to wait forever, set timeout to None
+        to wait forever, set timeout to C{None}
         """
         AbstractCardRequest.__init__(
             self, newcardonly, readers, cardType, cardServiceClass, timeout)

diff --git a/smartcard/pcsc/PCSCPart10.py b/smartcard/pcsc/PCSCPart10.py
@@ -110,10 +110,10 @@
 def parseFeatureRequest(response):
     """ Get the list of Part10 features supported by the reader.
 
-    @param response: result of CM_IOCTL_GET_FEATURE_REQUEST commmand
+    @param response: result of L{CM_IOCTL_GET_FEATURE_REQUEST} commmand
 
     @rtype: list
-    @return: a list of list [[tag1, value1], [tag2, value2]]
+    @return: a list of list C{[[tag1, value1], [tag2, value2]]}
     """
     features = []
     while (len(response) > 0):
@@ -136,7 +136,7 @@ def getFeatureRequest(cardConnection):
     @param cardConnection: L{CardConnection} object
 
     @rtype: list
-    @return: a list of list [[tag1, value1], [tag2, value2]]
+    @return: a list of list C{[[tag1, value1], [tag2, value2]]}
     """
     response = cardConnection.control(CM_IOCTL_GET_FEATURE_REQUEST, [])
     return parseFeatureRequest(response)
@@ -156,7 +156,7 @@ def hasFeature(featureList, feature):
 
 
 def getPinProperties(cardConnection, featureList=None, controlCode=None):
-    """ return the PIN_PROPERTIES structure
+    """ return the C{PIN_PROPERTIES} structure
 
     @param cardConnection: L{CardConnection} object
     @param featureList: feature list as returned by L{getFeatureRequest()}
@@ -184,7 +184,7 @@ def getPinProperties(cardConnection, featureList=None, controlCode=None):
 
 
 def getTlvProperties(cardConnection, featureList=None, controlCode=None):
-    """ return the GET_TLV_PROPERTIES structure
+    """ return the C{GET_TLV_PROPERTIES} structure
 
     @param cardConnection: L{CardConnection} object
     @param featureList: feature list as returned by L{getFeatureRequest()}