Skip to content

Commit 02cb0bf

Browse files
suricactussuricactus
authored
Merge pull request #67 from opengisch/adding_examples_and_formatting
Adding examples and Formatting for the examples code
2 parents bc4413a + 22e6a8b commit 02cb0bf

File tree

1 file changed

+203
-1
lines changed

1 file changed

+203
-1
lines changed

‎qfieldcloud_sdk/sdk.py‎

Lines changed: 203 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -269,8 +269,10 @@ def login(self, username: str, password: str) -> Dict[str, Any]:
269269
Authentication token and additional metadata.
270270
271271
Example:
272+
```python
272273
client = sdk.Client(url="https://app.qfield.cloud/api/v1/")
273274
client.login("ninjamaster", "secret_password123")
275+
```
274276
"""
275277
resp = self._request(
276278
"POST",
@@ -292,7 +294,9 @@ def logout(self) -> None:
292294
"""Logs out from the current session, invalidating the authentication token.
293295
294296
Example:
297+
```python
295298
client.logout()
299+
```
296300
"""
297301
resp = self._request("POST", "auth/logout")
298302

@@ -312,6 +316,11 @@ def list_projects(
312316
313317
Returns:
314318
A list of dictionaries containing project details.
319+
320+
Example:
321+
```python
322+
client.list_projects()
323+
```
315324
"""
316325
params = {
317326
"include-public": str(int(include_public)), # type: ignore
@@ -335,7 +344,9 @@ def list_remote_files(
335344
A list of file details.
336345
337346
Example:
338-
client.list_remote_files("project_id", True)
347+
```python
348+
client.list_remote_files("123e4567-e89b-12d3-a456-426614174000", False)
349+
```
339350
"""
340351
params = {}
341352

@@ -366,6 +377,13 @@ def create_project(
366377
367378
Returns:
368379
A dictionary containing the details of the created project.
380+
381+
Example:
382+
```python
383+
client.create_project(
384+
"Tree_Survey", "My_Organization_Clan", "Description"
385+
)
386+
```
369387
"""
370388
resp = self._request(
371389
"POST",
@@ -388,6 +406,11 @@ def delete_project(self, project_id: str) -> requests.Response:
388406
389407
Returns:
390408
The response object from the file delete request.
409+
410+
Example:
411+
```python
412+
client.delete_project("123e4567-e89b-12d3-a456-426614174000")
413+
```
391414
"""
392415
resp = self._request("DELETE", f"projects/{project_id}")
393416

@@ -418,6 +441,19 @@ def upload_files(
418441
419442
Returns:
420443
A list of dictionaries with information about the uploaded files.
444+
445+
Example:
446+
```python
447+
client.upload_files(
448+
project_id="123e4567-e89b-12d3-a456-426614174000",
449+
upload_type=sdk.FileTransferType.PROJECT,
450+
project_path="/home/ninjamaster/QField/cloud/Tree_Survey",
451+
filter_glob="*",
452+
throw_on_error=True,
453+
show_progress=True,
454+
force=True
455+
)
456+
```
421457
"""
422458
if not filter_glob:
423459
filter_glob = "*"
@@ -500,6 +536,17 @@ def upload_file(
500536
501537
Returns:
502538
The response object from the upload request.
539+
540+
Example:
541+
```python
542+
client.upload_file(
543+
project_id="123e4567-e89b-12d3-a456-426614174000",
544+
upload_type=FileTransferType.PROJECT,
545+
local_filename="/home/ninjamaster/QField/cloud/Tree_Survey/trees.gpkg",
546+
remote_filename="trees.gpkg",
547+
show_progress=True
548+
)
549+
```
503550
"""
504551
# if the filepath is invalid, it will throw a new error `pathvalidate.ValidationError`
505552
is_valid_filepath(str(local_filename))
@@ -560,6 +607,17 @@ def download_project(
560607
561608
Returns:
562609
A list of dictionaries with information about the downloaded files.
610+
611+
Example:
612+
```python
613+
client.download_project(
614+
project_id="123e4567-e89b-12d3-a456-426614174000",
615+
local_dir="/home/ninjamaster/QField/cloud/Tree_Survey",
616+
filter_glob="*",
617+
show_progress=True,
618+
force_download=True
619+
)
620+
```
563621
"""
564622
files = self.list_remote_files(project_id)
565623

@@ -589,6 +647,14 @@ def list_jobs(
589647
590648
Returns:
591649
A list of dictionaries representing the jobs.
650+
651+
Example:
652+
```python
653+
client.list_jobs(
654+
project_id="123e4567-e89b-12d3-a456-426614174000",
655+
job_type=JobTypes.PACKAGE
656+
)
657+
```
592658
"""
593659
payload = self._request_json(
594660
"GET",
@@ -613,6 +679,15 @@ def job_trigger(
613679
614680
Returns:
615681
A dictionary containing the job information.
682+
683+
Example:
684+
```python
685+
client.job_trigger(
686+
project_id="123e4567-e89b-12d3-a456-426614174000",
687+
job_type=JobTypes.PACKAGE,
688+
force=True
689+
)
690+
```
616691
"""
617692
resp = self._request(
618693
"POST",
@@ -634,6 +709,11 @@ def job_status(self, job_id: str) -> Dict[str, Any]:
634709
635710
Returns:
636711
A dictionary containing the job status.
712+
713+
Example:
714+
```python
715+
client.job_status("123e4567-e89b-12d3-a456-426614174000")
716+
```
637717
"""
638718
resp = self._request("GET", f"jobs/{job_id}")
639719

@@ -648,6 +728,14 @@ def push_delta(self, project_id: str, delta_filename: str) -> DeltaPushResponse:
648728
649729
Returns:
650730
A DeltaPushResponse containing the response from the server.
731+
732+
Example:
733+
```python
734+
client.push_delta(
735+
project_id="123e4567-e89b-12d3-a456-426614174000",
736+
delta_filename="/home/ninjamaster/QField/cloud/Tree_Survey/deltas.json"
737+
)
738+
```
651739
"""
652740
with open(delta_filename, "r") as delta_file:
653741
files = {"file": delta_file}
@@ -679,6 +767,15 @@ def delete_files(
679767
680768
Returns:
681769
Deleted files by glob pattern.
770+
771+
Example:
772+
```python
773+
client.delete_files(
774+
project_id="123e4567-e89b-12d3-a456-426614174000",
775+
glob_patterns=["*.csv", "*.jpg"],
776+
throw_on_error=True
777+
)
778+
```
682779
"""
683780
project_files = self.list_remote_files(project_id)
684781
glob_results: Dict[str, List[Dict[str, Any]]] = {}
@@ -755,6 +852,11 @@ def package_latest(self, project_id: str) -> Dict[str, Any]:
755852
756853
Returns:
757854
A dictionary containing the latest packaging status.
855+
856+
Example:
857+
```python
858+
client.package_latest("123e4567-e89b-12d3-a456-426614174000")
859+
```
758860
"""
759861
resp = self._request("GET", f"packages/{project_id}/latest/")
760862

@@ -781,6 +883,16 @@ def package_download(
781883
782884
Returns:
783885
A list of dictionaries with information about the downloaded files.
886+
887+
Example:
888+
```python
889+
client.package_download(
890+
project_id="123e4567-e89b-12d3-a456-426614174000",
891+
local_dir="/home/ninjamaster/QField/cloud/Tree_Survey",
892+
filter_glob="*",
893+
show_progress=True
894+
)
895+
```
784896
"""
785897
project_status = self.package_latest(project_id)
786898

@@ -830,6 +942,18 @@ def download_files(
830942
831943
Returns:
832944
A list of file dicts.
945+
946+
Example:
947+
```python
948+
client.download_files(
949+
files=[{"name": "trees.gpkg"}, {"name": "roads.gpkg"],
950+
project_id="123e4567-e89b-12d3-a456-426614174000",
951+
download_type=FileTransferType.PROJECT,
952+
local_dir="/home/ninjamaster/QField/cloud/Tree_Survey",
953+
filter_glob="*",
954+
show_progress=True
955+
)
956+
```
833957
"""
834958
if not filter_glob:
835959
filter_glob = "*"
@@ -898,6 +1022,16 @@ def download_file(
8981022
8991023
Returns:
9001024
The response object.
1025+
1026+
Example:
1027+
```python
1028+
client.download_file(
1029+
project_id="123e4567-e89b-12d3-a456-426614174000",
1030+
download_type=FileTransferType.PROJECT,
1031+
local_filename="/home/ninjamaster/QField/cloud/Tree_Survey/trees.gpkg",
1032+
remote_filename="trees.gpkg",
1033+
show_progress=True
1034+
)
9011035
"""
9021036

9031037
if remote_etag and local_filename.exists():
@@ -953,6 +1087,11 @@ def list_local_files(
9531087
"""
9541088
Returns a list of dicts with information about local files. Usually used before uploading files.
9551089
NOTE: files and dirs starting with leading dot (.) or ending in tilde (~) will be ignored.
1090+
1091+
Example:
1092+
```python
1093+
client.list_local_files("/home/ninjamaster/QField/cloud/Tree_Survey", "*.gpkg")
1094+
```
9561095
"""
9571096
if not filter_glob:
9581097
filter_glob = "*"
@@ -989,6 +1128,11 @@ def get_project_collaborators(self, project_id: str) -> List[CollaboratorModel]:
9891128
9901129
Returns:
9911130
The list of project collaborators.
1131+
1132+
Example:
1133+
```python
1134+
client.get_project_collaborators("123e4567-e89b-12d3-a456-426614174000")
1135+
```
9921136
"""
9931137
collaborators = cast(
9941138
List[CollaboratorModel],
@@ -1009,6 +1153,15 @@ def add_project_collaborator(
10091153
10101154
Returns:
10111155
The added project collaborator.
1156+
1157+
Example:
1158+
```python
1159+
client.add_project_collaborator(
1160+
project_id="123e4567-e89b-12d3-a456-426614174000",
1161+
username="ninja_001",
1162+
role=ProjectCollaboratorRole.EDITOR
1163+
)
1164+
```
10121165
"""
10131166
collaborator = cast(
10141167
CollaboratorModel,
@@ -1030,6 +1183,14 @@ def remove_project_collaborator(self, project_id: str, username: str) -> None:
10301183
Args:
10311184
project_id: Project ID.
10321185
username: the username of the collaborator to be removed
1186+
1187+
Example:
1188+
```python
1189+
client.remove_project_collaborator(
1190+
project_id="123e4567-e89b-12d3-a456-426614174000",
1191+
username="ninja_007"
1192+
)
1193+
```
10331194
"""
10341195
self._request("DELETE", f"/collaborators/{project_id}/{username}")
10351196

@@ -1045,6 +1206,15 @@ def patch_project_collaborators(
10451206
10461207
Returns:
10471208
The updated project collaborator.
1209+
1210+
Example:
1211+
```python
1212+
client.patch_project_collaborators(
1213+
project_id="123e4567-e89b-12d3-a456-426614174000",
1214+
username="ninja_001",
1215+
role=ProjectCollaboratorRole.MANAGER
1216+
)
1217+
```
10481218
"""
10491219
collaborator = cast(
10501220
CollaboratorModel,
@@ -1069,6 +1239,11 @@ def get_organization_members(
10691239
10701240
Returns:
10711241
The list of organization members.
1242+
1243+
Example:
1244+
```python
1245+
client.get_organization_members("My_Organization_Clan")
1246+
```
10721247
"""
10731248
members = cast(
10741249
List[OrganizationMemberModel],
@@ -1094,6 +1269,16 @@ def add_organization_member(
10941269
10951270
Returns:
10961271
The added organization member.
1272+
1273+
Example:
1274+
```python
1275+
client.add_organization_member(
1276+
organization="My_Organization_Clan",
1277+
username="ninja_001",
1278+
role=OrganizationMemberRole.MEMBER,
1279+
is_public=False
1280+
)
1281+
```
10971282
"""
10981283
member = cast(
10991284
OrganizationMemberModel,
@@ -1116,6 +1301,14 @@ def remove_organization_members(self, project_id: str, username: str) -> None:
11161301
Args:
11171302
project_id: Project ID.
11181303
username: the username of the member to be removed
1304+
1305+
Example:
1306+
```python
1307+
client.remove_organization_members(
1308+
organization="My_Organization_Clan",
1309+
username="ninja_007"
1310+
)
1311+
```
11191312
"""
11201313
self._request("DELETE", f"/members/{project_id}/{username}")
11211314

@@ -1131,6 +1324,15 @@ def patch_organization_members(
11311324
11321325
Returns:
11331326
The updated organization member.
1327+
1328+
Example:
1329+
```python
1330+
client.patch_organization_members(
1331+
organization="My_Organization_Clan",
1332+
username="ninja_001",
1333+
role=OrganizationMemberRole.ADMIN
1334+
)
1335+
```
11341336
"""
11351337
member = cast(
11361338
OrganizationMemberModel,

0 commit comments

Comments
 (0)