Utility Functions & Helpers

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_plugin/utilities.py
• src/flext_plugin/_utilities/__init__.py
• src/flext_plugin/__init__.py
• examples/basic-plugin.md
• tests/unit/test_domain_entities.py
• examples/03_docker_integration.py

Utility Functions & Helpers in the FLEXT Plugin system provide a centralized set of domain-specific tools for plugin discovery, manifest validation, metadata extraction, and lifecycle management. These utilities leverage Python 3.13+ patterns and composition-based architectures to ensure type safety and consistent behavior across the platform.

The primary entry point for these helpers is the FlextPluginUtilities class (aliased as u), which integrates core conversion logic, type guards, and model runtime utilities from the broader FLEXT ecosystem. Sources: src/flext_plugin/utilities.py:23-28, src/flext_plugin/__init__.py:46-77

Plugin Discovery and Metadata

The discovery system identifies potential plugins within a directory by scanning for specific file extensions and manifest files. Once a file is identified, the system extracts relevant metadata such as versioning information and descriptions.

Discovery Workflow

The discovery logic follows a sequence of checking file existence, iterating through the directory tree, and validating each file before attempting metadata extraction.

Metadata Extraction Logic

Metadata is extracted differently based on the file type. For Python files, the utility searches for dunder versions (e.g., __version__) and triple-quoted docstrings.

Field	Source/Logic	Default Value
name	File stem (filename without extension)	N/A
version	Regex match: VERSION_DUNDER_RE	DEFAULT_PLUGIN_VERSION
description	Regex match: DOCSTRING_TRIPLE_RE	"Plugin from [filename]"
plugin_type	Hardcoded for discovery	"extension"
metadata	System info (e.g., discovery timestamp)	{"discovered_at": ...}

Sources: src/flext_plugin/utilities.py:101-137, tests/unit/test_domain_entities.py:112-140

Validation Helpers

The utility suite includes strict validation rules to ensure plugin safety and naming consistency. This includes checking for "dangerous" Python patterns and enforcing specific regex patterns for plugin identifiers.

Safety and Security Checks

The validate_plugin_file method performs size checks and static analysis for potentially harmful code patterns.

• Size Limit: Maximum 100MB per plugin file.
• Prohibited Patterns: exec(, eval(, __import__, subprocess, os.system.
• Naming Conventions: Plugin names must match the pattern ^[a-zA-Z][a-zA-Z0-9_-]*$.

Sources: src/flext_plugin/utilities.py:34-48, src/flext_plugin/utilities.py:149-183

Plugin Lifecycle and Execution Tracking

Utilities within the domain entities allow for tracking the health and performance of plugins during their active lifecycle. This includes recording execution times, success/failure counts, and error messages.

Metric Tracking Sequence

When a plugin is executed, the record_execution helper updates the internal metadata to reflect the new state.

Lifecycle State Management

Plugins transition between enabled and disabled states using specialized methods that return a Result type, ensuring that operations like enabling an already-enabled plugin are caught as failures.
Sources: tests/unit/test_domain_entities.py:44-63

Integration and Configuration Helpers

The system provides helper patterns for configuring plugins that interact with external services like Docker-based PostgreSQL, Redis, or LDAP.

Service Connectivity Checks

A dedicated utility check_service_availability is used to verify network connectivity before a plugin attempts to initialize its primary resources.

def check_service_availability(host: str, port: int, timeout: float = 5.0) -> bool:
    """Check if a network service is available."""
    try:
        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        sock.settimeout(timeout)
        result = sock.connect_ex((host, port))
        sock.close()
        return result == 0
    except OSError:
        return False

Sources: examples/03_docker_integration.py:20-30

Configuration Templates

The utilities encourage the use of standard JSON mappings for complex configurations.

Service	Key Config Elements	Description
PostgreSQL	host, port, ssl_mode, max_connections	Database connector settings
Redis	db, decode_responses, health_check_interval	Cache connector settings
LDAP	base_dn, bind_dn, search_timeout	Directory service settings

Sources: examples/03_docker_integration.py:36-104, examples/basic-plugin.md:460-485

Summary

Utility Functions & Helpers in flext-plugin serve as the operational backbone for the plugin ecosystem. By providing robust tools for discovery (discover_plugins), safety validation (validate_plugin_file), and execution monitoring (record_execution), the system ensures that plugins are not only easy to integrate but also secure and observable within the FLEXT Platform. These helpers are exposed through a lazy-loading architecture to maintain high performance and minimal startup overhead. Sources: src/flext_plugin/utilities.py, src/flext_plugin/__init__.py