Skip to content

Commit

Permalink
Merge pull request #67 from opengisch/adding_examples_and_formatting
Browse files Browse the repository at this point in the history 
Adding examples and Formatting for the examples code
  • Loading branch information
@suricactus
suricactus authored Oct 4, 2024
2 parents bc4413a + 22e6a8b commit 02cb0bf
Showing 1 changed file with 203 additions and 1 deletion.
204 changes: 203 additions & 1 deletion qfieldcloud_sdk/sdk.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -269,8 +269,10 @@ def login(self, username: str, password: str) -> Dict[str, Any]:
Authentication token and additional metadata.
Example:
```python
client = sdk.Client(url="https://app.qfield.cloud/api/v1/")
client.login("ninjamaster", "secret_password123")
```
"""
resp = self._request(
"POST",
Expand All @@ -292,7 +294,9 @@ def logout(self) -> None:
"""Logs out from the current session, invalidating the authentication token.
Example:
```python
client.logout()
```
"""
resp = self._request("POST", "auth/logout")

Expand All @@ -312,6 +316,11 @@ def list_projects(
Returns:
A list of dictionaries containing project details.
Example:
```python
client.list_projects()
```
"""
params = {
"include-public": str(int(include_public)), # type: ignore
Expand All @@ -335,7 +344,9 @@ def list_remote_files(
A list of file details.
Example:
client.list_remote_files("project_id", True)
```python
client.list_remote_files("123e4567-e89b-12d3-a456-426614174000", False)
```
"""
params = {}

Expand Down Expand Up @@ -366,6 +377,13 @@ def create_project(
Returns:
A dictionary containing the details of the created project.
Example:
```python
client.create_project(
"Tree_Survey", "My_Organization_Clan", "Description"
)
```
"""
resp = self._request(
"POST",
Expand All @@ -388,6 +406,11 @@ def delete_project(self, project_id: str) -> requests.Response:
Returns:
The response object from the file delete request.
Example:
```python
client.delete_project("123e4567-e89b-12d3-a456-426614174000")
```
"""
resp = self._request("DELETE", f"projects/{project_id}")

Expand Down Expand Up @@ -418,6 +441,19 @@ def upload_files(
Returns:
A list of dictionaries with information about the uploaded files.
Example:
```python
client.upload_files(
project_id="123e4567-e89b-12d3-a456-426614174000",
upload_type=sdk.FileTransferType.PROJECT,
project_path="/home/ninjamaster/QField/cloud/Tree_Survey",
filter_glob="*",
throw_on_error=True,
show_progress=True,
force=True
)
```
"""
if not filter_glob:
filter_glob = "*"
Expand Down Expand Up @@ -500,6 +536,17 @@ def upload_file(
Returns:
The response object from the upload request.
Example:
```python
client.upload_file(
project_id="123e4567-e89b-12d3-a456-426614174000",
upload_type=FileTransferType.PROJECT,
local_filename="/home/ninjamaster/QField/cloud/Tree_Survey/trees.gpkg",
remote_filename="trees.gpkg",
show_progress=True
)
```
"""
# if the filepath is invalid, it will throw a new error `pathvalidate.ValidationError`
is_valid_filepath(str(local_filename))
Expand Down Expand Up @@ -560,6 +607,17 @@ def download_project(
Returns:
A list of dictionaries with information about the downloaded files.
Example:
```python
client.download_project(
project_id="123e4567-e89b-12d3-a456-426614174000",
local_dir="/home/ninjamaster/QField/cloud/Tree_Survey",
filter_glob="*",
show_progress=True,
force_download=True
)
```
"""
files = self.list_remote_files(project_id)

Expand Down Expand Up @@ -589,6 +647,14 @@ def list_jobs(
Returns:
A list of dictionaries representing the jobs.
Example:
```python
client.list_jobs(
project_id="123e4567-e89b-12d3-a456-426614174000",
job_type=JobTypes.PACKAGE
)
```
"""
payload = self._request_json(
"GET",
Expand All @@ -613,6 +679,15 @@ def job_trigger(
Returns:
A dictionary containing the job information.
Example:
```python
client.job_trigger(
project_id="123e4567-e89b-12d3-a456-426614174000",
job_type=JobTypes.PACKAGE,
force=True
)
```
"""
resp = self._request(
"POST",
Expand All @@ -634,6 +709,11 @@ def job_status(self, job_id: str) -> Dict[str, Any]:
Returns:
A dictionary containing the job status.
Example:
```python
client.job_status("123e4567-e89b-12d3-a456-426614174000")
```
"""
resp = self._request("GET", f"jobs/{job_id}")

Expand All @@ -648,6 +728,14 @@ def push_delta(self, project_id: str, delta_filename: str) -> DeltaPushResponse:
Returns:
A DeltaPushResponse containing the response from the server.
Example:
```python
client.push_delta(
project_id="123e4567-e89b-12d3-a456-426614174000",
delta_filename="/home/ninjamaster/QField/cloud/Tree_Survey/deltas.json"
)
```
"""
with open(delta_filename, "r") as delta_file:
files = {"file": delta_file}
Expand Down Expand Up @@ -679,6 +767,15 @@ def delete_files(
Returns:
Deleted files by glob pattern.
Example:
```python
client.delete_files(
project_id="123e4567-e89b-12d3-a456-426614174000",
glob_patterns=["*.csv", "*.jpg"],
throw_on_error=True
)
```
"""
project_files = self.list_remote_files(project_id)
glob_results: Dict[str, List[Dict[str, Any]]] = {}
Expand Down Expand Up @@ -755,6 +852,11 @@ def package_latest(self, project_id: str) -> Dict[str, Any]:
Returns:
A dictionary containing the latest packaging status.
Example:
```python
client.package_latest("123e4567-e89b-12d3-a456-426614174000")
```
"""
resp = self._request("GET", f"packages/{project_id}/latest/")

Expand All @@ -781,6 +883,16 @@ def package_download(
Returns:
A list of dictionaries with information about the downloaded files.
Example:
```python
client.package_download(
project_id="123e4567-e89b-12d3-a456-426614174000",
local_dir="/home/ninjamaster/QField/cloud/Tree_Survey",
filter_glob="*",
show_progress=True
)
```
"""
project_status = self.package_latest(project_id)

Expand Down Expand Up @@ -830,6 +942,18 @@ def download_files(
Returns:
A list of file dicts.
Example:
```python
client.download_files(
files=[{"name": "trees.gpkg"}, {"name": "roads.gpkg"],
project_id="123e4567-e89b-12d3-a456-426614174000",
download_type=FileTransferType.PROJECT,
local_dir="/home/ninjamaster/QField/cloud/Tree_Survey",
filter_glob="*",
show_progress=True
)
```
"""
if not filter_glob:
filter_glob = "*"
Expand Down Expand Up @@ -898,6 +1022,16 @@ def download_file(
Returns:
The response object.
Example:
```python
client.download_file(
project_id="123e4567-e89b-12d3-a456-426614174000",
download_type=FileTransferType.PROJECT,
local_filename="/home/ninjamaster/QField/cloud/Tree_Survey/trees.gpkg",
remote_filename="trees.gpkg",
show_progress=True
)
"""

if remote_etag and local_filename.exists():
Expand Down Expand Up @@ -953,6 +1087,11 @@ def list_local_files(
"""
Returns a list of dicts with information about local files. Usually used before uploading files.
NOTE: files and dirs starting with leading dot (.) or ending in tilde (~) will be ignored.
Example:
```python
client.list_local_files("/home/ninjamaster/QField/cloud/Tree_Survey", "*.gpkg")
```
"""
if not filter_glob:
filter_glob = "*"
Expand Down Expand Up @@ -989,6 +1128,11 @@ def get_project_collaborators(self, project_id: str) -> List[CollaboratorModel]:
Returns:
The list of project collaborators.
Example:
```python
client.get_project_collaborators("123e4567-e89b-12d3-a456-426614174000")
```
"""
collaborators = cast(
List[CollaboratorModel],
Expand All @@ -1009,6 +1153,15 @@ def add_project_collaborator(
Returns:
The added project collaborator.
Example:
```python
client.add_project_collaborator(
project_id="123e4567-e89b-12d3-a456-426614174000",
username="ninja_001",
role=ProjectCollaboratorRole.EDITOR
)
```
"""
collaborator = cast(
CollaboratorModel,
Expand All @@ -1030,6 +1183,14 @@ def remove_project_collaborator(self, project_id: str, username: str) -> None:
Args:
project_id: Project ID.
username: the username of the collaborator to be removed
Example:
```python
client.remove_project_collaborator(
project_id="123e4567-e89b-12d3-a456-426614174000",
username="ninja_007"
)
```
"""
self._request("DELETE", f"/collaborators/{project_id}/{username}")

Expand All @@ -1045,6 +1206,15 @@ def patch_project_collaborators(
Returns:
The updated project collaborator.
Example:
```python
client.patch_project_collaborators(
project_id="123e4567-e89b-12d3-a456-426614174000",
username="ninja_001",
role=ProjectCollaboratorRole.MANAGER
)
```
"""
collaborator = cast(
CollaboratorModel,
Expand All @@ -1069,6 +1239,11 @@ def get_organization_members(
Returns:
The list of organization members.
Example:
```python
client.get_organization_members("My_Organization_Clan")
```
"""
members = cast(
List[OrganizationMemberModel],
Expand All @@ -1094,6 +1269,16 @@ def add_organization_member(
Returns:
The added organization member.
Example:
```python
client.add_organization_member(
organization="My_Organization_Clan",
username="ninja_001",
role=OrganizationMemberRole.MEMBER,
is_public=False
)
```
"""
member = cast(
OrganizationMemberModel,
Expand All @@ -1116,6 +1301,14 @@ def remove_organization_members(self, project_id: str, username: str) -> None:
Args:
project_id: Project ID.
username: the username of the member to be removed
Example:
```python
client.remove_organization_members(
organization="My_Organization_Clan",
username="ninja_007"
)
```
"""
self._request("DELETE", f"/members/{project_id}/{username}")

Expand All @@ -1131,6 +1324,15 @@ def patch_organization_members(
Returns:
The updated organization member.
Example:
```python
client.patch_organization_members(
organization="My_Organization_Clan",
username="ninja_001",
role=OrganizationMemberRole.ADMIN
)
```
"""
member = cast(
OrganizationMemberModel,
Expand Down

0 comments on commit 02cb0bf

Please sign in to comment.