Coverage for /usr/local/lib/python3.9/site-packages/tgclients/aggregator.py: 100%

1# SPDX-FileCopyrightText: 2022 Georg-August-Universität Göttingen 

2# 

3# SPDX-License-Identifier: LGPL-3.0-or-later 

4 

5"""API for the TextGrid aggregator service""" 

6import logging 

7from typing import List, Optional, Union, overload 

8 

9import requests 

10from requests.models import Response 

11 

12from tgclients.config import TextgridConfig 

13 

14logger = logging.getLogger(__name__) 

15 

16 

17class Aggregator: 

18 """Provide access to the Textgrid Aggregator Service. 

19 API docs: https://textgridlab.org/doc/services/submodules/aggregator/docs/api.html""" 

20 

21 def __init__(self, config: TextgridConfig = TextgridConfig()) -> None: 

22 self._url = config.aggregator 

23 self._config = config 

24 self._requests = requests.Session() 

25 

26 @overload 

27 def zip(self, textgrid_uris: str, sid: Optional[str] = None) -> Response: 

28 ... 

29 

30 @overload 

31 def zip(self, textgrid_uris: List[str], sid: Optional[str] = None) -> Response: 

32 ... 

33 

34 def zip(self, textgrid_uris: Union[str, List[str]], sid: Optional[str] = None) -> Response: 

35 """Download aggregated TextGrid objects as ZIP file. 

36 https://textgridlab.org/doc/services/submodules/aggregator/docs/zip.html 

37 

38 Args: 

39 textgrid_uris (List[str] or str): a single or a list of TextGrid URIs 

40 sid (Optional[str], optional): Session ID. Defaults to None. 

41 

42 Returns: 

43 Response: the response with zip file in body.content 

44 """ 

45 if isinstance(textgrid_uris, list): 

46 textgrid_uris = ','.join(textgrid_uris) 

47 url = self._url + '/zip/' 

48 response = self._requests.get(url + textgrid_uris, params={ 'sid': sid }, 

49 timeout=self._config.http_timeout) 

50 return response 

51 

52 @overload 

53 def text(self, textgrid_uris: str, sid: Optional[str] = None) -> Response: 

54 ... 

55 

56 @overload 

57 def text(self, textgrid_uris: List[str], sid: Optional[str] = None) -> Response: 

58 ... 

59 

60 # python 3.10 allows writinh Union as | 

61 # https://www.blog.pythonlibrary.org/2021/09/11/python-3-10-simplifies-unions-in-type-annotations/ 

62 def text(self, textgrid_uris: Union[str, List[str]], sid: Optional[str] = None) -> Response: 

63 """Download aggregated TextGrid objects as plain text file. 

64 

65 Args: 

66 textgrid_uris (List[str] or str): a single or a list of TextGrid URIs 

67 sid (Optional[str], optional): Session ID. Defaults to None. 

68 

69 Returns: 

70 Response: the respone with the text in the body 

71 """ 

72 if isinstance(textgrid_uris, list): 

73 textgrid_uris = ','.join(textgrid_uris) 

74 url = self._url + '/text/' 

75 response = self._requests.get(url + textgrid_uris, params={ 'sid': sid }, 

76 timeout=self._config.http_timeout) 

77 return response 

78 

79 @overload 

80 def teicorpus(self, textgrid_uris: str, sid: Optional[str] = None) -> Response: 

81 ... 

82 

83 @overload 

84 def teicorpus(self, textgrid_uris: List[str], sid: Optional[str] = None) -> Response: 

85 ... 

86 

87 def teicorpus(self, textgrid_uris: Union[str, List[str]], sid: Optional[str] = None 

88 ) -> Response: 

89 """Download aggregated TextGrid objects as TEI corpus. 

90 

91 Args: 

92 textgrid_uris (List[str] or str): a single or a list of TextGrid URIs 

93 sid (Optional[str], optional): Session ID. Defaults to None. 

94 

95 Returns: 

96 Response: the respone with the TEI corpus in the body 

97 """ 

98 if isinstance(textgrid_uris, list): 

99 textgrid_uris = ','.join(textgrid_uris) 

100 url = self._url + '/teicorpus/' 

101 response = self._requests.get(url + textgrid_uris, params={ 'sid': sid }, 

102 timeout=self._config.http_timeout) 

103 return response 

104 

105 @overload 

106 def render(self, 

107 textgrid_uris: str, 

108 sid: Optional[str] = None, 

109 stylesheet_uri: Optional[str] = None, 

110 mediatype: Optional[str] = None, 

111 link_pattern: Optional[str] = None, 

112 sandbox: Optional[bool] = None 

113 ) -> Response: 

114 ... 

115 

116 @overload 

117 def render(self, textgrid_uris: List[str], 

118 sid: Optional[str] = None, 

119 stylesheet_uri: Optional[str] = None, 

120 mediatype: Optional[str] = None, 

121 link_pattern: Optional[str] = None, 

122 sandbox: Optional[bool] = None 

123 ) -> Response: 

124 ... 

125 

126 def render(self, 

127 textgrid_uris: Union[str, List[str]], 

128 sid: Optional[str] = None, 

129 stylesheet_uri: Optional[str] = None, 

130 mediatype: Optional[str] = None, 

131 link_pattern: Optional[str] = None, 

132 sandbox: Optional[bool] = None 

133 ) -> Response: 

134 """Apply an XSLT stylesheet to one or more TextGrid URIs. 

135 Will render (X)HTML by default with XSLT stylesheets from tei-c.org 

136 see https://textgridlab.org/doc/services/submodules/aggregator/docs/html.html 

137 

138 Args: 

139 textgrid_uris (List[str] or str): a single or a list of TextGrid URIs 

140 sid (Optional[str], optional): Session ID. Defaults to None. 

141 stylesheet_uri (Optional[str], optional): alternative XSLT stylesheet to use. 

142 Must be a TextGrid URI. 

143 mediatype (Optional[str], optional): The requested content type. 

144 E.g., text/html or text/xml. Default is text/html 

145 link_pattern (Optional[str], optional): URL pattern for links. 

146 @URI@ will be replaced with the textgrid: URI. 

147 sandbox (Optional[bool], optional): access sandboxed data. Defaults to false 

148 

149 Returns: 

150 Response: the respone with the TEI corpus in the body 

151 """ 

152 if isinstance(textgrid_uris, list): 

153 textgrid_uris = ','.join(textgrid_uris) 

154 url = self._url + '/html/' 

155 response = self._requests.get(url + textgrid_uris, 

156 params={ 

157 'sid': sid, 

158 'stylesheet': stylesheet_uri, 

159 'mediatype': mediatype, 

160 'linkPattern': link_pattern, 

161 'sandbox': sandbox 

162 }, 

163 timeout=self._config.http_timeout) 

164 return response