Flet Extension

When to Use Which

• Service: SDKs that run in background, platform APIs (push, permissions, location, audio)
• UI Control: Widgets that render on screen and occupy visual space (players, maps, charts)

Directory Structure

flet-my-extension/
├── pyproject.toml                    # Python package config
├── README.md
├── CHANGELOG.md
├── LICENSE
├── tests/
│   └── test_my_extension.py
├── examples/
│   └── flet_my_extension_example/
│       ├── pyproject.toml            # Example app config
│       └── src/
│           └── main.py
└── src/
    ├── flet_my_extension/            # Python code
    │   ├── __init__.py               # Public exports
    │   ├── my_service.py             # Main control (ft.Service or ft.LayoutControl)
    │   ├── sub_module_a.py           # Sub-module A (pure Python class)
    │   ├── sub_module_b.py           # Sub-module B (pure Python class)
    │   └── types.py                  # Enums, events, dataclasses
    └── flutter/flet_my_extension/    # Flutter/Dart code
        ├── pubspec.yaml
        └── lib/
            ├── flet_my_extension.dart  # Only exports Extension
            └── src/
                ├── extension.dart      # Extension registration
                └── my_service.dart     # Flutter implementation

Extension Registration Pattern

// lib/flet_my_extension.dart
library flet_my_extension;
export 'src/extension.dart' show Extension;

// lib/src/extension.dart — FOR SERVICES
import 'package:flet/flet.dart';
import 'my_service.dart';

class Extension extends FletExtension {
  @override
  void ensureInitialized() {
    debugPrint("MyPlugin: ensureInitialized");
  }

  @override
  FletService? createService(Control control) {
    switch (control.type) {
      case "MyService":  // Must match @ft.control("MyService")
        return MyServiceImpl(control: control);
      default:
        return null;
    }
  }
}

// lib/src/extension.dart — FOR UI CONTROLS
import 'package:flet/flet.dart';
import 'my_widget.dart';

class Extension extends FletExtension {
  @override
  Widget? createWidget(Control control) {
    switch (control.type) {
      case "MyWidget":  // Must match @ft.control("MyWidget")
        return MyWidgetWidget(control: control);
      default:
        return null;
    }
  }
}

Critical rule: control.type must be identical to the string in @ft.control("MyService").

flet-pkg CLI Tool

Overview

flet-pkg is a CLI tool that scaffolds Flet extension packages with auto-generated code from Flutter package analysis.

Usage

# Auto-analyze a Flutter package from pub.dev and generate code
flet-pkg create my-extension --analyze

# Skip analysis (manual implementation)
flet-pkg create my-extension --no-analyze

# Use a local Dart package instead of pub.dev
flet-pkg create my-extension --local-package /path/to/dart/pkg

# Choose extension type
flet-pkg create my-extension --type service     # ft.Service
flet-pkg create my-extension --type ui_control  # ft.LayoutControl

Pipeline: download → parse → analyze → generate

1. Download: Fetches Flutter package source from pub.dev (cached in ~/.cache/flet-pkg/)
2. Parse: Extracts Dart API (classes, methods, properties, enums) from source files
3. Analyze: Creates a GenerationPlan with Python↔Dart mappings, type conversions, invoke keys
4. Generate: Produces Python control, types, init, and Dart service files from templates

When to Use flet-pkg vs Manual

• flet-pkg: When wrapping an existing Flutter/Dart package — auto-generates type mappings, method stubs, enum definitions
• Manual: When creating a novel extension or when the Flutter package is very complex with custom patterns

Service Control Pattern (Python)

Main Control Class

# src/flet_my_extension/my_service.py

from dataclasses import field
from typing import Any, Optional

import flet as ft

from flet_my_extension.sub_module_a import SubModuleA
from flet_my_extension.types import (
    MyEvent,
    MyLogLevel,
    ErrorEvent,
)


