Universal Zero-Modification Plugin System

A minimalist plugin system for Python that requires zero modifications to existing code.

🚀 Quick Start

1. Copy the Plugin System

Copy plugin_core.py to your Python project directory.

2. Create Plugins Directory (Optional)

The system will automatically create a plugins/ directory on first use, or you can create it manually.

3. Add Your Plugins

Copy any existing Python files to the plugins/ directory. No changes needed!

4. Integrate in One Line

Add this single line to your main program:

from plugin_core import call_plugin_func

5. Call Your Functions

Call any function from any plugin:

result = call_plugin_func("your_module", "your_function", param1="value1")

📁 Project Structure

Your_Project/
├── main.py                    # Your main program
├── plugin_core.py             # Plugin system (single file)
└── plugins/                   # Auto-discovered plugins
    ├── your_module_1.py       # Existing Python file 1
    ├── your_module_2.py       # Existing Python file 2
    └── subdirectory/          # Subdirectories supported
        └── your_module_3.py   # Call as "subdirectory.your_module_3"

🔧 Core Features

Zero Modification

• Existing Python files work as plugins without any changes
• No decorators, base classes, or configuration needed
• Copy files to plugins/ directory and they're ready to use

One-Line Integration

# Only this line needed in your main program
from plugin_core import call_plugin_func

Function-Level Calling

Call any function within any module:

call_plugin_func("data_processor", "process_data", data=[1,2,3])
call_plugin_func("data_processor", "main")  # Even main functions

Graceful Error Handling

• Module not found → Returns None, logs warning
• Function not found → Returns None, logs warning
• Execution errors → Returns None, logs error
• Main program continues unaffected

📖 Basic Usage Examples

Basic Call

result = call_plugin_func("data_tools", "process_data",
                         data=my_data, format="json")

Fallback Calling

from plugin_core import call_plugin_func_with_fallback

result = call_plugin_func_with_fallback(
    "exporter",
    primary_func="advanced_export",
    fallback_func="basic_export",
    data=my_data
)

Inter-Plugin Communication

from plugin_core import plugin_context

# Plugin A stores data
plugin_context.set_data("processing_result", result)

# Plugin B reads data
data = plugin_context.get_data("processing_result")

🧪 Testing and Development

Run the Generic Demo

python generic_demo.py

The demo shows usage patterns without providing specific implementations.

Create Test Plugins

1. Create plugins/ directory in your project
2. Copy any Python files to plugins/
3. Test with call_plugin_func()

📚 Documentation

For detailed technical documentation:

• English Documentation - Complete technical reference, architecture, and advanced features
• 中文文档 - 完整的技术参考、架构设计和高级功能

This README provides a quick start guide. For in-depth understanding of the system design, plugin development, and advanced usage patterns, please refer to the detailed documentation above.

Quick Navigation

• 🚀 New Users: Read this entire README for quick setup
• 🔧 Developers: See docs/en-US/index.md for API reference and advanced features
• 📖 Chinese Users: 查看 docs/zh-CN/index.md 获取中文文档

🎯 Design Principles

1. Zero Modification: No changes to existing code
2. Minimal Intrusion: One-line integration
3. Maximum Compatibility: Works with any Python file
4. Graceful Degradation: Failures don't crash the program
5. Performance First: Caching and optimization built-in

🤝 Contributing

This is a complete, self-contained system. To adapt it to your needs:

1. Copy plugin_core.py to your project
2. Modify as needed for your specific requirements
3. Maintain the core principles of zero modification and graceful degradation

📄 License

This system is designed to be copied and adapted freely. No restrictions on usage.

---

Remember: The power of this system is its simplicity. Copy plugin_core.py, add your existing Python files to plugins/, and start calling functions with a single import. No configuration, no modification, no complexity.