add disposition and status models, methods for respondent gateway

Author: dy-waltergrantward

README.md

@@ -70,15 +70,15 @@ signed_url = gateway.sign_url(url, url_quoting=True)
 ##### Valid URL
 ```
 # Termination Endlink
-end_url = "https://respondent.fake.rex.dynata.com/end?ctx=XXXX&transaction_id=123456disposition=2&status=1&access_key=rex_access_key&expiration=2021-11-24T16:50:53.899Z&signature=15da726b7802bda810c059ee1604f8fd1237a0618c29185c6b16f09e14242278"
+end_url = "https://respondent.fake.rex.dynata.com/end?ctx=XXXX&transaction_id=123456&disposition=2&status=1&access_key=rex_access_key&expiration=2021-11-24T19:23:23.439Z&signature=d351ff102b3ae6252d47fd54b859ecaf38c2701f214c233848bbdf64c0bc7fe1"
 
 gateway.verify_url(end_url)
 
 # True
 ```
 ##### Missing Signature
 ```
-missing_signature = "https://respondent.fake.rex.dynata.com/end?ctx=XXXX&transaction_id=123456disposition=2&status=1&access_key=rex_access_key&expiration=2021-11-24T16:50:53.899Z"
+missing_signature = "https://respondent.fake.rex.dynata.com/end?ctx=XXXX&transaction_id=123456&disposition=2&status=1&access_key=rex_access_key&expiration=2021-11-24T19:23:23.439Z"
 
 gateway.verify_url(missing_signature)
 
@@ -88,10 +88,42 @@ gateway.verify_url(missing_signature)
 ```
 # Disposition changed to 1 (from 2) and status to 0 (from 1)
 
-altered_parameters = "https://respondent.fake.rex.dynata.com/end?ctx=XXXX&transaction_id=123456disposition=1&status=0&access_key=rex_access_key&expiration=2021-11-24T16:50:53.899Z&signature=15da726b7802bda810c059ee1604f8fd1237a0618c29185c6b16f09e14242278"
+altered_parameters = "https://respondent.fake.rex.dynata.com/end?ctx=XXXX&transaction_id=123456&disposition=1&status=0&access_key=rex_access_key&expiration=2021-11-24T19:23:23.439Z&signature=d351ff102b3ae6252d47fd54b859ecaf38c2701f214c233848bbdf64c0bc7fe1"
 
 gateway.verify_url(altered_parameters)
 
 # False
 ```
+##### Get Disposition of a Survey from Endlink
+```
+termination = "https://respondent.fake.rex.dynata.com/end?ctx=XXXX&transaction_id=123456&disposition=2&status=1&access_key=rex_access_key&expiration=2021-11-24T19:23:23.439Z&signature=d351ff102b3ae6252d47fd54b859ecaf38c2701f214c233848bbdf64c0bc7fe1"
+
+disposition = gateway.get_respondent_disposition(termination)
+
+# <GatewayDispositionsEnum.TERMINATION: 2>
+
+disposition.name
+
+# 'TERMINATION'
+
+disposition.value
+
+# 2
+```
+
+##### Get Disposition + Status of a Survey from Endlink
+```
+termination = "https://respondent.fake.rex.dynata.com/end?ctx=XXXX&transaction_id=123456&disposition=2&status=1&access_key=rex_access_key&expiration=2021-11-24T19:23:23.439Z&signature=d351ff102b3ae6252d47fd54b859ecaf38c2701f214c233848bbdf64c0bc7fe1"
+
+status = gateway.get_respondent_status(termination)
+
+#<GatewayStatusEnum.TERMINATION_DYNATA: (<GatewayDispositionsEnum.TERMINATION: 2>, 1)>
+
+status.name
+
+# 'TERMINATION_DYNATA'
+
+status.value
 