@ft.control("MyService")  # Name must correspond to Flutter side
class MyService(ft.Service):
    """
    Integration service for XYZ SDK.

    Add to `page.services` — do NOT use `page.overlay`.

    Example:
        ```python
        service = MyService(app_id="your-id")
        page.services.append(service)
        await service.do_something("param")
        ```
    """

    # ── Public properties (sent to Flutter) ─────────────────────────────
    app_id: str = ""
    log_level: Optional[MyLogLevel] = None
    require_consent: bool = False

    # ── Public events ────────────────────────────────────────────────────
    on_event: Optional[ft.EventHandler[MyEvent]] = None
    on_error: Optional[ft.EventHandler[ErrorEvent]] = None

    # ── Internal fields (NOT sent to Flutter) ────────────────────────────
    _sub_a: SubModuleA = field(default=None, init=False, metadata={"skip": True})

    # ── Lifecycle ────────────────────────────────────────────────────────
    def init(self):
        """Called when the control is mounted in the Flutter tree."""
        super().init()
        self._sub_a = SubModuleA(self)

    # ── Properties (lazy init for robustness) ────────────────────────────
    @property
    def sub_a(self) -> SubModuleA:
        if self._sub_a is None:
            self._sub_a = SubModuleA(self)
        return self._sub_a

    # ── Public methods (call Flutter via _invoke_method) ─────────────────
    async def login(self, user_id: str) -> None:
        await self._invoke_method("login", {"user_id": user_id})

    async def logout(self) -> None:
        await self._invoke_method("logout")

    async def get_status(self, timeout: float = 10.0) -> bool:
        result = await self._invoke_method("get_status", timeout=timeout)
        return result == "true"

    async def get_tags(self) -> dict:
        import json
        result = await self._invoke_method("get_tags")
        return json.loads(result) if result else {}

    # ── Platform validation ──────────────────────────────────────────────
    def _is_supported_platform(self) -> bool:
        """Validate before calling methods (NOT in before_update)."""
        if not self.page:
            return False
        return self.page.platform in (
            ft.PagePlatform.ANDROID,
            ft.PagePlatform.IOS,
        )

    async def _invoke_method(
        self,
        method_name: str,
        arguments: Optional[dict[str, Any]] = None,
        timeout: Optional[float] = None,
    ) -> Any:
        """Override to add platform validation."""
        if not self._is_supported_platform():
            platform = self.page.platform.value if self.page else "unknown"
            raise ft.FletUnsupportedPlatformException(
                f"MyService only supports Android and iOS. "
                f"Current platform: {platform}."
            )
        effective_timeout = timeout if timeout is not None else 25.0
        return await super()._invoke_method(
            method_name=method_name,
            arguments=arguments or {},
            timeout=effective_timeout,
        )

Sub-Module (Pure Python Class)

# src/flet_my_extension/sub_module_a.py

from typing import TYPE_CHECKING, Optional

if TYPE_CHECKING:
    from flet_my_extension.my_service import MyService


class SubModuleA:
    """
    Sub-module A — Namespace for functionality.

    Does not inherit from ft.Service. Delegates _invoke_method to parent service.
    Mirrors the modular architecture of third-party SDKs.
    """

    def __init__(self, service: "MyService"):
        self._service = service

    async def do_something(self, param: str) -> Optional[str]:
        result = await self._service._invoke_method(
            "sub_a_do_something",
            {"param": param},
        )
        return result if result else None

    async def get_value(self, timeout: float = 25) -> bool:
        result = await self._service._invoke_method(
            "sub_a_get_value",
            timeout=timeout,
        )
        return result == "true"

Service Control Pattern (Dart)

FletService Implementation

// lib/src/my_service.dart
import 'dart:convert';
import 'package:flet/flet.dart';
import 'package:flutter/foundation.dart';
import 'package:third_party_sdk/third_party_sdk.dart';

class MyServiceImpl extends FletService {
  MyServiceImpl({required super.control});

  bool _initialized = false;
  bool _listenersSetup = false;

  // ── Lifecycle ─────────────────────────────────────────────────────────

  @override
  void init() {
    super.init();
    debugPrint("MyService.init: type=${control.type}");

    // Register invoke method handler BEFORE initializing
    control.addInvokeMethodListener(_onInvokeMethod);

    // Initialize SDK with current control properties
    _initializeSdk();
  }

