From 3580fb7d7a6f8eba7846ee0812abef2f7eb6d187 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andreas=20Kr=C3=BCger?= <andreas.krueger@famsik.de>
Date: Fri, 5 Jan 2024 20:38:09 +0100
Subject: [PATCH] Deprecate Yapsy function names.

---
 nikola/plugin_manager.py     | 33 ++++++++++++++++++++++++++++++---
 tests/test_plugin_manager.py | 11 +++++++++++
 2 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/nikola/plugin_manager.py b/nikola/plugin_manager.py
index 47db9f6df..53ff53ea2 100644
--- a/nikola/plugin_manager.py
+++ b/nikola/plugin_manager.py
@@ -32,7 +32,8 @@
 import sys
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Dict, List, Optional, Type, TYPE_CHECKING, Set
+import traceback
+from typing import Dict, List, Optional, Set, Tuple, Type, TYPE_CHECKING
 
 from .plugin_categories import BasePlugin, CATEGORIES
 from .utils import get_logger
@@ -87,6 +88,7 @@ class PluginManager:
     candidates: List[PluginCandidate]
     plugins: List[PluginInfo]
     _plugins_by_category: Dict[str, List[PluginInfo]]
+    _deprecation_already_warned: Set[Tuple[str, str, Optional[int]]]
 
     def __init__(self, plugin_places: List[Path]):
         """Initialize the plugin manager."""
@@ -95,6 +97,7 @@ def __init__(self, plugin_places: List[Path]):
         self.plugins = []
         self._plugins_by_category = {}
         self.logger = get_logger("PluginManager")
+        self._deprecation_already_warned = set()
 
     def locate_plugins(self) -> List[PluginCandidate]:
         """Locate plugins in plugin_places."""
@@ -225,10 +228,34 @@ def get_plugin_by_name(self, name: str, category: Optional[str] = None) -> Optio
                 return p
 
     # Aliases for Yapsy compatibility
+
+    def _warn_deprecation(self, deprecated_method: str) -> None:
+        caller = traceback.extract_stack()[-3]
+        name, filename, lineno = caller.name, caller.filename, caller.lineno
+        if (deprecated_method, filename, lineno) not in self._deprecation_already_warned:
+            self._deprecation_already_warned.add((deprecated_method, filename, lineno))
+            if lineno is not None:
+                self.logger.warning("Deprecated method %s still called by %s in %s, line %i.",
+                                    deprecated_method, name, filename, lineno)
+            else:
+                self.logger.warning("Deprecated method %s still called by %s in %s.",
+                                    deprecated_method, name, filename)
+
+
     def getPluginsOfCategory(self, category: str) -> List[PluginInfo]:
-        """Get loaded plugins of a given category."""
+        """Get loaded plugins of a given category.
+
+        This deprecated method is to be removed, probably in Nikola 9.0.0.
+        Use get_plugins_of_category(), it is functionally identical.
+        """
+        self._warn_deprecation("getPluginsOfCategory")
         return self._plugins_by_category.get(category, [])
 
     def getPluginByName(self, name: str, category: Optional[str] = None) -> Optional[PluginInfo]:
-        """Get a loaded plugin by name and optionally by category. Returns None if no such plugin is loaded."""
+        """Get a loaded plugin by name and optionally by category. Returns None if no such plugin is loaded.
+
+        This deprecated method is to be removed, probably in Nikola 9.0.0.
+        Use get_plugin_by_name(), it is functionally identical.
+        """
+        self._warn_deprecation("getPluginByName")
         return self.get_plugin_by_name(name, category)
diff --git a/tests/test_plugin_manager.py b/tests/test_plugin_manager.py
index a4039c5a2..d45d91a88 100644
--- a/tests/test_plugin_manager.py
+++ b/tests/test_plugin_manager.py
@@ -106,6 +106,17 @@ def test_load_plugins():
     assert plugin_manager.get_plugin_by_name("2nd").plugin_object.two_site_set
     assert plugin_manager.get_plugin_by_name("2nd", "Command") is None
 
+    deprecation_warning_seen = False
+    def expect_deprecation_warning(msg:str, deprecated_method:str, name:str, filename:str, lineno:int = -1):
+        nonlocal deprecation_warning_seen
+        deprecation_warning_seen = True
+        assert deprecated_method == "getPluginByName"
+        assert filename.endswith("/test_plugin_manager.py")
+
+    plugin_manager.logger.warning = expect_deprecation_warning
+    assert plugin_manager.getPluginByName("2nd", "Command") is None
+    assert deprecation_warning_seen
+
 
 def test_load_plugins_twice():
     """Ensure that extra plugins can be added."""