Module Map & Public API

Relevant source files

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

• src/flext_plugin/__init__.py
• src/flext_plugin/models.py
• src/flext_plugin/utilities.py
• src/flext_plugin/_exports_lazy_part_01.py
• README.md
• examples/basic-plugin.md
• examples/README.md

The flext-plugin package provides a standardized plugin system for the FLEXT Platform. It enables the creation, discovery, and lifecycle management of various plugin types—such as data processors, Singer taps/targets, and service extensions—using a Railway-Oriented Programming (ROP) pattern with r[T] result types for robust error handling.

The system is architected around a core set of domain models (entities and value objects) and high-level APIs that abstract complex plugin operations. It utilizes lazy loading for its public surface to optimize performance while maintaining a strictly typed interface for developers.

Sources: README.md:9-12, src/flext_plugin/models.py:16-24, examples/README.md:15-30

Package Structure & Lazy Exports

The package uses a lazy export mechanism to expose its public API. This ensures that heavy dependencies or submodules are only loaded when accessed. The primary entry point, src/flext_plugin/__init__.py, defines a set of standardized aliases (c, m, p, u, etc.) that map to internal modules.

Public Surface Map

Alias	Target Module	Purpose
c	.constants	Shared constants and validation patterns
m	.models	Domain entities (Plugin, Registry) and Value Objects
p	.protocols	Interface definitions and result types
r	flext_core.r	Railway-Oriented Programming result wrappers
t	.typings	Type definitions and JSON mappings
u	.utilities	Discovery and validation logic

Sources: src/flext_plugin/init.py:42-69, src/flext_plugin/_exports_lazy_part_01.py:9-41

Core Domain Models

The plugin system relies on Pydantic-backed models to enforce identity and validation rules. The primary entity is the Plugin.Entity, which manages the state and metadata of a specific plugin.

Plugin Entity Lifecycle

The Entity class provides methods to transition a plugin between enabled and disabled states and to record runtime performance data.

Key Model Attributes

Model Class	Field	Type	Constraint / Description
Plugin.Entity	name	str	Regex: ^[a-zA-Z][a-zA-Z0-9_-]*$
Plugin.Entity	plugin_version	str	Semantic version (X.Y.Z)
Plugin.Entity	plugin_type	c.Plugin.Type	Enum: UTILITY, PROCESSOR, TAP, etc.
DiscoveryData	path	Path	File system location of the plugin
PluginMetadata	entry_point	str	The callable path for execution

Sources: src/flext_plugin/models.py:53-83, src/flext_plugin/utilities.py:39-44

Plugin Discovery & Utilities

The FlextPluginUtilities class (aliased as u) provides static methods for scanning directories and extracting metadata from source files without fully importing them initially.

Discovery Workflow

1. Scanning: discover_plugins recursively searches a directory for files matching PLUGIN_FILE_EXTENSIONS (.py, .yaml, .json).
2. Validation: validate_plugin_file checks file size (max 100MB) and scans for dangerous code patterns (e.g., exec, eval, os.system).
3. Extraction: extract_plugin_metadata parses dunder versions (__version__) and triple-quoted docstrings to populate metadata.

Plugin Lifecycle API

As demonstrated in the basic plugin implementation, a plugin must adhere to a specific lifecycle contract including initialization, execution, and cleanup.

Implementation Example

class BasicProcessor(FlextPlugin):
    def initialize(self) -> p.Result[bool]:
        # Setup resources
        return r[bool].ok(data=True)

    def execute(self, data: m.Dict) -> p.Result[m.Dict]:
        # Process and return result
        return r[m.Dict].ok({"processed": True})

    def cleanup(self) -> p.Result[bool]:
        # Release resources
        return r[bool].ok(data=True)

Sources: examples/basic-plugin.md:37-120, examples/README.md:129-180

Execution Metrics & Monitoring

Plugins automatically track their performance via the record_execution and record_error methods on the Plugin.Entity. These metrics are stored in a metadata mapping:

• execution_count: Total number of times the plugin was called.
• total_execution_time: Cumulative time in seconds.
• success_count / failure_count: Outcome counters.
• last_error: The error message from the most recent failure.

Sources: src/flext_plugin/models.py:108-144, tests/unit/test_domain_entities.py:72-105

Conclusion

The Module Map and Public API of flext-plugin provide a rigid yet extensible framework. By leveraging the r[T] pattern and strict Pydantic validation, the system ensures that plugins are discovered safely and executed reliably within the FLEXT ecosystem. The centralized use of lazy exports via src/flext_plugin/__init__.py allows the project to maintain a high-level API surface without sacrificing startup performance.

Sources: README.md:5-20, src/flext_plugin/models.py:16-24