Coverage for src/lanraragi_api/api/plugin.py: 70%

1from lanraragi_api.api.base import ( 

2 BaseAPICall, 

3) 

4from lanraragi_api.entity.minion import MinionJobResponse 

5from lanraragi_api.entity.plugin import PluginInfo, PluginUseResponse 

6 

7 

8class PluginAPI(BaseAPICall): 

9 """APIs to list and execute Plugins. 

10 

11 Shared request and error behavior is documented on ``BaseAPICall``. 

12 """ 

13 

14 def get_available_plugins(self, type: str) -> list[PluginInfo]: 

15 """List all plugins of the given type. 

16 

17 Args: 

18 type: Type of plugins you want to list, one of ``download``, 

19 ``login``, ``metadata`` or ``script``. Use ``all`` to get 

20 every type at once. 

21 

22 Returns: 

23 list[PluginInfo]: One entry per plugin of the given type. 

24 

25 Raises: 

26 APIHttpError: Any status code other than 200. 

27 APIResponseDecodeError: If the body is not a list of objects 

28 matching ``PluginInfo``. 

29 """ 

30 return self.request_model_list("GET", f"/api/plugins/{type}", PluginInfo) 

31 

32 def use_plugin( 

33 self, plugin: str, id: str | None = None, arg: str | None = None 

34 ) -> PluginUseResponse: 

35 """Use a Plugin and return the result. 

36 

37 If using a metadata plugin, the matching archive will not be modified 

38 in the database. See more info on Plugins in the matching section of 

39 the Docs. 

40 

41 Args: 

42 plugin: Namespace of the plugin to use. 

43 id: ID of the archive to use the plugin on. Only mandatory for 

44 metadata plugins. Defaults to None. 

45 arg: One-shot argument to use when executing this plugin. Defaults 

46 to None. 

47 

48 Returns: 

49 PluginUseResponse: Result of the plugin run, with the type of the 

50 plugin and any data it returned. 

51 

52 Raises: 

53 APIResponseDecodeError: If the body is not valid JSON, or does not 

54 match ``PluginUseResponse``. 

55 APIOperationError: If the operation failed and raising is enabled. 

56 

57 Note: 

58 A failed plugin run is reported inside the body, through ``success`` 

59 set to 0, and does not raise unless raising is enabled. 

60 """ 

61 return self.request_operation( 

62 "POST", 

63 "/api/plugins/use", 

64 model=PluginUseResponse, 

65 params={"plugin": plugin, "id": id, "arg": arg}, 

66 ) 

67 

68 def use_plugin_async( 

69 self, 

70 plugin: str, 

71 id: str | None = None, 

72 arg: str | None = None, 

73 priority: int = 0, 

74 ) -> MinionJobResponse: 

75 """Use a Plugin and return the Minion job ID matching the run. 

76 

77 This endpoint is useful if you want to run longer-lived plugins which 

78 might timeout if ran with the standard endpoint. 

79 

80 Args: 

81 plugin: Namespace of the plugin to use. 

82 id: ID of the archive to use the plugin on. Only mandatory for 

83 metadata plugins. Defaults to None. 

84 arg: One-shot argument to use when executing this plugin. Defaults 

85 to None. 

86 priority: Priority of the Minion job. The higher the number, the 

87 more important the job is. Defaults to 0. 

88 

89 Returns: 

90 MinionJobResponse: Result of the call, with the ID of the queued 

91 job. 

92 

93 Raises: 

94 APIResponseDecodeError: If the body is not valid JSON, or does not 

95 match ``MinionJobResponse``. 

96 APIOperationError: If the operation failed and raising is enabled. 

97 """ 

98 return self.request_operation( 

99 "POST", 

100 "/api/plugins/queue", 

101 model=MinionJobResponse, 

102 params={"plugin": plugin, "id": id, "arg": arg, "priority": priority}, 

103 )