feat: trait typing

examples/myapp.py

@@ -96,6 +96,7 @@ def start(self):
         print("app.config:")
         print(self.config)
         print("try running with --help-all to see all available flags")
+        assert self.log is not None
         self.log.debug("Debug Message")
         self.log.info("Info Message")
         self.log.warning("Warning Message")

pyproject.toml

@@ -22,7 +22,7 @@ requires-python = ">=3.7"
 dynamic = ["version"]
 
 [project.optional-dependencies]
-test = ["pytest", "pytest-mock", "pre-commit", "argcomplete>=2.0"]
+test = ["pytest>=7.0,<7.2", "pytest-mock", "pre-commit", "argcomplete>=2.0", "pytest-mypy-testing"]
 docs = [
     "myst-parser",
     "pydata-sphinx-theme",

traitlets/config/application.py

@@ -17,7 +17,7 @@
 from copy import deepcopy
 from logging.config import dictConfig
 from textwrap import dedent
-from typing import Any, Callable, TypeVar, cast
+from typing import Callable, TypeVar, cast
 
 from traitlets.config.configurable import Configurable, SingletonConfigurable
 from traitlets.config.loader import (
@@ -29,6 +29,7 @@
     PyFileConfigLoader,
 )
 from traitlets.traitlets import (
+    Any,
     Bool,
     Dict,
     Enum,
@@ -151,6 +152,8 @@ class Application(SingletonConfigurable):
     # line application
     name: t.Union[str, Unicode] = Unicode("application")
 
+    log = Any(help="Logger or LoggerAdapter instance", allow_none=False)
+
     # The description of the application that is printed at the beginning
     # of the help.
     description: t.Union[str, Unicode] = Unicode("This is an application.")
@@ -201,19 +204,19 @@ def _classes_inc_parents(self, classes=None):
     )
 
     # The log level for the application
-    log_level: t.Union[str, int, Enum] = Enum(
+    log_level: t.Union[str, int, Enum] = Enum(  # type:ignore[assignment]
         (0, 10, 20, 30, 40, 50, "DEBUG", "INFO", "WARN", "ERROR", "CRITICAL"),
         default_value=logging.WARN,
         help="Set the log level by value or name.",
     ).tag(config=True)
 
     _log_formatter_cls = LevelFormatter
 
-    log_datefmt: t.Union[str, Unicode] = Unicode(
+    log_datefmt: t.Union[str, Unicode] = Unicode(  # type:ignore[assignment]
         "%Y-%m-%d %H:%M:%S", help="The date format used by logging formatters for %(asctime)s"
     ).tag(config=True)
 
-    log_format: t.Union[str, Unicode] = Unicode(
+    log_format: t.Union[str, Unicode] = Unicode(  # type:ignore[assignment]
         "[%(name)s]%(highlevel)s %(message)s",
         help="The Logging format template",
     ).tag(config=True)
@@ -237,7 +240,7 @@ def get_default_logging_config(self):
                 "console": {
                     "class": "logging.StreamHandler",
                     "formatter": "console",
-                    "level": logging.getLevelName(self.log_level),
+                    "level": logging.getLevelName(self.log_level),  # type:ignore[arg-type]
                     "stream": "ext://sys.stderr",
                 },
             },
@@ -402,7 +405,7 @@ def _log_default(self):
     # and the second being the help string for the subcommand
     subcommands: t.Union[t.Dict[str, t.Tuple[t.Any, str]], Dict] = Dict()
     # parse_command_line will initialize a subapp, if requested
-    subapp = Instance("traitlets.config.application.Application", allow_none=True)
+    subapp: Instance[t.Any] = Instance("traitlets.config.application.Application", allow_none=True)
 
     # extra command-line arguments that don't set config values
     extra_args: t.Union[t.List[str], List] = List(Unicode())
@@ -420,11 +423,11 @@ def _log_default(self):
 
     _loaded_config_files = List()
 
-    show_config: t.Union[bool, Bool] = Bool(
+    show_config: t.Union[bool, Bool] = Bool(  # type:ignore[assignment]
         help="Instead of starting the Application, dump configuration to stdout"
     ).tag(config=True)
 
-    show_config_json: t.Union[bool, Bool] = Bool(
+    show_config_json: t.Union[bool, Bool] = Bool(  # type:ignore[assignment]
         help="Instead of starting the Application, dump configuration to stdout (as JSON)"
     ).tag(config=True)
 
@@ -563,6 +566,7 @@ def emit_flag_help(self):
             return
 
         for flags, (cfg, fhelp) in self.flags.items():
+            assert isinstance(cfg, dict)
             try:
                 if not isinstance(flags, tuple):
                     flags = (flags,)

traitlets/config/configurable.py

@@ -5,6 +5,7 @@
 
 
 import logging
+import typing as t
 import warnings
 from copy import deepcopy
 from textwrap import dedent
@@ -44,8 +45,10 @@ class MultipleInstanceError(ConfigurableError):
 
 class Configurable(HasTraits):
 
-    config = Instance(Config, (), {})
-    parent = Instance("traitlets.config.configurable.Configurable", allow_none=True)
+    config: Instance[Config] = Instance(Config, (), {})
+    parent: Instance[t.Any] = Instance(
+        "traitlets.config.configurable.Configurable", allow_none=True
+    )
 
     def __init__(self, **kwargs):
         """Create a configurable given a config config.
@@ -183,6 +186,7 @@ def _load_config(self, cfg, section_names=None, traits=None):
                     from difflib import get_close_matches
 
                     if isinstance(self, LoggingConfigurable):
+                        assert self.log is not None
                         warn = self.log.warning
                     else:
                         warn = lambda msg: warnings.warn(msg, stacklevel=9)  # noqa[E371]
@@ -460,6 +464,7 @@ def _validate_log(self, proposal):
     @default("log")
     def _log_default(self):
         if isinstance(self.parent, LoggingConfigurable):
+            assert self.parent is not None
             return self.parent.log
         from traitlets import log
 

traitlets/config/loader.py

@@ -97,9 +97,9 @@ class LazyConfigValue(HasTraits):
     _value = None
 
     # list methods
-    _extend = List()
-    _prepend = List()
-    _inserts = List()
+    _extend: List = List()
+    _prepend: List = List()
+    _inserts: List = List()
 
     def append(self, obj):
         """Append an item to a List"""

traitlets/tests/test_typing.py

@@ -0,0 +1,120 @@
+from typing import Optional
+
+import pytest
+from typing_extensions import reveal_type
+
+from traitlets import Bool, CInt, HasTraits, Int, TCPAddress
+
+
+@pytest.mark.mypy_testing
+def mypy_bool_typing():
+    class T(HasTraits):
+        b = Bool(True).tag(sync=True)
+        ob = Bool(None, allow_none=True).tag(sync=True)
+
+    t = T()
+    reveal_type(
+        Bool(True)
+    )  # R: traitlets.traitlets.Bool[builtins.bool, Union[builtins.bool, builtins.int]]
+    reveal_type(
+        Bool(True).tag(sync=True)
+    )  # R: traitlets.traitlets.Bool[builtins.bool, Union[builtins.bool, builtins.int]]
+    reveal_type(
+        Bool(None, allow_none=True)
+    )  # R: traitlets.traitlets.Bool[Union[builtins.bool, None], Union[builtins.bool, builtins.int, None]]
+    reveal_type(
+        Bool(None, allow_none=True).tag(sync=True)
+    )  # R: traitlets.traitlets.Bool[Union[builtins.bool, None], Union[builtins.bool, builtins.int, None]]
+    reveal_type(
+        T.b
+    )  # R: traitlets.traitlets.Bool[builtins.bool, Union[builtins.bool, builtins.int]]
+    reveal_type(t.b)  # R: builtins.bool
+    reveal_type(t.ob)  # R: Union[builtins.bool, None]
+    reveal_type(
+        T.b
+    )  # R: traitlets.traitlets.Bool[builtins.bool, Union[builtins.bool, builtins.int]]
+    reveal_type(
+        T.ob
+    )  # R: traitlets.traitlets.Bool[Union[builtins.bool, None], Union[builtins.bool, builtins.int, None]]
+    # we would expect this to be Optional[Union[bool, int]], but...
+    t.b = "foo"  # E: Incompatible types in assignment (expression has type "str", variable has type "Union[bool, int]")  [assignment]
+    t.b = None  # E: Incompatible types in assignment (expression has type "None", variable has type "Union[bool, int]")  [assignment]
+
+
+@pytest.mark.mypy_testing
+def mypy_int_typing():
+    class T(HasTraits):
+        i: Int[int, int] = Int(42).tag(sync=True)
+        oi: Int[Optional[int], Optional[int]] = Int(42, allow_none=True).tag(sync=True)
+
+    t = T()
+    reveal_type(Int(True))  # R: traitlets.traitlets.Int[builtins.int, builtins.int]
+    reveal_type(Int(True).tag(sync=True))  # R: traitlets.traitlets.Int[builtins.int, builtins.int]
+    reveal_type(
+        Int(None, allow_none=True)
+    )  # R: traitlets.traitlets.Int[Union[builtins.int, None], Union[builtins.int, None]]
+    reveal_type(
+        Int(None, allow_none=True).tag(sync=True)
+    )  # R: traitlets.traitlets.Int[Union[builtins.int, None], Union[builtins.int, None]]
+    reveal_type(T.i)  # R: traitlets.traitlets.Int[builtins.int, builtins.int]
+    reveal_type(t.i)  # R: builtins.int
+    reveal_type(t.oi)  # R: Union[builtins.int, None]
+    reveal_type(T.i)  # R: traitlets.traitlets.Int[builtins.int, builtins.int]
+    reveal_type(
+        T.oi
+    )  # R: traitlets.traitlets.Int[Union[builtins.int, None], Union[builtins.int, None]]
+    t.i = "foo"  # E: Incompatible types in assignment (expression has type "str", variable has type "int")  [assignment]
+    t.i = None  # E: Incompatible types in assignment (expression has type "None", variable has type "int")  [assignment]
+    t.i = 1.2  # E: Incompatible types in assignment (expression has type "float", variable has type "int")  [assignment]
+
+
+@pytest.mark.mypy_testing
+def mypy_cint_typing():
+    class T(HasTraits):
+        i = CInt(42).tag(sync=True)
+        oi = CInt(42, allow_none=True).tag(sync=True)
+
+    t = T()
+    reveal_type(CInt(True))  # R: traitlets.traitlets.CInt[builtins.int, Union[builtins.int, Any]]
+    reveal_type(
+        CInt(True).tag(sync=True)
+    )  # R: traitlets.traitlets.CInt[builtins.int, Union[builtins.int, Any]]
+    reveal_type(
+        CInt(None, allow_none=True)
+    )  # R: traitlets.traitlets.CInt[Union[builtins.int, None], Union[builtins.int, Any, None]]
+    reveal_type(
+        CInt(None, allow_none=True).tag(sync=True)
+    )  # R: traitlets.traitlets.CInt[Union[builtins.int, None], Union[builtins.int, Any, None]]
+    reveal_type(T.i)  # R: traitlets.traitlets.CInt[builtins.int, Union[builtins.int, Any]]
+    reveal_type(t.i)  # R: builtins.int
+    reveal_type(t.oi)  # R: Union[builtins.int, None]
+    reveal_type(T.i)  # R: traitlets.traitlets.CInt[builtins.int, Union[builtins.int, Any]]
+    reveal_type(
+        T.oi
+    )  # R: traitlets.traitlets.CInt[Union[builtins.int, None], Union[builtins.int, Any, None]]
+
+
+@pytest.mark.mypy_testing
+def mypy_tcp_typing():
+    class T(HasTraits):
+        tcp = TCPAddress()
+        otcp = TCPAddress(None, allow_none=True)
+
+    t = T()
+    reveal_type(t.tcp)  # R: Tuple[builtins.str, builtins.int]
+    reveal_type(
+        T.tcp
+    )  # R: traitlets.traitlets.TCPAddress[Tuple[builtins.str, builtins.int], Tuple[builtins.str, builtins.int]]
+    reveal_type(
+        T.tcp.tag(sync=True)
+    )  # R:traitlets.traitlets.TCPAddress[Tuple[builtins.str, builtins.int], Tuple[builtins.str, builtins.int]]
+    reveal_type(t.otcp)  # R: Union[Tuple[builtins.str, builtins.int], None]
+    reveal_type(
+        T.otcp
+    )  # R: traitlets.traitlets.TCPAddress[Union[Tuple[builtins.str, builtins.int], None], Union[Tuple[builtins.str, builtins.int], None]]
+    reveal_type(
+        T.otcp.tag(sync=True)
+    )  # R: traitlets.traitlets.TCPAddress[Union[Tuple[builtins.str, builtins.int], None], Union[Tuple[builtins.str, builtins.int], None]]
+    t.tcp = "foo"  # E: Incompatible types in assignment (expression has type "str", variable has type "Tuple[str, int]")  [assignment]
+    t.otcp = "foo"  # E: Incompatible types in assignment (expression has type "str", variable has type "Optional[Tuple[str, int]]")  [assignment]
+    t.tcp = None  # E: Incompatible types in assignment (expression has type "None", variable has type "Tuple[str, int]")  [assignment]