Generate type stubs for stransi and ochre

typings/ochre/__init__.pyi

@@ -0,0 +1,10 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from .color_pair import ColorPair
+from .spaces import Ansi256, Color, HCL, Hex, RGB, WebColor
+
+"""Facilities for working with colors."""
+__version__ = ...
+__all__ = ["Ansi256", "Color", "ColorPair", "HCL", "Hex", "RGB", "WebColor"]

typings/ochre/ansi256.pyi

@@ -0,0 +1,11 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+"""
+Colors by index.
+
+This is a
+[8-bit, 256-color lookup table](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit).
+"""
+colors = ...

typings/ochre/color_pair.pyi

@@ -0,0 +1,16 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+from .spaces import Color
+
+"""A color pair of foreground and background colors."""
+@dataclass(frozen=True)
+class ColorPair:
+    """A color pair of foreground and background colors."""
+    foreground: Optional[Color] = ...
+    background: Optional[Color] = ...
+
+

typings/ochre/colorsys.pyi

@@ -0,0 +1,105 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from typing import Text
+
+"""Simple color conversions.
+
+This module is a drop-in replacement for the
+[standard `colorsys` module](https://docs.python.org/3/library/colorsys.html).
+
+It provides extra functionality to the standard `colorsys` module, but also re-exports
+its contents for convenience.
+
+Examples
+--------
+>>> from ochre import colorsys
+
+This module provides some conversions, among which is RGB from and to HCL:
+
+>>> colorsys.rgb_to_hcl(0.2, 0.4, 0.4)  # doctest: +NUMBER
+(3.4, 0.2, 0.4)
+>>> colorsys.hcl_to_rgb(3.4, 0.2, 0.4)  # doctest: +NUMBER
+(0.2, 0.4, 0.4)
+
+For convenience, the module also re-exports the standard conversions from `colorsys`:
+
+>>> colorsys.rgb_to_hsv(0.2, 0.4, 0.4)
+(0.5, 0.5, 0.4)
+>>> colorsys.hsv_to_rgb(0.5, 0.5, 0.4)
+(0.2, 0.4, 0.4)
+"""
+__all__ = ["hcl_to_rgb", "rgb_to_hcl", "hls_to_rgb", "hsv_to_rgb", "rgb_to_hls", "rgb_to_hsv", "rgb_to_yiq", "yiq_to_rgb"]
+def rgb_to_xyz(r: float, g: float, b: float) -> tuple[float, float, float]:
+    """Convert the color from RGB coordinates to CIEXYZ coordinates."""
+    ...
+
+def xyz_to_rgb(x: float, y: float, z: float) -> tuple[float, float, float]:
+    """Convert the color from CIEXYZ coordinates to RGB coordinates."""
+    ...
+
+def luv_to_rgb(ell: float, u: float, v: float) -> tuple[float, float, float]:
+    """Convert the color from CIELUV coordinates to RGB coordinates."""
+    ...
+
+def rgb_to_luv(r: float, g: float, b: float) -> tuple[float, float, float]:
+    """Convert the color from RGB coordinates to CIELUV coordinates."""
+    ...
+
+def hcl_to_rgb(h: float, c: float, ell: float) -> tuple[float, float, float]:
+    """Convert the color from HCL coordinates to RGB coordinates."""
+    ...
+
+def rgb_to_hcl(r: float, g: float, b: float) -> tuple[float, float, float]:
+    """Convert the color from RGB coordinates to HCL coordinates."""
+    ...
+
+def xyz_to_luv(x: float, y: float, z: float) -> tuple[float, float, float]:
+    """Convert the color from CIEXYZ coordinates to CIELUV coordinates."""
+    ...
+
+def luv_to_xyz(ell: float, u: float, v: float) -> tuple[float, float, float]:
+    """Convert the color from CIELUV coordinates to CIEXYZ coordinates."""
+    ...
+
+def luv_to_hcl(ell: float, u: float, v: float) -> tuple[float, float, float]:
+    """Convert the color from CIELUV coordinates to HCL coordinates."""
+    ...
+
+def hcl_to_luv(h: float, c: float, ell: float) -> tuple[float, float, float]:
+    """Convert the color from HCL coordinates to CIELUV coordinates."""
+    ...
+
+def rgb_to_hex(r: float, g: float, b: float) -> int:
+    """Convert the color from RGB coordinates to hexadecimal."""
+    ...
+
+def hex_to_rgb(hc: int | Text) -> tuple[float, float, float]:
+    """Convert the color from hexadecimal to RGB coordinates."""
+    ...
+
+def web_color_to_hex(name: Text) -> int:
+    """Convert the color from web color name to hexadecimal."""
+    ...
+
+def web_color_to_rgb(name: Text) -> tuple[float, float, float]:
+    """Convert the color from web color name to RGB coordinates."""
+    ...
+
+def ansi256_to_hex(c: int) -> int:
+    """Convert the color from ANSI 256 color code to hexadecimal."""
+    ...
+
+def ansi256_to_rgb(c: int) -> tuple[float, float, float]:
+    """Convert the color from ANSI 256 color code to RGB coordinates."""
+    ...
+
+def hex_to_hex(hc: int | Text) -> int:
+    """Ensure that the hexadecimal code is an integer."""
+    ...
+
+EPSILON = ...
+KAPPA = ...
+REF_XYZ_D65_2 = ...
+REF_UV_D65_2 = ...

