flet-android-background 0.0.1__tar.gz

flet_android_background-0.0.1/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+build/
+evidence/
+*.egg-info/
+.pytest_cache/
+.dart_tool/
+.flutter-plugins-dependencies
+tests/flutter/pubspec.lock

flet_android_background-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Stoica
+
+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.

flet_android_background-0.0.1/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: flet-android-background
+Version: 0.0.1
+Summary: Experimental foreground tasks for Flet on Android
+Project-URL: Homepage, https://github.com/alex-stoica/flet-android-background
+Project-URL: Repository, https://github.com/alex-stoica/flet-android-background
+Project-URL: Issues, https://github.com/alex-stoica/flet-android-background/issues
+Author-email: Alex Stoica <alexstoica@protonmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.11
+Requires-Dist: flet==1.0.3
+Description-Content-Type: text/markdown
+
+# flet-android-background
+
+Experimental Flet Android tasks; one owns the foreground service.
+Locking permits continued execution; Android restrictions still apply.
+Dismissal or runtime loss stops the service. Process death has no recovery.
+
+Install the wheel with pip. Add `BackgroundTask` to your Flet app, then
+`await task.start(work)` or `await task.stop()`.
+
+Before building the generated Flutter project:
+
+```python
+from flet_android_background.android import configure_android_project
+
+configure_android_project(path, service_type="dataSync")
+```
+
+Supported types: `dataSync`, `shortService`, `specialUse`. The latter requires
+an app-specific `subtype` explanation. Android time limits apply.

flet_android_background-0.0.1/README.md

@@ -0,0 +1,19 @@
+# flet-android-background
+
+Experimental Flet Android tasks; one owns the foreground service.
+Locking permits continued execution; Android restrictions still apply.
+Dismissal or runtime loss stops the service. Process death has no recovery.
+
+Install the wheel with pip. Add `BackgroundTask` to your Flet app, then
+`await task.start(work)` or `await task.stop()`.
+
+Before building the generated Flutter project:
+
+```python
+from flet_android_background.android import configure_android_project
+
+configure_android_project(path, service_type="dataSync")
+```
+
+Supported types: `dataSync`, `shortService`, `specialUse`. The latter requires
+an app-specific `subtype` explanation. Android time limits apply.

