Fix the type annotation for DEFINE_xxx functions where the intention for the first `@overload` is to only match when `required=` is passed True.

Previously, omitting `required=` (all most all the calls) matches it, resulting in `_FLAG.value` being non-optional when `default=None`.

PiperOrigin-RevId: 354557367
Change-Id: I05e8b705ed0b02189f6d5e09bef4095b87499cad

2 files changed, 64 insertions, 33 deletions

diff --git a/absl/flags/_defines.py b/absl/flags/_defines.py
index 10abb76..f655714 100644
--- a/absl/flags/_defines.py
+++ b/absl/flags/_defines.py
@@ -94,7 +94,8 @@ def DEFINE(  # pylint: disable=invalid-name
     serializer: ArgumentSerializer, the flag serializer instance.
     module_name: str, the name of the Python module declaring this flag. If not
       provided, it will be computed using the stack trace of this call.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
     **args: dict, the extra keyword args that are passed to Flag __init__.
 
   Returns:
@@ -125,7 +126,8 @@ def DEFINE_flag(  # pylint: disable=invalid-name
       registered. This should almost never need to be overridden.
     module_name: str, the name of the Python module declaring this flag. If not
       provided, it will be computed using the stack trace of this call.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
 
   Returns:
     a handle to defined flag.
@@ -318,7 +320,8 @@ def DEFINE_boolean(  # pylint: disable=invalid-name,redefined-builtin
       registered. This should almost never need to be overridden.
     module_name: str, the name of the Python module declaring this flag. If not
       provided, it will be computed using the stack trace of this call.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
     **args: dict, the extra keyword args that are passed to Flag __init__.
 
   Returns:
@@ -351,7 +354,8 @@ def DEFINE_float(  # pylint: disable=invalid-name,redefined-builtin
     upper_bound: float, max value of the flag.
     flag_values: FlagValues, the FlagValues instance with which the flag will be
       registered. This should almost never need to be overridden.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
     **args: dict, the extra keyword args that are passed to DEFINE.
 
   Returns:
@@ -394,7 +398,8 @@ def DEFINE_integer(  # pylint: disable=invalid-name,redefined-builtin
     upper_bound: int, max value of the flag.
     flag_values: FlagValues, the FlagValues instance with which the flag will be
       registered. This should almost never need to be overridden.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
     **args: dict, the extra keyword args that are passed to DEFINE.
 
   Returns:
@@ -439,7 +444,8 @@ def DEFINE_enum(  # pylint: disable=invalid-name,redefined-builtin
       registered. This should almost never need to be overridden.
     module_name: str, the name of the Python module declaring this flag. If not
       provided, it will be computed using the stack trace of this call.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
     **args: dict, the extra keyword args that are passed to Flag __init__.
 
   Returns:
@@ -473,7 +479,8 @@ def DEFINE_enum_class(  # pylint: disable=invalid-name,redefined-builtin
       provided, it will be computed using the stack trace of this call.
     case_sensitive: bool, whether to map strings to members of the enum_class
       without considering case.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
     **args: dict, the extra keyword args that are passed to Flag __init__.
 
   Returns:
@@ -506,7 +513,8 @@ def DEFINE_list(  # pylint: disable=invalid-name,redefined-builtin
     help: str, the help message.
     flag_values: FlagValues, the FlagValues instance with which the flag will be
       registered. This should almost never need to be overridden.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
     **args: Dictionary with extra keyword args that are passed to the Flag
       __init__.
 
@@ -547,7 +555,8 @@ def DEFINE_spaceseplist(  # pylint: disable=invalid-name,redefined-builtin
       backwards compatibility with flags that used to be comma-separated.
     flag_values: FlagValues, the FlagValues instance with which the flag will be
       registered. This should almost never need to be overridden.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
     **args: Dictionary with extra keyword args that are passed to the Flag
       __init__.
 
@@ -600,7 +609,8 @@ def DEFINE_multi(  # pylint: disable=invalid-name,redefined-builtin
       registered. This should almost never need to be overridden.
     module_name: A string, the name of the Python module declaring this flag. If
       not provided, it will be computed using the stack trace of this call.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
     **args: Dictionary with extra keyword args that are passed to the Flag
       __init__.
 
@@ -634,7 +644,8 @@ def DEFINE_multi_string(  # pylint: disable=invalid-name,redefined-builtin
     help: str, the help message.
     flag_values: FlagValues, the FlagValues instance with which the flag will be
       registered. This should almost never need to be overridden.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
     **args: Dictionary with extra keyword args that are passed to the Flag
       __init__.
 
@@ -679,7 +690,8 @@ def DEFINE_multi_integer(  # pylint: disable=invalid-name,redefined-builtin
     upper_bound: int, max values of the flag.
     flag_values: FlagValues, the FlagValues instance with which the flag will be
       registered. This should almost never need to be overridden.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
     **args: Dictionary with extra keyword args that are passed to the Flag
       __init__.
 
@@ -724,7 +736,8 @@ def DEFINE_multi_float(  # pylint: disable=invalid-name,redefined-builtin
     upper_bound: float, max values of the flag.
     flag_values: FlagValues, the FlagValues instance with which the flag will be
       registered. This should almost never need to be overridden.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
     **args: Dictionary with extra keyword args that are passed to the Flag
       __init__.
 
@@ -770,7 +783,8 @@ def DEFINE_multi_enum(  # pylint: disable=invalid-name,redefined-builtin
     flag_values: FlagValues, the FlagValues instance with which the flag will be
       registered. This should almost never need to be overridden.
     case_sensitive: Whether or not the enum is to be case-sensitive.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
     **args: Dictionary with extra keyword args that are passed to the Flag
       __init__.
 
@@ -820,7 +834,8 @@ def DEFINE_multi_enum_class(  # pylint: disable=invalid-name,redefined-builtin
       not provided, it will be computed using the stack trace of this call.
     case_sensitive: bool, whether to map strings to members of the enum_class
       without considering case.
-    required: bool, is this a required flag.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
     **args: Dictionary with extra keyword args that are passed to the Flag
       __init__.
 
diff --git a/absl/flags/_defines.pyi b/absl/flags/_defines.pyi
index c0dbb30..1f482a2 100644
--- a/absl/flags/_defines.pyi
+++ b/absl/flags/_defines.pyi
@@ -81,11 +81,13 @@ def DEFINE_flag(
 #   guaranteed to be not None after flag parsing has finished.
 # The information above is captured with three overloads as follows.
 #
-# (if required=True, return type is FlagHolder[Y])
+# (if required=True and passed in as a keyword argument,
+#  return type is FlagHolder[Y])
 # @overload
 # def DEFINE_xxx(
 #    ... arguments...
-#    default : Union[None, X],
+#    default: Union[None, X] = ...,
+#    *,
 #    required: Literal[True]) -> _flagvalues.FlagHolder[Y]:
 #   ...
 #
@@ -93,11 +95,11 @@ def DEFINE_flag(
 # @overload
 # def DEFINE_xxx(
 #    ... arguments...
-#    default : None,
+#    default: None,
 #    required: bool = ...) -> _flagvalues.FlagHolder[Optional[Y]]:
 #   ...
 #
-# (if default!=None, return type is FlagHolder[Y])#
+# (if default!=None, return type is FlagHolder[Y]):
 # @overload
 # def DEFINE_xxx(
 #    ... arguments...
@@ -114,7 +116,8 @@ def DEFINE_string(
     default: Optional[Text],
     help: Optional[Text],
     flag_values: _flagvalues.FlagValues = ...,
-    required: Literal[True] = ...,
+    *,
+    required: Literal[True],
     **args: Any) -> _flagvalues.FlagHolder[Text]:
   ...
 
@@ -145,7 +148,8 @@ def DEFINE_boolean(
     help: Optional[Text],
     flag_values: _flagvalues.FlagValues = ...,
     module_name: Optional[Text] = ...,
-    required: Literal[True] = ...,
+    *,
+    required: Literal[True],
     **args: Any) -> _flagvalues.FlagHolder[bool]:
   ...
 
@@ -179,7 +183,8 @@ def DEFINE_float(
     lower_bound: Optional[float] = ...,
     upper_bound: Optional[float] = ...,
     flag_values: _flagvalues.FlagValues = ...,
-    required: Literal[True] = ...,
+    *,
+    required: Literal[True],
     **args: Any) -> _flagvalues.FlagHolder[float]:
   ...
 
@@ -216,7 +221,8 @@ def DEFINE_integer(
     lower_bound: Optional[int] = ...,
     upper_bound: Optional[int] = ...,
     flag_values: _flagvalues.FlagValues = ...,
-    required: Literal[True] = ...,
+    *,
+    required: Literal[True],
     **args: Any) -> _flagvalues.FlagHolder[int]:
   ...
 
@@ -252,7 +258,8 @@ def DEFINE_enum(
     help: Optional[Text],
     flag_values: _flagvalues.FlagValues = ...,
     module_name:  Optional[Text] = ...,
-    required: Literal[True] = ...,
+    *,
+    required: Literal[True],
     **args: Any) -> _flagvalues.FlagHolder[Text]:
   ...
 
@@ -289,7 +296,8 @@ def DEFINE_enum_class(
     flag_values: _flagvalues.FlagValues = ...,
     module_name: Optional[Text] = ...,
     case_sensitive: bool = ...,
-    required: Literal[True] = ...,
+    *,
+    required: Literal[True],
     **args: Any) -> _flagvalues.FlagHolder[_ET]:
   ...
 
@@ -326,7 +334,8 @@ def DEFINE_list(
     default: Union[None, Iterable[Text], Text],
     help: Text,
     flag_values: _flagvalues.FlagValues  = ...,
-    required: Literal[True] = ...,
+    *,
+    required: Literal[True],
     **args: Any) -> _flagvalues.FlagHolder[List[Text]]:
   ...
 
@@ -357,7 +366,8 @@ def DEFINE_spaceseplist(
     help: Text,
     comma_compat: bool = ...,
     flag_values: _flagvalues.FlagValues = ...,
-    required: Literal[True] = ...,
+    *,
+    required: Literal[True],
     **args: Any) -> _flagvalues.FlagHolder[List[Text]]:
   ...
 
@@ -392,7 +402,8 @@ def DEFINE_multi(
     help: Text,
     flag_values:_flagvalues.FlagValues = ...,
     module_name: Optional[Text] = ...,
-    required: Literal[True] = ...,
+    *,
+    required: Literal[True],
     **args: Any) -> _flagvalues.FlagHolder[List[_T]]:
   ...
 
@@ -428,7 +439,8 @@ def DEFINE_multi_string(
     default: Union[None, Iterable[Text], Text],
     help: Text,
     flag_values: _flagvalues.FlagValues = ...,
-    required: Literal[True] = ...,
+    *,
+    required: Literal[True],
     **args: Any) -> _flagvalues.FlagHolder[List[Text]]:
   ...
 
@@ -460,7 +472,8 @@ def DEFINE_multi_integer(
     lower_bound: Optional[int] = ...,
     upper_bound: Optional[int] = ...,
     flag_values: _flagvalues.FlagValues = ...,
-    required: Literal[True] = ...,
+    *,
+    required: Literal[True],
     **args: Any) -> _flagvalues.FlagHolder[List[int]]:
   ...
 
@@ -496,7 +509,8 @@ def DEFINE_multi_float(
     lower_bound: Optional[float] = ...,
     upper_bound: Optional[float] = ...,
     flag_values: _flagvalues.FlagValues = ...,
-    required: Literal[True] = ...,
+    *,
+    required: Literal[True],
     **args: Any) -> _flagvalues.FlagHolder[List[float]]:
   ...
 
@@ -532,7 +546,8 @@ def DEFINE_multi_enum(
     enum_values: Iterable[Text],
     help: Text,
     flag_values: _flagvalues.FlagValues = ...,
-    required: Literal[True] = ...,
+    *,
+    required: Literal[True],
     **args: Any) -> _flagvalues.FlagHolder[List[Text]]:
   ...
 
@@ -566,7 +581,8 @@ def DEFINE_multi_enum_class(
     help: Text,
     flag_values: _flagvalues.FlagValues = ...,
     module_name: Optional[Text] = ...,
-    required: Literal[True] = ...,
+    *,
+    required: Literal[True],
     **args: Any) -> _flagvalues.FlagHolder[List[_ET]]:
   ...