Coverage for pephubclient/pephubclient.py: 90%

132 statements  

« prev     ^ index     » next       coverage.py v7.15.3, created at 2026-08-04 18:15 +0000

1from typing import NoReturn, Optional, Literal 

2from typing_extensions import deprecated 

3 

4import peppy 

5from peppy.const import ( 

6 NAME_KEY, 

7 CONFIG_KEY, 

8 SUBSAMPLE_RAW_LIST_KEY, 

9 SAMPLE_RAW_DICT_KEY, 

10) 

11import urllib3 

12from pydantic import ValidationError 

13from ubiquerg import parse_registry_path 

14 

15from pephubclient.constants import ( 

16 RegistryPath, 

17 ResponseStatusCodes, 

18 PATH_TO_TOKEN_FILE, 

19) 

20from pephubclient.exceptions import ( 

21 IncorrectQueryStringError, 

22 ResponseError, 

23) 

24from pephubclient.files_manager import FilesManager 

25from pephubclient.helpers import MessageHandler, RequestManager, save_pep 

26from pephubclient.models import ( 

27 ProjectDict, 

28 ProjectUploadData, 

29 SearchReturnModel, 

30 ProjectAnnotationModel, 

31) 

32from pephubclient.pephub_oauth.pephub_oauth import PEPHubAuth 

33from pephubclient.modules.view import PEPHubView 

34from pephubclient.modules.sample import PEPHubSample 

35from pephubclient.schemas.schema import PEPHubSchema 

36 

37urllib3.disable_warnings() 

38 

39 

40class PEPHubClient(RequestManager): 

41 def __init__(self): 

42 cached = FilesManager.load_token_data(PATH_TO_TOKEN_FILE) 

43 self.__jwt_data = cached.token 

44 self.__base_url = cached.base_url.rstrip("/") + "/" 

45 

46 self.__view = PEPHubView(self.__jwt_data) 

47 self.__sample = PEPHubSample(self.__jwt_data) 

48 self.__schema = PEPHubSchema(self.__jwt_data) 

49 

50 @property 

51 def view(self) -> PEPHubView: 

52 return self.__view 

53 

54 @property 

55 def sample(self) -> PEPHubSample: 

56 return self.__sample 

57 

58 @property 

59 def schema(self) -> PEPHubSchema: 

60 return self.__schema 

61 

62 def login(self, token: Optional[str] = None, url: Optional[str] = None) -> NoReturn: 

63 """ 

64 Log in to PEPhub. 

65 

66 :param str token: JWT token to register directly. If provided, the browser 

67 device-code flow is skipped. 

68 :param str url: Base URL for PEPhub. If provided, overrides the cached/default URL. 

69 """ 

70 cached = FilesManager.load_token_data(PATH_TO_TOKEN_FILE) 

71 if url: 

72 cached.base_url = url 

73 if token: 

74 MessageHandler.print_warning("Token provided. Registering...") 

75 cached.token = token 

76 else: 

77 cached.token = PEPHubAuth().login_to_pephub(base_url=cached.base_url) 

78 

79 FilesManager.save_token_data(PATH_TO_TOKEN_FILE, cached) 

80 self.__jwt_data = cached.token 

81 self.__base_url = cached.base_url.rstrip("/") + "/" 

82 

83 def logout(self) -> NoReturn: 

84 """ 

85 Log out from PEPhub 

86 """ 

87 FilesManager.delete_file_if_exists(PATH_TO_TOKEN_FILE) 

88 self.__jwt_data = None 

89 

90 def pull( 

91 self, 

92 project_registry_path: str, 

93 force: Optional[bool] = False, 

94 zip: Optional[bool] = False, 

95 output: Optional[str] = None, 

96 ) -> None: 

97 """ 

98 Download project locally 

99 

100 :param str project_registry_path: Project registry path in PEPhub (e.g. databio/base:default) 

101 :param bool force: if project exists, overwrite it. 

102 :param bool zip: if True, save project as zip file 

103 :param str output: path where project will be saved 

104 :return: None 

105 """ 

106 project_dict = self.load_raw_pep( 

107 registry_path=project_registry_path, 

108 ) 

109 

110 save_pep( 

111 project=project_dict, 

112 reg_path=project_registry_path, 

113 force=force, 

114 project_path=output, 

115 zip=zip, 

116 ) 

117 

118 def load_project( 

119 self, 

120 project_registry_path: str, 

121 query_param: Optional[dict] = None, 

122 ) -> peppy.Project: 

123 """ 

124 Load peppy project from PEPhub in peppy.Project object 

125 

126 :param project_registry_path: registry path of the project 

127 :param query_param: query parameters used in get request 

128 :return Project: peppy project. 

129 """ 

130 raw_pep = self.load_raw_pep(project_registry_path, query_param) 

131 peppy_project = peppy.Project().from_dict(raw_pep) 

132 return peppy_project 

133 