+# (<GatewayDispositionsEnum.TERMINATION: 2>, 1)
+```

dynata_rex/models/__init__.py

@@ -22,6 +22,12 @@
     Opportunity
 )
 
+from .respondent_gateway import (
+    GatewayGenderEnum,
+    GatewayDispositionsEnum,
+    GatewayStatusEnum
+)
+
 
 __all__ = [
     'HashableModel',
@@ -40,5 +46,8 @@
     'Links',
     'Quota',
     'Filter',
-    'Opportunity'
+    'Opportunity',
+    'GatewayGenderEnum',
+    'GatewayDispositionsEnum',
+    'GatewayStatusEnum'
 ]

dynata_rex/models/respondent_gateway.py

@@ -0,0 +1,49 @@
+"""
+Package: dynata-rex.models
+Filename: respondent_gateway.py
+Author(s): Grant W
+
+Description: Implementation of dataclasses for Respondent Gateway
+"""
+# Python Imports
+from enum import Enum
+
+
+class GatewayGenderEnum(Enum):
+    MALE = 1
+    FEMALE = 2
+
+
+class GatewayDispositionsEnum(Enum):
+    UNKNOWN = 0
+    COMPLETE = 1
+    TERMINATION = 2
+    OVERQUOTA = 3
+    DUPLICATE = 4
+    QUALITY = 5
+
+
+class GatewayStatusEnum(Enum):
+    """
+    Composite status code from Disposition + non-unique status code
+    Must call as tuple of Gateway Disposition + Status code
+    ie
+    >>> disp_code, status_code = 1, 0
+    >>> disp = GatewayDispositionsEnum(disp_code)
+    >>> status = RespondentGatewayStatusEnum((disp, status_code))
+    >>> status.name
+    'COMPLETE_DEFAULT`
+    >>> status.value
+    (<GatewayDispositionsEnum.COMPLETE: 1>, 0)
+    """
+    UNKNOWN_DEFAULT = GatewayDispositionsEnum.UNKNOWN, 0
+    COMPLETE_DEFAULT = GatewayDispositionsEnum.COMPLETE, 0
+    COMPLETE_PARTIAL = GatewayDispositionsEnum.COMPLETE, 1
+    TERMINATION_DYNATA = GatewayDispositionsEnum.TERMINATION, 1
+    TERMINATION_CLIENT = GatewayDispositionsEnum.TERMINATION, 2
+    OVERQUOTA_DYNATA = GatewayDispositionsEnum.OVERQUOTA, 1
+    OVERQUOTA_CLIENT = GatewayDispositionsEnum.OVERQUOTA, 2
+    DUPLICATE_DEFAULT = GatewayDispositionsEnum.DUPLICATE, 0
+    QUALITY_ANSWER = GatewayDispositionsEnum.QUALITY, 1
+    QUALITY_SPEEDING = GatewayDispositionsEnum.QUALITY, 2
+    QUALITY_SUSPENDED = GatewayDispositionsEnum.QUALITY, 3

dynata_rex/respondent_gateway.py

@@ -13,6 +13,7 @@
 # Third Party Imports
 
 # Local Imports
+from dynata_rex.models import GatewayDispositionsEnum, GatewayStatusEnum
 from .signer import Signer
 from .exceptions import SignatureExpiredException, SignatureInvalidException
 
@@ -113,3 +114,32 @@ def verify_url(self,
                 SignatureExpiredException,
                 SignatureInvalidException):
             return False
+
+    def get_respondent_disposition(
+            self, url) -> Union[GatewayDispositionsEnum, None]:
+        """
+        Get the disposition of a respondent from a URL
+        """
+        parsed = urlparse(url)
+        query_parameters = dict(parse_qsl(parsed.query))
+        try:
+            disposition = int(query_parameters['disposition'])
+            return GatewayDispositionsEnum(disposition)
+        except KeyError:
+            return None
+
+    def get_respondent_status(
+            self, url) -> Union[GatewayStatusEnum, None]:
+        """
+        Get the status of a respondent from a URL
+        """
+        parsed = urlparse(url)
+        query_parameters = dict(parse_qsl(parsed.query))
+        disposition = self.get_respondent_disposition(url)
+        if not disposition:
+            return None
+        try:
+            status = int(query_parameters['status'])
+            return GatewayStatusEnum((disposition, status))
+        except KeyError:
+            return None