desklab 0.1.0__tar.gz

desklab-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: desklab
+Version: 0.1.0
+Summary: Simple and easy to use interface package
+Author: Jonatas Cortes
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pygame==2.6.1
+Requires-Dist: pynput==1.8.1
+Requires-Dist: pyobjc-core==12.1; sys_platform == "darwin"
+Requires-Dist: pyobjc-framework-ApplicationServices==12.1; sys_platform == "darwin"
+Requires-Dist: pyobjc-framework-Cocoa==12.1; sys_platform == "darwin"
+Requires-Dist: pyobjc-framework-CoreText==12.1; sys_platform == "darwin"
+Requires-Dist: pyobjc-framework-Quartz==12.1; sys_platform == "darwin"
+Requires-Dist: pyperclip==1.11.0
+Requires-Dist: six==1.17.0
+
+![DeskLab-banner](./desklab_banner.png)
+
+DeskLab is a Python interface library designed for small projects that prioritize fast development over extensive customization.
+
+It simulates the web development programing style, with separation of responsibilities and reusable components.
+
+## 🛠️ Installation & Development Setup
+
+If you want to clone this repository to contribute to the code, run tests, or develop features locally, follow the steps below using **`uv`**, a fast Python package installer and environment manager.
+
+
+### Windows
+
+Open **PowerShell** and run:
+
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Alternative:
+
+```powershell
+winget install astral-sh.uv
+```
+
+---
+
+### Linux / macOS
+
+Open a terminal and run:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Alternative on macOS using Homebrew:
+
+```bash
+brew install uv
+```
+
+Alternative on Linux using pip:
+
+```bash
+pip install uv
+```
+
+After installation, restart your terminal so the `uv` command becomes available.
+
+Verify installation:
+
+```bash
+uv --version
+```
+
+---
+
+### Clone the Repository
+
+Clone the project and enter its directory:
+
+```bash
+git clone https://github.com/your-username/desklab.git
+cd desklab
+```
+
+---
+
+### Install Dependencies & Create Environment
+
+You do **not** need to manually create a virtual environment or run `pip install`.
+
+Simply execute:
+
+```bash
+uv sync
+```
+
+This command automatically:
+
+- Creates a local virtual environment (`.venv/`)
+- Installs all project dependencies
+- Installs desklab in editable mode
+- Synchronizes dependencies from `pyproject.toml`
+
+---
+
+### Running the Project
+
+Run your application inside the managed environment:
+
+```bash
+uv run <your_file>.py
+```
+
+This guarantees execution inside the project's environment and avoids dependency conflicts.
+
+---

desklab-0.1.0/README.md

@@ -0,0 +1,98 @@
+![DeskLab-banner](./desklab_banner.png)
+
+DeskLab is a Python interface library designed for small projects that prioritize fast development over extensive customization.
+
+It simulates the web development programing style, with separation of responsibilities and reusable components.
+
+## 🛠️ Installation & Development Setup
+
+If you want to clone this repository to contribute to the code, run tests, or develop features locally, follow the steps below using **`uv`**, a fast Python package installer and environment manager.
+
+
+### Windows
+
+Open **PowerShell** and run:
+
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Alternative:
+
+```powershell
+winget install astral-sh.uv
+```
+
+---
+
+### Linux / macOS
+
+Open a terminal and run:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Alternative on macOS using Homebrew:
+
+```bash
+brew install uv
+```
+
+Alternative on Linux using pip:
+
+```bash
+pip install uv
+```
+
+After installation, restart your terminal so the `uv` command becomes available.
+
+Verify installation:
+
+```bash
+uv --version
+```
+
+---
+
+### Clone the Repository
+
+Clone the project and enter its directory:
+
+```bash
+git clone https://github.com/your-username/desklab.git
+cd desklab
+```
+
+---
+
+### Install Dependencies & Create Environment
+
+You do **not** need to manually create a virtual environment or run `pip install`.
+
+Simply execute:
+
+```bash
+uv sync
+```
+
+This command automatically:
+
+- Creates a local virtual environment (`.venv/`)
+- Installs all project dependencies
+- Installs desklab in editable mode
+- Synchronizes dependencies from `pyproject.toml`
+
+---
+
+### Running the Project
+
+Run your application inside the managed environment:
+
+```bash
+uv run <your_file>.py
+```
+
+This guarantees execution inside the project's environment and avoids dependency conflicts.
+
+---

desklab-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "desklab"
+version = "0.1.0"
+description = "Simple and easy to use interface package"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "Jonatas Cortes"}
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "pygame==2.6.1",
+    "pynput==1.8.1",
+    "pyobjc-core==12.1; sys_platform == 'darwin'",
+    "pyobjc-framework-ApplicationServices==12.1; sys_platform == 'darwin'",
+    "pyobjc-framework-Cocoa==12.1; sys_platform == 'darwin'",
+    "pyobjc-framework-CoreText==12.1; sys_platform == 'darwin'",
+    "pyobjc-framework-Quartz==12.1; sys_platform == 'darwin'",
+    "pyperclip==1.11.0",
+    "six==1.17.0"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"desklab._assets" = ["*"]

desklab-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

desklab-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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())