Merge pull request #2863 from phw/plugin-api-reorganize-imports

Plugin API reorganize imports

Author: phw

docs/PLUGINSV3/API.md

@@ -69,28 +69,29 @@ class MyWidget(QWidget):
 
 ## Class References
 
-The following classes are available through the `api` object:
-
-- `api.Album` - Album object
-- `api.Track` - Track object
-- `api.File` - File base class (for custom formats)
-- `api.Cluster` - Cluster object
-- `api.Metadata` - Metadata container for tags
-- `api.BaseAction` - Base class for UI actions
-- `api.OptionsPage` - Base class for options pages
-- `api.CoverArtImage` - Cover art image object
-- `api.CoverArtProvider` - Base class for cover art providers
-- `api.ProviderOptions` - Base class for cover art provider option pages
+The following classes are available through the `api` module:
+
+- `Album` - Album object
+- `Track` - Track object
+- `File` - File base class (for custom formats)
+- `Cluster` - Cluster object
+- `Metadata` - Metadata container for tags
+- `BaseAction` - Base class for UI actions
+- `OptionsPage` - Base class for options pages
+- `CoverArtImage` - Cover art image object
+- `CoverArtProvider` - Base class for cover art providers
+- `ProviderOptions` - Base class for cover art provider option pages
+- `ScriptParser` - A parser for parsing tagger scripts
 
 **Example**:
 ```python
-from picard.plugin3.api import BaseAction, OptionsPage, File, CoverArtProvider
-from picard.metadata import Metadata
+from picard.plugin3.api import BaseAction, OptionsPage, File, CoverArtProvider, Metadata
 
 class MyProvider(CoverArtProvider):
     NAME = "My Provider"
 
 class MyFormat(File):
+    NAME = "Custom Format"
     EXTENSIONS = [".custom"]
 
     def _load(self, filename):
@@ -99,10 +100,9 @@ class MyFormat(File):
         return metadata
 ```
 
-**Note**: Classes that are considered part of the API `Metadata`, `Track`, `Album`, etc.
-should be accessed via their aliases defined in `PluginApi`, e.g. `PluginApi.Track`.
-This is also the case for classes meant for inheritance (`BaseAction`, `OptionsPage`,
-`File`, `CoverArtProvider`).
+**Note**: Classes that are considered part of the API like `Metadata`, `Track`, `Album`,
+etc. should be imported directly from `picard.plugin3.api` instead from elsewhere
+in Picard.
 
 ---
 
@@ -216,9 +216,9 @@ def enable(api):
 
 **In OptionsPage:**
 ```python
-from picard.plugin3 import PluginApi
+from picard.plugin3.api import PluginApi, OptionsPage
 
-class MyOptionsPage(PluginApi.OptionsPage):
+class MyOptionsPage(OptionsPage):
     def __init__(self):
         super().__init__()
         # Initialize the UI here
@@ -385,8 +385,7 @@ Mark a string for translation extraction without translating it immediately.
 This is a marker function that allows you to define translatable strings at module level or in data structures before the API is available. At runtime, it simply returns the key (or tuple for plurals) unchanged.
 
 ```python