134 def push( 

135 self, 

136 cfg: str, 

137 namespace: str, 

138 name: Optional[str] = None, 

139 tag: Optional[str] = None, 

140 is_private: Optional[bool] = False, 

141 force: Optional[bool] = False, 

142 ) -> None: 

143 """ 

144 Push (upload/update) project to Pephub using config/csv path 

145 

146 :param str cfg: Project config file (YAML) or sample table (CSV/TSV) 

147 with one row per sample to constitute project 

148 :param str namespace: namespace 

149 :param str name: project name 

150 :param str tag: project tag 

151 :param bool is_private: Specifies whether project should be private [Default= False] 

152 :param bool force: Force push to the database. Use it to update, or upload project. [Default= False] 

153 :return: None 

154 """ 

155 peppy_project = peppy.Project(cfg=cfg) 

156 self.upload( 

157 project=peppy_project, 

158 namespace=namespace, 

159 name=name, 

160 tag=tag, 

161 is_private=is_private, 

162 force=force, 

163 ) 

164 

165 def upload( 

166 self, 

167 project: peppy.Project, 

168 namespace: str, 

169 name: str = None, 

170 tag: str = None, 

171 is_private: bool = False, 

172 force: bool = True, 

173 ) -> None: 

174 """ 

175 Upload peppy project to the PEPhub. 

176 

177 :param peppy.Project project: Project object that has to be uploaded to the DB 

178 :param namespace: namespace 

179 :param name: project name 

180 :param tag: project tag 

181 :param force: Force push to the database. Use it to update, or upload project. 

182 :param is_private: Make project private 

183 :param force: overwrite project if it exists 

184 :return: None 

185 """ 

186 pep_dict = project.to_dict( 

187 extended=True, 

188 orient="records", 

189 ) 

190 if name: 

191 pep_dict[CONFIG_KEY][NAME_KEY] = name 

192 

193 pep_dict["config"] = pep_dict.pop(CONFIG_KEY) 

194 pep_dict["samples"] = pep_dict.pop(SAMPLE_RAW_DICT_KEY) 

195 pep_dict["subsamples"] = pep_dict.pop(SUBSAMPLE_RAW_LIST_KEY) 

196 print(pep_dict) 

197 upload_data = ProjectUploadData( 

198 pep_dict=pep_dict, 

199 tag=tag, 

200 is_private=is_private, 

201 overwrite=force, 

202 ) 

203 pephub_response = self.send_request( 

204 method="POST", 

205 url=self._build_push_request_url(namespace=namespace), 

206 headers=self.parse_header(self.__jwt_data), 

207 json=upload_data.model_dump(), 

208 cookies=None, 

209 ) 

210 if pephub_response.status_code == ResponseStatusCodes.ACCEPTED: 

211 MessageHandler.print_success( 

212 f"Project '{namespace}/{name}:{upload_data.tag}' was successfully uploaded" 

213 ) 

214 elif pephub_response.status_code == ResponseStatusCodes.CONFLICT: 

215 raise ResponseError( 

216 "Project already exists. Set force to overwrite project." 

217 ) 

218 elif pephub_response.status_code == ResponseStatusCodes.UNAUTHORIZED: 

219 raise ResponseError("Unauthorized! Failure in uploading project.") 

220 elif pephub_response.status_code == ResponseStatusCodes.FORBIDDEN: 

221 raise ResponseError( 

222 "User does not have permission to write to this namespace!" 

223 ) 

224 else: 

225 detail = "" 

226 try: 

227 detail = self.decode_response(pephub_response, output_json=True).get( 

228 "detail", "" 

229 ) 

230 except Exception: 

231 pass 

232 raise ResponseError( 

233 f"Unexpected Response Error. {pephub_response.status_code}: {detail}" 

234 if detail 

235 else f"Unexpected Response Error. {pephub_response.status_code}" 

236 ) 

237 return None 

238 

239 def find_project( 

240 self, 

241 namespace: str, 

242 query_string: str = "", 

243 tag: str = None, 

244 limit: int = 100, 

245 offset: int = 0, 

246 filter_by: Literal["submission_date", "last_update_date"] = None, 

247 start_date: str = None, 

248 end_date: str = None, 

249 ) -> SearchReturnModel: 

250 """ 

251 Find project in specific namespace and return list of PEP annotation 

252 

253 :param namespace: Namespace where to search for projects 

254 :param query_string: Search query 

255 :param tag: Project tag 

256 :param limit: Return limit 

257 :param offset: Return offset 

258 :param filter_by: Use filter date. Option: [submission_date, last_update_date] 

259 :param start_date: filter beginning date 

260 :param end_date: filter end date (if none today's date is used) 

261 :return: 

262 """ 

263 

264 query_param = { 

265 "q": query_string, 

266 "limit": limit, 

267 "offset": offset, 

268 "tag": tag, 

269 } 

270 if filter_by in ["submission_date", "last_update_date"]: 

271 query_param["filter_by"] = filter_by 

