desklab 0.1.0__py3-none-any.whl

desklab/__init__.py

@@ -0,0 +1,9 @@
+from .primitives import *
+from .areas import *
+from .components import *
+from .containers import *
+from .entity_types import *
+from .listeners import *
+from .media import *
+from .system import *
+from .exceptions import *

desklab/_check/__init__.py

@@ -0,0 +1,10 @@
+from ._value import value_check
+from ._check_operations import (Check, CheckRange,
+                                CheckLength)
+
+__all__ = [
+    'value_check',
+    'Check',
+    'CheckRange',
+    'CheckLength'
+]

desklab/_check/_check_operations/__init__.py

@@ -0,0 +1,9 @@
+from ._check import Check
+from ._range import CheckRange
+from ._length import CheckLength
+
+__all__ = [
+    'Check',
+    'CheckRange',
+    'CheckLength'
+]

desklab/_check/_check_operations/_check.py

@@ -0,0 +1,14 @@
+from typing import Any
+from typing import Any, Callable
+
+
+class Check:
+    def __init__(self, rule: Callable[[Any], bool], description: str | None = None) -> None:
+        self.__rule = rule
+        self.__description = description
+
+    def __call__(self, *args: Any, **kwargs: Any) -> bool:
+        return self.__rule(*args, **kwargs)
+
+    def __str__(self) -> str:
+        return self.__description or self.__rule.__name__

desklab/_check/_check_operations/_length.py

@@ -0,0 +1,33 @@
+from typing import Any
+
+from desklab._check._check_operations import Check
+from desklab.exceptions import InvalidParameterValue
+
+
+class CheckLength(Check):
+
+    def __init__(self, reference_length: int, comparison: str = "=", variable_name: str | None = None) -> None:
+
+        operators = {"=", ">", "<", ">=", "<="}
+        if comparison not in operators:
+            raise InvalidParameterValue(f"comparison", comparison,
+                                        f"'comparison' must be one of: {operators}")
+
+        def compare(value: Any) -> bool:
+            if comparison == "=":
+                return len(value) == reference_length
+            elif comparison == ">":
+                return len(value) > reference_length
+            elif comparison == "<":
+                return len(value) < reference_length
+            elif comparison == ">=":
+                return len(value) >= reference_length
+            elif comparison == "<=":
+                return len(value) <= reference_length
+            raise InvalidParameterValue(f"comparison", comparison,
+                                        f"'comparison' must be one of: {operators}")
+
+        name = variable_name or "Value"
+        message = f"length({name}) {comparison} {reference_length}"
+
+        super().__init__(compare, message)

desklab/_check/_check_operations/_range.py

@@ -0,0 +1,41 @@
+from typing import Any
+from typing import Any, cast
+from desklab.exceptions import MissingParameters
+from desklab._check._check_operations import Check
+from collections.abc import Iterable
+
+
+class CheckRange(Check):
+
+    def __init__(self, min_value: Any = None, max_value: Any = None, variable_name: str | None = None) -> None:
+
+        if min_value is None and max_value is None:
+            raise MissingParameters(["min_value", "max_value"],
+                                    "At least one of 'min_value' or 'max_value' must be provided")
+
+        def is_valid(value: Any) -> bool:
+
+            if isinstance(value, Iterable) and not isinstance(value, (str, bytes)):
+                iterable = cast(Iterable[Any], value)
+                return all(is_valid(v) for v in iterable)
+
+            if min_value is not None and value < min_value:
+                return False
+
+            if max_value is not None and value > max_value:
+                return False
+
+            return True
+
+        name = variable_name or "Value"
+
+        if min_value is not None and max_value is not None:
+            message = f"{name} must be between {min_value} and {max_value}"
+
+        elif min_value is not None:
+            message = f"{name} must be greater than or equal to {min_value}"
+
+        else:
+            message = f"{name} must be less than or equal to {max_value}"
+
+        super().__init__(is_valid, message)

desklab/_check/_value.py

