Bug: Add capability to use external python packages in apps

.gitignore

@@ -1,5 +1,6 @@
 # Generated repos
 venv/
+log/
 sysroot-android-64/
 build-android-64/
 

docs/features/pyqt5_features.md

@@ -1,6 +1,6 @@
 # PyQt5 Features
 
-:mag: This section introduces the main PyQt5 features needed to create a custom standard app.
+> :mag: **Info**: This section introduces the main PyQt5 features needed to create a custom standard app.
 
 <a id="toc"></a>
 ## Table of Contents
@@ -36,7 +36,7 @@ PyQt5 lets you work with many other database engines as shown on [tutorialspoint
 <a id="database-management-setup"></a>
 #### 1.2. Setup for database management
 
-Before attempting to run any `SQLite`-related actions, make sure that the library is available on your machine:
+> :triangular_flag_on_post: **Important**: Before attempting to run any `SQLite`-related actions, make sure that the library is available on your machine with the following command.
 
 ```
 sudo apt-get install sqlite3
@@ -58,7 +58,7 @@ A dialog window will pop up in which you can perform the following:
 - Add a row to the database
 - Remove a row from the database
 
-You can view the content of the generated and edited database at any time outside of the application with:
+> :bulb: **Tip**: You can view the content of the generated and edited database at any time outside of the application with the following command.
 
 ```
 cd $PYQT_CROM_DIR/examples/database
@@ -81,7 +81,7 @@ This demo app is built on the one highlighted in the [Getting started](../../REA
 - Once the pop-up has been acknowledged, a database (called `sportsdatabase.db`) is created in the `home` folder as shown in the alert window, if not already existing
 - In the dialog window displaying the content of the database, rows can be added, removed or edited
 
-:bulb: _You can view the content of `sportsdatabase.db` at any time by following the instructions in [Example PyQt5 app with database](#database-pyqt5-demo-app) after ensuring that your [Database manager](#database-management-setup) is correctly setup._
+> :bulb: **Tip**: You can view the content of `sportsdatabase.db` at any time by following the instructions in [Example PyQt5 app with database](#database-pyqt5-demo-app) after ensuring that your [Database manager](#database-management-setup) is correctly setup.
 
 <a id="pyqt5-database-management-app-android-video"></a>
 
@@ -110,7 +110,6 @@ As we are showcasing a prototyping tool for mobile apps, we have decided to expl
 
 To visualise a basic example of 2D Graphics in a PyQt app, run the following:
 
-
 ```
 cd $PYQT_CROM_DIR/examples/graphics
 python3 pyqt5_app_with_graphics.py
@@ -177,7 +176,7 @@ cd $PYQT_CROM_DIR/examples/network
 python3 pyqt5_app_with_bluetooth.py
 ```
 
-:bulb: _If you encounter issues with Bluetooth, please refer to the [Bluetooth troubleshooting](../troubleshooting/common_issues.md#virtual-machine-bluetooth)._
+> :bulb: **Tip**: If you encounter issues with Bluetooth, please refer to the [Bluetooth troubleshooting](../troubleshooting/common_issues.md#virtual-machine-bluetooth).
 
 The example Bluetooth app provides the following experience:
 - A window appears on the screen with 2 buttons: Search for Bluetooth devices and EXIT
@@ -186,8 +185,6 @@ The example Bluetooth app provides the following experience:
 - Once your Bluetooth is ON, click again on Search for Bluetooth devices so that the app can search for nearby devices for 5 seconds
 - The app displays the list of found nearby devices on the main window
 
-
-
 <a id="operational-bluetooth-pyqt5-demo-app"></a>
 #### 3.3. Example operational PyQt5 Bluetooth app
 
@@ -198,9 +195,9 @@ cd $PYQT_CROM_DIR/examples/network/bluetooth_scanner_project/bluetooth_scanner_p
 python3 operational_pyqt5_app_with_bluetooth.py
 ```
 
-:bulb: _If you encounter issues with Bluetooth, please refer to the [Bluetooth troubleshooting](../troubleshooting/common_issues.md#virtual-machine-bluetooth)._
+> :bulb: **Tip**: If you encounter issues with Bluetooth, please refer to the [Bluetooth troubleshooting](../troubleshooting/common_issues.md#virtual-machine-bluetooth).
 
-The operational example Bluetooth app has a similar behaviour to the [example Bluetooth app](#bluetooth-pyqt5-demo-app).
+> :bulb: **Tip**: The operational example Bluetooth app has a similar behaviour to the [example Bluetooth app](#bluetooth-pyqt5-demo-app).
 
 <a id="pyqt5-bluetooth-scanner-app-android-video"></a>
 

docs/licencing/licencing_information.md

@@ -1,6 +1,6 @@
 # Licencing information
 
-:mag: This section gathers the licences of the main dependencies.
+> :mag: **Info**: This section gathers the licences of the main dependencies.
 
 | Dependency | Version | Licence |
 | --- | --- | --- |

docs/troubleshooting/common_issues.md

@@ -1,6 +1,6 @@
 # Common issues
 
-:mag: This section walks you through tips and fixes for the main challenges you might encounter while setting up the repo or running the scripts.
+> :mag: **Info**: This section walks you through tips and fixes for the main challenges you might encounter while setting up the repo or running the scripts.
 
 <a id="toc"></a>
 ## Table of Contents
@@ -61,13 +61,32 @@ sudo apt-get install libxcb-xinerama0
 <a id="virtual-machine-setup"></a>
 ### 4. Setup repo with a Virtual Machine
 
-To setup a Linux Virtual Machine on Windows via VirtualBox, follow [It's FOSS virtualbox setup tutorial](https://itsfoss.com/install-linux-in-virtualbox/).
-
-If you would prefer to setup a Linux Virtual Machine on MacOS via VirtualBox, follow [TecAdmin virtualbox setup tutorial](https://tecadmin.net/how-to-install-virtualbox-on-macos/).
-
-It is also recommended to install the VirtualBox Guest Additions. Follow the [LinuxTechi guest addition setup tutorial](https://www.linuxtechi.com/install-virtualbox-guest-additions-on-ubuntu/) for more information.
-
-:bulb: _It is also recommended to set the size of the Virtual Machine to at least 50GB so that there is enough space to download and install all dependencies._
+Follow the relevant tutorial to setup a Virtual Machine on your machine.
+
+<table style="width:100%">
+    <!-- Headers -->
+    <tr>
+        <th align="center" style="width:30%"> HOST </th> <!-- Col 1 -->
+        <th align="center" style="width:30%"> GUEST </th> <!-- Col 2 -->
+        <th align="center"> TUTORIAL </th> <!-- Col 3 -->
+    </tr>
+    <!-- Row 1 -->
+    <tr>
+        <td>You have Windows OS installed on your machine</td>
+        <td>You want a Linux Virtual Machine</td>
+        <td><a href="https://itsfoss.com/install-linux-in-virtualbox">It's FOSS virtualbox setup tutorial</a> </td>
+    </tr>
+    <!-- Row 2 -->
+    <tr>
+        <td>You have Mac OS installed on your machine</td>
+        <td>You want a Linux Virtual Machine</td>
+        <td><a href="https://tecadmin.net/how-to-install-virtualbox-on-macos/">TecAdmin virtualbox setup tutorial</a> </td>
+    </tr>
+</table>
+
+> :bulb: **Tip**: It is recommended to install the VirtualBox Guest Additions. Follow the [LinuxTechi guest addition setup tutorial](https://www.linuxtechi.com/install-virtualbox-guest-additions-on-ubuntu/) for more information.
+
+> :bulb: **Tip**: It is also recommended to set the size of the Virtual Machine to at least 50GB so that there is enough space to download and install all dependencies.
 
 <a id="virtual-machine-bluetooth"></a>
 ### 5. Setup Bluetooth in a Virtual Machine
@@ -88,7 +107,7 @@ If you are using VirtualBox (Virtual Machine) and you want to run a pyqt5 app re
 
 To setup an Android Emulator, it is recommended to use Android Studio.
 
-_If you want to set up the Android Emulator in VirtualBox, please refer to [this issue](https://github.com/achille-martin/pyqt-crom/issues/12)._
+> :bulb: **Tip**: If you want to set up the Android Emulator in VirtualBox, please refer to [this issue](https://github.com/achille-martin/pyqt-crom/issues/12).
 
 To setup the Android Emulator in Ubuntu, make sure that you have:
 * Android Studio installed (refer to [External dependencies setup](../../README.md#external-dependency-installation) if needed)
@@ -112,7 +131,7 @@ sudo chown <username> /dev/kvm
 
 Once the Android Emulator is set up and running, you can drag and drop your `.apk` to install it and run it.
 
-If you wish to access more Android logs, please refer to [this issue](https://github.com/achille-martin/pyqt-crom/issues/12), which mentions tips for `adb`, the Android Debug Bridge.
+> :bulb: **Tip**: If you wish to access more Android logs, please refer to [this issue](https://github.com/achille-martin/pyqt-crom/issues/12), which mentions tips for `adb`, the Android Debug Bridge.
 
 [:arrow_heading_up: Back to TOP](#toc)
 

examples/demo/module_finder_project/config.pdt

@@ -0,0 +1,27 @@
+version = 0
+sysroot = "sysroot.toml"
+sysroots_dir = ""
+parts = [ "PyQt:PyQt5.QtWidgets", "Python:logging",]
+
+[Application]
+entry_point = "modfinder_pkg.modfinder_app:main"
+is_console = false
+is_bundle = false
+name = "ModFinderApp"
+qmake_configuration = ""
+script = ""
+syspath = ""
+
+[Application.Package]
+name = "modfinder_pkg"
+exclude = [ "*.pyc", "*.pyd", "*.pyo", "*.pyx", "*.pxi", "__pycache__", "*-info", "EGG_INFO", "*.so",]
+[[Application.Package.Content]]
+name = "__init__.py"
+included = true
+is_directory = false
+
+[[Application.Package.Content]]
+name = "modfinder_app.py"
+included = true
+is_directory = false
+

examples/demo/module_finder_project/modfinder_pkg/modfinder_app.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+
+# MIT License
+
+# Copyright (c) 2024 Achille MARTIN
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# Module Finder PyQt5 app
+# Inspired by Martin Fitzpatrick from https://www.pythonguis.com/tutorials/creating-your-first-pyqt-window/
+#
+# This app helps you identify
+# the python module dependencies
+# related to specific non-standard python libraries
+
+
+## Imports
+
+import sys
+sys_modules = dict(sorted(sys.modules.items()))
+sys_modules_base = list(sys_modules.keys())
+sys_modules_base.sort()
+
+import_error_msg = ""
+sys_modules_base_with_pkg = None
+sys_modules_pkg = None
+try:
+    # Import your non-standard python pkg
+    import numpy
+    sys_modules = dict(sorted(sys.modules.items()))
+    sys_modules_base_with_pkg = list(sys_modules.keys())
+    sys_modules_base_with_pkg.sort()
+    sys_modules_pkg = list(
+        set(
+            sys_modules_base_with_pkg
+        ).difference(
+            set(sys_modules_base)
+        )
+    )
+    sys_modules_pkg.sort()
+except Exception as e:
+    import_error_msg = f"Exception caught: {e}"
+
+import os
+import logging as log_tool  # The logging library for debugging
+from PyQt5.QtWidgets import QApplication, QMainWindow, QPushButton, QMessageBox
+from PyQt5.QtCore import QStandardPaths
+
+built_in_modules = list(sys.stdlib_module_names)
+built_in_modules.sort()
+
+## Main variables and objects
+
+# Retrieve app data folder path reference
+std_app_data_folder_path_list = QStandardPaths.writableLocation(
+    QStandardPaths.AppDataLocation
+)
+
+# Define custom app data folder path
+std_app_data_folder_path = ""
+if isinstance(std_app_data_folder_path_list, list):
+    std_app_data_folder_path = std_app_data_folder_path_list[0]
+else:
+    std_app_data_folder_path = str(std_app_data_folder_path_list)
+app_data_folder_path = os.path.join(
+    std_app_data_folder_path, 
+    'pyqt5_app_data', 
+)
+
+# Generate custom app data folder at convenient writable location
+os.makedirs(app_data_folder_path, exist_ok = True)
+
+# Set logger config and instantiate object
+logger_logging_level = "DEBUG"
+logger_output_file_name = "modfinder_app.log"
+logger_output_prefix_format = "[%(asctime)s] [%(levelname)s] - %(message)s"
+logger = log_tool.getLogger(__name__)
+logger.setLevel(logger_logging_level)
+logger_output_file_path = os.path.join(app_data_folder_path, str(logger_output_file_name))
+file_handler = log_tool.FileHandler(logger_output_file_path)
+formatter = log_tool.Formatter(logger_output_prefix_format)
+file_handler.setFormatter(formatter)
+logger.addHandler(file_handler)
+
+# Set additional log output location
+# for non-root debugging
+# when flag is_non_root_debug_active is set to True
+is_non_root_debug_active = True
+# WARNING: this feature might require 
+# to allow storage access permission before launching the app
+if is_non_root_debug_active:
+    # Retrieve documents folder path reference
+    # to save logs at a location accessible by non-root users
+    std_documents_folder_path_list = QStandardPaths.writableLocation(
+        QStandardPaths.DocumentsLocation
+    )
+    # Define custom alternative app data folder path
+    std_documents_folder_path = ""
+    if isinstance(std_documents_folder_path_list, list):
+        std_documents_folder_path = std_documents_folder_path_list[0]
+    else:
+        std_documents_folder_path = str(std_documents_folder_path_list)
+    alternative_app_data_folder_path = os.path.join(
+        std_documents_folder_path, 
+        'pyqt5_app_data', 
+    )
+    # Generate alternative app data folder at convenient writable location
+    os.makedirs(alternative_app_data_folder_path, exist_ok = True)
+    # Add log file output alternative to logger
+    logger_output_file_path_alternative = os.path.join(
+        alternative_app_data_folder_path, 
+        str(logger_output_file_name)
+    )
+    file_handler_alternative = log_tool.FileHandler(
+        logger_output_file_path_alternative
+    )
+    formatter_alternative = log_tool.Formatter(logger_output_prefix_format)
+    file_handler_alternative.setFormatter(formatter_alternative)
+    logger.addHandler(file_handler_alternative)
+
+## Investigating the imports
+logger.debug("---- SYS MODULES BASE ----")
+logger.debug(sys_modules_base)
+logger.debug("---- SYS MODULES BASE WITH PKG ----")
+logger.debug(sys_modules_base_with_pkg)
+logger.debug("---- SYS MODULES NUMPY ----")
+logger.debug(sys_modules_pkg)
+logger.debug("---- PYTHON BUILT-IN MODULES ----")
+logger.debug(built_in_modules)
+logger.debug("---- IMPORT ERRORS ----")
+logger.debug(import_error_msg)
+
+
+## Class definition
+
+# Subclass QMainWindow to customize your application's main window
+class MainWindow(QMainWindow):
+    def __init__(self):
+        super().__init__()
+
+        self.setWindowTitle("Module Finder PyQt5 app")
+
+        button = QPushButton("Press Here for the magic")
+
+        button.setCheckable(True)
+        button.clicked.connect(self.on_button_clicked)
+
+        # Set properties of the  widget in the Window.
+        self.setCentralWidget(button)
+
+
+    def on_button_clicked(self):
+        print("Button has been clicked!")
+        alert = QMessageBox()
+        alert.setText('You clicked the button!')
+        alert.exec()
+
+
+## Application definition
+
+def main():
+    # Only one QApplication instance is needed per application.
+    # Pass in sys.argv to allow command line arguments for the app: `QApplication(sys.argv)`
+    # If command line arguments are not needed, use: `QApplication([])`
+    app = QApplication([])
+
+    # Create a QMainWindow object which represents the Main Window.
+    main_window = MainWindow()
+    main_window.showMaximized()  # This line will show windows that are normally hidden. Plus, it will maximise the main window.
+
+    # Start the application event loop.
+    app.exec()
+
+    # The application will only reach here when exiting or event loop has stopped.
+
+if __name__ == "__main__":
+    # This section needs to only define main
+    # due to how pyqtdeploy is implemented to build packages
+    main()