docs: explain flag type validation and fallback behavior

Document the boolean/integer distinction, async type-mismatch fallback, and the regression cases. Keep the evaluation logic and test assertions unchanged.

Signed-off-by: Hexecu <vaingloryhex@gmail.com>

Author: Hexecu

openfeature/client.py

@@ -861,6 +861,19 @@ async def _create_provider_evaluation_async(
         default_value: FlagValueType,
         evaluation_context: EvaluationContext | None = None,
     ) -> FlagEvaluationDetails[FlagValueType]:
+        """
+        Resolve a flag asynchronously and validate the returned value.
+
+        Provider-reported errors are returned unchanged. A type mismatch detected
+        by the client returns the caller's default with TYPE_MISMATCH error details.
+
+        :param provider: the provider selected for this evaluation
+        :param flag_type: the requested flag type
+        :param flag_key: the key of the selected flag
+        :param default_value: fallback used for an unknown type or a type mismatch
+        :param evaluation_context: context passed to the provider
+        :return: evaluation details containing the resolved value or fallback
+        """
         get_details_callables_async: Mapping[FlagType, ResolveDetailsCallableAsync] = {
             FlagType.BOOLEAN: provider.resolve_boolean_details_async,
             FlagType.INTEGER: provider.resolve_integer_details_async,
@@ -991,6 +1004,17 @@ def track(
 def _typecheck_flag_value(
     value: typing.Any, flag_type: FlagType
 ) -> OpenFeatureError | None:
+    """
+    Check a resolved value against the requested flag type without coercing it.
+
+    Booleans are not integer flag values, even though bool subclasses int in
+    Python. Other subclasses of the expected type remain valid.
+
+    :param value: the value returned by the provider
+    :param flag_type: the requested flag type
+    :return: None for a matching value, TypeMismatchError for an incompatible
+        value, or GeneralError for an unknown flag type
+    """
     type_map: TypeMap = {
         FlagType.BOOLEAN: bool,
         FlagType.STRING: str,
@@ -1001,7 +1025,6 @@ def _typecheck_flag_value(
     py_type = type_map.get(flag_type)
     if not py_type:
         return GeneralError(error_message="Unknown flag type")
-    # bool is an int subclass in Python, but not an integer flag value.
     if not isinstance(value, py_type) or (
         flag_type == FlagType.INTEGER and isinstance(value, bool)
     ):

tests/test_client.py

@@ -424,6 +424,7 @@ async def test_client_type_mismatch_exceptions():
 
 @pytest.mark.asyncio
 async def test_typecheck_flag_value_general_error():
+    """Unknown flag types produce GENERAL rather than TYPE_MISMATCH."""
     # Given
     flag_value = "A"
     flag_type = None
@@ -453,6 +454,7 @@ async def test_typecheck_flag_value_general_error():
 async def test_client_returns_default_on_type_mismatch(
     flag_type, flag_value, default_value, is_async
 ):
+    """Both APIs return typed defaults and pass the fallback to finally hooks."""
     provider = InMemoryProvider(
         {"flag": InMemoryFlag("enabled", {"enabled": flag_value})}
     )
@@ -518,6 +520,7 @@ async def test_client_returns_default_on_type_mismatch(
 async def test_client_preserves_matching_flag_types(
     flag_type, flag_value, default_value, is_async
 ):
+    """Matching values keep their type and successful evaluation details."""
     provider = InMemoryProvider(
         {"flag": InMemoryFlag("enabled", {"enabled": flag_value})}
     )
@@ -545,14 +548,19 @@ async def test_client_preserves_matching_flag_types(
 
 
 def test_typecheck_flag_value_accepts_integer_subclasses():
+    """Rejecting booleans must not reject other integer subclasses."""
+
     class IntegerValue(int):
+        """An integer subtype with the same value semantics as int."""
+
         pass
 
     assert _typecheck_flag_value(IntegerValue(1), FlagType.INTEGER) is None
 
 
 @pytest.mark.asyncio
 async def test_typecheck_flag_value_type_mismatch_error():
+    """An incompatible value reports both the expected and actual types."""
     # Given
     flag_value = "A"
     flag_type = FlagType.BOOLEAN