272 query_param["filter_start_date"] = start_date 

273 if end_date: 

274 query_param["filter_end_date"] = end_date 

275 

276 url = self._build_project_search_url( 

277 namespace=namespace, 

278 query_param=query_param, 

279 ) 

280 

281 pephub_response = self.send_request( 

282 method="GET", 

283 url=url, 

284 headers=self.parse_header(self.__jwt_data), 

285 json=None, 

286 cookies=None, 

287 ) 

288 if pephub_response.status_code == ResponseStatusCodes.OK: 

289 decoded_response = self.decode_response(pephub_response, output_json=True) 

290 project_list = [] 

291 for project_found in decoded_response["results"]: 

292 project_list.append(ProjectAnnotationModel(**project_found)) 

293 return SearchReturnModel(**decoded_response) 

294 

295 @deprecated("This method is deprecated. Use load_raw_pep instead.") 

296 def _load_raw_pep( 

297 self, 

298 registry_path: str, 

299 jwt_data: Optional[str] = None, 

300 query_param: Optional[dict] = None, 

301 ) -> dict: 

302 """ 

303 !!! This method is deprecated. Use load_raw_pep instead. !!! 

304 

305 Request PEPhub and return the requested project as peppy.Project object. 

306 

307 :param registry_path: Project namespace, eg. "geo/GSE124224:tag" 

308 :param query_param: Optional variables to be passed to PEPhub 

309 :return: Raw project in dict. 

310 """ 

311 return self.load_raw_pep(registry_path, query_param) 

312 

313 def load_raw_pep( 

314 self, 

315 registry_path: str, 

316 query_param: Optional[dict] = None, 

317 ) -> dict: 

318 """ 

319 Request PEPhub and return the requested project as peppy.Project object. 

320 

321 :param registry_path: Project namespace, eg. "geo/GSE124224:tag" 

322 :param query_param: Optional variables to be passed to PEPhub 

323 :return: Raw project in dict. 

324 """ 

325 query_param = query_param or {} 

326 query_param["raw"] = "true" 

327 

328 self._set_registry_data(registry_path) 

329 pephub_response = self.send_request( 

330 method="GET", 

331 url=self._build_pull_request_url(query_param=query_param), 

332 headers=self.parse_header(self.__jwt_data), 

333 cookies=None, 

334 ) 

335 if pephub_response.status_code == ResponseStatusCodes.OK: 

336 decoded_response = self.decode_response(pephub_response, output_json=True) 

337 correct_proj_dict = ProjectDict(**decoded_response) 

338 

339 # This step is necessary because of this issue: https://github.com/pepkit/pephub/issues/124 

340 return correct_proj_dict.model_dump(by_alias=True) 

341 

342 if pephub_response.status_code == ResponseStatusCodes.NOT_EXIST: 

343 raise ResponseError("File does not exist, or you are unauthorized.") 

344 if pephub_response.status_code == ResponseStatusCodes.INTERNAL_ERROR: 

345 raise ResponseError( 

346 f"Internal server error. Unexpected return value. Error: {pephub_response.status_code}" 

347 ) 

348 

349 def _set_registry_data(self, query_string: str) -> None: 

350 """ 

351 Parse provided query string to extract project name, sample name, etc. 

352 

353 :param query_string: Passed by user. Contain information needed to locate the project. 

354 :return: Parsed query string. 

355 """ 

356 try: 

357 self.registry_path = RegistryPath(**parse_registry_path(query_string)) 

358 except (ValidationError, TypeError): 

359 raise IncorrectQueryStringError(query_string=query_string) 

360 

361 def _build_pull_request_url(self, query_param: dict = None) -> str: 

362 """ 

363 Build request for getting projects form pephub 

364 

365 :param query_param: dict of parameters used in query string 

366 :return: url string 

367 """ 

368 query_param = query_param or {} 

369 query_param["tag"] = self.registry_path.tag 

370 

371 endpoint = self.registry_path.namespace + "/" + self.registry_path.item 

372 

373 variables_string = self.parse_query_param(query_param) 

374 endpoint += variables_string 

375 

376 return f"{self.__base_url}api/v1/projects/" + endpoint 

377 

378 def _build_project_search_url( 

379 self, namespace: str, query_param: dict = None 

380 ) -> str: 

381 """ 

382 Build request for searching projects form pephub 

383 

384 :param query_param: dict of parameters used in query string 

385 :return: url string 

386 """ 

387 

388 variables_string = RequestManager.parse_query_param(query_param) 

389 endpoint = variables_string 

390 

391 return f"{self.__base_url}api/v1/namespaces/{namespace}/projects" + endpoint 

392 

393 def _build_push_request_url(self, namespace: str) -> str: 

394 """ 

395 Build project uplaod request used in pephub 

396 

397 :param namespace: namespace where project will be uploaded 

398 :return: url string 

399 """ 

400 return f"{self.__base_url}api/v1/namespaces/{namespace}/projects/json"