typings/ochre/spaces.pyi

@@ -0,0 +1,187 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Iterable, Iterator, Text, TypeVar, Union
+
+"""Objects representing colors in different color spaces."""
+C = TypeVar("C", bound="Color")
+class Color(ABC, Iterable[float]):
+    """Abstract base class for color spaces."""
+    @property
+    @abstractmethod
+    def rgb(self) -> RGB:
+        """Return the color as an RGB object."""
+        ...
+    
+    @property
+    def hex(self) -> Hex:
+        """Return the color as an Hex object."""
+        ...
+    
+    @property
+    def web_color(self) -> WebColor:
+        """Return the color as a WebColor object."""
+        ...
+    
+    @property
+    def ansi256(self) -> Ansi256:
+        """Return the color as an Ansi256 object."""
+        ...
+    
+    @property
+    def hcl(self) -> HCL:
+        """Return the color as an HCL object."""
+        ...
+    
+    def __index__(self) -> int:
+        """Return the index of the color as an hexadecimal integer."""
+        ...
+    
+    def __eq__(self, other: object) -> bool:
+        """Return True if the colors are almost equal in RGB space."""
+        ...
+    
+    def __hash__(self) -> int:
+        """Return the hash of the color."""
+        ...
+    
+    def __iter__(self) -> Iterator[float]:
+        """Return an iterator over the color's RGB channels."""
+        ...
+    
+    def distance(self, other: Color) -> float:
+        """Return the distance between colors in the HCL color space."""
+        ...
+    
+    def closest(self, colors: Iterable[C]) -> C:
+        """Find the color in the given list that is closest to this color."""
+        ...
+    
+
+
+@dataclass(frozen=True, eq=False)
+class RGB(Color):
+    """An RGB color."""
+    red: float
+    green: float
+    blue: float
+    N_DIGITS = ...
+    def __post_init__(self) -> None:
+        """Round the RGB channels."""
+        ...
+    
+    @property
+    def rgb(self) -> RGB:
+        """Return the color as an RGB object."""
+        ...
+    
+    @property
+    def hex(self) -> Hex:
+        """Return the color as an Hex object."""
+        ...
+    
+    @property
+    def web_color(self) -> WebColor:
+        """Return the color as a WebColor object."""
+        ...
+    
+    @property
+    def ansi256(self) -> Ansi256:
+        """Return the color as an Ansi256 object."""
+        ...
+    
+    @property
+    def hcl(self) -> HCL:
+        """Return the color as an HCL object."""
+        ...
+    
+
+
+@dataclass(frozen=True, eq=False)
+class Hex(Color):
+    """A color represented by a hexadecimal integer."""
+    hex_code: Union[int, Text]
+    def __repr__(self) -> Text:
+        """Return a string representation of the color."""
+        ...
+    
+    @property
+    def rgb(self) -> RGB:
+        """Return the color as an RGB object."""
+        ...
+    
+    @property
+    def hex(self) -> Hex:
+        """Return the color as an Hex object."""
+        ...
+    
+
+
+@dataclass(frozen=True, eq=False)
+class WebColor(Color):
+    """A color represented by a name."""
+    name: Text
+    NORM_PATTERN = ...
+    def __post_init__(self) -> None:
+        """Normalize the name of the color."""
+        ...
+    
+    @property
+    def rgb(self) -> RGB:
+        """Return the color as an RGB object."""
+        ...
+    
+    @property
+    def hex(self) -> Hex:
+        """Return the color as an Hex object."""
+        ...
+    
+    @property
+    def web_color(self) -> WebColor:
+        """Return the color as a WebColor object."""
+        ...
+    
+
+
+@dataclass(frozen=True, eq=False)
+class Ansi256(Color):
+    """A color represented by an integer between 0 and 255."""
+    code: int
+    @property
+    def rgb(self) -> RGB:
+        """Return the color as an RGB object."""
+        ...
+    
+    @property
+    def hex(self) -> Hex:
+        """Return the color as an Hex object."""
+        ...
+    
+    @property
+    def ansi256(self) -> Ansi256:
+        """Return the color as an Ansi256 object."""
+        ...
+    
+
+
+@dataclass(frozen=True, eq=False)
+class HCL(Color):
+    """An HCL color."""
+    hue: float
+    chroma: float
+    luminance: float
+    @property
+    def rgb(self) -> RGB:
+        """Return the color as an RGB object."""
+        ...
+    
+    @property
+    def hcl(self) -> HCL:
+        """Return the color as an HCL object."""
+        ...
+    
+
+