  @override
  Future<void> update() async {
    // Called when Python properties change
    final appId = control.getString("app_id");
    if (appId != null && !_initialized) {
      _initializeSdk();
    }
  }

  @override
  void dispose() {
    // Clean up listeners and resources on unmount
    super.dispose();
  }

  // ── SDK Initialization ────────────────────────────────────────────────

  void _initializeSdk() {
    final appId = control.getString("app_id");
    if (appId == null || appId.isEmpty) {
      debugPrint("MyService: app_id not provided");
      return;
    }

    try {
      // Configure BEFORE initializing (read SDK docs)
      final logLevel = control.getString("log_level");
      if (logLevel != null) {
        _configureLog(logLevel);
      }

      final requireConsent = control.getBool("require_consent", false)!;
      if (requireConsent) {
        Sdk.consentRequired(true);
      }

      Sdk.initialize(appId);
      _initialized = true;

      // Set up listeners AFTER initialization
      _setupListeners();
    } catch (error, stackTrace) {
      _handleError("_initializeSdk", error, stackTrace);
    }
  }

  // ── SDK Listeners → Python Events ─────────────────────────────────────

  void _setupListeners() {
    if (_listenersSetup) return;  // Guard against duplicates
    _listenersSetup = true;

    Sdk.addListener((event) {
      try {
        control.triggerEvent("event", {
          "data": event.data,
          "success": true,
        });
      } catch (error, stackTrace) {
        _handleError("event_listener", error, stackTrace);
      }
    });

    debugPrint("MyService._setupListeners: ready");
  }

  // ── Invoke Method Handler (Python → Dart) ─────────────────────────────

  Future<dynamic> _onInvokeMethod(String methodName, dynamic args) async {
    try {
      // IMPORTANT: Convert args to Map<String, dynamic>
      // Can arrive as _Map<dynamic, dynamic> from Flet
      Map<String, dynamic> arguments = {};
      if (args != null && args is Map) {
        arguments = Map<String, dynamic>.from(args);
      }

      debugPrint("MyService._onInvokeMethod: method=$methodName, args=$arguments");

      // Use switch expression (Dart 3+)
      return switch (methodName) {
        "login"              => await _login(arguments),
        "logout"             => await _logout(),
        "get_status"         => _getStatus(),
        "get_tags"           => await _getTags(),
        "sub_a_do_something" => await _subADoSomething(arguments),
        "sub_a_get_value"    => _subAGetValue(),
        _                    => throw Exception("Unknown method: $methodName"),
      };
    } catch (error, stackTrace) {
      _handleError(methodName, error, stackTrace);
      return null;
    }
  }

  // ── Method Implementations ────────────────────────────────────────────

  Future<String?> _login(Map<String, dynamic> args) async {
    final userId = args["user_id"] as String?;
    if (userId != null) {
      await Sdk.login(userId);
    }
    return null;  // Return null for void methods
  }

  Future<String?> _logout() async {
    await Sdk.logout();
    return null;
  }

  String _getStatus() {
    // Return "true"/"false" for booleans
    // Python does: result == "true"
    return Sdk.getStatus().toString();
  }

  Future<String?> _getTags() async {
    final tags = await Sdk.getTags();
    // Return as JSON string — Python does json.loads()
    return jsonEncode(tags);
  }

  Future<String?> _subADoSomething(Map<String, dynamic> args) async {
    final param = args["param"] as String?;
    if (param != null) {
      await Sdk.doSomething(param);
    }
    return null;
  }

  String _subAGetValue() {
    return Sdk.getValue().toString();
  }

  // ── Error Handling ────────────────────────────────────────────────────

  void _handleError(String method, Object error, StackTrace stackTrace) {
    debugPrint("MyService ERROR in $method: $error");
    FlutterError.reportError(FlutterErrorDetails(
      exception: error,
      stack: stackTrace,
      library: 'flet_my_extension',
      context: ErrorDescription('while executing method "$method"'),
    ));
    // Trigger error event for Python
    control.triggerEvent("error", {
      "method": method,
      "message": error.toString(),
      "stack_trace": stackTrace.toString(),
    });
  }

