Getting Started: Basic Plugin
Relevant source files
The following files were used as context for generating this wiki page:
The FLEXT Plugin system provides a standardized framework for creating, registering, and executing modular extensions within the FLEXT platform. A basic plugin acts as a standalone unit of logic—typically a data processor or utility—that adheres to a strict lifecycle managed by the FlextPluginPlatform. This system leverages Railway-Oriented Programming (ROP) using the r[T] pattern to ensure type-safe error handling and predictable state transitions.
Sources: examples/basic-plugin.md:3-8, src/flext_plugin/models.py:16-22
Plugin Architecture and Lifecycle
Plugins in the FLEXT ecosystem are built by extending the FlextPlugin base class. They follow a defined lifecycle consisting of initialization, activation, execution, and cleanup. The FlextPluginPlatform coordinates these states, ensuring that resources are allocated and released correctly.
Core Components
| Component | Description |
|---|---|
| FlextPlugin | The base class for all custom plugins, providing metadata management and lifecycle hooks. |
| PluginPlatform | The orchestrator responsible for registering, activating, and executing plugins. |
| PluginRegistry | A central storage mechanism for managing plugin discovery and identity. |
| PluginStatus | An enumeration representing the current state (e.g., ACTIVE, INACTIVE, ERROR). |
Sources: examples/basic-plugin.md:21-40, src/flext_plugin/_utilities/plugin_platform.py:113-118
Lifecycle Flow
The following diagram illustrates the standard progression of a plugin from registration to shutdown within the platform.
This flow ensures that initialize() validates configurations before any data processing occurs, and cleanup() is triggered to save statistics or release file handles.
Sources: examples/basic-plugin.md:85-130, src/flext_plugin/_utilities/plugin_platform.py:284-315
Implementation Details
Plugin Entity Model
The m.Plugin.Entity defines the data structure and validation rules for a plugin. It includes semantic version validation and built-in methods for performance tracking.
| Field | Type | Description |
|---|---|---|
name | str | Unique identifier following the pattern ^[a-zA-Z][a-zA-Z0-9_-]*$. |
plugin_version | str | Semantic version (X.Y.Z). |
plugin_type | Enum | Classification such as TAP, TARGET, PROCESSOR, or UTILITY. |
is_enabled | bool | Current operational state of the plugin. |
Sources: src/flext_plugin/models.py:46-88, src/flext_plugin/utilities.py:46-46
Execution Logic
Execution is handled via the execute method, which receives a data dictionary (typically containing a payload) and returns a result wrapped in the r pattern.
def execute(self, data: m.Dict) -> p.Result[m.Dict]:
# 1. Validate state (is_initialized, is_active)
# 2. Validate input data format
# 3. Process data and update internal stats
# 4. Return r[bool].ok(result) or r[bool].fail(error)
Sources: examples/basic-plugin.md:111-130, src/flext_plugin/_utilities/plugin_platform.py:382-415
Plugin Discovery and Utilities
The system includes utilities for discovering plugins within the filesystem by scanning for specific file extensions (.py, .yaml, .json) or manifest files (plugin.yaml).
The FlextPluginUtilities class provides static methods to extract metadata from dunder variables (like __version__) or docstrings within Python files.
Sources: src/flext_plugin/utilities.py:38-78, src/flext_plugin/_utilities/plugin_platform.py:360-375
Monitoring and Statistics
Plugins automatically track execution metrics within their metadata, which can be persisted during the cleanup phase.
| Metric | Description |
|---|---|
execution_count | Total number of times the plugin has been executed. |
total_execution_time | Cumulative time spent in the execute method. |
success_count | Number of successful executions. |
error_count | Number of executions that returned a failure result. |
Sources: src/flext_plugin/models.py:160-200, examples/basic-plugin.md:154-165
Conclusion
Creating a basic plugin involves implementing core lifecycle methods—initialize, execute, and cleanup—while adhering to the platform's validation rules. By utilizing the FlextPluginPlatform for registration and execution, developers benefit from standardized error handling, performance monitoring, and discovery mechanisms that ensure consistency across the FLEXT ecosystem.
Sources: examples/README.md:280-295, examples/basic-plugin.md:465-475