Typing

.travis.yml

@@ -3,7 +3,7 @@ matrix:
   fast_finish: true
   include:
     - python: 3.8
-      env: TOXENV=about,pydocstyle,pylint,flake8,flake8_tests,sphinx COVERAGE_ID=travis-ci
+      env: TOXENV=about,pydocstyle,pylint,flake8,flake8_tests,mypy,sphinx COVERAGE_ID=travis-ci
     - python: 2.6
       env: TOXENV=py26,codecov TEST_QUICK=1 COVERAGE_ID=travis-ci
       dist: trusty

MANIFEST.in

@@ -4,5 +4,7 @@ global-exclude *.py[cod] __pycache__
 include LICENSE
 include version.json
 include *.txt
+include mypy.ini
 include tox.ini
+recursive-include blessed *.pyi py.typed
 recursive-include tests *.py *.ans

blessed/__init__.py

@@ -10,7 +10,7 @@
 if _platform.system() == 'Windows':
     from blessed.win_terminal import Terminal
 else:
-    from blessed.terminal import Terminal
+    from blessed.terminal import Terminal  # type: ignore
 
 if (3, 0, 0) <= _sys.version_info[:3] < (3, 2, 3):
     # Good till 3.2.10

blessed/_capabilities.py

@@ -6,7 +6,7 @@
     from collections import OrderedDict
 except ImportError:
     # python 2.6 requires 3rd party library (backport)