-from picard.plugin3 import PluginApi
-from picard.plugin3.api import t_
+from picard.plugin3.api import PluginApi, BaseAction, t_
 
 # Define translatable strings at module level
 ERROR_MESSAGES = {
@@ -398,8 +397,8 @@ ERROR_MESSAGES = {
 FILE_COUNT = t_('files.count', '{n} file', '{n} files')
 
 # Use in class definitions
-class MyAction(PluginApi.BaseAction):
-    NAME = "My Custom Action"
+class MyAction(BaseAction):
+    TITLE = "My Custom Action"
 
     def __init__(self):
         super().__init__()
@@ -617,10 +616,10 @@ Plugin Tools menu actions:
 Register menu actions for different object types.
 
 ```python
-from picard.plugin3 import PluginApi
+from picard.plugin3.api import BaseAction
 
-class MyAction(PluginApi.BaseAction):
-    NAME = "My Custom Action"
+class MyAction(BaseAction):
+    TITLE = "My Custom Action"
 
     def callback(self, objs):
         for obj in objs:
@@ -650,9 +649,9 @@ the class to access the `PluginApi` instance of the plugin.
 Register a settings page in Picard's options dialog.
 
 ```python
-from picard.plugin3 import PluginApi
+from picard.plugin3.api import OptionsPage
 
-class MyOptionsPage(PluginApi.OptionsPage):
+class MyOptionsPage(OptionsPage):
     NAME = "my_plugin"
     TITLE = "My Plugin"
     PARENT = "plugins"
@@ -691,9 +690,9 @@ def enable(api):
 Register a custom cover art provider.
 
 ```python
-from picard.plugin3 import PluginApi
+from picard.plugin3.api import CoverArtProvider
 
-class MyProvider(PluginApi.CoverArtProvider):
+class MyProvider(CoverArtProvider):
     NAME = "My Provider"
 
     def queue_images(self):
@@ -773,9 +772,9 @@ def enable(api):
 Register support for a custom file format.
 
 ```python
-from picard.plugin3 import PluginApi
+from picard.plugin3.api import File
 
-class MyFormat(PluginApi.File):
+class MyFormat(File):
     EXTENSIONS = [".myformat"]
     NAME = "My Format"
 
@@ -905,9 +904,9 @@ def enable(api):
 
 **For Classes**:
 ```python
-from picard.plugin3 import PluginApi
+from picard.plugin3.api import OptionsPage
 
-class MyPage(PluginApi.OptionsPage):
+class MyPage(OptionsPage):
     def load(self):
         self.api.logger.info("Loading")
 
@@ -948,12 +947,12 @@ def enable(api):
 
 ```python
 from PyQt6.QtWidgets import QCheckBox
-from picard.plugin3 import PluginApi
+from picard.plugin3.api import PluginApi, BaseAction, OptionsPage, t_
 
 
-class MyOptionsPage(PluginApi.OptionsPage):
+class MyOptionsPage(OptionsPage):
     NAME = "example"
-    TITLE = "Example Plugin"
+    TITLE = t_("Example Plugin")
     PARENT = "plugins"
 
     def __init__(self):
@@ -981,8 +980,8 @@ def on_file_saved(api, file):
     api.logger.info(f"Saved: {file.filename}")
 
 
-class MyAction(PluginApi.BaseAction):
-    NAME = "Example Action"
+class MyAction(BaseAction):
+    TITLE = t_("Example Action")
 
     def callback(self, objs):
         self.api.logger.info(f"Action on {len(objs)} objects")
@@ -1011,8 +1010,8 @@ def enable(api):
 4. **Handle errors gracefully**: Wrap risky operations in try/except
 5. **Set priorities wisely**: Only use non-zero priorities when order matters
 6. **Pass api to parent classes**: You can use `self.api` in classes inherited from
-   base classes meant to be subclassed like `PluginApi.BaseAction` or
-   `PluginApi.OptionsPage`.
+   base classes meant to be subclassed and imported from `picard.plugin3.api`,
+   like `BaseAction` or `OptionsPage`.
 
 ---
 

docs/PLUGINSV3/MANIFEST.md

@@ -29,7 +29,7 @@ api = ["3.0"]
 
 ```python
 # __init__.py
-from picard.plugin3 import PluginApi
+from picard.plugin3.api import PluginApi
 
 def enable(api: PluginApi):
     """Called when plugin is enabled"""
@@ -416,7 +416,7 @@ Vollständige deutsche Beschreibung hier...
 Every plugin must have an `__init__.py` file with an `enable()` function:
 
 ```python
-from picard.plugin3 import PluginApi
+from picard.plugin3.api import PluginApi
 
 def enable(api: PluginApi):
     """
@@ -571,7 +571,7 @@ def enable(api: PluginApi):
 
 ```python
 # __init__.py
-from picard.plugin3 import PluginApi
+from picard.plugin3.api import PluginApi
 
 def enable(api: PluginApi):
     @api.on_album_metadata_loaded
@@ -584,7 +584,7 @@ def enable(api: PluginApi):
 
 ```python
 # __init__.py
-from picard.plugin3 import PluginApi
+from picard.plugin3.api import PluginApi
 
 def enable(api: PluginApi):
     @api.register_cover_art_provider
@@ -599,7 +599,7 @@ def enable(api: PluginApi):
 
 ```python
 # __init__.py
-from picard.plugin3 import PluginApi
+from picard.plugin3.api import PluginApi
 
 def enable(api: PluginApi):
     @api.register_album_action("Export to CSV")

docs/PLUGINSV3/TRANSLATIONS.md

@@ -56,7 +56,7 @@ Simple flat JSON structure with dot notation for namespacing:
 ### Usage in Plugin Code
 
 ```python
-from picard.plugin3 import PluginApi
+from picard.plugin3.api import PluginApi
 from picard.i18n import gettext as _  # Picard's translations
 
 def enable(api: PluginApi):
@@ -102,7 +102,7 @@ FILE_COUNT = t_('files.count', '{n} file', '{n} files')
 
 # Use in class definitions
 class MyAction(BaseAction):
-    NAME = "My Custom Action"
+    TITLE = t_("My Custom Action")
 
 def enable(api):
     # Translate at runtime
@@ -666,7 +666,7 @@ fr = "Soumettez votre musique sur ListenBrainz"
 
 ### __init__.py
 ```python
-from picard.plugin3 import PluginApi
+from picard.plugin3.api import PluginApi
 from picard.i18n import gettext as _
 
 def enable(api: PluginApi):

docs/Plugin2to3MigrationGuide.md

@@ -340,7 +340,7 @@ register_file_action(action)
 from picard.plugin3.api import BaseAction
 
 class MyAction(BaseAction):
-    NAME = 'My Action'
+    TITLE = 'My Action'
 
     def __init__(self, api=None):
         super().__init__()

picard/plugin3/__init__.py

@@ -24,11 +24,9 @@
     GitReferenceError,
     GitRepositoryError,
 )
-from picard.plugin3.api import PluginApi
 
 
 __all__ = [
-    'PluginApi',
     'GitBackendError',
     'GitRepositoryError',
     'GitReferenceError',