chromatic-python 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

chromatic/__init__.py

@@ -3,107 +3,6 @@ try:
 except ImportError:
     __version__ = "0.0.0"
 
-from . import ascii, color, data
-from .ascii import (
-    AnsiImage,
-    ansi2img,
-    ansify,
-    ansi_quantize,
-    ascii2img,
-    ascii_printable,
-    contrast_stretch,
-    cp437_printable,
-    equalize_white_point,
-    get_font_key,
-    get_font_object,
-    img2ansi,
-    img2ascii,
-    read_ans,
-    render_ans,
-    reshape_ansi,
-    to_sgr_array,
-)
-from .ascii._glyph_proc import get_glyph_masks
-from .color import (
-    Back,
-    Color,
-    ColorNamespace,
-    ColorStr,
-    Fore,
-    SgrParameter,
-    Style,
-    ansicolor24Bit,
-    ansicolor4Bit,
-    ansicolor8Bit,
-    colorbytes,
-    named_color,
-)
-from .data import register_user_font
+import lazy_loader as _lazy
 
-__all__ = []
-
-try:
-    import os
-    import sys
-    from functools import lru_cache, wraps
-    from types import ModuleType
-
-    def find_modules(path: str):
-        from setuptools import find_packages
-        from pkgutil import iter_modules
-
-        tree: dict[str, dict | ModuleType] = {__name__: {'__module__': sys.modules[__name__]}}
-        children = set()
-        for pkg in find_packages(path):
-            children.add(pkg)
-            pkg_path = path + '/' + pkg.replace('.', '/')
-            if sys.version_info.major == 2 or (
-                sys.version_info.major == 3 and sys.version_info.minor < 6
-            ):
-                for _, name, ispkg in iter_modules([pkg_path]):
-                    if not ispkg:
-                        children.add(f"{pkg}.{name}")
-            else:
-                for info in iter_modules([pkg_path]):
-                    if not info.ispkg:
-                        children.add(f"{pkg}.{info.name}")
-        for child in children:
-            name = f"{__name__}.{child}"
-            depth = tree
-            for node in name.split('.'):
-                if node not in depth:
-                    depth[node] = {}
-                depth = depth[node]
-            if name in sys.modules:
-                depth['__module__'] = sys.modules[name]
-        return tree
-
-    def publicize_modules(modulename: str, tree: dict[str, dict | ModuleType]):
-        def is_local(obj: object):
-            if isinstance(obj, ModuleType):
-                return obj.__spec__.parent == modulename
-            elif hasattr(obj, '__module__'):
-                return obj.__module__ == modulename
-            return obj is not None
-
-        for name, subtree in tree.items():
-            if name == '__module__' and isinstance(subtree, ModuleType):
-                submodule = subtree
-                init_dir = dir(submodule)
-
-                @wraps(submodule.__dir__)
-                def wrapped():
-                    s = set(attr for attr in init_dir if is_local(getattr(submodule, attr, None)))
-                    if hasattr(submodule, '__all__'):
-                        s.update(submodule.__all__)
-                    return list(s)
-
-                sys.modules[submodule.__name__].__dir__ = wrapped
-
-            else:
-                publicize_modules(f"{modulename}.{name}", subtree)
-
-    publicize_modules(*find_modules(os.path.split(__file__)[0]).popitem())
-
-finally:
-    del find_modules, publicize_modules
+__getattr__, __dir__, __all__ = _lazy.attach_stub(__name__, __file__)

chromatic/__init__.pyi

@@ -0,0 +1,74 @@
+__all__ = [
+    'AnsiImage',
+    'Back',
+    'Color',
+    'ColorNamespace',
+    'ColorStr',
+    'Fore',
+    'SgrParameter',
+    'Style',
+    '__version__',
+    'ansi2img',
+    'ansi_quantize',
+    'ansicolor24Bit',
+    'ansicolor4Bit',
+    'ansicolor8Bit',
+    'ansify',
+    'image',
+    'ascii2img',
+    'ascii_printable',
+    'color',
+    'colorbytes',
+    'contrast_stretch',
+    'cp437_printable',
+    'data',
+    'equalize_white_point',
+    'get_font_key',
+    'get_font_object',
+    'get_glyph_masks',
+    'img2ansi',
+    'img2ascii',
+    'named_color',
+    'read_ans',
+    'register_userfont',
+    'render_ans',
+    'reshape_ansi',
+    'to_sgr_array',
+]
+from . import color, data, image
+from ._version import version as __version__
+from .color import (
+    Back,
+    Color,
+    ColorNamespace,
+    ColorStr,
+    Fore,
+    SgrParameter,
+    Style,
+    ansicolor24Bit,
+    ansicolor4Bit,
+    ansicolor8Bit,
+    colorbytes,
+    named_color,
+)
+from .data import register_userfont
+from .image import (
+    AnsiImage,
+    ansi2img,
+    ansi_quantize,
+    ansify,
+    ascii2img,
+    ascii_printable,
+    contrast_stretch,
+    cp437_printable,
+    equalize_white_point,
+    get_font_key,
+    get_font_object,
+    img2ansi,
+    img2ascii,
+    read_ans,
+    render_ans,
+    reshape_ansi,
+    to_sgr_array,
+)
+from .image._glyph_proc import get_glyph_masks