@@ -0,0 +1,31 @@
+import inspect
+from typing import Callable, TypeVar, ParamSpec
+from functools import wraps
+from desklab.exceptions import InvalidParameterValue
+from desklab._check._check_operations import Check
+
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def value_check(**validations: Check) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    def decorator(function: Callable[P, R]) -> Callable[P, R]:
+        signature = inspect.signature(function)
+
+        @wraps(function)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            bound_arguments = signature.bind(*args, **kwargs)
+            bound_arguments.apply_defaults()
+
+            for param_name, param_value in bound_arguments.arguments.items():
+                if param_name in ("self", "cls"):
+                    continue
+                validation_rule = validations.get(param_name)
+                if validation_rule is not None and not validation_rule(param_value):
+                    raise InvalidParameterValue(param_name, param_value,
+                                                str(validation_rule))
+
+            return function(*args, **kwargs)
+        return wrapper
+    return decorator

desklab/_utils/__init__.py

@@ -0,0 +1,10 @@
+from ._geometry import point_to_segment_distance, is_inside_circle
+from ._regex import camel_case_to_snake_case
+from ._imageio_ffmpeg_exe import get_ffmpeg_exe
+
+__all__ = [
+    "point_to_segment_distance",
+    "is_inside_circle",
+    "camel_case_to_snake_case",
+    "get_ffmpeg_exe"
+]

desklab/_utils/_geometry.py

@@ -0,0 +1,36 @@
+import math
+
+
+def point_to_segment_distance(point: tuple[int, int], segment_start: tuple[int, int], segment_end: tuple[int, int]) -> float:
+    point_x, point_y = point
+    start_x, start_y = segment_start
+    end_x, end_y = segment_end
+
+    vector_segment_x = end_x - start_x
+    vector_segment_y = end_y - start_y
+
+    vector_point_x = point_x - start_x
+    vector_point_y = point_y - start_y
+
+    segment_length_squared = vector_segment_x ** 2 + vector_segment_y ** 2
+
+    if segment_length_squared == 0:
+        return math.sqrt((point_x - start_x) ** 2 + (point_y - start_y) ** 2)
+
+    dot_product = vector_point_x * vector_segment_x + \
+        vector_point_y * vector_segment_y
+    projection_ratio = max(0.0, min(1.0, dot_product / segment_length_squared))
+
+    closest_x = start_x + vector_segment_x * projection_ratio
+    closest_y = start_y + vector_segment_y * projection_ratio
+
+    distance_x = point_x - closest_x
+    distance_y = point_y - closest_y
+
+    return math.sqrt(distance_x ** 2 + distance_y ** 2)
+
+
+def is_inside_circle(coordinates: tuple[int, int], circle_center: tuple[int, int], circle_radius: int):
+    x, y = coordinates
+    cx, cy = circle_center
+    return (x - cx)**2 + (y - cy)**2 <= circle_radius**2

desklab/_utils/_imageio_ffmpeg_exe.py

