pygments: Correct Formatter generics

933fec0 made
pygments.formatter.Formatter generic to improve the type-safety
of pygments.format() and pygments.highlight().

The actual pygments.formatter.Formatter however is not generic,
meaning that pygments.formatter.Formatter[str] should not type check
(since it leads to a runtime type error).

Furthermore the pygments ImageFormatter always expects BinaryIO,
no matter which constructor arguments are passed.

This commit addresses both problems.

Author: not-my-profile

stubs/Pygments/pygments/__init__.pyi

@@ -1,16 +1,16 @@
 from _typeshed import SupportsWrite
 from typing import TypeVar, overload
 
-from pygments.formatter import Formatter
+from pygments.formatter import _Formatter
 
 _T = TypeVar("_T", str, bytes)
 
 def lex(code, lexer): ...
 @overload
-def format(tokens, formatter: Formatter[_T], outfile: SupportsWrite[_T]) -> None: ...
+def format(tokens, formatter: _Formatter[_T], outfile: SupportsWrite[_T]) -> None: ...
 @overload
-def format(tokens, formatter: Formatter[_T], outfile: None = ...) -> _T: ...
+def format(tokens, formatter: _Formatter[_T], outfile: None = ...) -> _T: ...
 @overload
-def highlight(code, lexer, formatter: Formatter[_T], outfile: SupportsWrite[_T]) -> None: ...
+def highlight(code, lexer, formatter: _Formatter[_T], outfile: SupportsWrite[_T]) -> None: ...
 @overload
-def highlight(code, lexer, formatter: Formatter[_T], outfile: None = ...) -> _T: ...
+def highlight(code, lexer, formatter: _Formatter[_T], outfile: None = ...) -> _T: ...

stubs/Pygments/pygments/formatter.pyi

@@ -1,8 +1,8 @@
-from typing import Any, Generic, TypeVar, overload
+from typing import Any, Generic, TypeVar, overload, type_check_only
 
 _T = TypeVar("_T", str, bytes)
 
-class Formatter(Generic[_T]):
+class Formatter:
     name: Any
     aliases: Any
     filenames: Any
@@ -12,11 +12,21 @@ class Formatter(Generic[_T]):
     title: Any
     encoding: Any
     options: Any
+    def get_style_defs(self, arg: str = ...): ...
+    def format(self, tokensource, outfile): ...
+
+@type_check_only
+class _Formatter(Generic[_T], Formatter): ...
+
+@type_check_only
+class _BinaryFormatter(_Formatter[bytes]):
+    def __init__(self, **options) -> None: ...
+
+@type_check_only
+class _TextFormatter(_Formatter[_T]):
     @overload
-    def __init__(self: Formatter[str], *, encoding: None = ..., outencoding: None = ..., **options) -> None: ...
+    def __init__(self: _Formatter[str], *, encoding: None = ..., outencoding: None = ..., **options) -> None: ...
     @overload
-    def __init__(self: Formatter[bytes], *, encoding: str, outencoding: None = ..., **options) -> None: ...
+    def __init__(self: _Formatter[bytes], *, encoding: str, outencoding: None = ..., **options) -> None: ...
     @overload
-    def __init__(self: Formatter[bytes], *, encoding: None = ..., outencoding: str, **options) -> None: ...
-    def get_style_defs(self, arg: str = ...): ...
-    def format(self, tokensource, outfile): ...
+    def __init__(self: _Formatter[bytes], *, encoding: None = ..., outencoding: str, **options) -> None: ...

stubs/Pygments/pygments/formatters/__init__.pyi

@@ -1,6 +1,6 @@
 from typing import Any, Generator
 