chromatic/_typing.py

@@ -14,12 +14,13 @@ from typing import (
     Concatenate,
     Hashable,
     Iterable,
-    Literal,
+    Literal as L,
     NamedTuple,
     Optional,
     ParamSpec,
     Protocol,
     Sequence,
+    TYPE_CHECKING,
     Type,
     TypeAlias,
     TypeAliasType,
@@ -40,7 +41,8 @@ from PIL.ImageFont import FreeTypeFont
 from numpy import dtype, float64, generic, ndarray, number, uint8
 from numpy._typing import NDArray, _ArrayLike
 
-from chromatic.data import UserFont
+if TYPE_CHECKING:
+    from .data import UserFont
 
 _P = ParamSpec('_P')
 _T = TypeVar('_T')
@@ -49,10 +51,10 @@ _T_contra = TypeVar('_T_contra', contravariant=True)
 _AnyNumber_co = TypeVar('_AnyNumber_co', number, Number, covariant=True)
 
 type ArrayReducerFunc[_SCT: generic] = Callable[Concatenate[_ArrayLike[_SCT], _P], NDArray[_SCT]]
-type ShapedNDArray[_Shape: tuple[int, ...], _SCT: generic] = ndarray[_Shape, dtype[_SCT]]
+type ShapedNDArray[_Shape: tuple[int, ...], _SCT = generic] = ndarray[_Shape, dtype[_SCT]]
 type MatrixLike[_SCT: generic] = ShapedNDArray[TupleOf2[int], _SCT]
 type SquareMatrix[_I: int, _SCT: generic] = ShapedNDArray[TupleOf2[_I], _SCT]
-type GlyphArray[_SCT: generic] = SquareMatrix[Literal[24], _SCT]
+type GlyphArray[_SCT: generic] = SquareMatrix[L[24], _SCT]
 type TupleOf2[_T] = tuple[_T, _T]
 type TupleOf3[_T] = tuple[_T, _T, _T]
 
@@ -64,25 +66,41 @@ GlyphBitmask: TypeAlias = GlyphArray[bool]
 Bitmask: TypeAlias = MatrixLike[bool]
 GreyscaleGlyphArray: TypeAlias = GlyphArray[float64]
 GreyscaleArray: TypeAlias = MatrixLike[float64]
-RGBArray: TypeAlias = ShapedNDArray[tuple[int, int, Literal[3]], uint8]
-RGBPixel: TypeAlias = ShapedNDArray[tuple[Literal[3]], uint8]
+RGBArray: TypeAlias = ShapedNDArray[tuple[int, int, L[3]], uint8]
+RGBPixel: TypeAlias = ShapedNDArray[tuple[L[3]], uint8]
 
 RGBImageLike: TypeAlias = Image | RGBArray
-RGBVectorLike: TypeAlias = Int3Tuple | IntSequence | RGBPixel
-ColorDictKeys = Literal['fg', 'bg']
-Ansi4BitAlias = Literal['4b']
-Ansi8BitAlias = Literal['8b']
-Ansi24BitAlias = Literal['24b']
+RGBVectorLike: TypeAlias = IntSequence | RGBPixel
+ColorDictKeys = L['fg', 'bg']
+Ansi4BitAlias = L['4b']
+Ansi8BitAlias = L['8b']
+Ansi24BitAlias = L['24b']
 AnsiColorAlias = Ansi4BitAlias | Ansi8BitAlias | Ansi24BitAlias
-FontArgType: TypeAlias = FreeTypeFont | UserFont | str | int
+FontArgType: TypeAlias = 'FreeTypeFont | UserFont | str'
+
+
+def eval_annotation(annotation: str, **kwargs) -> Any:
+    globals_ = kwargs.get('globals', {}) | globals()
+    locals_ = kwargs.get('locals', {})
+    try:
+        return subtype(eval(annotation, globals_.copy(), locals_.copy()))
+    except NameError as e:
+        try:
+            import typing
+
+            globals_[e.name] = getattr(typing, e.name)
+            return eval_annotation(annotation, globals=globals_, locals=locals_)
+        except AttributeError:
+            pass
+        raise
 
 
 def type_error_msg(err_obj, *expected, context: str = '', obj_repr=False):
     n_expected = len(expected)
-    name_slots = ['{%d.__qualname__!r}' % n for n in range(n_expected)]
-    if name_slots and n_expected > 1:
+    name_slots = ["{%d.__name__!r}" % n for n in range(n_expected)]
+    if n_expected > 1:
         name_slots[-1] = f"or {name_slots[-1]}"
-    names = (', ' if n_expected > 2 else ' ').join([context.strip()] + name_slots).format(*expected)
+    names = (', ' if n_expected > 2 else ' ').join([context.strip(), *name_slots]).format(*expected)
     if not obj_repr:
         if not isinstance(err_obj, type):
             err_obj = type(err_obj)
@@ -100,7 +118,7 @@ def is_matching_type(value, typ):
     origin, args = deconstruct_type(typ)
     if origin is Union:
         return any(is_matching_type(value, arg) for arg in args)
-    elif origin is Literal:
+    elif origin is L:
         return value in args
     elif isinstance(typ, TypeVar):
         if typ.__constraints__:
@@ -188,20 +206,20 @@ def unionize(__iterable: Iterable[SupportsUnion[_T_contra, _T_co]]) -> _T_co:
 
 _GenericAlias = type(Type[...]) | types.GenericAlias
 _UnionGenericType = type(Union[..., None])
-_LiteralGenericType = type(Literal[''])
+_LiteralGenericType = type(L[''])
 _CallableGenericType = type(Callable[[], ...]) | type(ABC_Callable[[], ...])
 _CallableType = type(Callable) | ABC_Callable
 
 
 class _BoundedDict[_KT, _VT](OrderedDict[_KT, _VT]):
+    """Bounded OrderedDict, mimics FIFO behavior of `functools.lru_cache`"""
 
     def __init__(self, *, maxsize: Optional[int] = 128):
-        """Bounded OrderedDict, mimics FIFO behavior of `functools.lru_cache`"""
         super().__init__()
         if maxsize is not None:
             maxsize = max(maxsize, 0)
 
-            @wraps(self.__setitem__)
+            @wraps(_BoundedDict.__setitem__)
             def _fifo(_, key, value):
                 if maxsize <= len(self):
                     self.popitem(last=True)
@@ -345,7 +363,7 @@ def subtype[_T](typ: _T) -> _T:
                     return getattr(value, '__args__', ())
 
                 start = args[literals.pop(0)]
-                args_list[args_list.index(start)] = Literal[
+                args_list[args_list.index(start)] = L[
                     *start.__args__,
                     *dict.fromkeys(arg for idx in literals for arg in _next_args(idx)),
                 ]

chromatic/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.2.2'
-__version_tuple__ = version_tuple = (0, 2, 2)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)

chromatic/color/__init__.py

@@ -1,6 +1,3 @@
-from . import core, palette
-from .colorconv import *
-from .core import *
-from .palette import *
+import lazy_loader as _lazy
 
-__all__ = list(set(core.__all__) | set(colorconv.__all__) | set(palette.__all__))
+__getattr__, __dir__, __all__ = _lazy.attach_stub(__name__, __file__)

chromatic/color/__init__.pyi

@@ -0,0 +1,86 @@
+__all__ = [
+    'ANSI_4BIT_RGB',
+    'Back',
+    'CSI',
+    'Color',
+    'ColorNamespace',
+    'ColorStr',
+    'Fore',
+    'SGR_RESET',
+    'SgrParameter',
+    'SgrSequence',
+    'Style',
+    'ansi_4bit_to_rgb',
+    'ansi_8bit_to_rgb',
+    'ansicolor24Bit',
+    'ansicolor4Bit',
+    'ansicolor8Bit',
+    'color_chain',
+    'colorbytes',
+    'get_ansi_type',
+    'int2rgb',
+    'hexstr2rgb',
+    'hsl2rgb',
+    'hsv2rgb',
+    'is_u24',
+    'lab2rgb',
+    'lab2xyz',
+    'named_color',
+    'nearest_ansi_4bit_rgb',
+    'nearest_ansi_8bit_rgb',
+    'randcolor',
+    'rgb2ansi_escape',
+    'rgb2int',
+    'rgb2hexstr',
+    'rgb2hsl',
+    'rgb2hsv',
+    'rgb2lab',
+    'rgb2xyz',
+    'rgb_diff',
+    'rgb_dispatch',
+    'rgb_to_ansi_8bit',
+    'xyz2lab',
+    'xyz2rgb',
+]
+from . import colorconv, core, iterators, palette
+from .colorconv import (
+    ANSI_4BIT_RGB,
+    ansi_4bit_to_rgb,
+    ansi_8bit_to_rgb,
+    int2rgb,
+    hexstr2rgb,
+    hsl2rgb,
+    hsv2rgb,
+    is_u24,
+    lab2rgb,
+    lab2xyz,
+    nearest_ansi_4bit_rgb,
+    nearest_ansi_8bit_rgb,
+    rgb2int,
+    rgb2hexstr,
+    rgb2hsl,
+    rgb2hsv,
+    rgb2lab,
+    rgb2xyz,
+    rgb_diff,
+    rgb_to_ansi_8bit,
+    xyz2lab,
+    xyz2rgb,
+)
+from .core import (
+    CSI,
+    Color,
+    ColorStr,
+    SGR_RESET,
+    SgrParameter,
+    SgrSequence,
+    ansicolor24Bit,
+    ansicolor4Bit,
+    ansicolor8Bit,
+    color_chain,
+    colorbytes,
+    get_ansi_type,
+    randcolor,
+    rgb2ansi_escape,
+)
+from .palette import Back, ColorNamespace, Fore, Style, named_color, rgb_dispatch

chromatic/color/colorconv.py

@@ -2,16 +2,16 @@ __all__ = [
     'ANSI_4BIT_RGB',
     'ansi_4bit_to_rgb',
     'ansi_8bit_to_rgb',
-    'hex2rgb',
+    'int2rgb',
     'hexstr2rgb',
     'hsl2rgb',
     'hsv2rgb',
-    'is_hex_rgb',
+    'is_u24',
     'lab2rgb',
     'lab2xyz',
     'nearest_ansi_4bit_rgb',
     'nearest_ansi_8bit_rgb',
-    'rgb2hex',
+    'rgb2int',
     'rgb2hexstr',
     'rgb2hsl',
     'rgb2hsv',
@@ -23,40 +23,69 @@ __all__ = [
     'xyz2rgb',
 ]
 
+from functools import lru_cache
 from operator import mul, truediv
-from typing import Final, Literal, SupportsInt, cast
+from typing import Final, Literal, SupportsInt, TypeGuard
 
 import numpy as np
 
 from .._typing import Float3Tuple, FloatSequence, Int3Tuple, RGBPixel, RGBVectorLike, ShapedNDArray
 
 
-def is_hex_rgb(value, *, strict: bool = False):
-    if issubclass(type(value), SupportsInt):
-        if 0x0 <= int(value) <= 0xFFFFFF:
+@lru_cache
+def _supports_int(typ: type) -> TypeGuard[type[SupportsInt]]:
+    return issubclass(typ, SupportsInt)
+
+
+def is_u24(value, *, strict: bool = False):
+    """Check if value is an unsigned 24-bit integer.
+
+    Parameters
+    ---------
+    value
+        Input number
+    strict : bool
+        Whether to return False or raise ValueError on failure
+
+    Raises
+    ------
+    ValueError
+        Raised when `strict=True` and value is not u24
+    """
+    if _supports_int(type(value)):
+        if 0 <= int(value) <= 0xFFFFFF:
             return True
         elif not strict:
             return False
-    raise TypeError(f"{value!r} is not a valid RGB color") from None
+    raise ValueError(f"{value!r} is not u24")
 
 
 def hexstr2rgb(__str: str) -> Int3Tuple:
-    if is_hex_rgb(value := int(__str, 16), strict=True):
-        return hex2rgb(value)
+    n = len(__str)
+    if n % 4 == 0:  # trunc alpha
+        n *= 3
+        n //= 4
+        __str = __str[:n]
+    if n == 3:  # rgb -> rrggbb
+        __str = ''.join(c * 2 for c in __str)
+    if is_u24(value := int(__str, 16), strict=True):
+        return int2rgb(value)
 
 
 def rgb2hexstr(rgb: RGBVectorLike) -> str:
-    r, g, b = rgb
-    return f'{r:02x}{g:02x}{b:02x}'
+    return "%02x%02x%02x" % tuple(rgb)
 
 
-def rgb2hex(rgb: RGBVectorLike) -> int:
+def rgb2int(rgb: RGBVectorLike) -> int:
     r, g, b = map(int, rgb)
     return r << 16 | g << 8 | b
 
 
-def hex2rgb(value: int) -> Int3Tuple:
-    return (value >> 16) & 0xFF, (value >> 8) & 0xFF, value & 0xFF
+def int2rgb(__x: int) -> Int3Tuple:
+    try:
+        return getattr(__x, 'rgb')
+    except AttributeError:
+        return (__x >> 16) & 0xFF, (__x >> 8) & 0xFF, __x & 0xFF
 
 
 def xyz2lab(xyz: FloatSequence) -> Float3Tuple:
@@ -78,7 +107,7 @@ def lab2xyz(lab: FloatSequence) -> Float3Tuple:
     x, y, z = map(
         mul,
         (95.047, 100.0, 108.883),
-        map(lambda n: (lambda c: c if c > 0.008856 else (n - 16 / 116) / 7.787)(n**3), (x, y, z)),
+        map(lambda i: (lambda j: j if j > 0.008856 else (i - 16 / 116) / 7.787)(i**3), (x, y, z)),
     )
     return x, y, z
 
@@ -104,41 +133,30 @@ def xyz2rgb(xyz: ShapedNDArray[tuple[Literal[3]], np.float64]) -> Int3Tuple:
 
 def hsl2rgb(hsl: FloatSequence) -> Int3Tuple:
     h, s, L = hsl
-    h = (h / 360) % 1
+    h /= 360
+    h %= 1
     if h < 0:
         h += 1
-    r = g = b = L
     v = (L * (1.0 + s)) if L <= 0.5 else (L + s - L * s)
-    if v > 0:
+    if v > 0 and 0 <= (sextant := int(h)) <= 5:
         m = L + L - v
         sv = (v - m) / v
         h *= 6.0
-        sextant = int(h)
-        fract = h - sextant
-        vsf = v * sv * fract
+        vsf = v * sv * (h - sextant)
         mid1 = m + vsf
         mid2 = v - vsf
-        if sextant == 0:
-            r, g, b = v, mid1, m
-        elif sextant == 1:
-            r, g, b = mid2, v, m
-        elif sextant == 2:
-            r, g, b = m, v, mid1
-        elif sextant == 3:
-            r, g, b = m, mid2, v
-        elif sextant == 4:
-            r, g, b = mid1, m, v
-        elif sextant == 5:
-            r, g, b = v, m, mid2
-        r, g, b = (round(x * 255) for x in (r, g, b))
+        r, g, b = (
+            round(x * 0xFF)
+            for x in [[v, mid1, m], [mid2, v, m], [m, v, mid1], [m, mid2, v], [mid1, m, v]][sextant]
+        )
     else:
-        r, g, b = (round(L * 255) for _ in range(3))
+        r, g, b = [round(L * 0xFF)] * 3
     return r, g, b
 
 
 def rgb2hsl(rgb: RGBVectorLike) -> Float3Tuple:
     r, g, b = (x / 255.0 for x in rgb)
-    m, v = sorted([r, g, b])[::2]
+    m, _, v = sorted([r, g, b])
     L = (m + v) / 2
     h = s = 0
     if L > 0:
@@ -245,7 +263,7 @@ def ansi_4bit_to_rgb(value: int):
     return ANSI_4BIT_RGB[value]
 
 
-def _4b_lookup():
+def _4b_lookup() -> dict[Int3Tuple, Int3Tuple]:
     def rgb_dist(rgb, ansi):
         r_mean = (rgb[:, 0:1] + ansi[:, 0]) / 2
         r_diff = (rgb[:, 0:1] - ansi[:, 0]) * (2 + r_mean / 256)
@@ -257,12 +275,11 @@ def _4b_lookup():
     quants = np.stack(
         np.meshgrid(*np.repeat(np.arange(32).reshape([1, -1]), 3, 0), indexing='ij'), axis=-1
     ).reshape([-1, 3])
-    rgb_colors = quants * 8
-    nearest_colors = rgb_4b_arr[np.argmin(rgb_dist(rgb_colors, rgb_4b_arr), axis=1)]
-    table = {
+    nearest_colors = rgb_4b_arr[np.argmin(rgb_dist(quants * 8, rgb_4b_arr), axis=1)]
+    table: dict = {
         tuple(map(int, color)): tuple(map(int, nearest_colors[i])) for i, color in enumerate(quants)
     }
-    return cast(dict[Int3Tuple, Int3Tuple], table)
+    return table
 
 
 ANSI_4BIT_RGB_MAP = _4b_lookup()