@@ -0,0 +1,163 @@
+# ==============================================================================
+# The following code block or function incorporates code from 'imageio'.
+#
+# Copyright (c) 2019-2025, imageio
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# * 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.
+#
+# 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 HOLD
+
+import os
+import platform
+import subprocess
+import sys
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Optional, no_type_check
+
+FNAME_PER_PLATFORM = {
+    "macos-aarch64": "ffmpeg-macos-aarch64-v7.1",
+    "macos-x86_64": "ffmpeg-macos-x86_64-v7.1",
+    "windows-x86_64": "ffmpeg-win-x86_64-v7.1.exe",
+    "windows-i686": "ffmpeg-win32-v4.2.2.exe",
+    "linux-aarch64": "ffmpeg-linux-aarch64-v7.0.2",
+    "linux-x86_64": "ffmpeg-linux-x86_64-v7.0.2",
+}
+
+
+def _get_os_string() -> str:
+    if sys.platform.startswith("win"):
+        return "windows"
+    elif sys.platform.startswith("darwin"):
+        return "macos"
+    elif sys.platform.startswith("linux"):
+        return "linux"
+    return sys.platform
+
+
+def _get_arch() -> str:
+    is_64_bit = sys.maxsize > 2**32
+    machine = platform.machine()
+
+    if machine == "armv7l":
+        return "armv7"
+    elif is_64_bit and machine.startswith(("arm", "aarch64")):
+        return "aarch64"
+    elif is_64_bit:
+        return "x86_64"
+    return "i686"
+
+
+def _get_platform() -> str:
+    return _get_os_string() + "-" + _get_arch()
+
+
+@no_type_check
+def _popen_kwargs() -> dict[str, Any]:
+    startupinfo = None
+    creationflags = 0
+    if sys.platform.startswith("win"):
+        startupinfo = subprocess.STARTUPINFO()
+        startupinfo.dwFlags |= subprocess.STARTF_USESHOWWINDOW
+    return {
+        "startupinfo": startupinfo,
+        "creationflags": creationflags,
+    }
+
+
+def _is_valid_exe(exe: str) -> bool:
+    cmd = [exe, "-version"]
+    try:
+        with open(os.devnull, "w") as null:
+            subprocess.check_call(
+                cmd, stdout=null, stderr=subprocess.STDOUT, **_popen_kwargs()
+            )
+        return True
+    except (OSError, ValueError, subprocess.CalledProcessError):
+        return False
+
+
+@lru_cache(maxsize=1)
+def _find_ffmpeg_path() -> Optional[Path]:
+    plat = _get_platform()
+    os_str = _get_os_string()
+    expected_filename = FNAME_PER_PLATFORM.get(plat, "ffmpeg")
+
+    possible_paths: list[Path] = []
+    home = Path.home()
+
+    imageio_cache_dir = home / ".imageio" / "ffmpeg"
+    desklab_cache_dir = home / ".desklab" / "ffmpeg"
+
+    possible_paths.extend([
+        imageio_cache_dir / expected_filename,
+        desklab_cache_dir / expected_filename,
+    ])
+
+    prefix_path = Path(sys.prefix)
+    if os_str == "windows":
+        possible_paths.append(prefix_path / "Library" / "bin" / "ffmpeg.exe")
+    else:
+        possible_paths.append(prefix_path / "bin" / "ffmpeg")
+
+    if os_str == "windows":
+        appdata_local = Path(os.environ.get(
+            "LOCALAPPDATA", home / "AppData/Local"))
+        possible_paths.extend([
+            appdata_local / "Microsoft/WindowsApps/ffmpeg.exe",
+            home / "ffmpeg" / "bin" / "ffmpeg.exe",
+            Path("C:/Program Files/ffmpeg/bin/ffmpeg.exe"),
+            Path("C:/ffmpeg/bin/ffmpeg.exe"),
+        ])
+    elif os_str == "macos":
+        possible_paths.extend([
+            Path("/opt/homebrew/bin/ffmpeg"),
+            Path("/usr/local/bin/ffmpeg"),
+            Path("/usr/bin/ffmpeg"),
+            home / "bin" / "ffmpeg",
+        ])
+    elif os_str == "linux":
+        possible_paths.extend([
+            Path("/usr/bin/ffmpeg"),
+            Path("/usr/local/bin/ffmpeg"),
+            Path("/snap/bin/ffmpeg"),
+            home / "bin" / "ffmpeg",
+            home / ".local" / "bin" / "ffmpeg",
+        ])
+
+    for path in possible_paths:
+        if path.is_file() and _is_valid_exe(str(path)):
+            return path
+
+    if _is_valid_exe("ffmpeg"):
+        return Path("ffmpeg")
+
+    return None
+
+
+def get_ffmpeg_exe() -> Path:
+    exe_env = os.getenv("DESKLAB_FFMPEG_EXE") or os.getenv(
+        "IMAGEIO_FFMPEG_EXE")
+    if exe_env:
+        return Path(exe_env)
+
+    detected_path = _find_ffmpeg_path()
+    if detected_path:
+        return detected_path
+
+    raise RuntimeError(
+        "No ffmpeg exe could be found. Install ffmpeg on your system, "
+        "or set the DESKLAB_FFMPEG_EXE environment variable."
+    )

desklab/_utils/_regex.py