  // ── Configuration Helpers ─────────────────────────────────────────────

  void _configureLog(String level) {
    final sdkLevel = switch (level.toLowerCase()) {
      "none"  => LogLevel.none,
      "debug" => LogLevel.debug,
      "info"  => LogLevel.info,
      "warn"  => LogLevel.warn,
      "error" => LogLevel.error,
      _       => LogLevel.warn,
    };
    Sdk.setLogLevel(sdkLevel);
  }
}

UI Control Pattern (Python)

Main Control Class

# src/flet_my_widget/my_widget.py

from typing import Optional
import flet as ft
from flet_my_widget.types import MyWidgetEvent, MyWidgetConfig


@ft.control("MyWidget")  # Name for Flutter registration
class MyWidget(ft.LayoutControl):
    """
    Visual widget for displaying custom content.

    Inherits from ft.LayoutControl (has width, height, expand, etc.)

    Example:
        ```python
        widget = MyWidget(
            url="https://example.com",
            width=400,
            height=300,
            on_load=lambda e: print("Loaded!"),
        )
        page.add(widget)
        ```
    """

    # Properties (sent to Flutter via automatic serialization)
    url: str = ""
    """URL or content source."""

    auto_play: bool = False
    """If True, starts automatically."""

    config: Optional[MyWidgetConfig] = None
    """Advanced configuration."""

    # Events
    on_load: Optional[ft.EventHandler[MyWidgetEvent]] = None
    """Called when content finishes loading."""

    on_error: Optional[ft.EventHandler[ft.ControlEvent]] = None
    """Called when an error occurs."""

    # Methods invoked on Flutter
    async def play(self) -> None:
        await self._invoke_method("play")

    async def pause(self) -> None:
        await self._invoke_method("pause")

    async def get_duration(self, timeout: float = 10) -> Optional[float]:
        result = await self._invoke_method("get_duration", timeout=timeout)
        return float(result) if result else None

    async def seek(self, position_seconds: float) -> None:
        await self._invoke_method("seek", {"position": position_seconds})

    # Platform validation (optional for UI controls)
    def before_update(self):
        super().before_update()
        if self.page and self.page.web and not self._supports_web():
            raise ft.FletUnsupportedPlatformException("MyWidget doesn't support web.")

    def _supports_web(self) -> bool:
        return False

New 0.81.0 LayoutControl Properties

All inherited automatically by any UI Control:

@ft.control("MyWidget")
class MyWidget(ft.LayoutControl):
    url: str = ""
    # Can now use Matrix4 transforms (inherited):
    # widget = MyWidget(url="...", transform=Matrix4.rotation_z(0.5))
    # widget = MyWidget(url="...", on_size_change=handle_resize)

@ft.control New Parameters (0.81.0)

# isolated=True: excludes control from parent updates
@ft.control("MyWidget", isolated=True)
class MyWidget(ft.LayoutControl):
    ...

# post_init_args: for controls with InitVar
@ft.control("MyWidget", post_init_args=1)
class MyWidget(ft.LayoutControl):
    ...

UI Control Pattern (Dart)

StatefulWidget Implementation

// lib/src/my_widget.dart
import 'package:flet/flet.dart';
import 'package:flutter/widgets.dart';
import 'package:third_party_sdk/third_party_sdk.dart';

class MyWidgetWidget extends StatefulWidget {
  final Control control;
  const MyWidgetWidget({super.key, required this.control});

  @override
  State<MyWidgetWidget> createState() => _MyWidgetWidgetState();
}

class _MyWidgetWidgetState extends State<MyWidgetWidget> {
  late final SdkController _controller;

  @override
  void initState() {
    super.initState();
    _controller = SdkController();

    // Register handler for Python method invocations
    widget.control.addInvokeMethodListener(_onInvokeMethod);

    // Setup listeners
    _setupListeners();
  }

