Coverage for src/lanraragi_api/api/minion.py: 67%

1import json 

2from typing import Any 

3 

4from lanraragi_api.api.base import BaseAPICall 

5from lanraragi_api.entity.minion import BasicJobStatus, FullJobStatus, MinionJobResponse 

6 

7 

8class MinionAPI(BaseAPICall): 

9 """Minion Job Queue APIs. 

10 

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

12 """ 

13 

14 def get_basic_status(self, job_id: int | str) -> BasicJobStatus: 

15 """Check whether a Minion job succeeded or failed. 

16 

17 Minion jobs are ran for various occasions like thumbnails, cache 

18 warmup and handling incoming files. 

19 

20 For some jobs, you can check the notes field for progress information. 

21 Look at the Minion Guide for more details: 

22 https://docs.mojolicious.org/Minion/Guide#Job-progress 

23 

24 Args: 

25 job_id: ID of the job to query status for. 

26 

27 Returns: 

28 BasicJobStatus: Basic status of the job. 

29 

30 Raises: 

31 APIHttpError: Any status code other than 200. 

32 APIResponseDecodeError: If the body does not match 

33 ``BasicJobStatus``. 

34 """ 

35 return self.request_model("GET", f"/api/minion/{job_id}", BasicJobStatus) 

36 

37 def get_full_status(self, job_id: int | str) -> FullJobStatus: 

38 """Get the status of a Minion job. 

39 

40 This API is there for internal usage mostly, but you can use it to get 

41 detailed status for jobs like plugin runs or URL downloads. 

42 

43 Args: 

44 job_id: ID of the job. 

45 

46 Returns: 

47 FullJobStatus: Detailed status of the job. 

48 

49 Raises: 

50 APIHttpError: Any status code other than 200. 

51 APIResponseDecodeError: If the body does not match 

52 ``FullJobStatus``. 

53 """ 

54 return self.request_model("GET", f"/api/minion/{job_id}/detail", FullJobStatus) 

55 

56 def queue_minion_job( 

57 self, 

58 jobname: str, 

59 args: str | list[Any], 

60 priority: int = 0, 

61 ) -> MinionJobResponse: 

62 """Queue a job with the specified type and parameters. 

63 

64 See LANraragi::Utils::Minion for all the available types of jobs and 

65 the parameters they require. 

66 

67 There's no API contract in place for whether a job type exists on a 

68 given server version, so using this is not recommended unless you have 

69 a good reason to. 

70 

71 Args: 

72 jobname: Type of the job to instantiate. Documented values are 

73 ``thumbnail_task``, ``tank_thumbnail_task``, 

74 ``page_thumbnails``, ``regen_all_thumbnails``, 

75 ``find_duplicates``, ``build_stat_hashes``, ``handle_upload``, 

76 ``download_url`` and ``run_plugin``. 

77 args: Arguments of the job, either a JSON array string or a list of 

78 values. 

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

80 more important the job is. Defaults to 0. 

81 

82 Returns: 

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

84 job. 

85 

86 Raises: 

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

88 match ``MinionJobResponse``. 

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

90 """ 

91 args_value = args if isinstance(args, str) else json.dumps(args) 

92 return self.request_operation( 

93 "POST", 

94 f"/api/minion/{jobname}/queue", 

95 model=MinionJobResponse, 

96 params={"args": args_value, "priority": priority}, 

97 )