@@ -0,0 +1,5 @@
+import re
+
+
+def camel_case_to_snake_case(text: str) -> str:
+    return re.sub(r'(?<!^)(?=[A-Z])', '_', text).lower()

desklab/areas/__init__.py

@@ -0,0 +1,9 @@
+from ._area_interface import AreaInterface
+from ._rectangular_area import RectangularArea
+from ._clickable_area import ClickableArea
+
+__all__ = [
+    "AreaInterface",
+    "RectangularArea",
+    "ClickableArea"
+]

desklab/areas/_area_interface.py

@@ -0,0 +1,17 @@
+from desklab.entity_types import ContainableEntity, DisplayableEntity, CopiableEntity, ColorableEntity
+from desklab.primitives import Color
+from abc import abstractmethod
+
+
+class AreaInterface(ContainableEntity, DisplayableEntity, ColorableEntity, CopiableEntity):
+
+    def __init__(self, width: int, height: int, color: Color | tuple[int, ...] | str = "BLACK") -> None:
+        super().__init__(x=0, y=0, width=width, height=height, color=color)
+
+    @abstractmethod
+    def contains(self, coordinates: tuple[int, int]) -> bool:
+        pass
+
+    def get_rect(self) -> tuple[int, int, int, int]:
+        return (self.get_x(), self.get_y(),
+                self.get_width(), self.get_height())

desklab/areas/_clickable_area.py

@@ -0,0 +1,27 @@
+from typing import Any
+from ._rectangular_area import RectangularArea
+from desklab.entity_types import EventSensitiveEntity
+from desklab.primitives import Color
+from desklab.system import Mouse
+
+
+class ClickableArea(RectangularArea, EventSensitiveEntity):
+
+    def __init__(self, width: int, height: int, color: Color | tuple[int, ...] | str = "BLACK", corners_radius: tuple[int, int, int, int] | int = 0) -> None:
+        super().__init__(width, height, color, corners_radius)
+        self.__is_clicked = False
+        self.__is_held = False
+
+    def is_clicked(self) -> bool:
+        return self.__is_clicked
+
+    def is_held(self) -> bool:
+        return self.__is_held
+
+    def handle_event(self, *args: Any, **kwargs: Any) -> None:
+        super().handle_event(*args, **kwargs)
+        mouse = self._get_from_kwargs(Mouse, kwargs)
+        inside = self.contains(mouse.get_position())
+
+        self.__is_clicked = mouse.is_clicked() and inside
+        self.__is_held = mouse.is_held() and inside

desklab/areas/_rectangular_area.py

