Coverage for pephubclient/pephubclient.py: 90%
132 statements
« prev ^ index » next coverage.py v7.15.3, created at 2026-08-04 18:15 +0000
« 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
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
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
37urllib3.disable_warnings()
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("/") + "/"
46 self.__view = PEPHubView(self.__jwt_data)
47 self.__sample = PEPHubSample(self.__jwt_data)
48 self.__schema = PEPHubSchema(self.__jwt_data)
50 @property
51 def view(self) -> PEPHubView:
52 return self.__view
54 @property
55 def sample(self) -> PEPHubSample:
56 return self.__sample
58 @property
59 def schema(self) -> PEPHubSchema:
60 return self.__schema
62 def login(self, token: Optional[str] = None, url: Optional[str] = None) -> NoReturn:
63 """
64 Log in to PEPhub.
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)
79 FilesManager.save_token_data(PATH_TO_TOKEN_FILE, cached)
80 self.__jwt_data = cached.token
81 self.__base_url = cached.base_url.rstrip("/") + "/"
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
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
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 )
110 save_pep(
111 project=project_dict,
112 reg_path=project_registry_path,
113 force=force,
114 project_path=output,
115 zip=zip,
116 )
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
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
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
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 )
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.
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
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
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
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 """
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
276 url = self._build_project_search_url(
277 namespace=namespace,
278 query_param=query_param,
279 )
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)
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. !!!
305 Request PEPhub and return the requested project as peppy.Project object.
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)
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.
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"
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)
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)
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 )
349 def _set_registry_data(self, query_string: str) -> None:
350 """
351 Parse provided query string to extract project name, sample name, etc.
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)
361 def _build_pull_request_url(self, query_param: dict = None) -> str:
362 """
363 Build request for getting projects form pephub
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
371 endpoint = self.registry_path.namespace + "/" + self.registry_path.item
373 variables_string = self.parse_query_param(query_param)
374 endpoint += variables_string
376 return f"{self.__base_url}api/v1/projects/" + endpoint
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
384 :param query_param: dict of parameters used in query string
385 :return: url string
386 """
388 variables_string = RequestManager.parse_query_param(query_param)
389 endpoint = variables_string
391 return f"{self.__base_url}api/v1/namespaces/{namespace}/projects" + endpoint
393 def _build_push_request_url(self, namespace: str) -> str:
394 """
395 Build project uplaod request used in pephub
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"