typings/ochre/web.pyi

@@ -0,0 +1,14 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+"""
+Colors by name.
+
+This are the
+["extended colors"](https://en.wikipedia.org/wiki/Web_colors#Extended_colors) from the
+[CSS Color Module Level 3](https://www.w3.org/TR/css-color-3/#svg-color), which is the
+result of merging specifications from HTML 4.01, CSS 2.0, SVG 1.0 and CSS3 User
+Interfaces (CSS3 UI).
+"""
+colors = ...

typings/stransi/__init__.pyi

@@ -0,0 +1,15 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from .ansi import Ansi
+from .attribute import SetAttribute
+from .clear import SetClear
+from .color import SetColor
+from .cursor import SetCursor
+from .escape import Escape
+from .unsupported import Unsupported
+
+"""A lightweight parser for ANSI escape sequences."""
+__version__ = ...
+__all__ = ["Ansi", "Escape", "SetAttribute", "SetClear", "SetColor", "SetCursor", "Unsupported"]

typings/stransi/_misc.pyi

@@ -0,0 +1,15 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from typing import Text
+
+"""Private miscellaneous utilities."""
+class _CustomText(Text):
+    """A custom string type for subclassing."""
+    def __repr__(self) -> Text:
+        """Return a string representation of the object."""
+        ...
+    
+
+

typings/stransi/ansi.pyi

