rel 2025

Author: FredHappyface

.github/workflows/test-lint.yaml

@@ -20,6 +20,7 @@ jobs:
           - '3.10'
           - '3.11'
           - '3.12'
+          - '3.13'
 
     steps:
       - name: Checkout code
@@ -30,16 +31,16 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install Poetry
+      - name: Install UV
         run: |
-          curl -sSL https://install.python-poetry.org | python3 -
+          curl -LsSf https://astral.sh/uv/install.sh | sh
 
       - name: Install dependencies
-        run: poetry install
+        run: uv sync
 
       - name: Run pytest
-        run: poetry run pytest
+        run: uv run pytest
 
       - name: Run ruff
-        run: poetry run ruff check --output-format=github
+        run: uv run ruff check --output-format=github
         continue-on-error: true

CHANGELOG.md

@@ -3,6 +3,11 @@
 All major and minor version changes will be documented in this file. Details of
 patch-level version changes can be found in [commit messages](../../commits/master).
 
+## 2025 - 2025/02/20
+
+- optimise `_setLum` and `_setSat` functions
+- use uv instead of poetry
+
 ## 2024.1.1 - 2024/03/17
 
 - suppress warnings

blendmodes/blend.py

@@ -239,7 +239,7 @@ def _setSat(originalColours: np.ndarray, newSaturation: np.ndarray) -> np.ndarra
 	) / rangeColours[nonzeroMask]
 	maxColours[nonzeroMask] = newSaturation[nonzeroMask]
 
-	# Zero out mid and max when rangeColours == 0
+	# Zero out mid and max when rangeColours is 0
 	midColours[~nonzeroMask] = 0
 	maxColours[~nonzeroMask] = 0
 
@@ -471,36 +471,30 @@ def blendLayers(
 	opacity: float = 1.0,
 	offsets: tuple[int, int] = (0, 0),
 ) -> Image.Image:
-	"""Blend two layers (background, and foreground).
-
-	Note if the background is smaller than the foreground then some of the foreground will be cut
-	off
-
-	Args:
-	----
-		background (Image.Image): The background layer.
-		foreground (Image.Image): The foreground layer (must be the same size as the background).
-		blendType (BlendType): The blend type to be applied.
-		opacity (float, optional): The opacity of the foreground image. Defaults to 1.0.
-		offsets (Tuple[int, int], optional): Offsets for the foreground layer. Defaults to (0, 0).
-
-	Returns:
-	-------
-		Image.Image: The combined image.
-
-	Examples:
+	"""Blend two layers (background and foreground), where the background may
+	be cropped if smaller than the foreground.
+
+	:param Image.Image background: The background layer.
+	:param Image.Image foreground: The foreground layer (must be the
+	same size as the background).
+	:param BlendType blendType: The blend type to be applied.
+	:param float opacity: The opacity of the foreground image. Defaults to 1.0. (optional)
+	:param tuple[int, int] offsets: Offsets for the foreground layer. Defaults to (0, 0). (optional)
+	:return Image.Image: The combined image.
+
+	Examples
 	--------
