refactor: type hints private interface (#389)

* add type hints

* add null checks/disambiguation for typing

* enable mypy strict check

* bucket returns None instead of empty dict

Author: andrewleap-optimizely

.github/workflows/python.yml

@@ -46,7 +46,7 @@ jobs:
         flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
 
   integration_tests:
-    uses: optimizely/python-sdk/.github/workflows/integration_test.yml@uzair/test-with-fsc
+    uses: optimizely/python-sdk/.github/workflows/integration_test.yml@master
     secrets:
       CI_USER_TOKEN: ${{ secrets.CI_USER_TOKEN }}
       TRAVIS_COM_TOKEN: ${{ secrets.TRAVIS_COM_TOKEN }}
@@ -98,5 +98,4 @@ jobs:
     - name: Type check with mypy
       run: |
         mypy .
-      # disabled until entire sdk is type hinted
-        # mypy . --exclude "tests/" --strict
+        mypy . --exclude "tests/" --strict

mypy.ini

@@ -11,13 +11,5 @@ show_error_codes = True
 pretty = True
 
 # suppress error on conditional import of typing_extensions module
-[mypy-optimizely.entities]
-no_warn_unused_ignores = True
-
-# suppress error on conditional import of typing_extensions module
-[mypy-event_dispatcher]
-no_warn_unused_ignores = True
-
-# suppress error on conditional import of typing_extensions module
-[mypy-optimizely.condition]
+[mypy-optimizely.helpers.types]
 no_warn_unused_ignores = True

optimizely/bucketer.py

@@ -1,4 +1,4 @@
-# Copyright 2016-2017, 2019-2021 Optimizely
+# Copyright 2016-2017, 2019-2022 Optimizely
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -11,28 +11,44 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+from typing import Optional, TYPE_CHECKING
 import math
+from sys import version_info
 
 from .lib import pymmh3 as mmh3
 
 
-MAX_TRAFFIC_VALUE = 10000
-UNSIGNED_MAX_32_BIT_VALUE = 0xFFFFFFFF
-MAX_HASH_VALUE = math.pow(2, 32)
-HASH_SEED = 1
-BUCKETING_ID_TEMPLATE = '{bucketing_id}{parent_id}'
-GROUP_POLICIES = ['random']
+if version_info < (3, 8):
+    from typing_extensions import Final
+else:
+    from typing import Final  # type: ignore
+
+
+if TYPE_CHECKING:
+    # prevent circular dependenacy by skipping import at runtime
+    from .project_config import ProjectConfig
+    from .entities import Experiment, Variation
+    from .helpers.types import TrafficAllocation
+
+
+MAX_TRAFFIC_VALUE: Final = 10000
+UNSIGNED_MAX_32_BIT_VALUE: Final = 0xFFFFFFFF
+MAX_HASH_VALUE: Final = math.pow(2, 32)
+HASH_SEED: Final = 1
+BUCKETING_ID_TEMPLATE: Final = '{bucketing_id}{parent_id}'
+GROUP_POLICIES: Final = ['random']
 
 
 class Bucketer:
     """ Optimizely bucketing algorithm that evenly distributes visitors. """
 
-    def __init__(self):
+    def __init__(self) -> None:
         """ Bucketer init method to set bucketing seed and logger instance. """
 
         self.bucket_seed = HASH_SEED
 
-    def _generate_unsigned_hash_code_32_bit(self, bucketing_id):
+    def _generate_unsigned_hash_code_32_bit(self, bucketing_id: str) -> int:
         """ Helper method to retrieve hash code.
 
         Args:
@@ -45,7 +61,7 @@ def _generate_unsigned_hash_code_32_bit(self, bucketing_id):
         # Adjusting MurmurHash code to be unsigned
         return mmh3.hash(bucketing_id, self.bucket_seed) & UNSIGNED_MAX_32_BIT_VALUE
 
-    def _generate_bucket_value(self, bucketing_id):
+    def _generate_bucket_value(self, bucketing_id: str) -> int:
         """ Helper function to generate bucket value in half-closed interval [0, MAX_TRAFFIC_VALUE).
 
         Args:
@@ -58,7 +74,10 @@ def _generate_bucket_value(self, bucketing_id):
         ratio = float(self._generate_unsigned_hash_code_32_bit(bucketing_id)) / MAX_HASH_VALUE
         return math.floor(ratio * MAX_TRAFFIC_VALUE)
 
-    def find_bucket(self, project_config, bucketing_id, parent_id, traffic_allocations):
+    def find_bucket(
+        self, project_config: ProjectConfig, bucketing_id: str,
+        parent_id: Optional[str], traffic_allocations: list[TrafficAllocation]
+    ) -> Optional[str]:
         """ Determine entity based on bucket value and traffic allocations.
 
         Args:
@@ -78,12 +97,15 @@ def find_bucket(self, project_config, bucketing_id, parent_id, traffic_allocatio
 
         for traffic_allocation in traffic_allocations:
             current_end_of_range = traffic_allocation.get('endOfRange')
-            if bucketing_number < current_end_of_range:
+            if current_end_of_range is not None and bucketing_number < current_end_of_range:
                 return traffic_allocation.get('entityId')
 
         return None
 
-    def bucket(self, project_config, experiment, user_id, bucketing_id):
+    def bucket(
+        self, project_config: ProjectConfig,
+        experiment: Experiment, user_id: str, bucketing_id: str
+    ) -> tuple[Optional[Variation], list[str]]:
         """ For a given experiment and bucketing ID determines variation to be shown to user.
 
         Args:
@@ -97,7 +119,7 @@ def bucket(self, project_config, experiment, user_id, bucketing_id):
             and array of log messages representing decision making.
      */.
         """
-        decide_reasons = []
+        decide_reasons: list[str] = []
         if not experiment:
             return None, decide_reasons