@@ -0,0 +1,38 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from typing import Iterable, Text
+from ._misc import _CustomText
+from .escape import Escape
+from .instruction import Instruction
+
+"""A string that can be disassembled into text and ANSI escape sequences."""
+class Ansi(_CustomText):
+    r"""
+    A string that can be disassembled into text and ANSI escape sequences.
+
+    Examples
+    --------
+    >>> s = Ansi("\x1b[1;31mHello\x1b[m, world!")
+    >>> list(s.escapes())
+    [Escape('\x1b[1;31m'), 'Hello', Escape('\x1b[m'), ', world!']
+    >>> list(s.instructions())  # doctest: +NORMALIZE_WHITESPACE
+    [SetAttribute(attribute=<Attribute.BOLD: 1>),
+     SetColor(role=<ColorRole.FOREGROUND: 30>,
+     color=Ansi256(code=1)),
+     'Hello',
+     SetAttribute(attribute=<Attribute.NORMAL: 0>),
+     ', world!']
+    """
+    PATTERN = ...
+    def escapes(self) -> Iterable[Escape | Text]:
+        """Yield ANSI escapes and text in the order they appear."""
+        ...
+    
+    def instructions(self) -> Iterable[Instruction | Text]:
+        """Yield ANSI instructions and text in the order they appear."""
+        ...
+    
+
+

typings/stransi/attribute.pyi

@@ -0,0 +1,42 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from .instruction import Instruction
+
+"""ANSI text style attributes."""
+class Attribute(Enum):
+    """An ANSI text style attribute."""
+    NORMAL = ...
+    BOLD = ...
+    DIM = ...
+    NEITHER_BOLD_NOR_DIM = ...
+    ITALIC = ...
+    NOT_ITALIC = ...
+    UNDERLINE = ...
+    NOT_UNDERLINE = ...
+    BLINK = ...
+    NOT_BLINK = ...
+    REVERSE = ...
+    NOT_REVERSE = ...
+    HIDDEN = ...
+    NOT_HIDDEN = ...
+    def is_on(self): # -> bool:
+        """Return True if this attribute actually "turns on" an attribute."""
+        ...
+    
+    def is_off(self): # -> Any:
+        """Return True if this attribute actually "turns off" (resets) an attribute."""
+        ...
+    
+
+
+@dataclass
+class SetAttribute(Instruction[Attribute]):
+    """Instruction to set an ANSI text style attribute."""
+    attribute: Attribute
+    ...
+
+

typings/stransi/clear.pyi

@@ -0,0 +1,26 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from .instruction import Instruction
+
+"""Clear screen regions."""
+class Clear(Enum):
+    """Screen regions to clear."""
+    SCREEN_AFTER = ...
+    SCREEN_BEFORE = ...
+    SCREEN = ...
+    LINE_AFTER = ...
+    LINE_BEFORE = ...
+    LINE = ...
+
+
+@dataclass
+class SetClear(Instruction[Clear]):
+    """Instruction to clear a screen region."""
+    region: Clear
+    ...
+
+

typings/stransi/color.pyi

@@ -0,0 +1,24 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+from ochre import Color
+from .instruction import Instruction
+
+"""ANSI foreground and background colors."""
+class ColorRole(Enum):
+    """An ANSI color kinds: foreground or background."""
+    FOREGROUND = ...
+    BACKGROUND = ...
+
+
+@dataclass
+class SetColor(Instruction[Color]):
+    """An ANSI instruction to set a foreground or background color."""
+    role: ColorRole
+    color: Optional[Color] = ...
+
+

typings/stransi/cursor.pyi

