Coverage for src/lanraragi_api/api/misc.py: 45%

1from typing import Any 

2 

3from lanraragi_api.api.base import ( 

4 BaseAPICall, 

5) 

6from lanraragi_api.entity.minion import MinionJobResponse 

7from lanraragi_api.entity.misc import ( 

8 DownloadUrlResponse, 

9 ServerInfo, 

10 TempfolderCleanupResponse, 

11) 

12 

13 

14class MiscAPI(BaseAPICall): 

15 """Other APIs that don't fit a dedicated theme. 

16 

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

18 """ 

19 

20 def get_server_information(self) -> ServerInfo: 

21 """Return basic information about the LRR instance this server is running. 

22 

23 Returns: 

24 ServerInfo: Basic information about the instance. 

25 

26 Raises: 

27 APIHttpError: Any status code other than 200. 

28 APIResponseDecodeError: If the body does not match ``ServerInfo``. 

29 """ 

30 return self.request_model("GET", "/api/info", ServerInfo) 

31 

32 def clean_temporary_folder(self) -> TempfolderCleanupResponse: 

33 """Clean the server's temporary folder. 

34 

35 Returns: 

36 TempfolderCleanupResponse: Result of the cleanup, with the new size 

37 of the temporary folder. 

38 

39 Raises: 

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

41 match ``TempfolderCleanupResponse``. 

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

43 

44 Note: 

45 A cleanup error is reported in the ``error`` field of the result 

46 while the call still answers with 200. 

47 """ 

48 return self.request_operation( 

49 "DELETE", "/api/tempfolder", model=TempfolderCleanupResponse 

50 ) 

51 

52 def queue_url_to_download( 

53 self, 

54 url: str, 

55 category_id: str | None = None, 

56 use_form_data: bool = False, 

57 ) -> DownloadUrlResponse: 

58 """Add a URL to be downloaded by the server and added to its library. 

59 

60 Args: 

61 url: URL to download. 

62 category_id: Category ID to add the downloaded URL to. Defaults to 

63 None. 

64 use_form_data: Send the arguments as form data instead of query 

65 parameters. Defaults to False. 

66 

67 Returns: 

68 DownloadUrlResponse: Result of the call, with the ID of the queued 

69 job and the URL that was queued. 

70 

71 Raises: 

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

73 match ``DownloadUrlResponse``. 

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

75 

76 Note: 

77 The endpoint takes its arguments either as query parameters or in a 

78 multipart form body; this switch picks the body variant. 

79 A 400 response, returned for a bad request such as a missing URL, 

80 is returned in the operation result, with ``success`` set to 0, 

81 instead of raising. 

82 """ 

83 request_kwargs: dict[str, Any] = {"params": {"url": url, "catid": category_id}} 

84 if use_form_data: 

85 files = {} 

86 files["url"] = (None, url) 

87 if category_id is not None: 

88 files["catid"] = (None, category_id) 

89 request_kwargs = {"files": files} 

90 

91 return self.request_operation( 

92 "POST", 

93 "/api/download_url", 

94 model=DownloadUrlResponse, 

95 **request_kwargs, 

96 ) 

97 

98 def regenerate_thumbnails(self, force: bool = False) -> MinionJobResponse: 

99 """Queue a Minion job to regenerate missing/all thumbnails on the server. 

100 

101 Args: 

102 force: Whether to generate all thumbnails, or only the missing 

103 ones. Defaults to False. 

104 

105 Returns: 

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

107 job. 

108 

109 Raises: 

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

111 match ``MinionJobResponse``. 

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

113 """ 

114 return self.request_operation( 

115 "POST", 

116 "/api/regen_thumbs", 

117 model=MinionJobResponse, 

118 params={"force": force if force else None}, 

119 )