  @override
  void didUpdateWidget(MyWidgetWidget oldWidget) {
    super.didUpdateWidget(oldWidget);
    // React to changes in Python properties
    final url = widget.control.getString("url");
    if (url != null) {
      _controller.loadUrl(url);
    }
  }

  void _setupListeners() {
    _controller.onLoad = () {
      widget.control.triggerEvent("load", {
        "status": "ready",
        "duration": _controller.duration,
      });
    };

    _controller.onError = (error) {
      widget.control.triggerEvent("error", {
        "status": "error",
        "message": error,
      });
    };
  }

  Future<dynamic> _onInvokeMethod(String name, dynamic args) async {
    Map<String, dynamic> arguments = {};
    if (args != null && args is Map) {
      arguments = Map<String, dynamic>.from(args);
    }

    return switch (name) {
      "play"         => _controller.play(),
      "pause"        => _controller.pause(),
      "get_duration" => _controller.duration?.toString(),
      "seek"         => _controller.seek(
                          Duration(
                            milliseconds: ((arguments["position"] as double) * 1000).toInt(),
                          )
                        ),
      _              => throw Exception("Unknown method: $name"),
    };
  }

  @override
  Widget build(BuildContext context) {
    return ConstrainedBox(
      constraints: BoxConstraints(
        minWidth: widget.control.getDouble("width") ?? 0,
        minHeight: widget.control.getDouble("height") ?? 0,
      ),
      child: SdkWidget(controller: _controller),
    );
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }
}

Python ↔ Flutter Communication

Overview

Python (ft.Service)               Flutter (FletService)
─────────────────────             ─────────────────────
Properties (fields)      →→→→→→   control.getString("field")
                                  control.getBool("field", default)

await _invoke_method()   →→→→→→   control.addInvokeMethodListener()
        ↑                                    ↓
    returns value        ←←←←←←   return "value"

ft.EventHandler[Type]   ←←←←←←   control.triggerEvent("name", data)

1. Python → Flutter: Properties

# Python declaration
@ft.control("MyService")
class MyService(ft.Service):
    app_id: str = ""
    log_level: Optional[MyLogLevel] = None
    require_consent: bool = False

// Dart reading
final appId = control.getString("app_id");
final logLevel = control.getString("log_level");
final requireConsent = control.getBool("require_consent", false)!;

Enums are serialized as their .value (string):

# Python
class MyLogLevel(Enum):
    DEBUG = "debug"

# Dart receives: "debug"
final levelStr = control.getString("log_level");  // "debug"

2. Python → Flutter: Invoke Methods

# Python — basic call (no return)
await self._invoke_method("logout")

# With arguments
await self._invoke_method("login", {"user_id": user_id})

# With return + custom timeout
result = await self._invoke_method("get_status", timeout=10.0)
return result == "true"

# Complex data return (JSON)
result = await self._invoke_method("get_tags")
return json.loads(result) if result else {}

// Dart — handler
control.addInvokeMethodListener(_onInvokeMethod);

Future<dynamic> _onInvokeMethod(String methodName, dynamic args) async {
    // ALWAYS convert args
    Map<String, dynamic> arguments = {};
    if (args != null && args is Map) {
        arguments = Map<String, dynamic>.from(args);
    }

    return switch (methodName) {
        "logout"     => await _logout(),
        "login"      => await _login(arguments),
        "get_status" => _getStatus(),
        "get_tags"   => await _getTags(),
        _            => throw Exception("Unknown method: $methodName"),
    };
}

3. Flutter → Python: Events

// Dart — trigger event
control.triggerEvent("permission_change", {
    "permission": true,
});

// Error event (standard pattern)
control.triggerEvent("error", {
    "method": "method_name",
    "message": error.toString(),
    "stack_trace": stackTrace.toString(),
});

# Python — receive event
@dataclass
class PermissionChangeEvent(ft.Event["MyService"]):
    permission: bool = False

@ft.control("MyService")
class MyService(ft.Service):
    on_permission_change: Optional[ft.EventHandler[PermissionChangeEvent]] = None