@@ -0,0 +1,58 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from dataclasses import dataclass
+from .instruction import Instruction
+
+"""Cursor movements."""
+@dataclass
+class CursorMove:
+    """A single cursor movement."""
+    x: int = ...
+    y: int = ...
+    relative: bool = ...
+    @staticmethod
+    def to(x: int = ..., y: int = ...) -> CursorMove:
+        """
+        Move the cursor to the given position.
+
+        The position is relative to the zero-based origin of the screen
+        (home position).
+        """
+        ...
+    
+    @staticmethod
+    def to_home() -> CursorMove:
+        """Move the cursor to the home position."""
+        ...
+    
+    @staticmethod
+    def up(steps: int = ...) -> CursorMove:
+        """Move the cursor up by the given number of steps."""
+        ...
+    
+    @staticmethod
+    def down(steps: int = ...) -> CursorMove:
+        """Move the cursor down by the given number of steps."""
+        ...
+    
+    @staticmethod
+    def left(steps: int = ...) -> CursorMove:
+        """Move the cursor left by the given number of steps."""
+        ...
+    
+    @staticmethod
+    def right(steps: int = ...) -> CursorMove:
+        """Move the cursor right by the given number of steps."""
+        ...
+    
+
+
+@dataclass
+class SetCursor(Instruction[CursorMove]):
+    """Instruction to set the cursor position."""
+    move: CursorMove
+    ...
+
+

typings/stransi/escape.pyi

@@ -0,0 +1,42 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from typing import Iterable, Iterator, Text
+from ._misc import _CustomText
+from .instruction import Instruction
+from .token import Token
+
+"""A dedicated class for representing ANSI escape sequences."""
+def isescape(text: Text) -> bool:
+    """Return True if text is an ANSI escape sequence."""
+    ...
+
+class Escape(_CustomText):
+    """A single ANSI escape sequence."""
+    SEPARATOR = ...
+    ALL_ATTRIBUTE_CODES: set[int] = ...
+    ALL_FOREGROUND_CODES: set[int] = ...
+    ALL_BACKGROUND_CODES: set[int] = ...
+    ALL_COLOR_CODES: set[int] = ...
+    def tokens(self) -> Iterator[Token]:
+        """Yield individual tokens from the escape sequence."""
+        ...
+    
+    def instructions(self) -> Iterable[Instruction]:
+        r"""
+        Decode a string of tokens into escapable objects.
+
+        Examples
+        --------
+        >>> list(Escape("\x1b[1m").instructions())
+        [SetAttribute(attribute=<Attribute.BOLD: 1>)]
+        >>> list(Escape("\x1b[5;44m")
+        ...      .instructions())  # doctest: +NORMALIZE_WHITESPACE
+        [SetAttribute(attribute=<Attribute.BLINK: 5>),
+         SetColor(role=<ColorRole.BACKGROUND: 40>, color=Ansi256(code=4))]
+        """
+        ...
+    
+
+

typings/stransi/instruction.pyi

@@ -0,0 +1,13 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from typing import Generic, TypeVar
+
+"""Generic ANSI instructions."""
+T = TypeVar("T")
+class Instruction(Generic[T]):
+    """An ANSI instruction."""
+    ...
+
+

typings/stransi/token.pyi

@@ -0,0 +1,41 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from dataclasses import dataclass
+from typing import Text
+
+"""The basic unit of ANSI escape sequences."""
+@dataclass
+class Token:
+    r"""
+    The basic unit of ANSI escape sequences.
+
+    Examples
+    --------
+    >>> from stransi import Escape
+    >>> list(Escape("\033[38;2;255;0;255m")
+    ...      .tokens())  # doctest: +NORMALIZE_WHITESPACE
+    [Token(kind='m', data=38),
+     Token(kind='m', data=2),
+     Token(kind='m', data=255),
+     Token(kind='m', data=0),
+     Token(kind='m', data=255)]
+    """
+    kind: Text
+    data: int
+    def issgr(self) -> bool:
+        """
+        Return True if this is a SGR escape sequence.
+
+        Examples
+        --------
+        >>> Token(kind="m", data=0).issgr()
+        True
+        >>> Token(kind="H", data=0).issgr()
+        False
+        """
+        ...
+    
+
+

typings/stransi/unsupported.pyi

@@ -0,0 +1,16 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from dataclasses import dataclass
+from .instruction import Instruction
+from .token import Token
+
+"""An instruction that we don't support."""
+@dataclass
+class Unsupported(Instruction[Token]):
+    """An instruction that we don't support."""
+    token: Token
+    ...
+
+