Merge branch 'end-4:main' into main

.config/quickshell/ii/modules/background/Background.qml

@@ -152,7 +152,7 @@ Variants {
             property int contentHeight: 300
             property int horizontalPadding: bgRoot.movableXSpace
             property int verticalPadding: bgRoot.movableYSpace
-            command: [Quickshell.shellPath("scripts/images/least_busy_region.py"), "--screen-width", Math.round(bgRoot.screen.width / bgRoot.effectiveWallpaperScale), "--screen-height", Math.round(bgRoot.screen.height / bgRoot.effectiveWallpaperScale), "--width", contentWidth, "--height", contentHeight, "--horizontal-padding", horizontalPadding, "--vertical-padding", verticalPadding, path
+            command: [Quickshell.shellPath("scripts/images/least-busy-region-venv.sh"), "--screen-width", Math.round(bgRoot.screen.width / bgRoot.effectiveWallpaperScale), "--screen-height", Math.round(bgRoot.screen.height / bgRoot.effectiveWallpaperScale), "--width", contentWidth, "--height", contentHeight, "--horizontal-padding", horizontalPadding, "--vertical-padding", verticalPadding, path
                 // "--visual-output",
                 ,]
             stdout: StdioCollector {

.config/quickshell/ii/screenshot.qml

@@ -307,7 +307,7 @@ ShellRoot {
 
             Process {
                 id: imageDetectionProcess
-                command: ["bash", "-c", `${Directories.scriptPath}/images/find_regions.py ` 
+                command: ["bash", "-c", `${Directories.scriptPath}/images/find-regions-venv.sh ` 
                     + `--hyprctl ` 
                     + `--image '${StringUtils.shellSingleQuoteEscape(panelWindow.screenshotPath)}' ` 
                     + `--max-width ${Math.round(panelWindow.screen.width * root.falsePositivePreventionRatio)} ` 

.config/quickshell/ii/scripts/images/find-regions-venv.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+source $(eval echo $ILLOGICAL_IMPULSE_VIRTUAL_ENV)/bin/activate
+"$SCRIPT_DIR/find_regions.py" "$@"
+

.config/quickshell/ii/scripts/images/find_regions.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env -S\_/bin/sh\_-c\_"source\_\$(eval\_echo\_\$ILLOGICAL_IMPULSE_VIRTUAL_ENV)/bin/activate&&exec\_python\_-E\_"\$0"\_"\$@""
+#!/usr/bin/env python3
 
 import argparse
 import cv2

.config/quickshell/ii/scripts/images/least-busy-region-venv.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+source $(eval echo $ILLOGICAL_IMPULSE_VIRTUAL_ENV)/bin/activate
+"$SCRIPT_DIR/least_busy_region.py" "$@"
+

dist-arch/illogical-impulse-python/PKGBUILD

@@ -13,5 +13,4 @@ depends=(
   libportal-gtk4
   gobject-introspection
   sassc
-  python-opencv
 )

scriptdata/step/1.install-deps-selector.sh

@@ -2,7 +2,7 @@
 # It's not for directly running.
 
 function outdate_detect(){
-  # Shallow clone makes latest_commit_timestamp() not worky.
+  # Shallow clone prevent latest_commit_timestamp() from working.
   git_auto_unshallow
 
   local source_path="$1"
@@ -42,6 +42,7 @@ case $MACHINE_ARCH in
     printf "It is very likely to fail when installing dependencies on your machine.\n"
     printf "\n"
     printf "${STY_RESET}"
+    pause
     ;;
 esac
 

scriptdata/uv/README.md

@@ -6,18 +6,22 @@ This is important because there has been so many complaints about the failure in
 ## How to add/remove python package?
 
 1. Edit `requirements.in`. You may refer to [PyPI](https://pypi.org/) for possible package names.
-   - See also [uv doc](https://docs.astral.sh/uv/pip/dependencies/#using-requirementsin).
 2. Run `uv pip compile requirements.in -o requirements.txt` in this folder.
 
+**Notes:**
+- See also [uv doc](https://docs.astral.sh/uv/pip/dependencies/#using-requirementsin).
+- `requirements.txt` is included in Git. It's for locking package versions to enhance stability and reproducibility.
+  - In fact, including package version lock file in Git is also the most common way for similar situations, for example the `package-lock.json` of Node.js projects (see also [this stackoverflow question](https://stackoverflow.com/questions/48524417/should-the-package-lock-json-file-be-added-to-gitignore)). Although there are some situations when it's not suitable to include the lock file, for example [the poetry document](https://python-poetry.org/docs/basic-usage/#committing-your-poetrylock-file-to-version-control) recommend application developers to include package version lock file in Git, but library developers should consider more, such as not inluding the lock file or including it but refreshing regularly.
+
 ## How will the python packages get installed?
 
 - They will be installed to the virtual environment `$ILLOGICAL_IMPULSE_VIRTUAL_ENV`.
 - The default value of `$ILLOGICAL_IMPULSE_VIRTUAL_ENV` is `$XDG_STATE_HOME/quickshell/.venv`.
   - The default value of `$XDG_STATE_HOME` is `$HOME/.local/state`.
-  - Currently we use `env = ILLOGICAL_IMPULSE_VIRTUAL_ENV, ~/.local/state/quickshell/.venv` in `~/.config/hypr/hyprland/env.conf` to set this environment variable.[^1]
+  - Currently we use `env = ILLOGICAL_IMPULSE_VIRTUAL_ENV, ~/.local/state/quickshell/.venv` in `~/.config/hypr/hyprland/env.conf` to set this environment variable.[^2]
 - See the function `install-python-packages()` defined in `/scriptdata/lib/package-installers.sh` for details.
 
-[^1]: Hyprland seems to have weird problem dealing with recursive variable, so we can not use `$XDG_STATE_HOME/quickshell/.venv` even if we had set `$XDG_STATE_HOME` to `~/.local/state` explicitly, else `$XDG_STATE_HOME` will possibly not get expanded but get recognised as literally `$XDG_STATE_HOME`. This problem never happens for some users, but according to some issues when we were using recursive variable setting in the past, it's possible to happen for other users. Reason unknown.
+[^2]: Hyprland seems to have weird problem dealing with recursive variable, so we can not use `$XDG_STATE_HOME/quickshell/.venv` even if we had set `$XDG_STATE_HOME` to `~/.local/state` explicitly, else `$XDG_STATE_HOME` will possibly not get expanded but get recognised as literally `$XDG_STATE_HOME`. This problem never happens for some users, but according to some issues when we were using recursive variable setting in the past, it's possible to happen for other users. Reason unknown.
 
 ## How to use the python packages installed through here?
 
@@ -25,21 +29,93 @@ Basically you'll need to activate the virtual environment first:
 ```bash
 source $(eval echo $ILLOGICAL_IMPULSE_VIRTUAL_ENV)/bin/activate
 ```
-then use the python package inside it;
+
+It will add the python executable located in the venv to `$PATH` and give it the highest priority.
+Run `which python` and you'll understand.
+
+This python executable will also search and use the python package inside the venv,
+which enables running any python script or running command provided via python package using the venv.
+
 After that you probably need to deactivate it:
 ```bash
 deactivate
 ```
-### Situation 1: Call the command directly
-Take `kde-material-you-colors` as example.
+
+### Situation 1: As a single command
+**Description:** At someplace which accept a single command,
+- run a python script,
+- or run a command provided by python package.
+
+Example: In `~/‎.config/quickshell/ii/screenshot.qml`:
+```qml
+Process {
+id: imageDetectionProcess
+                command: ["bash", "-c", `${Directories.scriptPath}/images/find_regions.py ` 
++ `--hyprctl ` 
++ `--image '${StringUtils.shellSingleQuoteEscape(panelWindow.screenshotPath)}' ` 
++ `--max-width ${Math.round(panelWindow.screen.width * root.falsePositivePreventionRatio)} ` 
+```
+In this example, python script `find_regions.py` is called and receives some arguments.
+
+#### Solution A: shebang
+
+Add the shebang below to the beginning of python script:
+```python
+#!/usr/bin/env -S\_/bin/sh\_-c\_"source\_\$(eval\_echo\_\$ILLOGICAL_IMPULSE_VIRTUAL_ENV)/bin/activate&&exec\_python\_-E\_"\$0"\_"\$@""
+```
+And that's it!
+
+**Note:** This is the simplest solution as it only modifies the shebang of python script.
+However:
+- It's only for python script, not the command provided by python package.
+  - P.S. Run the script directly, eg. `./foo.py`, not `python3 foo.py`, or the shebang will be ignored.
+- It can not deal with complex argument (e.g. filaname containing spaces) passed to the python script.
+  - The example above is actually unstable, considering that `--image '${StringUtils.shellSingleQuoteEscape(panelWindow.screenshotPath)}'` could be a rather complex argument.
+
+#### Solution B: bash script as wrapper
+
+First make sure the python script is using the shebang `#!/usr/bin/env python3`, instead of `#!/usr/bin/python3` or something else.
+
+Then write a wrapper script in bash.
+Let's continue the `screenshot.qml` example, in the same directory as `find_regions.py`, write a `find-regions-venv.sh`:
 ```bash
-source "$(eval echo $ILLOGICAL_IMPULSE_VIRTUAL_ENV)/bin/activate"
-kde-material-you-colors "$mode_flag" --color "$color" -sv "$sv_num"
+#!/usr/bin/env bash
+
+# Specify the path of the python script.
+# The example below only applies when `find_regions.py` and this wrapper script are under the same folder.
+PY_SCRIPT="$(cd $(dirname "${BASH_SOURCE[0]}") && pwd)/find_regions.py"
+
+source $(eval echo $ILLOGICAL_IMPULSE_VIRTUAL_ENV)/bin/activate
+"$PY_SCRIPT" "$@"
 deactivate
 ```
+**Not done yet!** Do not forget to update the code calling the original python script.
+In this example, in `~/‎.config/quickshell/ii/screenshot.qml` we should modify `find_regions.py` to the wrapper script `find-regions-venv.sh`:
+```qml
+Process {
+id: imageDetectionProcess
+                command: ["bash", "-c", `${Directories.scriptPath}/images/find-regions-venv.sh ` 
++ `--hyprctl ` 
++ `--image '${StringUtils.shellSingleQuoteEscape(panelWindow.screenshotPath)}' ` 
++ `--max-width ${Math.round(panelWindow.screen.width * root.falsePositivePreventionRatio)} ` 
+```
 
-### Situation 2: Use python script (wrapped)
-Take `generate_colors_material.py` as example:
+### Situation 2: Inside a bash script
+Note: the solutions for `Situation 1: As a single command` also apply here; but **not** vice versa.
+
+**Description:**
+Inside a bash script,
+- run a python script,
+- or run a command provided by python package.
+
+**Solution:**
+- Add "activation command" before the target line,
+- Also add "deactivation command" after the target line.
+
+**Example:**
+
+For running a python script,
+take `generate_colors_material.py` as example:
 ```bash
 source "$(eval echo $ILLOGICAL_IMPULSE_VIRTUAL_ENV)/bin/activate"
 python3 "$SCRIPT_DIR/generate_colors_material.py" "${generate_colors_material_args[@]}" \
@@ -47,12 +123,13 @@ python3 "$SCRIPT_DIR/generate_colors_material.py" "${generate_colors_material_ar
 "$SCRIPT_DIR"/applycolor.sh
 ```
 
-### Situation 3: Use python script (shebang)
-**Note**: This method is only for simple situation.
-It can not deal with complex arguments (e.g. filaname containing spaces) passed to the python script.
-
-Take `generate_colors_material.py` as example, add the shebang below to its beginning:
-```python
-#!/usr/bin/env -S\_/bin/sh\_-c\_"source\_\$(eval\_echo\_\$ILLOGICAL_IMPULSE_VIRTUAL_ENV)/bin/activate&&exec\_python\_-E\_"\$0"\_"\$@""
+For running a python script provided by python package,
+take `kde-material-you-colors` as example:
+```bash
+source "$(eval echo $ILLOGICAL_IMPULSE_VIRTUAL_ENV)/bin/activate"
+kde-material-you-colors "$mode_flag" --color "$color" -sv "$sv_num"
+deactivate
 ```
-Then you should run the script directly, i.e. `./generate_colors_material.py`, **not** `python3 generate_colors_material.py`.
+
+
+

scriptdata/uv/requirements.in

@@ -14,3 +14,5 @@ loguru
 pycairo
 pygobject
 tqdm
+numpy
+opencv-contrib-python

scriptdata/uv/requirements.txt

@@ -22,8 +22,12 @@ materialyoucolor==2.0.10
     #   kde-material-you-colors
 numpy==2.2.2
     # via
+    #   -r scriptdata/uv/requirements.in
     #   kde-material-you-colors
     #   material-color-utilities
+    #   opencv-contrib-python
+opencv-contrib-python==4.12.0.88
+    # via -r scriptdata/uv/requirements.in
 packaging==24.2
     # via
     #   build