# Usage
service = MyService(
    on_permission_change=lambda e: print(f"Permission: {e.permission}"),
)

Event name mapping:

Rule: triggerEvent("snake_case_name") → on_snake_case_name

4. Internal Fields (NOT Sent to Flutter)

from dataclasses import field

@ft.control("MyService")
class MyService(ft.Service):
    # Normal field → sent to Flutter
    app_id: str = ""

    # Internal field → NOT sent to Flutter
    _sub_module: SubModule = field(
        default=None,
        init=False,
        metadata={"skip": True}  # This excludes it from serialization
    )

5. Timeout

# Default: 25 seconds
await self._invoke_method("login", {"user_id": uid})

# Custom timeout for fast operations
result = await self._invoke_method("get_permission", timeout=10.0)

# Custom timeout for slow operations (e.g., permission request with UI)
result = await self._invoke_method(
    "request_permission",
    {"fallback_to_settings": True},
    timeout=30.0,
)

Naming Conventions

Type Mapping (Dart → Python)

Standard Type Mappings

Generic Type Mappings

Nullable Types

Flet-Aware Mappings (UI Controls)

These use native Flet types for richer UI integration:

Flutter Enum Mappings

Common Flutter enums are mapped to str for serialization:

Return Type Conventions

Types, Events & Enums

Enum Pattern

from enum import Enum

class MyLogLevel(Enum):
    """Log levels for the SDK."""
    NONE = "none"
    DEBUG = "debug"
    INFO = "info"
    WARN = "warn"
    ERROR = "error"

Serialization: Sub-modules send param.value (the string), not the raw enum object.

Event Dataclass Pattern

from dataclasses import dataclass
from typing import Optional
import flet as ft


@dataclass
class MyEvent(ft.Event["MyService"]):
    """Event triggered by the SDK.

    The type parameter of ft.Event is the parent control class.
    """
    data: str = ""
    success: bool = False


@dataclass
class ErrorEvent(ft.Event["MyService"]):
    """Standard error event."""
    method: Optional[str] = None
    message: Optional[str] = None
    stack_trace: Optional[str] = None

Standard ErrorEvent Pattern

Every extension should include an ErrorEvent and on_error handler:

# types.py
@dataclass
class ErrorEvent(ft.Event["MyService"]):
    method: Optional[str] = None
    message: Optional[str] = None
    stack_trace: Optional[str] = None

# my_service.py
@ft.control("MyService")
class MyService(ft.Service):
    on_error: Optional[ft.EventHandler[ErrorEvent]] = None

// my_service.dart
void _handleError(String method, Object error, StackTrace stackTrace) {
    debugPrint("MyService ERROR in $method: $error");
    FlutterError.reportError(FlutterErrorDetails(
      exception: error,
      stack: stackTrace,
      library: 'flet_my_extension',
      context: ErrorDescription('while executing method "$method"'),
    ));
    control.triggerEvent("error", {
      "method": method,
      "message": error.toString(),
      "stack_trace": stackTrace.toString(),
    });
}

Project Configuration

pyproject.toml (Extension)

[project]
name = "flet-my-extension"
version = "0.1.0"
description = "My Flet extension."
requires-python = ">=3.10"
readme = "README.md"
authors = [{ name = "Your Name", email = "[email protected]" }]
license = "MIT"

classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
]

dependencies = ["flet>=0.80.0"]

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

# CRITICAL: Includes Flutter/Dart code in the Python wheel
[tool.setuptools.package-data]
"flutter.flet_my_extension" = ["**/*"]

[dependency-groups]
dev = [
    "flet[all]>=0.80.0",
    "pytest>=7.2.0",
    "pytest-cov>=7.0.0",
]

[tool.ruff]
target-version = "py312"
line-length = 100
src = ["src", "tests"]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --tb=short"

Why [tool.setuptools.package-data] is critical: The Flet build system locates Dart code inside the installed Python package. Without this, the wheel won't contain the Dart files and flet build will fail.

pubspec.yaml (Flutter)