flet_android_background-0.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "flet-android-background"
+version = "0.0.1"
+description = "Experimental foreground tasks for Flet on Android"
+readme = "README.md"
+license = "MIT"
+authors = [{name = "Alex Stoica", email = "alexstoica@protonmail.com"}]
+requires-python = ">=3.11"
+dependencies = ["flet==1.0.3"]
+classifiers = ["Development Status :: 3 - Alpha"]
+
+[project.urls]
+Homepage = "https://github.com/alex-stoica/flet-android-background"
+Repository = "https://github.com/alex-stoica/flet-android-background"
+Issues = "https://github.com/alex-stoica/flet-android-background/issues"
+
+[build-system]
+requires = ["hatchling<1.32"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flet_android_background", "src/flutter"]

flet_android_background-0.0.1/src/flet_android_background/__init__.py

@@ -0,0 +1,93 @@
+import asyncio
+from collections.abc import Awaitable, Callable
+
+from .service import ForegroundService
+
+Callback = Callable[[], Awaitable[None]]
+
+
+class BackgroundTask:
+    """Run one cooperative task. Process death ends execution without restart."""
+
+    def __init__(self, service: ForegroundService | None = None):
+        self.service = service or ForegroundService()
+        self.service.on_stopped = self._stopped
+        self.error: Exception | None = None
+        self._task: asyncio.Task[None] | None = None
+        self._work: asyncio.Task[None] | None = None
+        self._lock = asyncio.Lock()
+
+    @property
+    def running(self) -> bool:
+        return self._task is not None and not self._task.done()
+
+    async def start(self, work: Callback, *, on_stop: Callback | None = None,
+                    **notification) -> bool:
+        """Start once after notification permission; duplicates return False."""
+        async with self._lock:
+            if self.running:
+                return False
+            self.error = None
+            starting = asyncio.create_task(self._start_native(notification))
+            try:
+                failure = await asyncio.shield(starting)
+            except asyncio.CancelledError:
+                self._task = asyncio.create_task(self._rollback(starting))
+                await asyncio.shield(self._task)
+                raise
+            if failure is not None:
+                raise failure
+            self._work = asyncio.create_task(self._invoke(work))
+            self._task = asyncio.create_task(self._run(self._work, on_stop))
+            return True
+
+    async def _invoke(self, work: Callback):
+        await work()
+
+    async def _start_native(self, notification):
+        try:
+            await self.service.start_foreground_service(**notification)
+        except Exception as exc:
+            return exc
+
+    async def _rollback(self, starting):
+        try:
+            self.error = await starting
+            if self.error is None:
+                await self.service.stop_foreground_service()
+        except Exception as exc:
+            self.error = exc
+
+    async def _run(self, work: asyncio.Task[None], on_stop: Callback | None):
+        try:
+            await work
+        except asyncio.CancelledError:
+            pass
+        except Exception as exc:
+            self.error = exc
+        finally:
+            try:
+                if on_stop is not None:
+                    await on_stop()
+            except Exception as exc:
+                self.error = self.error or exc
+            finally:
+                try:
+                    await self.service.stop_foreground_service()
+                except Exception as exc:
+                    self.error = self.error or exc
+
+    async def stop(self) -> None:
+        """Cancel work and await cleanup once."""
+        async with self._lock:
+            if self.running:
+                if self._work is not None:
+                    self._work.cancel()
+                await asyncio.shield(self._task)
+
+    async def _stopped(self, event):
+        async with self._lock:
+            if event.data == self.service._owner and self.running:
+                if self._work is not None:
+                    self._work.cancel()
+                await asyncio.shield(self._task)

flet_android_background-0.0.1/src/flet_android_background/android.py

@@ -0,0 +1,43 @@
+from pathlib import Path
+import xml.etree.ElementTree as ET
+
+ANDROID = "http://schemas.android.com/apk/res/android"
+NAME = f"{{{ANDROID}}}name"
+SERVICE = "dev.alexstoica.background.TaskService"
+TYPES = {"dataSync": "DATA_SYNC", "shortService": None, "specialUse": "SPECIAL_USE"}
+
+
+def configure_android_project(project: str | Path, *, service_type: str,
+                              subtype: str = "") -> None:
+    """Declare the app's foreground purpose before building its generated Flutter project."""
+    if service_type not in TYPES:
+        raise ValueError(f"service_type must be one of {tuple(TYPES)}")
+    if service_type == "specialUse" and not subtype.strip():
+        raise ValueError("specialUse requires an app-specific subtype explanation")
+    path = Path(project) / "android/app/src/main/AndroidManifest.xml"
+    ET.register_namespace("android", ANDROID)
+    ET.register_namespace("tools", "http://schemas.android.com/tools")
+    tree = ET.parse(path, parser=ET.XMLParser(target=ET.TreeBuilder(insert_comments=True)))
+    manifest = tree.getroot()
+    application = manifest.find("application")
+    if application is None:
+        raise ValueError("Android manifest has no application")
+    service = next((s for s in application.findall("service") if s.get(NAME) == SERVICE), None)
+    if service is None:
+        service = ET.SubElement(application, "service", {NAME: SERVICE})
+    service.set(f"{{{ANDROID}}}foregroundServiceType", service_type)
+    service.set(f"{{{ANDROID}}}exported", "false")
+    for prop in list(service.findall("property")):
+        if prop.get(NAME) == "android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE":
+            service.remove(prop)
+    if service_type == "specialUse":
+        ET.SubElement(service, "property", {
+            NAME: "android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE",
+            f"{{{ANDROID}}}value": subtype.strip(),
+        })
+    suffix = TYPES[service_type]
+    if suffix:
+        permission = f"android.permission.FOREGROUND_SERVICE_{suffix}"
+        if not any(p.get(NAME) == permission for p in manifest.findall("uses-permission")):
+            ET.SubElement(manifest, "uses-permission", {NAME: permission})
+    tree.write(path, encoding="utf-8", xml_declaration=True)

flet_android_background-0.0.1/src/flet_android_background/service.py

@@ -0,0 +1,25 @@
+import flet as ft
+
+
+@ft.control("flet_android_background")
+class ForegroundService(ft.Service):
+    on_stopped: ft.ControlEventHandler | None = None
+    _owner: str | None = None
+
+    async def _call(self, method, **arguments):
+        result = await self._invoke_method(method_name=method, arguments=arguments)
+        if isinstance(result, dict) and "error" in result:
+            raise RuntimeError(result["error"])
+        return result
+
+    async def request_permissions(self) -> bool:
+        return await self._call("permission")
+
+    async def start_foreground_service(self, *, notification_id=1,
+                                       title="Background task", body="Running"):
+        if notification_id <= 0:
+            raise ValueError("notification_id must be positive")
+        self._owner = await self._call("start", id=notification_id, title=title, body=body)
+
+    async def stop_foreground_service(self):
+        await self._call("stop")

flet_android_background-0.0.1/src/flutter/flet_android_background/android/build.gradle

@@ -0,0 +1,13 @@
+group = "dev.alexstoica.background"
+version = "0.0.1"
+apply plugin: "com.android.library"
+
+android {
+    namespace = "dev.alexstoica.background"
+    compileSdk = 36
+    defaultConfig { minSdk = 24 }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+}

flet_android_background-0.0.1/src/flutter/flet_android_background/android/src/main/AndroidManifest.xml

@@ -0,0 +1,8 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <application>
+        <service android:name="dev.alexstoica.background.TaskService"
+            android:exported="false" />
+    </application>
+</manifest>

flet_android_background-0.0.1/src/flutter/flet_android_background/android/src/main/java/dev/alexstoica/background/BackgroundPlugin.java

@@ -0,0 +1,133 @@
+package dev.alexstoica.background;
+
+import android.Manifest;
+import android.content.Context;
+import android.content.Intent;
+import android.content.pm.PackageManager;
+import android.os.Build;
+import io.flutter.embedding.engine.plugins.FlutterPlugin;
+import io.flutter.embedding.engine.plugins.activity.ActivityAware;
+import io.flutter.embedding.engine.plugins.activity.ActivityPluginBinding;
+import io.flutter.plugin.common.MethodCall;
+import io.flutter.plugin.common.MethodChannel;
+import io.flutter.plugin.common.PluginRegistry.RequestPermissionsResultListener;
+import java.util.ArrayList;
+
+public class BackgroundPlugin implements FlutterPlugin, ActivityAware,
+        MethodChannel.MethodCallHandler, RequestPermissionsResultListener {
+    private Context context;
+    private MethodChannel channel;
+    private ActivityPluginBinding binding;
+    private MethodChannel.Result permission;
+    private MethodChannel.Result starting;
+    private final ArrayList<MethodChannel.Result> stopping = new ArrayList<>();
+    private String token;
+    private static final int REQUEST = 7141;
+
+    @Override public void onAttachedToEngine(FlutterPluginBinding engine) {
+        context = engine.getApplicationContext();
+        channel = new MethodChannel(engine.getBinaryMessenger(), "flet_android_background");
+        channel.setMethodCallHandler(this);
+    }
+
+    @Override public void onMethodCall(MethodCall call, MethodChannel.Result result) {
+        try {
+            switch (call.method) {
+                case "permission":
+                    if (Build.VERSION.SDK_INT < 33 || context.checkSelfPermission(
+                            Manifest.permission.POST_NOTIFICATIONS) == PackageManager.PERMISSION_GRANTED) {
+                        result.success(true);
+                    } else if (binding == null || permission != null) {
+                        result.error("permission", "No activity or permission request already pending", null);
+                    } else {
+                        permission = result;
+                        binding.getActivity().requestPermissions(
+                            new String[]{Manifest.permission.POST_NOTIFICATIONS}, REQUEST);
+                    }
+                    break;
+                case "start":
+                    if (TaskService.owner != null) {
+                        result.error("running", "A background task already owns this service", null);
+                        break;
+                    }
+                    Intent intent = new Intent(context, TaskService.class)
+                        .putExtra("id", ((Number) call.argument("id")).intValue())
+                        .putExtra("title", (String) call.argument("title"))
+                        .putExtra("body", (String) call.argument("body"));
+                    token = call.argument("owner");
+                    if (token == null) throw new IllegalArgumentException("Missing service owner");
+                    TaskService.owner = this;
+                    starting = result;
+                    try {
+                        if (Build.VERSION.SDK_INT >= 26) context.startForegroundService(intent);
+                        else context.startService(intent);
+                    } catch (Exception error) {
+                        TaskService.owner = null;
+                        onStarted(error);
+                    }
+                    break;
+                case "stop":
+                    if (TaskService.owner != this || !token.equals(call.argument("owner"))) {
+                        result.success(null);
+                    } else {
+                        stopping.add(result);
+                        context.stopService(new Intent(context, TaskService.class));
+                    }
+                    break;
+                default:
+                    result.notImplemented();
+            }
+        } catch (Exception error) {
+            result.error("native", error.toString(), null);
+        }
+    }
+
+    void onStarted(Exception error) {
+        if (starting == null) return;
+        MethodChannel.Result result = starting;
+        starting = null;
+        if (error == null) result.success(null);
+        else result.error("start", error.toString(), null);
+    }
+
+    void onStopped() {
+        onStarted(new IllegalStateException("Service stopped during startup"));
+        if (channel != null) channel.invokeMethod("stopped", token);
+        token = null;
+        for (MethodChannel.Result result : stopping) result.success(null);
+        stopping.clear();
+    }
+
+    @Override public boolean onRequestPermissionsResult(int code, String[] names, int[] grants) {
+        if (code != REQUEST || permission == null) return false;
+        permission.success(grants.length > 0 && grants[0] == PackageManager.PERMISSION_GRANTED);
+        permission = null;
+        return true;
+    }
+
+    @Override public void onAttachedToActivity(ActivityPluginBinding activity) {
+        binding = activity;
+        binding.addRequestPermissionsResultListener(this);
+    }
+    @Override public void onDetachedFromActivity() {
+        if (binding != null) binding.removeRequestPermissionsResultListener(this);
+        binding = null;
+        if (permission != null) {
+            permission.error("activity", "Activity detached during permission request", null);
+            permission = null;
+        }
+    }
+    @Override public void onDetachedFromActivityForConfigChanges() { onDetachedFromActivity(); }
+    @Override public void onReattachedToActivityForConfigChanges(ActivityPluginBinding activity) {
+        onAttachedToActivity(activity);
+    }
+    @Override public void onDetachedFromEngine(FlutterPluginBinding engine) {
+        onDetachedFromActivity();
+        channel.setMethodCallHandler(null);
+        channel = null;
+        if (TaskService.owner == this) {
+            onStopped();
+            context.stopService(new Intent(context, TaskService.class));
+        }
+    }
+}

flet_android_background-0.0.1/src/flutter/flet_android_background/android/src/main/java/dev/alexstoica/background/TaskService.java

@@ -0,0 +1,62 @@
+package dev.alexstoica.background;
+
+import android.app.Notification;
+import android.app.NotificationChannel;
+import android.app.NotificationManager;
+import android.app.PendingIntent;
+import android.app.Service;
+import android.content.Intent;
+import android.os.Build;
+import android.os.IBinder;
+
+public class TaskService extends Service {
+    static BackgroundPlugin owner;
+    private static final String CHANNEL = "python_background";
+
+    @Override public int onStartCommand(Intent intent, int flags, int startId) {
+        if (owner == null || intent == null || "stop".equals(intent.getAction())) {
+            stopSelf();
+            return START_NOT_STICKY;
+        }
+        Exception failure = null;
+        try {
+            Notification.Builder builder;
+            if (Build.VERSION.SDK_INT >= 26) {
+                getSystemService(NotificationManager.class).createNotificationChannel(
+                    new NotificationChannel(CHANNEL, "Background tasks", NotificationManager.IMPORTANCE_LOW));
+                builder = new Notification.Builder(this, CHANNEL);
+            } else {
+                builder = new Notification.Builder(this);
+            }
+            PendingIntent stop = PendingIntent.getService(this, 0,
+                new Intent(this, TaskService.class).setAction("stop"), PendingIntent.FLAG_IMMUTABLE);
+            Intent launch = getPackageManager().getLaunchIntentForPackage(getPackageName());
+            builder.setContentTitle(intent.getStringExtra("title"))
+                .setContentText(intent.getStringExtra("body"))
+                .setSmallIcon(getApplicationInfo().icon).setOngoing(true)
+                .addAction(new Notification.Action.Builder(null, "Stop", stop).build());
+            if (launch != null) builder.setContentIntent(PendingIntent.getActivity(
+                this, 0, launch, PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_UPDATE_CURRENT));
+            startForeground(intent.getIntExtra("id", 1), builder.build());
+        } catch (Exception error) {
+            failure = error;
+            stopSelf();
+        }
+        owner.onStarted(failure);
+        return START_NOT_STICKY;
+    }
+
+    @Override public void onTaskRemoved(Intent intent) { stopSelf(); }
+    @Override public void onTimeout(int startId) { stopSelf(); }
+    @Override public void onTimeout(int startId, int type) { stopSelf(); }
+
+    @Override public void onDestroy() {
+        BackgroundPlugin previous = owner;
+        owner = null;
+        stopForeground(STOP_FOREGROUND_REMOVE);
+        if (previous != null) previous.onStopped();
+        super.onDestroy();
+    }
+
+    @Override public IBinder onBind(Intent intent) { return null; }
+}

flet_android_background-0.0.1/src/flutter/flet_android_background/lib/flet_android_background.dart

@@ -0,0 +1,62 @@
+import 'package:flet/flet.dart';
+import 'package:flutter/services.dart';
+
+class Extension extends FletExtension {
+  @override
+  FletService? createService(Control control) =>
+      control.type == 'flet_android_background'
+          ? BackgroundService(control: control)
+          : null;
+}
+
+class BackgroundService extends FletService {
+  BackgroundService({required super.control});
+  static const channel = MethodChannel('flet_android_background');
+  static BackgroundService? owner;
+  static int sequence = 0;
+  String? token;
+
+  @override
+  void init() {
+    super.init();
+    control.addInvokeMethodListener(invoke);
+    channel.setMethodCallHandler((call) async {
+      final active = owner;
+      if (call.method == 'stopped' && active?.token == call.arguments) {
+        owner = null;
+        active?.token = null;
+        active?.control.triggerEvent('stopped', call.arguments);
+      }
+    });
+  }
+
+  Future<dynamic> invoke(String method, dynamic arguments) async {
+    if (method == 'start') {
+      if (owner != null) return {'error': 'A background task already owns this service'};
+      owner = this;
+      token = '${DateTime.now().microsecondsSinceEpoch}-${sequence++}';
+    } else if (method == 'stop' && owner != this) {
+      return null;
+    }
+    try {
+      final requested = token;
+      final result = await channel.invokeMethod(method, {...?arguments, 'owner': token});
+      return method == 'start' ? requested : result;
+    } on PlatformException catch (error) {
+      if (method == 'start' && owner == this) {
+        owner = null;
+        token = null;
+      }
+      return {'error': error.message ?? error.code};
+    }
+  }
+
+  @override
+  void dispose() {
+    control.removeInvokeMethodListener(invoke);
+    if (owner == this) {
+      invoke('stop', <String, dynamic>{});
+    }
+    super.dispose();
+  }
+}

flet_android_background-0.0.1/src/flutter/flet_android_background/pubspec.yaml

@@ -0,0 +1,17 @@
+name: flet_android_background
+description: Foreground task lifecycle for Flet Android apps
+version: 0.0.1
+publish_to: none
+environment:
+  sdk: '>=3.12.0 <4.0.0'
+  flutter: '>=3.44.8'
+dependencies:
+  flutter:
+    sdk: flutter
+  flet: 1.0.3
+flutter:
+  plugin:
+    platforms:
+      android:
+        package: dev.alexstoica.background
+        pluginClass: BackgroundPlugin