[Pygments] Complete stubs for Formatter (#15608)

stubs/Pygments/@tests/stubtest_allowlist.txt

@@ -14,6 +14,10 @@ pygments.lexer.Lexer.name
 pygments.lexer.Lexer.url
 pygments.lexer.Lexer.version_added
 
+# Class attributes that are set to None in the base class, but are
+# always overridden with a non-None value in subclasses.
+pygments.formatter.Formatter.name
+
 # Individual lexers and styles submodules are not stubbed at this time.
 pygments\.lexers\.(?!get_|find_|load_|guess_).*
 pygments\.styles\.(?!get_).*

stubs/Pygments/pygments/formatter.pyi

@@ -1,27 +1,58 @@
 import types
-from _typeshed import Incomplete
-from typing import Any, Generic, TypeVar, overload
+from _typeshed import SupportsWrite
+from collections.abc import Iterable, Sequence
+from typing import Any, ClassVar, Generic, TypeVar, overload
+
+from pygments.style import Style
+from pygments.token import _TokenType
 
 _T = TypeVar("_T", str, bytes)
 
 __all__ = ["Formatter"]
 
 class Formatter(Generic[_T]):
-    name: Incomplete
-    aliases: Incomplete
-    filenames: Incomplete
-    unicodeoutput: bool
-    style: Incomplete
-    full: Incomplete
-    title: Incomplete
-    encoding: Incomplete
-    options: Incomplete
+    name: ClassVar[str]  # Set to None, but always overridden with a non-None value in subclasses.
+    aliases: ClassVar[Sequence[str]]  # Not intended to be mutable
+    filenames: ClassVar[Sequence[str]]  # Not intended to be mutable
+    unicodeoutput: ClassVar[bool]
+    style: type[Style]
+    full: bool
+    title: str
+    encoding: str | None
+    options: dict[str, Any]  # arbitrary values used by subclasses
     @overload
-    def __init__(self: Formatter[str], *, encoding: None = None, outencoding: None = None, **options) -> None: ...
+    def __init__(
+        self: Formatter[str],
+        *,
+        style: type[Style] | str = "default",
+        full: bool = False,
+        title: str = "",
+        encoding: None = None,
+        outencoding: None = None,
+        **options: Any,  # arbitrary values used by subclasses
+    ) -> None: ...
     @overload
-    def __init__(self: Formatter[bytes], *, encoding: str, outencoding: None = None, **options) -> None: ...
+    def __init__(
+        self: Formatter[bytes],
+        *,
+        style: type[Style] | str = "default",
+        full: bool = False,
+        title: str = "",
+        encoding: str,
+        outencoding: None = None,
+        **options: Any,  # arbitrary values used by subclasses
+    ) -> None: ...
     @overload
-    def __init__(self: Formatter[bytes], *, encoding: None = None, outencoding: str, **options) -> None: ...
+    def __init__(
+        self: Formatter[bytes],
+        *,
+        style: type[Style] | str = "default",
+        full: bool = False,
+        title: str = "",
+        encoding: None = None,
+        outencoding: str,
+        **options: Any,  # arbitrary values used by subclasses
+    ) -> None: ...
     def __class_getitem__(cls, name: Any) -> types.GenericAlias: ...
-    def get_style_defs(self, arg: str = ""): ...
-    def format(self, tokensource, outfile): ...
+    def get_style_defs(self, arg: str = "") -> str: ...
+    def format(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[_T]) -> None: ...

stubs/Pygments/pygments/formatters/bbcode.pyi

@@ -1,15 +1,14 @@
-from _typeshed import Incomplete
+from _typeshed import SupportsWrite
+from collections.abc import Iterable
 from typing import TypeVar
 
 from pygments.formatter import Formatter
+from pygments.token import _TokenType
 
 _T = TypeVar("_T", str, bytes)
 
 __all__ = ["BBCodeFormatter"]
 
 class BBCodeFormatter(Formatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
-    styles: Incomplete
-    def format_unencoded(self, tokensource, outfile) -> None: ...
+    styles: dict[_TokenType, tuple[str, str]]
+    def format_unencoded(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[str]) -> None: ...

stubs/Pygments/pygments/formatters/html.pyi

@@ -1,16 +1,15 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, SupportsWrite
+from collections.abc import Iterable
 from typing import TypeVar
 
 from pygments.formatter import Formatter
+from pygments.token import _TokenType
 
 _T = TypeVar("_T", str, bytes)
 
 __all__ = ["HtmlFormatter"]
 
 class HtmlFormatter(Formatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
     title: Incomplete
     nowrap: Incomplete
     noclasses: Incomplete
@@ -41,4 +40,4 @@ class HtmlFormatter(Formatter[_T]):
     def get_linenos_style_defs(self): ...
     def get_css_prefix(self, arg): ...
     def wrap(self, source): ...
-    def format_unencoded(self, tokensource, outfile) -> None: ...
+    def format_unencoded(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[str]) -> None: ...

stubs/Pygments/pygments/formatters/img.pyi

@@ -1,9 +1,9 @@
-from _typeshed import Incomplete
-from typing import TypeVar
+from _typeshed import Incomplete, SupportsWrite
+from collections.abc import Iterable
+from typing_extensions import Never
 
 from pygments.formatter import Formatter
-
-_T = TypeVar("_T", str, bytes)
+from pygments.token import _TokenType
 
 __all__ = ["ImageFormatter", "GifImageFormatter", "JpgImageFormatter", "BmpImageFormatter"]
 
@@ -22,11 +22,7 @@ class FontManager:
     def get_font(self, bold, oblique): ...
     def get_style(self, style): ...
 
-class ImageFormatter(Formatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
-    unicodeoutput: bool
+class ImageFormatter(Formatter[bytes]):
     default_image_format: str
     encoding: str
     styles: Incomplete
@@ -49,23 +45,14 @@ class ImageFormatter(Formatter[_T]):
     hl_lines: Incomplete
     hl_color: Incomplete
     drawables: Incomplete
-    def get_style_defs(self, arg: str = "") -> None: ...
-    def format(self, tokensource, outfile) -> None: ...
+    def get_style_defs(self, arg: str = "") -> Never: ...
+    def format(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[bytes]) -> None: ...
 
-class GifImageFormatter(ImageFormatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
+class GifImageFormatter(ImageFormatter):
     default_image_format: str
 
-class JpgImageFormatter(ImageFormatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
+class JpgImageFormatter(ImageFormatter):
     default_image_format: str
 
-class BmpImageFormatter(ImageFormatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
+class BmpImageFormatter(ImageFormatter):
     default_image_format: str

stubs/Pygments/pygments/formatters/irc.pyi

@@ -1,17 +1,16 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, SupportsWrite
+from collections.abc import Iterable
 from typing import TypeVar
 
 from pygments.formatter import Formatter
+from pygments.token import _TokenType
 
 _T = TypeVar("_T", str, bytes)
 
 __all__ = ["IRCFormatter"]
 
 class IRCFormatter(Formatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
     darkbg: Incomplete
     colorscheme: Incomplete
     linenos: Incomplete
-    def format_unencoded(self, tokensource, outfile) -> None: ...
+    def format_unencoded(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[str]) -> None: ...

stubs/Pygments/pygments/formatters/latex.pyi

@@ -1,17 +1,16 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, SupportsWrite
+from collections.abc import Iterable
 from typing import TypeVar
 
 from pygments.formatter import Formatter
 from pygments.lexer import Lexer
+from pygments.token import _TokenType
 
 _T = TypeVar("_T", str, bytes)
 
 __all__ = ["LatexFormatter"]
 
 class LatexFormatter(Formatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
     docclass: Incomplete
     preamble: Incomplete
     linenos: Incomplete
@@ -27,7 +26,7 @@ class LatexFormatter(Formatter[_T]):
     right: Incomplete
     envname: Incomplete
     def get_style_defs(self, arg: str = ""): ...
-    def format_unencoded(self, tokensource, outfile) -> None: ...
+    def format_unencoded(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[str]) -> None: ...
 
 class LatexEmbeddedLexer(Lexer):
     left: Incomplete

stubs/Pygments/pygments/formatters/other.pyi

@@ -1,29 +1,22 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, SupportsWrite
+from collections.abc import Iterable
 from typing import TypeVar
 
 from pygments.formatter import Formatter
+from pygments.token import _TokenType
 
 _T = TypeVar("_T", str, bytes)
 
 __all__ = ["NullFormatter", "RawTokenFormatter", "TestcaseFormatter"]
 
 class NullFormatter(Formatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
-    def format(self, tokensource, outfile) -> None: ...
+    def format(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[_T]) -> None: ...
 
 class RawTokenFormatter(Formatter[bytes]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
-    unicodeoutput: bool
     encoding: str
     compress: Incomplete
     error_color: Incomplete
-    def format(self, tokensource, outfile) -> None: ...
+    def format(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[bytes]) -> None: ...
 
 class TestcaseFormatter(Formatter[_T]):
-    name: str
-    aliases: Incomplete
-    def format(self, tokensource, outfile) -> None: ...
+    def format(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[_T]) -> None: ...

stubs/Pygments/pygments/formatters/pangomarkup.pyi

@@ -1,15 +1,14 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, SupportsWrite
+from collections.abc import Iterable
 from typing import TypeVar
 
 from pygments.formatter import Formatter
+from pygments.token import _TokenType
 
 _T = TypeVar("_T", str, bytes)
 
 __all__ = ["PangoMarkupFormatter"]
 
 class PangoMarkupFormatter(Formatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
     styles: Incomplete
-    def format_unencoded(self, tokensource, outfile) -> None: ...
+    def format_unencoded(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[str]) -> None: ...

stubs/Pygments/pygments/formatters/rtf.pyi

@@ -1,18 +1,17 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, SupportsWrite
+from collections.abc import Iterable
 from typing import TypeVar
 
 from pygments.formatter import Formatter
+from pygments.token import _TokenType
 
 _T = TypeVar("_T", str, bytes)
 
 __all__ = ["RtfFormatter"]
 
 class RtfFormatter(Formatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
     fontface: Incomplete
     fontsize: Incomplete
     @staticmethod
     def hex_to_rtf_color(hex_color: str) -> str: ...
-    def format_unencoded(self, tokensource, outfile) -> None: ...
+    def format_unencoded(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[str]) -> None: ...

stubs/Pygments/pygments/formatters/svg.pyi

@@ -1,16 +1,15 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, SupportsWrite
+from collections.abc import Iterable
 from typing import TypeVar
 
 from pygments.formatter import Formatter
+from pygments.token import _TokenType
 
 _T = TypeVar("_T", str, bytes)
 
 __all__ = ["SvgFormatter"]
 
 class SvgFormatter(Formatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
     nowrap: Incomplete
     fontfamily: Incomplete
     fontsize: Incomplete
@@ -22,4 +21,4 @@ class SvgFormatter(Formatter[_T]):
     linenostart: Incomplete
     linenostep: Incomplete
     linenowidth: Incomplete
-    def format_unencoded(self, tokensource, outfile) -> None: ...
+    def format_unencoded(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[str]) -> None: ...

stubs/Pygments/pygments/formatters/terminal.pyi

@@ -1,18 +1,17 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, SupportsWrite
+from collections.abc import Iterable
 from typing import TypeVar
 
 from pygments.formatter import Formatter
+from pygments.token import _TokenType
 
 _T = TypeVar("_T", str, bytes)
 
 __all__ = ["TerminalFormatter"]
 
 class TerminalFormatter(Formatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
     darkbg: Incomplete
     colorscheme: Incomplete
     linenos: Incomplete
-    def format(self, tokensource, outfile): ...
-    def format_unencoded(self, tokensource, outfile) -> None: ...
+    def format(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[_T]) -> None: ...
+    def format_unencoded(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[str]) -> None: ...

stubs/Pygments/pygments/formatters/terminal256.pyi

@@ -1,7 +1,9 @@
-from _typeshed import Incomplete
+from _typeshed import Incomplete, SupportsWrite
+from collections.abc import Iterable
 from typing import TypeVar
 
 from pygments.formatter import Formatter
+from pygments.token import _TokenType
 
 _T = TypeVar("_T", str, bytes)
 
@@ -20,9 +22,6 @@ class EscapeSequence:
     def reset_string(self): ...
 
 class Terminal256Formatter(Formatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
     xterm_colors: Incomplete
     best_match: Incomplete
     style_string: Incomplete
@@ -30,10 +29,8 @@ class Terminal256Formatter(Formatter[_T]):
     useunderline: Incomplete
     useitalic: Incomplete
     linenos: Incomplete
-    def format(self, tokensource, outfile): ...
-    def format_unencoded(self, tokensource, outfile) -> None: ...
 
-class TerminalTrueColorFormatter(Terminal256Formatter[_T]):
-    name: str
-    aliases: Incomplete
-    filenames: Incomplete
+    def format(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[_T]) -> None: ...
+    def format_unencoded(self, tokensource: Iterable[tuple[_TokenType, str]], outfile: SupportsWrite[str]) -> None: ...
+
+class TerminalTrueColorFormatter(Terminal256Formatter[_T]): ...