-		# Blend two layers with default parameters
-		combined_image = blendLayers(background_image, foreground_image, BlendType.NORMAL)
-
-		# Blend two layers with custom opacity and offsets
-		combined_image = blendLayers(
-			background_image,
-			foreground_image,
-			BlendType.MULTIPLY,
-			opacity=0.7,
-			offsets=(100, 50)
-		)
+	Blend two layers with default parameters
+	>>> combined_image = blendLayers(background_image, foreground_image, BlendType.NORMAL)
+
+	Blend two layers with custom opacity and offsets
+	>>> combined_image = blendLayers(
+	...	background_image,
+	...	foreground_image,
+	...	BlendType.MULTIPLY,
+	...	opacity=0.7,
+	...	offsets=(100, 50)
+	...)
 
 	"""
 	arr = blendLayersArray(
@@ -521,38 +515,33 @@ def blendLayersArray(
 	opacity: float = 1.0,
 	offsets: tuple[int, int] = (0, 0),
 ) -> np.ndarray:
-	"""Blend two layers (background, and foreground).
-
-	Note if the background is smaller than the foreground then some of the foreground will be cut
-	off
-
-	Args:
-	----
-		background (np.ndarray | Image.Image): The background layer.
-		foreground (np.ndarray | Image.Image): The foreground layer (must be the same size as the background).
-		blendType (BlendType): The blend type to be applied.
-		opacity (float, optional): The opacity of the foreground image. Defaults to 1.0.
-		offsets (Tuple[int, int], optional): Offsets for the foreground layer. Defaults to (0, 0).
-
-	Returns:
-	-------
-		np.ndarray: The combined image.
-
-	Examples:
+	"""Blend two layers (background and foreground), where the background may
+	be cropped if smaller than the foreground.
+
+	:param np.ndarray | Image.Image background: The background layer.
+	:param np.ndarray | Image.Image foreground: The foreground layer (must be the
+	same size as the background).
+	:param BlendType blendType: The blend type to be applied.
+	:param float opacity: The opacity of the foreground image. Defaults to 1.0. (optional)
+	:param tuple[int, int] offsets: Offsets for the foreground layer. Defaults to (0, 0). (optional)
+	:return np.ndarray: The combined image.
+
+	Examples
 	--------
-		# Blend two layers with default parameters
-		combined_image = blendLayers(background_image, foreground_image, BlendType.NORMAL)
-
-		# Blend two layers with custom opacity and offsets
-		combined_image = blendLayers(
-			background_image,
-			foreground_image,
-			BlendType.MULTIPLY,
-			opacity=0.7,
-			offsets=(100, 50)
-		)
+	Blend two layers with default parameters
+	>>> combined_image = blendLayers(background_image, foreground_image, BlendType.NORMAL)
+
+	Blend two layers with custom opacity and offsets
+	>>> combined_image = blendLayers(
+	...	background_image,
+	...	foreground_image,
+	...	BlendType.MULTIPLY,
+	...	opacity=0.7,
+	...	offsets=(100, 50)
+	...)
 
 	"""
+
 	# Convert the Image.Image to a numpy array if required
 	if isinstance(background, Image.Image):
 		background = np.array(background.convert("RGBA"))

documentation/reference/blendmodes/blend.md

