# Plugins

This folder is the primary home for bundled plugins and also the default search
path for drop-in plugins.

Preferred layout:
- Put each plugin in its own folder under `plugins/<name>/` with an `__init__.py`.
- Keep plugin-specific assets beside the code in that same folder.
- Single-file `.py` plugins are still supported, but package folders are the
    recommended plug-and-play format.

That means a plugin can ship as a drag-and-drop folder with extras such as:
- `cookies.txt`
- templates or fixture files
- helper modules
- small static assets

Built-in bundled plugins use the same layout as external plugins. Additional
drop-in plugin search paths are:
- `plugins/` in the repo root
- `plugins/` in the current working directory
- Any directory listed in `MM_PLUGIN_PATH`
- Any directory listed in `MEDEIA_PLUGIN_PATH`

Plugin rules:
- A plugin can be a single `.py` file or a package directory with `__init__.py`.
- Define a class that inherits from `ProviderCore.base.Provider`.
- Give it a stable name using `PLUGIN_NAME` or the class name.

Example skeleton:

```python
from ProviderCore.base import Provider, SearchResult


class MyPlugin(Provider):
    PLUGIN_NAME = "myplugin"
    URL_DOMAINS = ("example.com",)

    def search(self, query, limit=50, filters=None, **kwargs):
        text = str(query or "").strip()
        if not text:
            return []
        return [
            SearchResult(
                table="myplugin",
                title=f"Result for {text}",
                path=f"https://example.com/{text}",
            )
        ]
```