@@ -0,0 +1,102 @@
+# fmt: off
+from desklab._check import value_check, CheckRange, CheckLength
+from desklab._utils import is_inside_circle
+from ._area_interface import AreaInterface
+from desklab.primitives import Color
+from typing import Any
+import os
+os.environ['PYGAME_HIDE_SUPPORT_PROMPT'] = "hide"
+import pygame
+from pygame import Surface
+# fmt: on
+
+
+class RectangularArea(AreaInterface):
+
+    def __init__(self,
+                 width: int,
+                 height: int,
+                 color: Color | tuple[int, ...] | str = "BLACK",
+                 corners_radius: tuple[int, int, int, int] | int = 0) -> None:
+        super().__init__(width, height, color)
+        self.set_corners_radius(corners_radius)
+
+    @value_check(corners_radius=CheckRange(min_value=0, variable_name="corners_radius"))
+    def __validate_corners_range(self, corners_radius: tuple[int, ...]) -> None:
+        pass
+
+    @value_check(corners_radius=CheckLength(reference_length=4, variable_name="corners_radius"))
+    def __validate_corners_length(self, corners_radius: tuple[int, ...]) -> None:
+        pass
+
+    def set_corners_radius(self, corners_radius: tuple[int, int, int, int] | int) -> None:
+        if isinstance(corners_radius, int):
+            corners = (corners_radius, ) * 4
+        else:
+            corners = corners_radius
+
+        self.__validate_corners_length(corners)
+        self.__validate_corners_range(corners)
+        self.__set_corners_radius(corners)
+
+    def __set_corners_radius(self, corners: tuple[int, ...]) -> None:
+        self.__corners_radius = corners
+
+    def get_corners_radius(self) -> tuple[int, int, int, int]:
+        assert len(self.__corners_radius) == 4
+        return self.__corners_radius
+
+    def contains(self, coordinates: tuple[int, int]) -> bool:
+        x, y = coordinates
+        self_x, self_y, self_w, self_h = self.get_rect()
+        if not (self_x <= x <= self_x + self_w and
+                self_y <= y <= self_y + self_h):
+            return False
+        return not self.__exceeds_corners(coordinates)
+
+    def __exceeds_corners(self, coordinates: tuple[int, int]) -> bool:
+        rect_x, rect_y, rect_width, rect_height = self.get_rect()
+        radius_top_left, radius_top_right, radius_bottom_left, radius_bottom_right = self.get_corners_radius()
+
+        corners_geometry_map = [
+            (radius_top_left, rect_x + radius_top_left,
+             rect_y + radius_top_left, True, True),  # Top-Left
+            (radius_top_right, rect_x + rect_width - radius_top_right,
+             rect_y + radius_top_right, False, True),  # Top-Right
+            (radius_bottom_left, rect_x + radius_bottom_left, rect_y +
+             rect_height - radius_bottom_left, True,  False),  # Bottom-Left
+            (radius_bottom_right, rect_x + rect_width - radius_bottom_right,
+             rect_y + rect_height - radius_bottom_right, False, False)  # Bottom-Right
+        ]
+
+        for corner_radius, arc_center_x, arc_center_y, check_left, check_top in corners_geometry_map:
+
+            if self.__is_point_inside_corner_bounding_box(coordinates, arc_center_x, arc_center_y, check_left, check_top):
+                if not is_inside_circle(coordinates, (arc_center_x, arc_center_y), corner_radius):
+                    return True
+
+        return False
+
+    def __is_point_inside_corner_bounding_box(self, coordinates: tuple[int, int], arc_center_x: int, arc_center_y: int, check_left: bool, check_top: bool) -> bool:
+        point_x, point_y = coordinates
+        is_within_horizontal_boundary = point_x < arc_center_x if check_left else point_x > arc_center_x
+        is_within_vertical_boundary = point_y < arc_center_y if check_top else point_y > arc_center_y
+        return is_within_horizontal_boundary and is_within_vertical_boundary
+
+    def display(self, screen: Surface) -> None:
+        corners = self.get_corners_radius()
+        pygame.draw.rect(screen,
+                         self.get_color_tuple(),
+                         self.get_rect(),
+                         border_top_left_radius=corners[0],
+                         border_top_right_radius=corners[1],
+                         border_bottom_left_radius=corners[2],
+                         border_bottom_right_radius=corners[3])
+
+    def _get_copy_replacement_map(self) -> dict[str, Any]:
+        return {
+            "width": self.get_width(),
+            "height": self.get_height(),
+            "color": self.get_color(),
+            "corners_radius": self.get_corners_radius()
+        }

desklab/components/__init__.py

@@ -0,0 +1,15 @@
+from ._text import Text
+from ._button import Button
+from ._drag_drop import DragDrop
+from ._drawing_area import DrawingArea
+from ._text_input import TextInput
+from ._window import Window
+
+__all__ = [
+    "Text",
+    "Button",
+    "DragDrop",
+    "DrawingArea",
+    "TextInput",
+    "Window"
+]

desklab/components/_button.py

