Update README.md

README.md

@@ -2,64 +2,169 @@
 
 This is an unofficial Chaquopy Flutter plugin to run Python code on Android. This is the simplest version, where you can write your code and run it.
 
-## Configuration Steps : 
+This guide provides step-by-step instructions to integrate Chaquopy into your Flutter project.
 
-Add  `maven { url "https://chaquo.com/maven" }` and add chaquopy dependency in dependencies section at project level `gradle.build` like following :
-You can find the latest-version of `chaquopy` [here](https://chaquo.com/chaquopy/), also make sure to update the gradle, python and minimum SDK versions accordingly. You can find the compatible python, android gradle version and minimum SDK version based on chaquopy version [here](https://chaquo.com/chaquopy/doc/15.0/versions.html):
+---
 
+### 1. Install the Chaquopy Dependency
+Run the following command to add Chaquopy to your Flutter project:
+```bash
+flutter pub add chaquopy
 ```
-buildscript {
-    repositories {
-        google()
-        jcenter()
-        maven { url "https://chaquo.com/maven" }
-    }
-    dependencies {
-        ...
-        classpath "com.chaquo.python:gradle:latest-version"
-    }
-}
+
+---
+
+### 2. Update `android/build.gradle`
+
+#### a. Add Chaquopy's Maven Repository
+In the `repositories` block, add the following:
+```gradle
+maven { url "https://chaquo.com/maven" }
+```
+
+#### b. Add Chaquopy and Android Build Tools to Dependencies
+In the `dependencies` block, add:
+```gradle
+classpath "com.android.tools.build:gradle:8.7.3"
+classpath "com.chaquo.python:gradle:12.0.0"
 ```
 
-Then, in the module-level build.gradle file (usually in the app directory), apply the Chaquopy plugin at the top of the file, but after the Android plugin:
+---
+
+### 3. Update `android/local.properties`
 
+Add the following lines:
+```properties
+chaquopy.license=free
+chaquopy.applicationId=com.company.app_name
 ```
-apply plugin: 'com.android.application' 
-apply plugin: 'com.chaquo.python' 
+
+> Replace `com.company.app_name` with your app's package name.
+
+---
+
+### 4. Update `android/app/build.gradle`
+
+#### a. Add the Chaquopy Plugin
+In the `plugins` block, add:
+```gradle
+id "com.chaquo.python"
 ```
 
-Apply ABI selection using following code.
+#### b. Update `compileSdkVersion`
+Set `compileSdkVersion` to:
+```gradle
+compileSdkVersion 34
+```
 
+#### c. Add Kotlin JVM Toolchain
+In the `android` block, add:
+```gradle
+kotlin {
+    jvmToolchain(17)
+}
 ```
-defaultConfig {
-    ndk {
-       abiFilters "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
+
+#### d. Update `defaultConfig`
+Add the following inside the `defaultConfig` block:
+```gradle
+ndk {
+    abiFilters "arm64-v8a", "x86_64"
+}
+python {
+    buildPython "C:\\Python83\\python.exe" // Path to Python 8.3 on your system
+    pip {
+        install "numpy>=1.17.3"
+        install "scikit-learn"
+        install "neurokit2"
     }
 }
 ```
 
-add this line to application tag in manifest file 
-```
-android:name="com.chaquo.python.android.PyApplication".
-```
+> Replace the `buildPython` path with the installation path of Python 8.3 on your system.  
+> In the `pip` block, list the Python libraries your project requires.
 
-After that sync your project.
+---
 
-Now, in your android folder, you'll have additional python folder created. Now, Download [script.py](https://drive.google.com/file/d/1D4Hjt66f0MXkaeAQ8WLX3DEebX3BrFvM/view?usp=sharing) and put it in python directory. (Kindly note that this python file should not be renamed other than script.py and also if your code doesn't work, check the intendations of the downloaded file.)
+### 5. Modify `AndroidManifest.xml`
 
-Now in order to use the chaquopy plugin import the chaquopy package in your flutter app through declaring the package inside pubspec.yaml file.
+Replace or remove the `android:name` attribute in the `<application>` tag:
+```xml
+android:name="com.chaquo.python.android.PyApplication"
+```
 
-Now you can run the code easily by calling `Chaquopy.executeCode(code)` function which returns a map. 
+---
 
-The map returned contains two properties and it contains follwing structure:
+### 6. Add a Python Script
 
+Create a file named `script.py` in the following directory:
+```
+android/app/src/main/python
 ```
-{
-    "textOutputOrError" : "code output or error",
+
+#### Content of `script.py`
+```python
+import io, os, sys, time, threading, ctypes, inspect, traceback
+
+def _async_raise(tid, exctype):
+    tid = ctypes.c_long(tid)
+    if not inspect.isclass(exctype):
+        exctype = type(exctype)
+    res = ctypes.pythonapi.PyThreadState_SetAsyncExc(tid, ctypes.py_object(exctype))
+    if res == 0:
+        raise ValueError("invalid thread id")
+    elif res != 1:
+        ctypes.pythonapi.PyThreadState_SetAsyncExc(tid, None)
+        raise SystemError("Timeout Exception")
+
+def stop_thread(thread):
+    _async_raise(thread.ident, SystemExit)
+
+def text_thread_run(code):
+    try:
+        env = {}
+        exec(code, env, env)
+    except Exception as e:
+        print(e)
+
+def mainTextCode(code):
+    global thread1
+    thread1 = threading.Thread(target=text_thread_run, args=(code,), daemon=True)
+    thread1.start()
+    timeout = 15  # Change timeout settings in seconds here...
+    thread1_start_time = time.time()
+    while thread1.is_alive():
+        if time.time() - thread1_start_time > timeout:
+            stop_thread(thread1)
+            raise TimeoutError
+        time.sleep(1)
+```
+
+---
+
+### 7. Usage Example in Flutter
+
+Assume your Python script always outputs JSON strings. Here’s how you can invoke it in Flutter:
+```dart
+import 'dart:convert';
+import 'package:chaquopy/chaquopy.dart';
+
+void executePythonScript() async {
+  final result = await Chaquopy.executeCode(
+      'print("{\\"msg\\": \\"Hello from Python!\\"}")');
+  final json = jsonDecode(result['textOutputOrError'].toString().replaceAll("'", "\""));
+  print(json["msg"]); // Outputs: Hello from Python!
 }
 ```
 
-you can easily access this code via `result["textOutputOrError"]` , where result is variable of type map and you can name it anything you want.
+---
+
+### Notes
+- Ensure Python 8.3 is installed on your system.
+- Update the paths and dependencies based on your project’s requirements.
+- Verify the `script.py` file is correctly placed under `android/app/src/main/python`.
+
+You are now ready to use Chaquopy with Flutter! 🎉
 
 ## FAQs: