Improve startup-times by lazy-loading imports (#88)

* Local imports of CV2, requests, and sklearn

* fmt

* Fix array type

* Update changelog

Author: qTipTip

CHANGELOG.md

@@ -12,6 +12,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Raise a ValueError if there are no pixels left after alpha channel masking.
 
+## Fixed
+
+- Local imports improve startup speed for CLI based usage, especially when not
+requiring K Means extraction.
+
 # Released
 
 ## 4.3.0 - 11/08/2025

Pylette/src/color.py

@@ -2,7 +2,6 @@
 from typing import Literal, cast
 
 import numpy as np
-from PIL import Image
 
 # Weights for calculating luminance
 luminance_weights = np.array([0.2126, 0.7152, 0.0722])
@@ -33,6 +32,9 @@ def display(self, w: int = 50, h: int = 50) -> None:
         w (int): Width of the window in pixels.
         h (int): Height of the window in pixels.
         """
+
+        from PIL import Image
+
         img = Image.new("RGBA", size=(w, h), color=self.rgba)
         img.show()
 

Pylette/src/color_extraction.py

@@ -4,7 +4,6 @@
 from typing import Literal
 
 import numpy as np
-import requests
 from PIL import Image
 
 from Pylette.src.extractors.k_means import k_means_extraction
@@ -117,6 +116,9 @@ def request_image(image_url: str) -> Image.Image:
     Raises:
         ValueError: If the URL does not point to a valid image.
     """
+
+    import requests
+
     response = requests.get(image_url)
     # Check if the request was successful and content type is an image
     if response.status_code == 200 and "image" in response.headers.get("Content-Type", ""):

Pylette/src/extractors/k_means.py

@@ -1,6 +1,5 @@
 import numpy as np
 from numpy.typing import NDArray
-from sklearn.cluster import KMeans
 
 from Pylette.src.color import Color
 from Pylette.src.extractors.protocol import NP_T, ColorExtractorBase
@@ -20,6 +19,9 @@ def extract(self, arr: NDArray[NP_T], height: int, width: int, palette_size: int
         Returns:
             list[Color]: A palette of colors sorted by frequency.
         """
+
+        from sklearn.cluster import KMeans
+
         arr = np.squeeze(arr)
         model = KMeans(n_clusters=palette_size, n_init="auto", init="k-means++", random_state=2024)
         labels = model.fit_predict(arr)

Pylette/src/extractors/median_cut.py

@@ -30,7 +30,7 @@ def extract(self, arr: NDArray[NP_T], height: int, width: int, palette_size: int
         return [Color(tuple(map(int, box.average)), box.pixel_count / valid_pixel_count) for box in boxes]
 
 
-def median_cut_extraction(arr: np.ndarray, height: int, width: int, palette_size: int) -> list[Color]:
+def median_cut_extraction(arr: NDArray[NP_T], height: int, width: int, palette_size: int) -> list[Color]:
     """
     Extracts a color palette using the median cut algorithm.
 

pyproject.toml

@@ -82,3 +82,8 @@ pythonVersion = "3.10"
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "importtime-waterfall>=1.0.0",
+]

tests/integration/test_colorspaces.py

@@ -1,22 +1,24 @@
 import pathlib
 from typing import Literal
 
-import cv2
 import pytest
 from numpy.testing import assert_approx_equal
-from PIL import Image
 
 from Pylette.src.color_extraction import extract_colors
 
 
 @pytest.fixture
 def test_image_from_opencv():
+    import cv2
+
     test_image = pathlib.Path(__file__).parent.parent / "data/test_image.png"
     return cv2.imread(str(test_image.absolute().resolve()))
 
 
 @pytest.fixture
 def test_image_from_PIL():
+    from PIL import Image
+
     test_image = pathlib.Path(__file__).parent.parent / "data/test_image.png"
     return Image.open(test_image)