Add type annotations for ArgumentParser and Flag.

This should make pytype infer the right type for all DEFINE_* and the base DEFINE() methods.

PiperOrigin-RevId: 311573548
Change-Id: I768db3cc43255a89689b2139ab4c5df045787e61

1 files changed, 18 insertions, 0 deletions

diff --git a/absl/flags/_argument_parser.py b/absl/flags/_argument_parser.py
index 20b61ed..a1f0daf 100644
--- a/absl/flags/_argument_parser.py
+++ b/absl/flags/_argument_parser.py
@@ -76,6 +76,24 @@ class _ArgumentParserCache(type):
         return type.__call__(cls, *args)
 
 
+# NOTE about Genericity and Metaclass of ArgumentParser.
+# (1) In the .py source (this file)
+#     - is not declared as Generic
+#     - has _ArgumentParserCache as a metaclass
+# (2) In the .pyi source (type stub)
+#     - is declared as Generic
+#     - doesn't have a metaclass
+# The reason we need this is due to Generic having a different metaclass
+# (for python versions <= 3.7) and a class can have only one metaclass.
+#
+# * Lack of metaclass in .pyi is not a deal breaker, since the metaclass
+#   doesn't affect any type information. Also type checkers can check the type
+#   parameters.
+# * However, not declaring ArgumentParser as Generic in the source affects
+#   runtime annotation processing. In particular this means, subclasses should
+#   inherit from `ArgumentParser` and not `ArgumentParser[SomeType]`.
+#   The corresponding DEFINE_someType method (the public API) can be annotated
+#   to return FlagHolder[SomeType].
 class ArgumentParser(six.with_metaclass(_ArgumentParserCache, object)):
   """Base class used to parse and convert arguments.