-from ..formatter import Formatter
+from ..formatter import _Formatter
 from .bbcode import BBCodeFormatter as BBCodeFormatter
 from .html import HtmlFormatter as HtmlFormatter
 from .img import (
@@ -18,7 +18,7 @@ from .svg import SvgFormatter as SvgFormatter
 from .terminal import TerminalFormatter as TerminalFormatter
 from .terminal256 import Terminal256Formatter as Terminal256Formatter, TerminalTrueColorFormatter as TerminalTrueColorFormatter
 
-def get_all_formatters() -> Generator[type[Formatter[Any]], None, None]: ...
+def get_all_formatters() -> Generator[type[_Formatter[Any]], None, None]: ...
 def get_formatter_by_name(_alias, **options): ...
 def load_formatter_from_file(filename, formattername: str = ..., **options): ...
 def get_formatter_for_filename(fn, **options): ...

stubs/Pygments/pygments/formatters/bbcode.pyi

@@ -1,10 +1,10 @@
 from typing import Any, TypeVar
 
-from pygments.formatter import Formatter
+from pygments.formatter import _TextFormatter
 
 _T = TypeVar("_T", str, bytes)
 
-class BBCodeFormatter(Formatter[_T]):
+class BBCodeFormatter(_TextFormatter[_T]):
     name: str
     aliases: Any
     filenames: Any

stubs/Pygments/pygments/formatters/html.pyi

@@ -1,10 +1,10 @@
 from typing import Any, TypeVar
 
-from pygments.formatter import Formatter
+from pygments.formatter import _TextFormatter
 
 _T = TypeVar("_T", str, bytes)
 
-class HtmlFormatter(Formatter[_T]):
+class HtmlFormatter(_TextFormatter[_T]):
     name: str
     aliases: Any
     filenames: Any

stubs/Pygments/pygments/formatters/img.pyi

@@ -1,8 +1,6 @@
-from typing import Any, TypeVar
+from typing import Any
 
-from pygments.formatter import Formatter
-
-_T = TypeVar("_T", str, bytes)
+from pygments.formatter import _BinaryFormatter
 
 class PilNotAvailable(ImportError): ...
 class FontNotFound(Exception): ...
@@ -17,7 +15,7 @@ class FontManager:
     def get_text_size(self, text): ...
     def get_font(self, bold, oblique): ...
 
-class ImageFormatter(Formatter[_T]):
+class ImageFormatter(_BinaryFormatter):
     name: str
     aliases: Any
     filenames: Any
@@ -47,19 +45,19 @@ class ImageFormatter(Formatter[_T]):
     def get_style_defs(self, arg: str = ...) -> None: ...
     def format(self, tokensource, outfile) -> None: ...
 
-class GifImageFormatter(ImageFormatter[_T]):
+class GifImageFormatter(ImageFormatter):
     name: str
     aliases: Any
     filenames: Any
     default_image_format: str
 
-class JpgImageFormatter(ImageFormatter[_T]):
+class JpgImageFormatter(ImageFormatter):
     name: str
     aliases: Any
     filenames: Any
     default_image_format: str
 
-class BmpImageFormatter(ImageFormatter[_T]):
+class BmpImageFormatter(ImageFormatter):
     name: str
     aliases: Any
     filenames: Any

stubs/Pygments/pygments/formatters/irc.pyi

@@ -1,10 +1,10 @@
 from typing import Any, TypeVar
 
-from pygments.formatter import Formatter
+from pygments.formatter import _TextFormatter
 
 _T = TypeVar("_T", str, bytes)
 
-class IRCFormatter(Formatter[_T]):
+class IRCFormatter(_TextFormatter[_T]):
     name: str
     aliases: Any
     filenames: Any

stubs/Pygments/pygments/formatters/latex.pyi

@@ -1,11 +1,11 @@
 from typing import Any, TypeVar
 
-from pygments.formatter import Formatter
+from pygments.formatter import _TextFormatter
 from pygments.lexer import Lexer
 
 _T = TypeVar("_T", str, bytes)
 
-class LatexFormatter(Formatter[_T]):
+class LatexFormatter(_TextFormatter[_T]):
     name: str
     aliases: Any
     filenames: Any

stubs/Pygments/pygments/formatters/other.pyi

@@ -1,16 +1,16 @@
 from typing import Any, TypeVar
 
-from pygments.formatter import Formatter
+from pygments.formatter import _TextFormatter
 
 _T = TypeVar("_T", str, bytes)
 
-class NullFormatter(Formatter[_T]):
+class NullFormatter(_TextFormatter[_T]):
     name: str
     aliases: Any
     filenames: Any
     def format(self, tokensource, outfile) -> None: ...
 
-class RawTokenFormatter(Formatter[_T]):
+class RawTokenFormatter(_TextFormatter[_T]):
     name: str
     aliases: Any
     filenames: Any
@@ -20,7 +20,7 @@ class RawTokenFormatter(Formatter[_T]):
     error_color: Any
     def format(self, tokensource, outfile) -> None: ...
 
-class TestcaseFormatter(Formatter[_T]):
+class TestcaseFormatter(_TextFormatter[_T]):
     name: str
     aliases: Any
     def format(self, tokensource, outfile) -> None: ...

stubs/Pygments/pygments/formatters/pangomarkup.pyi

@@ -1,10 +1,10 @@
 from typing import Any, TypeVar
 
-from pygments.formatter import Formatter
+from pygments.formatter import _TextFormatter
 
 _T = TypeVar("_T", str, bytes)
 
-class PangoMarkupFormatter(Formatter[_T]):
+class PangoMarkupFormatter(_TextFormatter[_T]):
     name: str
     aliases: Any
     filenames: Any

stubs/Pygments/pygments/formatters/rtf.pyi

@@ -1,10 +1,10 @@
 from typing import Any, TypeVar
 
-from pygments.formatter import Formatter
+from pygments.formatter import _TextFormatter
 
 _T = TypeVar("_T", str, bytes)
 
-class RtfFormatter(Formatter[_T]):
+class RtfFormatter(_TextFormatter[_T]):
     name: str
     aliases: Any
     filenames: Any

stubs/Pygments/pygments/formatters/svg.pyi

@@ -1,10 +1,10 @@
 from typing import Any, TypeVar
 
-from pygments.formatter import Formatter
+from pygments.formatter import _TextFormatter
 
 _T = TypeVar("_T", str, bytes)
 
-class SvgFormatter(Formatter[_T]):
+class SvgFormatter(_TextFormatter[_T]):
     name: str
     aliases: Any
     filenames: Any

stubs/Pygments/pygments/formatters/terminal.pyi

@@ -1,10 +1,10 @@
 from typing import Any, TypeVar
 
-from pygments.formatter import Formatter
+from pygments.formatter import _TextFormatter
 
 _T = TypeVar("_T", str, bytes)
 
-class TerminalFormatter(Formatter[_T]):
+class TerminalFormatter(_TextFormatter[_T]):
     name: str
     aliases: Any
     filenames: Any

stubs/Pygments/pygments/formatters/terminal256.pyi

@@ -1,6 +1,6 @@
 from typing import Any, TypeVar
 
-from pygments.formatter import Formatter
+from pygments.formatter import _TextFormatter
 
 _T = TypeVar("_T", str, bytes)
 
@@ -18,7 +18,7 @@ class EscapeSequence:
     def true_color_string(self): ...
     def reset_string(self): ...
 
-class Terminal256Formatter(Formatter[_T]):
+class Terminal256Formatter(_TextFormatter[_T]):
     name: str
     aliases: Any
     filenames: Any

stubs/Pygments/pygments/plugin.pyi

@@ -2,7 +2,7 @@ from typing import Any, Generator, Iterable
 
 from pkg_resources import EntryPoint
 from pygments.filter import Filter
-from pygments.formatter import Formatter
+from pygments.formatter import _Formatter
 from pygments.lexer import Lexer
 from pygments.style import Style
 
@@ -13,6 +13,6 @@ FILTER_ENTRY_POINT: str
 
 def iter_entry_points(group_name: str) -> Iterable[EntryPoint]: ...
 def find_plugin_lexers() -> Generator[type[Lexer], None, None]: ...
-def find_plugin_formatters() -> Generator[tuple[str, type[Formatter[Any]]], None, None]: ...
+def find_plugin_formatters() -> Generator[tuple[str, type[_Formatter[Any]]], None, None]: ...
 def find_plugin_styles() -> Generator[tuple[str, type[Style]], None, None]: ...
 def find_plugin_filters() -> Generator[tuple[str, type[Filter]], None, None]: ...