-    from ordereddict import OrderedDict  # pylint: disable=import-error
+    from ordereddict import OrderedDict  # type: ignore  # pylint: disable=import-error
 
 __all__ = (
     'CAPABILITY_DATABASE',

blessed/_capabilities.pyi

@@ -0,0 +1,6 @@
+from typing import Any, Dict, OrderedDict, Tuple
+
+CAPABILITY_DATABASE: OrderedDict[str, Tuple[str, Dict[str, Any]]]
+CAPABILITIES_RAW_MIXIN: Dict[str, str]
+CAPABILITIES_ADDITIVES: Dict[str, Tuple[str, str]]
+CAPABILITIES_CAUSE_MOVEMENT: Tuple[str, ...]

blessed/color.pyi

@@ -0,0 +1,16 @@
+from typing import Callable, Dict, Tuple
+
+_RGB = Tuple[int, int, int]
+
+def rgb_to_xyz(red: int, green: int, blue: int) -> Tuple[float, float, float]: ...
+def xyz_to_lab(
+    x_val: float, y_val: float, z_val: float
+) -> Tuple[float, float, float]: ...
+def rgb_to_lab(red: int, green: int, blue: int) -> Tuple[float, float, float]: ...
+def dist_rgb(rgb1: _RGB, rgb2: _RGB) -> float: ...
+def dist_rgb_weighted(rgb1: _RGB, rgb2: _RGB) -> float: ...
+def dist_cie76(rgb1: _RGB, rgb2: _RGB) -> float: ...
+def dist_cie94(rgb1: _RGB, rgb2: _RGB) -> float: ...
+def dist_cie2000(rgb1: _RGB, rgb2: _RGB) -> float: ...
+
+COLOR_DISTANCE_ALGORITHMS: Dict[str, Callable[[_RGB, _RGB], float]]

blessed/colorspace.pyi

@@ -0,0 +1,11 @@
+from typing import Dict, NamedTuple, Set, Tuple
+
+CGA_COLORS: Set[str]
+
+class RGBColor(NamedTuple):
+    red: int
+    green: int
+    blue: int
+
+X11_COLORNAMES_TO_RGB: Dict[str, RGBColor]
+RGB_256TABLE: Tuple[RGBColor, ...]

blessed/formatters.pyi

@@ -0,0 +1,70 @@
+from typing import (
+    Any,
+    Callable,
+    List,
+    NoReturn,
+    Optional,
+    Set,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+    overload,
+)
+
+from .terminal import Terminal
+
+COLORS = Set[str]
+COMPOUNDABLES = Set[str]
+
+_T = TypeVar("_T")
+
+class ParameterizingString(str):
+    def __new__(cls: Type[_T], cap: str, normal: str = ..., name: str = ...) -> _T: ...
+    @overload
+    def __call__(
+        self, *args: int
+    ) -> Union["FormattingString", "NullCallableString"]: ...
+    @overload
+    def __call__(self, *args: str) -> NoReturn: ...
+
+class ParameterizingProxyString(str):
+    def __new__(
+        cls: Type[_T],
+        fmt_pair: Tuple[str, Callable[..., Tuple[object, ...]]],
+        normal: str = ...,
+        name: str = ...,
+    ) -> _T: ...
+    def __call__(self, *args: Any) -> "FormattingString": ...
+
+class FormattingString(str):
+    def __new__(cls: Type[_T], sequence: str, normal: str = ...) -> _T: ...
+    @overload
+    def __call__(self, *args: int) -> NoReturn: ...
+    @overload
+    def __call__(self, *args: str) -> str: ...
+
+class FormattingOtherString(str):
+    def __new__(
+        cls: Type[_T], direct: ParameterizingString, target: ParameterizingString = ...
+    ) -> _T: ...
+    def __call__(self, *args: Union[int, str]) -> str: ...
+
+class NullCallableString(str):
+    def __new__(cls: Type[_T]) -> _T: ...
+    @overload
+    def __call__(self, *args: int) -> "NullCallableString": ...
+    @overload
+    def __call__(self, *args: str) -> str: ...
+
+def get_proxy_string(
+    term: Terminal, attr: str
+) -> Optional[ParameterizingProxyString]: ...
+def split_compound(compound: str) -> List[str]: ...
+def resolve_capability(term: Terminal, attr: str) -> str: ...
+def resolve_color(
+    term: Terminal, color: str
+) -> Union[NullCallableString, FormattingString]: ...
+def resolve_attribute(
+    term: Terminal, attr: str
+) -> Union[ParameterizingString, FormattingString]: ...

blessed/keyboard.pyi

@@ -0,0 +1,26 @@
+from typing import Dict, Iterable, Mapping, OrderedDict, Optional, Set, Type, TypeVar
+
+from .terminal import Terminal
+
+_T = TypeVar("_T")
+
+class Keystroke(str):
+    def __new__(
+        cls: Type[_T],
+        ucs: str = ...,
+        code: Optional[int] = ...,
+        name: Optional[str] = ...,
+    ) -> _T: ...
+    @property
+    def is_sequence(self) -> bool: ...
+    @property
+    def name(self) -> Optional[str]: ...
+    @property
+    def code(self) -> Optional[int]: ...
+
+def get_keyboard_codes() -> Dict[int, str]: ...
+def get_keyboard_sequences(term: Terminal) -> OrderedDict[str, int]: ...
+def get_leading_prefixes(sequences: Iterable[str]) -> Set[str]: ...
+def resolve_sequence(
+    text: str, mapper: Mapping[str, int], codes: Mapping[int, str]
+) -> Keystroke: ...

blessed/sequences.pyi

@@ -0,0 +1,52 @@
+import textwrap
+from typing import Any, Iterator, Optional, Pattern, Tuple, Type, TypeVar
+
+from .terminal import Terminal
+
+_T = TypeVar("_T")
+
+class Termcap:
+    name: str = ...
+    pattern: str = ...
+    attribute: str = ...
+    def __init__(self, name: str, pattern: str, attribute: str) -> None: ...
+    @property
+    def named_pattern(self) -> str: ...
+    @property
+    def re_compiled(self) -> Pattern[str]: ...
+    @property
+    def will_move(self) -> bool: ...
+    def horizontal_distance(self, text: str) -> int: ...
+    @classmethod
+    def build(
+        cls,
+        name: str,
+        capability: str,
+        attribute: str,
+        nparams: int = ...,
+        numeric: int = ...,
+        match_grouped: bool = ...,
+        match_any: bool = ...,
+        match_optional: bool = ...,
+    ) -> "Termcap": ...
+
+class SequenceTextWrapper(textwrap.TextWrapper):
+    term: Terminal = ...
+    def __init__(self, width: int, term: Terminal, **kwargs: Any) -> None: ...
+
+class Sequence(str):
+    def __new__(cls: Type[_T], sequence_text: str, term: Terminal) -> _T: ...
+    def ljust(self, width: int, fillchar: str = ...) -> str: ...
+    def rjust(self, width: int, fillchar: str = ...) -> str: ...
+    def center(self, width: int, fillchar: str = ...) -> str: ...
+    def length(self) -> int: ...
+    def strip(self, chars: Optional[str] = ...) -> str: ...
+    def lstrip(self, chars: Optional[str] = ...) -> str: ...
+    def rstrip(self, chars: Optional[str] = ...) -> str: ...
+    def strip_seqs(self) -> str: ...
+    def padd(self, strip: bool = ...) -> str: ...
+
+def iter_parse(
+    term: Terminal, text: str
+) -> Iterator[Tuple[str, Optional[Termcap]]]: ...
+def measure_length(text: str, term: Terminal) -> int: ...

blessed/terminal.pyi

@@ -0,0 +1,105 @@
+from typing import Any, ContextManager, IO, List, Optional, OrderedDict, Tuple, Union
+
+from .formatters import (
+    FormattingOtherString,
+    FormattingString,
+    NullCallableString,
+    ParameterizingString,
+)
+from .keyboard import Keystroke
+from .sequences import Termcap
+
+HAS_TTY: bool
+
+class Terminal:
+    caps: OrderedDict[str, Termcap]
+    errors: List[str] = ...
+    def __init__(
+        self,
+        kind: Optional[str] = ...,
+        stream: Optional[IO[str]] = ...,
+        force_styling: bool = ...,
+    ) -> None: ...
+    def __getattr__(
+        self, attr: str
+    ) -> Union[NullCallableString, ParameterizingString, FormattingString]: ...
+    @property
+    def kind(self) -> str: ...
+    @property
+    def does_styling(self) -> bool: ...
+    @property
+    def is_a_tty(self) -> bool: ...
+    @property
+    def height(self) -> int: ...
+    @property
+    def width(self) -> int: ...
+    @property
+    def pixel_height(self) -> int: ...
+    @property
+    def pixel_width(self) -> int: ...
+    def location(
+        self, x: Optional[int] = ..., y: Optional[int] = ...
+    ) -> ContextManager[None]: ...
+    def get_location(self, timeout: Optional[float] = ...) -> Tuple[int, int]: ...
+    def fullscreen(self) -> ContextManager[None]: ...
+    def hidden_cursor(self) -> ContextManager[None]: ...
+    def move_xy(self, x: int, y: int) -> ParameterizingString: ...
+    def move_yx(self, y: int, x: int) -> ParameterizingString: ...
+    @property
+    def move_left(self) -> FormattingOtherString: ...
+    @property
+    def move_right(self) -> FormattingOtherString: ...
+    @property
+    def move_up(self) -> FormattingOtherString: ...
+    @property
+    def move_down(self) -> FormattingOtherString: ...
+    @property
+    def color(self) -> Union[NullCallableString, ParameterizingString]: ...
+    def color_rgb(self, red: int, green: int, blue: int) -> FormattingString: ...
+    @property
+    def on_color(self) -> Union[NullCallableString, ParameterizingString]: ...
+    def on_color_rgb(self, red: int, green: int, blue: int) -> FormattingString: ...
+    def formatter(self, value: str) -> Union[NullCallableString, FormattingString]: ...
+    def rgb_downconvert(self, red: int, green: int, blue: int) -> int: ...
+    @property
+    def normal(self) -> str: ...
+    def link(self, url: str, text: str, url_id: str = ...) -> str: ...
+    @property
+    def stream(self) -> IO[str]: ...
+    @property
+    def number_of_colors(self) -> int: ...
+    @number_of_colors.setter
+    def number_of_colors(self, value: int) -> None: ...
+    @property
+    def color_distance_algorithm(self) -> str: ...
+    @color_distance_algorithm.setter
+    def color_distance_algorithm(self, value: str) -> None: ...
+    def ljust(
+        self, text: str, width: Optional[int] = ..., fillchar: str = ...
+    ) -> str: ...
+    def rjust(
+        self, text: str, width: Optional[int] = ..., fillchar: str = ...
+    ) -> str: ...
+    def center(
+        self, text: str, width: Optional[int] = ..., fillchar: str = ...
+    ) -> str: ...
+    def length(self, text: str) -> int: ...
+    def strip(self, text: str, chars: Optional[str] = ...) -> str: ...
+    def rstrip(self, text: str, chars: Optional[str] = ...) -> str: ...
+    def lstrip(self, text: str, chars: Optional[str] = ...) -> str: ...
+    def strip_seqs(self, text: str) -> str: ...
+    def split_seqs(self, text: str, **kwds: Any) -> List[str]: ...
+    def wrap(
+        self, text: str, width: Optional[int] = ..., **kwargs: Any
+    ) -> List[str]: ...
+    def getch(self) -> str: ...
+    def ungetch(self, text: str) -> None: ...
+    def kbhit(self, timeout: Optional[float] = ...) -> bool: ...
+    def cbreak(self) -> ContextManager[None]: ...
+    def raw(self) -> ContextManager[None]: ...
+    def keypad(self) -> ContextManager[None]: ...
+    def inkey(
+        self, timeout: Optional[float] = ..., esc_delay: float = ...
+    ) -> Keystroke: ...
+
+class WINSZ: ...

blessed/win_terminal.pyi

@@ -0,0 +1,8 @@
+from typing import ContextManager, Optional
+from .terminal import Terminal as _Terminal
+
+class Terminal(_Terminal):
+    def getch(self) -> str: ...
+    def kbhit(self, timeout: Optional[float] = ...) -> bool: ...
+    def cbreak(self) -> ContextManager[None]: ...
+    def raw(self) -> ContextManager[None]: ...

mypy.ini

@@ -0,0 +1,13 @@
+[mypy]
+
+[mypy-curses.has_key.*]
+ignore_missing_imports = True
+
+[mypy-jinxed.*]
+ignore_missing_imports = True
+
+[mypy-ordereddict.*]
+ignore_missing_imports = True
+
+[mypy-wcwidth.*]
+ignore_missing_imports = True

setup.py

@@ -41,10 +41,23 @@ def _get_long_description(fname):
     author_email='contact@jeffquast.com',
     license='MIT',
     packages=['blessed', ],
+    package_data={
+        'blessed': [
+            'py.typed',
+            '_capabilities.pyi',
+            'color.pyi',
+            'colorspace.pyi',
+            'formatters.pyi',
+            'keyboard.pyi',
+            'sequences.pyi',
+            'terminal.pyi',
+            'win_terminal.pyi',
+        ],
+    },
     url='https://github.com/jquast/blessed',
     project_urls={'Documentation': 'https://blessed.readthedocs.io'},
     include_package_data=True,
-    zip_safe=True,
+    zip_safe=False,
     classifiers=[
         'Intended Audience :: Developers',
         'Natural Language :: English',

tests/accessories.py

@@ -12,6 +12,11 @@
 import traceback
 import contextlib
 import subprocess
+try:
+    from typing import Callable
+except ImportError:  # py2
+    pass
+
 
 # 3rd party
 import six
@@ -31,7 +36,7 @@
 test_kind = 'xterm-256color'
 if platform.system() == 'Windows':
     test_kind = 'vtwin10'
-TestTerminal = functools.partial(Terminal, kind=test_kind)
+TestTerminal = functools.partial(Terminal, kind=test_kind)  # type: Callable[..., Terminal]
 SEND_SEMAPHORE = SEMAPHORE = b'SEMAPHORE\n'
 RECV_SEMAPHORE = b'SEMAPHORE\r\n'
 many_lines_params = [40, 80]