laser-prynter 0.2.5__py3-none-any.whl

laser_prynter/bench.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+'''
+A wee utility that I use to benchmark katas
+author: github.com/tmck-code
+
+usage:
+
+func_groups = [
+    [f1,f2],
+    [f3,f4,f5],
+    [f6],
+]
+tests = [
+    ( (arg1, arg2), {}, result1, ),
+    ( (arg3, arg4), {}, result2, ),
+]
+
+bench.bench(
+    tests=tests,
+    func_groups=func_groups,
+    n=100_000,
+    sort=('BENCH_SORT' in os.environ)
+)
+'''
+
+from collections import Counter, namedtuple
+from functools import lru_cache, wraps
+from itertools import chain, repeat
+import operator
+import pickle
+import time, sys, os
+from typing import Callable, Any
+import statistics
+
+from laser_prynter import pp
+
+Test = namedtuple('Test', 'args kwargs expected n')
+class NoExpectation:
+    'Denotes that a test/benchmark has no expected result (i.e. just benchmark it)'
+
+def set_function_module(func):
+    'Set the module of a function'
+    if func.__module__ != '__main__':
+        return
+    module = sys.modules[func.__module__]
+    if hasattr(module, '__file__'):
+        # if the function is defined in the main module, set the module to the filename
+        func.__module__ = os.path.basename(str(module.__file__)).split('.')[0]
+    else:
+        # if the module is not a file, set the module to the current directory
+        func.__module__ = os.path.basename(os.getcwd())
+
+@lru_cache
+def _load_serialised_args(serialised_args):
+    return pickle.loads(serialised_args)
+
+def timeit_func(func, args, kwargs, expected: object = NoExpectation, n: int = 10_000):
+    'Time a function with arguments and return the result, whether it is correct, and the times'
+
+    if os.environ.get('DEBUG'):
+        pp.ppd({'func': func, 'args': args, 'kwargs': kwargs, 'expected': expected, 'n': n})
+
+    start, times = 0, Counter()
+    # some functions may modify the input arguments, so a new copy is needed for every test
+    # "pickle" is used instead of "deepcopy" as it's much faster
+    args_ser = pickle.dumps(args)
+    # ensure that the function module is meaningful (replace it if it's just "__main__")
+    set_function_module(func)
+    for _ in range(n):
+        try:
+            start = time.time()
+            func(*_load_serialised_args(args_ser), **kwargs)
+        except Exception:
+            pass
+        finally:
+            times[time.time()-start] += 1
+    try:
+        result = func(*pickle.loads(args_ser), **kwargs)
+    except Exception as e:
+        result = e
+    return result, expected is NoExpectation or result == expected, times
+
+def _sum_times(times: Counter) -> float:
+    'sum the values*counts in a Counter'
+    return sum(map(operator.mul, *zip(*times.items())))
+
+def _avg_times(times: Counter) -> float:
+    return _sum_times(times) / times.total()
+
+def _median_times(times: Counter) -> float:
+    return statistics.median(list(times.elements()))
+
+TEST_STATUS = {
+    False: pp.ps('fail', 'red'),
+    True:  pp.ps('pass', 'green'),
+}
+TRUNCATE = 40
+
+def _truncate(s: str, n: int=TRUNCATE) -> str:
+    'Truncate a string to n characters'
+    if len(s) <= n:
+        return s
+    return s[:n-10] + '...' + str(s)[-10:]
+
+def _format_time(i: float) -> str:
+    '''
+    Format a time in seconds to a human-readable string, rounding to the nearest unit
+    e.g. 0.0000001 -> "100 ns"
+    Uses chars from the "mathematical italic small" unicode block for the units
+    '''
+    unit = 's'
+    for u in ('s ', '𝑚s', '𝜇s', '𝑛s'):
+        if i >= 1:
+            unit = u
+            break
+        i = i*10**3
+    return f'{i:7.03f} {unit}'
+
+RECORD_SEP = '│'
+BORDER_SEP = '─'
+HEADER_SEP = '┆'
+BORDER_END, BORDER_PATTERN = '★', '-⎽__⎽-⎻⎺⎺⎻'
+
+def gen_border():
+    w = os.get_terminal_size().columns
+    n = int(w/len(BORDER_PATTERN))
+    r = max(int(n%len(BORDER_PATTERN)/2)-1, 0)
+    b = (f'{BORDER_END}{" "*r}{BORDER_PATTERN*n}{" "*r}{BORDER_END}'
+        f'\n{BORDER_SEP*w}')
+    return b
+
+
+def _print_header(s: str, test: Test) -> None:
+    'Print the result of a timed test'
+    print('\n{s:s}{border:s}\n\n{n_s:s}: {n:,d}, {args_s:s}: {args:20s}{kwargs_s:s}: {kwargs:20s}\n'.format(**{
+        's':        s,
+        'border':   pp.ps(gen_border(), 'brightyellow'),
+        'n_s':      pp.ps('n', 'bold'),
+        'n':        test.n,
+        'args_s':   pp.ps('args', 'bold'),
+        'args':     _truncate(str(test.args)+', '),
+        'kwargs_s': pp.ps('kwargs', 'bold'),
+        'kwargs':   _truncate(str(test.kwargs)),
+    }))
+
+def _print_result_header(width: int=1) -> None:
+    msg = '{funcs:s}{status:<5s} {sep:s} {total:^10s} {sep:s} {median:^10s}'.format(**{
+        'funcs':  f'{"function":<{width}s}'.format('function'),
+        'status': 'status',
+        'total':  'Σ ',
+        'median': 'x̄',
+        'sep':     HEADER_SEP,
+    })
+    border = BORDER_SEP*len(msg)
+    print(msg, border, sep='\n')
+
+def _print_result(func: Callable, result: Any, correct: bool, times: Counter, width: int=1, colour: str='', extra: str='') -> None:
+    fail_sep, status_msg = '\n', ''
+    if not correct:
+        if os.get_terminal_size().columns >= 100:
+            fail_sep = ' '
+        result = _truncate(str(result))
+        status_msg = pp.ps(f'{fail_sep}>> {result=}', 'yellow')
+
+    msg = '{func_name:s}{status:<s}   {sep:s} {total:s} {sep:s} {median:s} {extra:s}{status_msg:s}'.format(**{
+        'func_name':  pp.ps(f'{func.__module__+"."+func.__name__+", ":<{width}s}', style=colour),
+        'total':      _format_time(_sum_times(times)),
+        'median':     _format_time(_median_times(times)),
+        'status':     TEST_STATUS[correct],
+        'extra':      extra,
+        'status_msg': status_msg,
+        'width':      width+2,
+        'sep':        RECORD_SEP,
+    })
+    print(msg)
+
+
+def timeit(n=10_000):
+    'Decorator to time a function'
+    def decorator_with_args(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            result, correct, times = timeit_func(func, args, kwargs, NoExpectation, n)
+            _print_result(func, result, correct, times)
+        return wrapper
+    return decorator_with_args
+
+
+def bench(tests, func_groups, n: int=10_000, sort: bool=False):
+    'Run a series of timed tests on a list of functions'
+    s, group_colours = '', ['yellow', 'brightred', 'cyan', 'bold']
+
+    if os.environ.get('DEBUG'):
+        pp.ppd({'tests': tests, 'func_groups': func_groups, 'n': n, 'sort': sort}, indent=None)
+    for func_group in func_groups:
+        for func in func_group:
+            set_function_module(func)
+    width = max(len(func.__module__)+len(func.__name__)+3 for func in chain.from_iterable(func_groups))
+
+    if 'BENCH_SORT' in os.environ:
+        sort = True
+
+    for test in tests:
+        test, results = Test(*test, n=n), []
+        _print_header(s, test)
+        pp.pps('results:', 'bold')
+        _print_result_header(width)
+        for funcs, group_colour in zip(func_groups, group_colours):
+            for func in funcs:
+                result, correct, times = timeit_func(func, *test)
+                _print_result(func, result, correct, times, width, group_colour)
+                results.append((func, result, correct, times, width, group_colour))
+        if sort:
+            pp.pps('\nsorted by time:', 'bold')
+            _print_result_header(width)
+            base, extra = 0, ''
+
+            for _, results in enumerate(sorted(results, key=lambda r: _median_times(r[3]))):
+                if not results[2]:
+                    continue
+                if base == 0:
+                    base = _median_times(results[3])
+                else:
+                    x = _median_times(results[3]) / base
+                    extra = pp.ps(f' ↓ x{x:.2f}', 'bold')
+                _print_result(*results, extra=extra)
+        s = '\n'

laser_prynter/colour/c.py

@@ -0,0 +1,104 @@
+'This module contains functions for converting between RGB and ANSI colour codes.'
+
+from __future__ import annotations
+from types import MappingProxyType
+from typing import Literal, TypeAlias, NamedTuple, Any, Tuple
+
+# Valid components of an RGB tuple.
+_RGB_COMPONENT: TypeAlias = Literal['r', 'g', 'b']
+_RGB_COMPONENTS: Tuple[_RGB_COMPONENT,
+                       _RGB_COMPONENT, _RGB_COMPONENT] = ('r', 'g', 'b')
+
+# Multipliers for each component of the RGB tuple in the ANSI colour code formula.
+_RGB_COMPONENT_MULTIPLIER: MappingProxyType[_RGB_COMPONENT, int] = MappingProxyType({
+    'r': 36,
+    'g': 6,
+    'b': 1
+})
+
+
+# component _must_ be one of 'r', 'g', or 'b'
+def _ansi_to_rgb_component(n: int, component: _RGB_COMPONENT) -> int:
+    '''
+    Reverses the rgb_to_ansi formula to calculate a specific component of the RGB tuple
+    given an ANSI colour code, and the component to calculate.
+
+    n = 16 + (36 * r) + (6 * g) + (1 * b)
+    '''
+    if n < 16 or n >= 232:
+        return 0
+        # raise ValueError(f'Invalid ANSI colour code for RGB conversion: {n}')
+
+    i = (
+        (n - 16)  # 16 is the base value
+                  # divide by 36/6/1
+        // _RGB_COMPONENT_MULTIPLIER[component]
+        % 6       # each value can be 0-5
+    )
+    if i == 0:
+        return 0
+    # I have nfi what this does, but it is crucial
+    return (14135 + (10280 * i)) // 256
+
+
+def ansi_to_rgb(n: int) -> tuple[int, int, int]:
+    'Reverses the rgb_to_ansi formula to calculate an RGB tuple given an ANSI colour code.'
+    return (
+        _ansi_to_rgb_component(n, 'r'),
+        _ansi_to_rgb_component(n, 'g'),
+        _ansi_to_rgb_component(n, 'b'),
+    )
+
+
+def cube_coords_to_ansi(r: int, g: int, b: int) -> int:
+    ''''
+    The golden formula. Via https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit:
+      0-  7:  standard colors (as in ESC [ 30–37 m)
+      8- 15:  high intensity colors (as in ESC [ 90–97 m)
+     16-231:  6 × 6 × 6 cube (216 colors): 16 + 36 × r + 6 × g + b (0 ≤ r, g, b ≤ 5)
+    232-255:  grayscale from dark to light in 24 steps
+    '''
+    return 16 + (
+        r * _RGB_COMPONENT_MULTIPLIER['r'] +
+        g * _RGB_COMPONENT_MULTIPLIER['g'] +
+        b * _RGB_COMPONENT_MULTIPLIER['b']
+    )
+
+
+# Valid (supported) ANSI styles.
+_ANSI_STYLES: TypeAlias = Literal['fg', 'bg']
+_ANSI_ESCAPE_CODES: MappingProxyType[_ANSI_STYLES, str] = MappingProxyType({
+    'fg': '38;5',
+    'bg': '48;5',
+})
+
+RESET: str = '\033[0m'
+
+
+class ANSIColour(NamedTuple):
+    'Represents a terminal colour in both RGB and ANSI formats.'
+    ansi_n: int
+    rgb: tuple[int, int, int]
+
+    def __escape(self, escape: str) -> str:
+        'Returns an ANSI escape code for setting the colour.'
+        return f'\033[{escape};{self.ansi_n}m'
+
+    def escape_code(self, style: _ANSI_STYLES) -> str:
+        'Returns the ANSI escape code for setting the colour.'
+        return self.__escape(_ANSI_ESCAPE_CODES[style])
+
+    def colorise(self, text: Any, style: _ANSI_STYLES = 'bg') -> str:
+        'Returns the text with the colour applied.'
+        return f'{self.escape_code(style)}{text}{RESET}'
+
+
+def from_cube_coords(r: int, g: int, b: int) -> ANSIColour:
+    'Creates an ANSIColour from an RGB tuple.'
+    ansi = cube_coords_to_ansi(r, g, b)
+    return ANSIColour(rgb=ansi_to_rgb(ansi), ansi_n=ansi)
+
+
+def from_ansi(n: int) -> ANSIColour:
+    'Creates an ANSIColour from an ANSI colour code.'
+    return ANSIColour(ansi_n=n, rgb=ansi_to_rgb(n))

laser_prynter/colour/gradient.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+from itertools import repeat
+from itertools import chain
+from dataclasses import dataclass, field
+from itertools import starmap
+from functools import partial
+import operator
+import os
+import re
+from typing import List, TypeAlias, Iterable, Literal, Iterator, Dict
+
+from laser_prynter.colour import c
+
+Cell: TypeAlias = c.ANSIColour
+Row = List[Cell]
+
+
+@dataclass
+class Face:
+    rows: List[Row]
+    with_rotations: bool = True
+    rotations: List[Face] = field(default_factory=list)
+    flipped_rotations: List[Face] = field(default_factory=list)
+
+    def __post_init__(self):
+        if self.with_rotations:
+            self.rotations = [Face._rot90(
+                self.rows, n, flip=False) for n in range(4)]
+            self.flipped_rotations = [Face._rot90(
+                self.rows, n, flip=True) for n in range(4)]
+
+    @staticmethod
+    def _rot90(rows: List[Row], n: int = 1, flip: bool = False) -> Face:
+        'Rotate a matrix 90 degrees, n times, optionally flipped'
+        if flip:
+            rows = list(reversed(rows))
+        for _ in range(n):
+            rows = list(zip(*rows[::-1]))
+        return Face(rows, with_rotations=False)
+
+    def rot90(self, n: int = 1, flip: bool = False) -> Face:
+        'Rotate a matrix 90 degrees, n times, optionally flipped'
+        if flip:
+            return self.flipped_rotations[n]
+        return self.rotations[n]
+
+    def __iter__(self) -> Iterator[Row]:
+        yield from self.rows
+
+    def __next__(self) -> Row:
+        return next(self.__iter__())
+
+    def __getitem__(self, i: int) -> Row:
+        return self.rows[i]
+
+    @staticmethod
+    def empty_face(width: int = 6) -> Face:
+        return Face([[c.from_ansi(256)] * width] * width)
+
+    def iter_s(self, padding_top: int = 0, padding_bottom: int = 0, cell_width: int = 15) -> Iterable[str]:
+        for row in self.__iter__():
+            p = [cell.colorise(' '*cell_width) for cell in row]
+            # r = [cell.colorise(f'{cell.ansi_n:^{cell_width}}') for cell in row]
+            r = [cell.colorise(f'{str(cell.rgb):^{cell_width}}')
+                 for cell in row]
+
+            for row in chain(repeat(p, padding_top), [r], repeat(p, padding_bottom)):
+                yield ''.join(row)
+
+    def print(self, padding_top: int = 0, padding_bottom: int = 0, cell_width: int = 6) -> None:
+        'Print the face, with optional cell padding top/bottom to make it more "square"'
+
+        print('\n'.join(self.iter_s(padding_top, padding_bottom, cell_width)))
+
+
+ANSI_COLOURS = re.compile(r"""
+    \x1b     # literal ESC
+    \[       # literal [
+    [;\d]*   # zero or more digits or semicolons
+    [A-Za-z] # a letter
+    """, re.VERBOSE)
+
+
+@dataclass
+class Faces:
+    faces: list[list[Face]]
+
+    def __iter__(self) -> Iterator[Face]:
+        for face_row in self.faces:
+            for face in face_row:
+                yield face
+
+    def __next__(self) -> Face:
+        return next(self.__iter__())
+
+    def iter_rows(self) -> Iterable[Row]:
+        for face_row in self.faces:
+            for row in zip(*face_row):
+                yield row
+
+    def iter_s(self, padding_top: int = 0, padding_bottom: int = 0, cell_width: int = 6) -> Iterable[str]:
+        for face_row in self.faces:
+            for row in zip(*[face.iter_s(padding_top, padding_bottom, cell_width) for face in face_row]):
+                yield ''.join(row)
+
+    def as_str(self, padding_top: int = 0, padding_bottom: int = 0, cell_width: int = 6) -> str:
+        s = ''
+        for row in self.iter_s(padding_top, padding_bottom, cell_width):
+            s += row + '\n'
+        return s
+
+    def print(self, padding_top: int = 0, padding_bottom: int = 0, cell_width: int = 6) -> None:
+        'Print the faces of the cube, with optional cell padding top/bottom to make it more "square"'
+
+        print(self.as_str(padding_top, padding_bottom, cell_width))
+
+
+def distance(c1: tuple[int, int, int], c2: tuple[int, int, int]) -> float:
+    return abs(sum(starmap(operator.sub, zip(c2, c1))))
+
+# In[69]: c1, c2 = (95, 135, 0), (0, 135, 255)
+# r = interp_xyz(c1, c2, 20)
+
+
+def lerp(v0: float, v1: float, t: int) -> float:
+    '''
+    Precise method for iterpolation, which guarantees v = v1 when t = 1.
+    This method is monotonic only when v0 * v1 < 0.
+    Lerping between same values might not produce the same value
+    (from: https://en.wikipedia.org/wiki/Linear_interpolation#Programming_language_support)
+    '''
+    return round((1 - (t/10)) * v0 + (t/10) * v1, 2)
+
+
+def interp(v0: float, v1: float, n_t: int) -> list[float]:
+    i = partial(lerp, v0, v1)
+    ts = list(map(lambda x: x/((n_t-1)/10), range(0, n_t)))
+    return list(map(i, ts))
+
+
+def interp_xyz(c1: tuple[int, int, int], c2: tuple[int, int, int], n_t: int) -> list[float]:
+    return list(zip(*starmap(interp, zip(c1, c2, repeat(n_t)))))
+
+
+@dataclass
+class RGBCube:
+    faces: Faces
+    width: int = 6
+
+    def print(self) -> None:
+        self.faces.print()
+
+    @property
+    def str_width(self) -> int:
+        return max(len(ANSI_COLOURS.sub('', line)) for line in self.faces.iter_s())
+
+    @staticmethod
+    def compare_rows(r1: Row, r2: Row) -> bool:
+        return all(c1 == c2 for c1, c2 in zip(r1, r2))
+
+    def find_face_with_edge(self, face: Face, edge_type: str = 'ts') -> Face:
+        if edge_type == 'ts':
+            edge = face[0]
+        elif edge_type == 'bs':
+            edge = face[-1]
+        elif edge_type == 'lhs':
+            edge = [r[0] for r in face]
+        elif edge_type == 'rhs':
+            edge = [r[-1] for r in face]
+
+        for face in self.faces:
+            for rot in range(4):
+                for flip in (False, True):
+                    if edge_type == 'ts' and RGBCube.compare_rows(face.rot90(rot, flip=flip)[-1], edge):
+                        return face.rot90(rot, flip=flip)
+                    elif edge_type == 'bs' and RGBCube.compare_rows(face.rot90(rot, flip=flip)[0], edge):
+                        return face.rot90(rot, flip=flip)
+                    elif edge_type == 'lhs' and RGBCube.compare_rows([r[-1] for r in face.rot90(rot, flip=flip)], edge):
+                        return face.rot90(rot, flip=flip)
+                    elif edge_type == 'rhs' and RGBCube.compare_rows([r[0] for r in face.rot90(rot, flip=flip)], edge):
+                        return face.rot90(rot, flip=flip)
+
+    @staticmethod
+    def from_ranges(c1: Literal[c._RGB_COMPONENT], c2: c._RGB_COMPONENT, c3: c._RGB_COMPONENT) -> RGBCube:
+        '''
+        Create a 6x6x6 cube of RGB values, where each face is a 6x6 grid of cells.
+        Takes an 'order' of RGB components, where
+        - c1 is iterated once per face
+        - c2 is iterated once per row
+        - c3 is iterated once per cell
+        '''
+        faces = []
+        for r1 in range(6):
+            face = []
+            for r2 in range(6):
+                row = []
+                for r3 in range(6):
+                    row.append(
+                        c.from_cube_coords(**{c1: r1, c2: r2, c3: r3})
+                    )
+                face.append(row)
+            faces.append([Face(face)])
+        return RGBCube(Faces(faces))
+
+
+@dataclass
+class RGBCubeCollection:
+    cubes: Dict[str, RGBCube]
+
+    def __post_init__(self):
+        self.width = os.get_terminal_size().columns
+
+    def print(self, grid_sep: str = ' '*2, padding_top: int = 0, padding_bottom: int = 0, cell_width: int = 6) -> None:
+        groups, current_group, current_width = [], {}, 0
+        for name, cube in self.cubes.items():
+            if sum(c.str_width for c in current_group.values()) + cube.str_width <= self.width:
+                current_group[name] = cube
+            else:
+                groups.append(current_group)
+                current_group = {name: cube}
+        groups.append(current_group)
+
+        for g in groups:
+            for name, c in g.items():
+                print(f'{name:<{c.str_width}s}', end=grid_sep)
+            print()
+            for rows in zip(*[c.faces.iter_s(padding_top, padding_bottom, cell_width) for n, c in g.items()]):
+                print(grid_sep.join(rows))
+
+def find_face_with_edge(collection: RGBCubeCollection, face_name: str, face: Face, edge_type: str) -> Face:
+    for n, cube in collection.cubes.items():
+        if n == face_name:
+            continue
+        f = cube.find_face_with_edge(face, edge_type)
+        if f:
+            return f, n
+
+
+def create_cube(f1, f1_name, cube_collection):
+    f2, f2_name = find_face_with_edge(cube_collection, f1_name, f1, 'lhs')
+    f3, f3_name = find_face_with_edge(cube_collection, f1_name, f1, 'bs')
+    f4, f4_name = find_face_with_edge(cube_collection, f1_name, f1, 'ts')
+    f5, f5_name = find_face_with_edge(cube_collection, f3_name, f3, 'rhs')
+    f6, f6_name = find_face_with_edge(cube_collection, f3_name, f3, 'bs')
+
+    faces = [
+        [Face.empty_face(6), f4, Face.empty_face(6)],
+        [f2,                          f1, Face.empty_face(6)],
+        [Face.empty_face(6), f3, f5],
+        [Face.empty_face(6), f6, Face.empty_face(6)],
+    ]
+    Faces(faces).print(padding_top=0, padding_bottom=1, cell_width=15)
+
+    c1 = f2[2][3].rgb
+    c2 = f4[2][3].rgb
+
+    print(f'c1: {c1}, c2: {c2}')
+
+    g = interp_xyz(c1, c2, 10)
+    for r, g, b in g:
+        print(
+            '\033[48;5;{};{};{}m'.format(
+                int(r), int(g), int(b)
+            ) + f'{str((r, g, b)):^10s}' + '\033[0m'
+        )
+        # print(c.from_rgb(r, g, b).colorise(' '*8))

laser_prynter/log.py

@@ -0,0 +1,171 @@
+'''
+A module to create loggers with custom handlers and a custom formatter.
+
+usage examples to initialise a logger:
+    ```python
+    # 1. initialise logger to stderr:
+    logger = getLogger('my_logger', level=logging.DEBUG, stream=sys.stderr)
+
+    # 2. initialise logger to file:
+    logger = getLogger('my_logger', level=logging.DEBUG, filename='my_log.log')
+
+    # 3. initialise logger to both stderr and file:
+    logger = getLogger('my_logger', level=logging.DEBUG, stream=sys.stderr, files={LogLevel.INFO: 'info.log'})
+    ```
+
+usage examples to log messages:
+    ```python
+    logger.info('This is a basic info message')
+    # {"timestamp": "2024-12-09T15:05:43.904417+10:00", "msg": "This is a basic info message", "event": {}}
+
+    logger.info('This is an info message', {'key': 'value'})
+    # {"timestamp": "2024-12-09T15:05:43.904600+10:00", "msg": "This is an info message", "event": {"key": "value"}}
+
+    logger.debug('This is a debug message', 'arg1', 'arg2', {'key': 'value'})
+    # {"timestamp": "2024-12-09T15:05:43.904749+10:00", "msg": "This is a debug message", "event": {"args": ["arg1", "arg2"], "key": "value"}}
+    ```
+'''
+
+from datetime import datetime
+import io
+import json
+import logging
+from logging.handlers import  TimedRotatingFileHandler
+import os
+import sys
+
+from laser_prynter.pp import _json_default
+
+class LogLevel:
+    'An enum type for log levels.'
+    CRITICAL = logging.CRITICAL
+    ERROR    = logging.ERROR
+    WARNING  = logging.WARNING
+    INFO     = logging.INFO
+    DEBUG    = logging.DEBUG
+    NOTSET   = logging.NOTSET
+
+
+DEFAULT_LOG_LEVEL = LogLevel.INFO
+
+class LogFormatter(logging.Formatter):
+    'Custom log formatter that formats log messages as JSON, aka "Structured Logging".'
+    def __init__(self, defaults: dict = {}):
+        '''
+        Initializes the log formatter with optional default context.
+        - `defaults` is a dictionary of default context values to include in every log message.
+        '''
+        self.defaults = defaults
+        super().__init__()
+
+    def format(self, record) -> str:
+        'Formats the log message as JSON.'
+
+        args, kwargs = None, {}
+        if isinstance(record.args, tuple):
+            if len(record.args) == 1:
+                args = record.args
+            elif len(record.args) > 1:
+                *args, kwargs = record.args
+        elif isinstance(record.args, dict):
+            kwargs = record.args
+
+        record.msg = json.dumps(
+            {
+                'timestamp': datetime.now().astimezone().isoformat(),
+                'level':     record.levelname,
+                'name':      record.name,
+                'msg':       record.msg,
+                'event':     {'args': args} if args else {} | kwargs or {},
+                **({'context': self.defaults} if self.defaults else {}),
+            },
+            default=_json_default,
+        )
+        record.args = ()
+        return super().format(record)
+
+
+def _getLogger(
+    name:     str,
+    level:    int                   = logging.CRITICAL,
+    handlers: list[logging.Handler] = [],
+    context:  dict                  = {},
+) -> logging.Logger:
+    '''
+    Creates a logger with the given name, level, and handlers.
+    - If no handlers are provided, the logger will not output any logs.
+    - This function requires the handlers to be initialized when passed as args.
+    - the same log level is applied to all handlers.
+    '''
+
+    # create the root logger
+    logger = logging.getLogger()
+    logger.setLevel(level)
+
+    # close/remove any existing handlers
+    while logger.handlers:
+        for handler in logger.handlers:
+            handler.close()
+            logger.removeHandler(handler)
+
+    # create the logger
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+
+    # close/remove any existing handlers
+    while logger.handlers:
+        for handler in logger.handlers:
+            handler.close()
+            logger.removeHandler(handler)
+
+    # add the new handlers
+    for handler in handlers:
+        logger.addHandler(handler)
+
+    if logger.handlers:
+        # only set the first handler to use the custom formatter
+        logger.handlers[0].setFormatter(LogFormatter(defaults=context))
+
+    return logger
+
+
+def getLogger(
+    name:     str,
+    level:    int                 = -1,
+    stream:   io.TextIOBase       = sys.stdout,
+    files:    dict[LogLevel, str] = {},
+    context:  dict                = {},
+) -> logging.Logger:
+    '''
+    Creates a logger with the given name, level, and handlers.
+    - `name` is the name of the logger.
+    - `stream` is the output stream for the logger (default is STDERR).
+    - `files` is a dictionary of log levels and filenames for file handlers.
+      - The keys are log levels (e.g., LogLevel.INFO, LogLevel.DEBUG).
+      - The values are the filenames to log to at the corresponding level.
+      - The file handlers will use `TimedRotatingFileHandler` to rotate logs at midnight and keep 7 backups.
+    - `level` is the log level for the logger and all handlers (default is INFO).
+        - if `level` is not provided, it will check the environment variable `LOG_LEVEL` and use its value if it exists
+        - otherwise it defaults to `LogLevel.INFO`.
+    '''
+
+    if level == -1:
+        if 'LOG_LEVEL' in os.environ:
+            level = getattr(logging, os.environ['LOG_LEVEL'].upper())
+        else:
+            level = DEFAULT_LOG_LEVEL
+
+    handlers = []
+    if stream:
+        handler = logging.StreamHandler(stream)
+        handler.setLevel(level)
+        handlers.append(handler)
+
+    for flevel, filename in files.items():
+        handler = TimedRotatingFileHandler(
+            filename, when='midnight', backupCount=7, encoding='utf-8',
+        )
+        handler.setLevel(flevel)
+        handlers.append(handler)
+
+    return _getLogger(name, level, handlers, context=context)

laser_prynter/pp.py

@@ -0,0 +1,75 @@
+from dataclasses import asdict, is_dataclass, dataclass
+from datetime import datetime
+import json
+import random
+from types import FunctionType
+
+from pygments import highlight, console
+from pygments.lexers import JsonLexer, OutputLexer
+from pygments.formatters import Terminal256Formatter
+from pygments.styles import get_style_by_name, get_all_styles
+
+STYLES = (
+    'dracula', 'fruity', 'gruvbox-dark', 'gruvbox-light', 'lightbulb', 'material', 'native',
+    'one-dark', 'perldoc', 'tango',
+)
+
+def _isnamedtuple(obj: object):
+    return isinstance(obj, tuple) and hasattr(obj, '_fields')
+
+def _normalise(obj: object):
+    'step through obj and normalise namedtuples to dicts'
+    if isinstance(obj, dict): return {k: _normalise(v) for k, v in obj.items()}
+    if isinstance(obj, list): return [_normalise(i) for i in obj]
+    if _isnamedtuple(obj):    return obj._asdict()
+    return obj
+
+def _json_default(obj: object):
+    'Default JSON serializer, supports most main class types'
+    if   isinstance(obj, str):          return obj # str
+    elif isinstance(obj, list):         return [_json_default(i) for i in obj]
+    elif is_dataclass(obj):             return asdict(obj) # dataclass
+    elif isinstance(obj, datetime):     return obj.isoformat() # datetime
+    elif isinstance(obj, FunctionType): return f'{obj.__name__}()' # function
+    elif hasattr(obj, '__slots__'):     return {k: getattr(obj, k) for k in obj.__slots__} # class with slots.
+    elif hasattr(obj, '__name__'):      return obj.__name__ # function/class name
+    elif hasattr(obj, '__dict__'):      return obj.__dict__ # class
+    return str(obj)
+
+def ppd(d_obj, indent=2, style='dracula', random_style=False):
+    'pretty-print a dict'
+    d = _normalise(d_obj) # convert any namedtuples to dicts
+
+    if random_style:
+        style = random.choice(STYLES)
+    code = json.dumps(d, indent=indent, default=_json_default)
+
+    if style is None:
+        print(code)
+    else:
+        print(highlight(
+            code      = code,
+            lexer     = JsonLexer(),
+            formatter = Terminal256Formatter(style=get_style_by_name(style))
+        ).strip())
+
+def ppj(j: str, indent: int=None, style: str='dracula', random_style: bool=False) -> None:
+    'pretty-print a JSON string'
+    ppd(json.loads(j), indent=indent, style=style, random_style=random_style)
+
+def ps(s: str, style: str='yellow', random_style: bool=False) -> str:
+    'add color to a string'
+    if random_style:
+        style = random.choice(console.dark_colors + console.light_colors)
+    return console.colorize(style, s)
+
+def pps(s: str, style: str='yellow', random_style: bool=False) -> None:
+    'pretty-print a string'
+    print(ps(s, style=style, random_style=random_style))
+
+def demo() -> None:
+    'demonstrate pretty-printing colours'
+
+    for s in STYLES:
+        ppd({'message': {'Hello': 'World', 'The answer is': 42}, 'style': s}, style=s, indent=None)
+

laser_prynter-0.2.5.dist-info/METADATA

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: laser-prynter
+Version: 0.2.5
+Summary: terminal/cli/python helpers for colour and pretty-printing
+Author-email: tmck-code <tmck01@gmail.com>
+Project-URL: Homepage, https://github.com/tmck-code/laser-prynter
+Project-URL: Issues, https://github.com/tmck-code/laser-prynter/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygments>=2.19.2
+Dynamic: license-file
+
+# laser-prynter
+terminal/cli/python helpers for colour and pretty-printing
+
+- [laser_prynter](#laser_prynter)
+  - [`bench`](#bench)
+  - [`laser_prynter`](#laser_prynter-1)
+
+---
+
+## `laser_prynter`
+
+
+https://github.com/user-attachments/assets/cce8f690-e411-459f-a04f-8e9bef533e4a
+
+
+---
+
+## `bench`
+
+
+https://github.com/user-attachments/assets/4af823b0-8d18-4086-9754-c76c65b66898
+
+
+```python
+from laser_prynter import bench
+
+bench.bench(
+    tests=[
+        (
+            (range(2),), # args
+            {},          # kwargs
+            [0,1],       # expected
+        )
+    ],
+    func_groups=[ [list] ],
+    n=100
+)
+```

laser_prynter-0.2.5.dist-info/RECORD

@@ -0,0 +1,12 @@
+laser_prynter/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+laser_prynter/bench.py,sha256=1nmDjp-8QPP6QGAYIGUOgASdmDqk1yM5V2s2ROmeGt4,7679
+laser_prynter/log.py,sha256=BnhFTwTzHskIlLEiZSRgfn51JEzfgd3e4x0_lX-Ad_o,5858
+laser_prynter/pp.py,sha256=HyChRTcpEhFtM5a9dyNWghr9Y1q_HZCPwkNUdsiJX9c,2917
+laser_prynter/colour/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+laser_prynter/colour/c.py,sha256=WYji8YnYef10iwW0iuPLlasqVV5CXNUNlFreYs3LevM,3468
+laser_prynter/colour/gradient.py,sha256=sTjTGNl8rStubVRJ7aYA4e41XZ4tnT_GF8-ZkRatiLg,9472
+laser_prynter-0.2.5.dist-info/licenses/LICENSE,sha256=NIfFgUC076pLuzRpq-VGlQay6_41rkkMaOJfYEN-M7E,1500
+laser_prynter-0.2.5.dist-info/METADATA,sha256=ckNeh8jyP143LBZGroY_jKK650MM9njOHOXSxZLZ_Hw,1214
+laser_prynter-0.2.5.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+laser_prynter-0.2.5.dist-info/top_level.txt,sha256=PG6nRKi_gi_kNhRrI1I91s7Z4hh2wLj7fpDQrp5FaFI,14
+laser_prynter-0.2.5.dist-info/RECORD,,

laser_prynter-0.2.5.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

laser_prynter-0.2.5.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Tom McKeesick
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

laser_prynter-0.2.5.dist-info/top_level.txt

@@ -0,0 +1 @@
+laser_prynter