@@ -0,0 +1,61 @@
+from typing import Any, Callable
+from desklab.containers import (FlexDirection, HorizontalAlignment,
+                                VerticalAlignment, FlexBox)
+from desklab.areas import ClickableArea
+from desklab.primitives import Color
+
+
+class Button(FlexBox, ClickableArea):
+
+    def __init__(self,
+                 width: int,
+                 height: int,
+                 actions: Callable[..., Any] | list[Callable[..., Any]] = [],
+                 padding: int = 0,
+                 space_between: int = 0,
+                 flex_direction: str | FlexDirection = FlexDirection.COLUMN,
+                 horizontal_alignment: str | HorizontalAlignment = HorizontalAlignment.CENTER,
+                 vertical_alignment: str | VerticalAlignment = VerticalAlignment.CENTER,
+                 corners_radius: tuple[int, int, int, int] | int = 0,
+                 color: Color | tuple[int, ...] | str = "BLACK",
+                 bounded: bool = True) -> None:
+
+        super().__init__(width, height, padding,
+                         space_between, flex_direction,
+                         horizontal_alignment, vertical_alignment,
+                         corners_radius, color, bounded)
+        self.__actions: list[Callable[..., Any]] = []
+        self.add_actions(actions)
+
+    def __add_click_listener(self):
+        if self.is_clicked():
+            for action in self.get_actions():
+                action()
+
+    def set_actions(self, actions: Callable[..., Any] | list[Callable[..., Any]]):
+        if not isinstance(actions, list):
+            actions = [actions]
+        self.__actions = actions
+
+    def add_actions(self, actions: Callable[..., Any] | list[Callable[..., Any]]):
+        if isinstance(actions, Callable):
+            actions = [actions]
+        self.__actions.extend(actions)
+
+    def get_actions(self) -> list[Callable[..., Any]]:
+        return self.__actions.copy()
+
+    def remove_actions(self, actions: Callable[..., Any] | list[Callable[..., Any]]) -> None:
+        if isinstance(actions, Callable):
+            actions = [actions]
+        for a in actions:
+            self.__actions.remove(a)
+
+    def handle_event(self, *args: Any, **kwargs: Any) -> None:
+        super().handle_event(*args, **kwargs)
+        self.__add_click_listener()
+
+    def _get_copy_replacement_map(self) -> dict[str, Any]:
+        replace = super()._get_copy_replacement_map()
+        replace["actions"] = self.get_actions()
+        return replace

desklab/components/_drag_drop.py

@@ -0,0 +1,58 @@
+# fmt: off
+from desklab.primitives import Color
+from typing import Any, Optional
+from desklab.system import Mouse
+from desklab.containers import FlexBox, FlexDirection, HorizontalAlignment, VerticalAlignment
+import os
+os.environ['PYGAME_HIDE_SUPPORT_PROMPT'] = "hide"
+from pygame.event import Event
+# fmt: on
+
+
+class DragDrop(FlexBox):
+
+    def __init__(self,
+                 width: int,
+                 height: int,
+                 padding: int = 0,
+                 space_between: int = 0,
+                 flex_direction: str | FlexDirection = FlexDirection.COLUMN,
+                 horizontal_alignment: str | HorizontalAlignment = HorizontalAlignment.CENTER,
+                 vertical_alignment: str | VerticalAlignment = VerticalAlignment.CENTER,
+                 corners_radius: tuple[int, int, int, int] | int = 0,
+                 color: Color | tuple[int, ...] | str = "BLACK",
+                 bounded: bool = True) -> None:
+
+        self.__files: list[str] = []
+        super().__init__(width, height, padding, space_between, flex_direction,
+                         horizontal_alignment, vertical_alignment, corners_radius,
+                         color, bounded)
+
+    def handle_event(self, *args: Any, **kwargs: Any) -> None:
+        super().handle_event(*args, **kwargs)
+        mouse = self._get_from_kwargs(Mouse, kwargs)
+        event = self._get_from_kwargs(Event, kwargs, _raise=False)
+        if event:
+            self.__add_file_drop_listener(event, mouse)
+
+    def __add_file_drop_listener(self, event: Event, mouse: Mouse) -> None:
+        if mouse.is_dropping_file() and self.contains(mouse.get_position()):
+            file_path = event.file
+            self.__files.append(file_path)
+
+    def get_files(self) -> list[str]:
+        return self.__files.copy()
+
+    def pop_file(self) -> Optional[str]:
+        if not self.__files:
+            return None
+        return self.__files.pop()
+
+    def clear_files(self) -> None:
+        self.__files.clear()
+
+    def has_files(self) -> bool:
+        return len(self.__files) > 0
+
+    def count_files(self) -> int:
+        return len(self.__files)