@@ -13,9 +13,7 @@
   - [alpha_comp_shell](#alpha_comp_shell)
   - [blend](#blend)
   - [blendLayers](#blendlayers)
-- [Blend two layers with custom opacity and offsets](#blend-two-layers-with-custom-opacity-and-offsets)
   - [blendLayersArray](#blendlayersarray)
-- [Blend two layers with custom opacity and offsets](#blend-two-layers-with-custom-opacity-and-offsets-1)
   - [colour](#colour)
   - [colourburn](#colourburn)
   - [colourdodge](#colourdodge)
@@ -136,7 +134,7 @@ def additive(background: np.ndarray, foreground: np.ndarray) -> np.ndarray: ...
 
 ## alpha_comp_shell
 
-[Show source in blend.py:638](../../../blendmodes/blend.py#L638)
+[Show source in blend.py:627](../../../blendmodes/blend.py#L627)
 
 Implement common transformations occurring in any blend or composite mode.
 
@@ -211,39 +209,43 @@ def blend(
 
 [Show source in blend.py:467](../../../blendmodes/blend.py#L467)
 
-Blend two layers (background, and foreground).
+Blend two layers (background and foreground), where the background may
+be cropped if smaller than the foreground.
 
-Note if the background is smaller than the foreground then some of the foreground will be cut
-off
+:param Image.Image background: The background layer.
+:param Image.Image foreground: The foreground layer (must be the
+same size as the background).
 
 #### Arguments
 
-----
- - `background` *Image.Image* - The background layer.
- - `foreground` *Image.Image* - The foreground layer (must be the same size as the background).
- - `blendType` *BlendType* - The blend type to be applied.
- - `opacity` *float, optional* - The opacity of the foreground image. Defaults to 1.0.
- offsets (Tuple[int, int], optional): Offsets for the foreground layer. Defaults to (0, 0).
+- `blendType` *BlendType* - The blend type to be applied.
+- `opacity` *float* - The opacity of the foreground image. Defaults to 1.0. (optional)
+:param tuple[int, int] offsets: Offsets for the foreground layer. Defaults to (0, 0). (optional)
 
 #### Returns
 
--------
- - `Image.Image` - The combined image.
-
-#### Examples
+Type: *Image.Image*
+The combined image.
 
+Examples
 --------
- # Blend two layers with default parameters
- combined_image = blendLayers(background_image, foreground_image, BlendType.NORMAL)
+Blend two layers with default parameters
+
+```python
+>>> combined_image = blendLayers(background_image, foreground_image, BlendType.NORMAL)
+```
 
-# Blend two layers with custom opacity and offsets
-combined_image = blendLayers(
- background_image,
- foreground_image,
- BlendType.MULTIPLY,
- opacity=0.7,
- offsets=(100, 50)
-)
+Blend two layers with custom opacity and offsets
+
+```python
+>>> combined_image = blendLayers(
+...	background_image,
+...	foreground_image,
+...	BlendType.MULTIPLY,
+...	opacity=0.7,
+...	offsets=(100, 50)
+...)
+```
 
 #### Signature
 
@@ -261,41 +263,45 @@ def blendLayers(
 
 ## blendLayersArray
 
-[Show source in blend.py:517](../../../blendmodes/blend.py#L517)
+[Show source in blend.py:511](../../../blendmodes/blend.py#L511)
 
-Blend two layers (background, and foreground).
+Blend two layers (background and foreground), where the background may
+be cropped if smaller than the foreground.
 
-Note if the background is smaller than the foreground then some of the foreground will be cut
-off
+:param np.ndarray | Image.Image background: The background layer.
+:param np.ndarray | Image.Image foreground: The foreground layer (must be the
+same size as the background).
 
 #### Arguments
 
-----
- background (np.ndarray | Image.Image): The background layer.
- foreground (np.ndarray | Image.Image): The foreground layer (must be the same size as the background).
- - `blendType` *BlendType* - The blend type to be applied.
- - `opacity` *float, optional* - The opacity of the foreground image. Defaults to 1.0.
- offsets (Tuple[int, int], optional): Offsets for the foreground layer. Defaults to (0, 0).
+- `blendType` *BlendType* - The blend type to be applied.
+- `opacity` *float* - The opacity of the foreground image. Defaults to 1.0. (optional)
+:param tuple[int, int] offsets: Offsets for the foreground layer. Defaults to (0, 0). (optional)
 
 #### Returns
 
--------
- - `np.ndarray` - The combined image.
-
-#### Examples
+Type: *np.ndarray*
+The combined image.
 
+Examples
 --------
- # Blend two layers with default parameters
- combined_image = blendLayers(background_image, foreground_image, BlendType.NORMAL)
-
-# Blend two layers with custom opacity and offsets
-combined_image = blendLayers(
- background_image,
- foreground_image,
- BlendType.MULTIPLY,
- opacity=0.7,
- offsets=(100, 50)
-)
+Blend two layers with default parameters
+
+```python
+>>> combined_image = blendLayers(background_image, foreground_image, BlendType.NORMAL)
+```
+
+Blend two layers with custom opacity and offsets
+
+```python
+>>> combined_image = blendLayers(
+...	background_image,
+...	foreground_image,
+...	BlendType.MULTIPLY,
+...	opacity=0.7,
+...	offsets=(100, 50)
+...)
+```
 
 #### Signature
 

pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "blendmodes"
-version = "2024.1.1"
+version = "2025"
 description = "Use this module to apply a number of blending modes to a background and foreground image"
 authors = [{ name = "FredHappyface" }]
-requires-python = ">=3.9,<4.0"
+requires-python = ">=3.9"
 readme = "README.md"
 license = "mit"
 classifiers = [
@@ -58,7 +58,7 @@ ignore = [
 fixable = ["ALL"]
 
 [tool.ruff.lint.per-file-ignores]
-"**/{tests,docs,tools}/*" = ["D", "S101", "E402"]
+"**/{tests,docs,tools}/*" = ["D", "S101", "E402", "S311"]
 
 [tool.ruff.lint.flake8-tidy-imports]
 ban-relative-imports = "all" # Disallow all relative imports.