Add .pyi type annotations to absl/app.py.

Also document that `flags_parser` in `app.run` should be passed as keyword-only. This will become mandatory in a future release.

PiperOrigin-RevId: 366074388
Change-Id: I15dfe0c8bcaaa227a2a06141ef01c46cceb2c3b7

3 files changed, 111 insertions, 3 deletions

diff --git a/absl/CHANGELOG.md b/absl/CHANGELOG.md
index b35c612..7a1de2f 100644
--- a/absl/CHANGELOG.md
+++ b/absl/CHANGELOG.md
@@ -6,7 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com).
 
 ## Unreleased
 
-Nothing notable unreleased.
+### Added
+
+*   (app) Type annotations for public `app` interfaces.
+
+### Changed
+
+*   (app) Annotated the `flag_parser` paramteter of `run` as keyword-only. This
+    keyword-only constraint will be enforced at runtime in a future release.
 
 ## 0.12.0 (2021-03-08)
 
@@ -62,8 +69,8 @@ Nothing notable unreleased.
 
 *   (testing) Failed tests output a copy/pastable test id to make it easier to
     copy the failing test to the command line.
-*   (testing) `@parameterized.parameters` now treats a single `abc.Mapping` as
-    a single test case, consistent with `named_parameters`. Previously the
+*   (testing) `@parameterized.parameters` now treats a single `abc.Mapping` as a
+    single test case, consistent with `named_parameters`. Previously the
     `abc.Mapping` is treated as if only its keys are passed as a list of test
     cases. If you were relying on the old inconsistent behavior, explicitly
     convert the `abc.Mapping` to a `list`.
diff --git a/absl/app.py b/absl/app.py
index 6b5e91d..a6e9216 100644
--- a/absl/app.py
+++ b/absl/app.py
@@ -286,6 +286,8 @@ def run(
     flags_parser: Callable[[List[Text]], Any], the function used to parse flags.
         The return value of this function is passed to `main` untouched.
         It must guarantee FLAGS is parsed after this function is called.
+        Should be passed as a keyword-only arg which will become mandatory in a
+        future release.
   - Parses command line flags with the flag module.
   - If there are any errors, prints usage().
   - Calls main() with the remaining arguments.
diff --git a/absl/app.pyi b/absl/app.pyi
new file mode 100644
index 0000000..fe5e448
--- /dev/null
+++ b/absl/app.pyi
@@ -0,0 +1,99 @@
+
+from typing import Any, Callable, Collection, Iterable, List, NoReturn, Optional, Text, TypeVar, Union, overload
+
+from absl.flags import _flag
+
+
+_MainArgs = TypeVar('_MainArgs')
+_Exc = TypeVar('_Exc', bound=Exception)
+
+
+class ExceptionHandler():
+
+  def wants(self, exc: _Exc) -> bool:
+    ...
+
+  def handle(self, exc: _Exc):
+    ...
+
+
+EXCEPTION_HANDLERS: List[ExceptionHandler] = ...
+
+
+class HelpFlag(_flag.BooleanFlag):
+  def __init__(self):
+    ...
+
+
+class HelpshortFlag(HelpFlag):
+  ...
+
+
+class HelpfullFlag(_flag.BooleanFlag):
+  def __init__(self):
+    ...
+
+
+class HelpXMLFlag(_flag.BooleanFlag):
+  def __init__(self):
+    ...
+
+
+def define_help_flags() -> None:
+  ...
+
+
+@overload
+def usage(shorthelp: Union[bool, int] = ...,
+          writeto_stdout: Union[bool, int] = ...,
+          detailed_error: Optional[Any] = ...,
+          exitcode: None = ...) -> None:
+  ...
+
+
+@overload
+def usage(shorthelp: Union[bool, int] = ...,
+          writeto_stdout: Union[bool, int] = ...,
+          detailed_error: Optional[Any] = ...,
+          exitcode: int = ...) -> NoReturn:
+  ...
+
+
+def install_exception_handler(handler: ExceptionHandler) -> None:
+  ...
+
+
+class Error(Exception):
+  ...
+
+
+class UsageError(Error):
+  exitcode: int
+
+
+def parse_flags_with_usage(args: List[Text]) -> List[Text]:
+  ...
+
+
+def call_after_init(callback: Callable[[], Any]) -> None:
+  ...
+
+
+# Without the flag_parser argument, `main` should require a List[Text].
+@overload
+def run(
+    main: Callable[[List[Text]], Any],
+    argv: Optional[List[Text]] = ...,
+    *,
+) -> NoReturn:
+  ...
+
+
+@overload
+def run(
+    main: Callable[[_MainArgs], Any],
+    argv: Optional[List[Text]] = ...,
+    *,
+    flags_parser: Callable[[List[Text]], _MainArgs],
+) -> NoReturn:
+  ...