specklia 1.9.101__py3-none-any.whl → 1.9.102__py3-none-any.whl

specklia/client.py

@@ -15,6 +15,7 @@ from shapely import MultiPolygon, Polygon, to_geojson
 from shapely.geometry import shape
 
 from specklia import chunked_transfer, utilities
+from specklia.internal_admin_client import SpeckliaInternalAdminClient
 
 if TYPE_CHECKING:
     from datetime import datetime
@@ -44,6 +45,13 @@ class Specklia:
     url : str
         The url where Specklia is running, by default the URL of the Specklia server.
 
+    Attributes
+    ----------
+    user_id : str
+        The unique ID of the user associated with this client.
+    internal_admin : SpeckliaInternalAdminClient
+        Contains endpoints only accessible to internal Specklia administrators.
+
     Examples
     --------
     To start using Specklia, we first need to navigate to https://specklia.earthwave.co.uk and follow the
@@ -59,23 +67,48 @@ class Specklia:
         >>> client = Specklia(auth_token=user_auth_token)
     """
 
+    user_id: str
+    internal_admin: SpeckliaInternalAdminClient
+
     def __init__(self: Specklia, auth_token: str, url: str = "https://specklia-api.earthwave.co.uk") -> None:
         self.server_url = url
         self.auth_token = auth_token
         self._data_streaming_timeout_s = 300
+
+        # Internal admin routes are accessed through a separate object to keep the distinction clear.
+        self.internal_admin = SpeckliaInternalAdminClient(self._request)
+
         # immediately retrieve the user's ID. This serves as a check that their API token is valid.
         self._fetch_user_id()
 
         _log.info("New Specklia client created.")
 
+    def _request(
+        self: Specklia,
+        method: Literal["GET", "POST", "PUT", "DELETE"],
+        endpoint: str,
+        params: dict | None = None,
+        json: dict | None = None,
+        data: str | None = None,
+    ) -> requests.Response:
+        response = requests.request(
+            method,
+            self.server_url + "/" + endpoint,
+            headers={"Authorization": "Bearer " + self.auth_token},
+            params=params,
+            json=json,
+            data=data,
+        )
+        _check_response_ok(response)
+        return response
+
     def _fetch_user_id(self: Specklia) -> None:
         """
         Set the client's User ID.
 
         We've separated this out for testing reasons.
         """
-        response = requests.post(self.server_url + "/users", headers={"Authorization": "Bearer " + self.auth_token})
-        _check_response_ok(response)
+        response = self._request("POST", "users")
         self.user_id = response.json()
         _log.info("fetched User ID for client, was %s", self.user_id)
 
@@ -114,12 +147,7 @@ class Specklia:
         client.delete_user_from_group(), client.add_user_to_group(), and client.update_user_privileges to make any
         desired changes.
         """
-        response = requests.get(
-            self.server_url + "/users",
-            headers={"Authorization": "Bearer " + self.auth_token},
-            params={"group_id": group_id},
-        )
-        _check_response_ok(response)
+        response = self._request("GET", "users", params={"group_id": group_id})
         _log.info("listed users within group_id %s.", group_id)
         return pd.DataFrame(response.json()).convert_dtypes()
 
@@ -220,10 +248,7 @@ class Specklia:
         }
 
         # submit the query
-        response = requests.post(
-            self.server_url + "/query", data=json.dumps(request), headers={"Authorization": "Bearer " + self.auth_token}
-        )
-        _check_response_ok(response)
+        response = self._request("POST", "query", data=json.dumps(request))
 
         _log.info("queried dataset with ID %s.", dataset_id)
 
@@ -290,9 +315,8 @@ class Specklia:
 
         You must have READ_WRITE or ADMIN permissions within the group that owns the dataset in order to do this.
 
-        Note that Ingests are temporarily restricted to those that have READ_WRITE permissions
-        within the all_users group (i.e. Specklia is read-only to the general public).
-        This restriction will be lifted once we have per-user billing in place for Specklia.
+        Note that Ingests are temporarily restricted to internal Specklia administrators (i.e. Specklia is read-only to
+        the general public). This restriction will be lifted once we have per-user billing in place for Specklia.
 
         Note that this can only be called up to 30,000 times per day for OLAP datasets - if you need to load more
         individual data files than this, ensure that you use this method on groups of files
@@ -331,17 +355,15 @@ class Specklia:
             )
             del n
 
-        response = requests.post(
-            self.server_url + "/ingest",
+        self._request(
+            "POST",
+            "ingest",
             json={
                 "dataset_id": dataset_id,
                 "new_points": upload_points,
                 "duplicate_source_behaviour": duplicate_source_behaviour,
             },
-            headers={"Authorization": "Bearer " + self.auth_token},
         )
-        _check_response_ok(response)
-
         _log.info("Added new data to specklia dataset ID %s.", dataset_id)
 
     def delete_points_in_dataset(
@@ -369,22 +391,6 @@ class Specklia:
         _log.error("this method is not yet implemented.")
         raise NotImplementedError()
 
-    def list_all_groups(self: Specklia) -> pd.DataFrame:
-        """
-        List all groups.
-
-        You must have ADMIN permissions within the special all_users group in order to do this.
-
-        Returns
-        -------
-        pd.DataFrame
-            A dataframe describing all groups
-        """
-        response = requests.get(self.server_url + "/groups", headers={"Authorization": "Bearer " + self.auth_token})
-        _check_response_ok(response)
-        _log.info("listing all groups within Specklia.")
-        return pd.DataFrame(response.json()).convert_dtypes()
-
     def create_group(self: Specklia, group_name: str) -> str:
         """
         Create a new Specklia group.
@@ -413,12 +419,7 @@ class Specklia:
         The endpoint will return the new group's unique ID, auto-generated by Specklia. We can pass this ID to other
         Specklia endpoints to modify the group, its members, and datasets.
         """
-        response = requests.post(
-            self.server_url + "/groups",
-            json={"group_name": group_name},
-            headers={"Authorization": "Bearer " + self.auth_token},
-        )
-        _check_response_ok(response)
+        response = self._request("POST", "groups", json={"group_name": group_name})
         _log.info("created new group with name %s.", group_name)
         return response.text.strip('\n"')
 
@@ -448,12 +449,11 @@ class Specklia:
 
         The group's unique ID, users, and datasets will remain unchanged.
         """
-        response = requests.put(
-            self.server_url + "/groups",
+        response = self._request(
+            "PUT",
+            "groups",
             json={"group_id": group_id, "new_group_name": new_group_name},
-            headers={"Authorization": "Bearer " + self.auth_token},
         )
-        _check_response_ok(response)
         _log.info("updated name of group ID %s to %s.", group_id, new_group_name)
         return response.text.strip('\n"')
 
@@ -482,12 +482,7 @@ class Specklia:
         The above will additionally delete any datasets owned by the group at the time of the deletion. Users within the
         group will be removed from it, but left unchanged otherwise.
         """
-        response = requests.delete(
-            self.server_url + "/groups",
-            headers={"Authorization": "Bearer " + self.auth_token},
-            params={"group_id": group_id},
-        )
-        _check_response_ok(response)
+        response = self._request("DELETE", "groups", params={"group_id": group_id})
         _log.info("deleted group ID %s", group_id)
         return response.text.strip('\n"')
 
@@ -517,10 +512,7 @@ class Specklia:
 
         We can now pass this ID to other Specklia endpoints to modify the group, its members, and datasets.
         """
-        response = requests.get(
-            self.server_url + "/groupmembership", headers={"Authorization": "Bearer " + self.auth_token}
-        )
-        _check_response_ok(response)
+        response = self._request("GET", "groupmembership")
         _log.info("listed groups that user is part of.")
         return pd.DataFrame(response.json()).convert_dtypes()
 
@@ -560,12 +552,11 @@ class Specklia:
         able to write to the group's datasets or manage users within the group, we can update their privileges via
         client.update_user_privileges().
         """
-        response = requests.post(
-            self.server_url + "/groupmembership",
+        response = self._request(
+            "POST",
+            "groupmembership",
             json={"group_id": group_id, "user_to_add_id": user_to_add_id},
-            headers={"Authorization": "Bearer " + self.auth_token},
         )
-        _check_response_ok(response)
         _log.info("added user ID %s to group ID %s", user_to_add_id, group_id)
         return response.text.strip('\n"')
 
@@ -621,12 +612,11 @@ class Specklia:
 
         We should always aim to grant users the lowest privileges necessary.
         """
-        response = requests.put(
-            self.server_url + "/groupmembership",
+        response = self._request(
+            "PUT",
+            "groupmembership",
             json={"group_id": group_id, "user_to_update_id": user_to_update_id, "new_privileges": new_privileges},
-            headers={"Authorization": "Bearer " + self.auth_token},
         )
-        _check_response_ok(response)
         _log.info(
             "Updated user ID %s privileges to %s within group ID %s.", user_to_update_id, new_privileges, group_id
         )
@@ -665,12 +655,11 @@ class Specklia:
             >>> client.delete_user_group_group(group_id=DETERMINED_GROUP_ID, user_to_delete_id=DETERMINED_USER_ID)
 
         """
-        response = requests.delete(
-            self.server_url + "/groupmembership",
-            headers={"Authorization": "Bearer " + self.auth_token},
+        response = self._request(
+            "DELETE",
+            "groupmembership",
             params={"group_id": group_id, "user_to_delete_id": user_to_delete_id},
         )
-        _check_response_ok(response)
         _log.info("Deleted user ID %s from group ID %s.", user_to_delete_id, group_id)
         return response.text.strip('\n"')
 
@@ -805,17 +794,16 @@ class Specklia:
             _log.warning(message)
             warnings.warn(message, stacklevel=1)
 
-        response = requests.post(
-            self.server_url + "/metadata",
+        response = self._request(
+            "POST",
+            "metadata",
             json={
                 "dataset_name": dataset_name,
                 "description": description,
                 "columns": columns,
                 "storage_technology": storage_technology,
             },
-            headers={"Authorization": "Bearer " + self.auth_token},
         )
-        _check_response_ok(response)
         _log.info("Created a new dataset with name '%s'", dataset_name)
         return response.text.strip('\n"')
 
@@ -860,12 +848,11 @@ class Specklia:
             ...                                 group_id=important_group_id)
 
         """
-        response = requests.put(
-            self.server_url + "/metadata",
+        response = self._request(
+            "PUT",
+            "metadata",
             json={"dataset_id": dataset_id, "new_owning_group_id": new_owning_group_id},
-            headers={"Authorization": "Bearer " + self.auth_token},
         )
-        _check_response_ok(response)
         _log.info("set owning group for dataset ID %s to group ID %s", dataset_id, new_owning_group_id)
         return response.text.strip('\n"')
 
@@ -895,12 +882,7 @@ class Specklia:
         Specklia will respond with a success message as long as the dataset exists and we are an ADMIN within the
         group that owns it.
         """
-        response = requests.delete(
-            self.server_url + "/metadata",
-            params={"dataset_id": dataset_id},
-            headers={"Authorization": "Bearer " + self.auth_token},
-        )
-        _check_response_ok(response)
+        response = self._request("DELETE", "metadata", params={"dataset_id": dataset_id})
         _log.info("Deleted dataset with ID %s", dataset_id)
         return response.text.strip('\n"')
 
@@ -939,12 +921,7 @@ class Specklia:
         Example usage:
             >>> client.report_usage(dataset_id="GROUP_IP")
         """
-        response = requests.get(
-            self.server_url + "/usage",
-            params={"group_id": group_id},
-            headers={"Authorization": "Bearer " + self.auth_token},
-        )
-        _check_response_ok(response)
+        response = self._request("GET", "usage", params={"group_id": group_id})
         _log.info("Usage report queried for group_id %s", group_id)
         return response.json()
 

specklia/internal_admin_client.py

@@ -0,0 +1,74 @@
+"""Specklia internal admin client module."""
+
+import logging
+from typing import Callable, Literal, Self
+
+import pandas as pd
+import requests
+
+_log = logging.getLogger(__name__)
+
+
+class SpeckliaInternalAdminClient:
+    """Specklia client for endpoints only accessible to internal Specklia administrators.
+
+    Parameters
+    ----------
+    specklia_request : Callable
+        The function to use to make requests to Specklia internal admin endpoints.
+    """
+
+    def __init__(
+        self: Self,
+        specklia_request: Callable,
+    ) -> None:
+        self._specklia_request = specklia_request
+
+    def _request(
+        self: Self,
+        method: Literal["GET", "POST", "PUT", "DELETE"],
+        endpoint: str,
+        params: dict | None = None,
+        json: dict | None = None,
+        data: str | None = None,
+    ) -> requests.Response:
+        return self._specklia_request(
+            method=method,
+            endpoint=endpoint,
+            params=params,
+            json=json,
+            data=data,
+        )
+
+    def list_all_groups(self: Self) -> pd.DataFrame:
+        """
+        List all groups.
+
+        Returns
+        -------
+        pd.DataFrame
+            A dataframe describing all groups
+        """
+        response = self._request("GET", "groups")
+        _log.info("listing all groups within Specklia.")
+        return pd.DataFrame(response.json()).convert_dtypes()
+
+    def generate_user_api_key(self: Self, user_id: str) -> dict[str, str]:
+        """
+        Generate an API key for a user, creating the user if they do not already exist.
+
+        This will create the user if they do not already exist, and will replace any existing API key if present.
+
+        Parameters
+        ----------
+        user_id : str
+            The ID of the user to generate an API key for.
+
+        Returns
+        -------
+        dict[str, str]
+            A dictionary containing the `user_id` and the generated `token`.
+        """
+        response = self._request("PUT", "generate_user_api_key/" + user_id)
+        _log.info("Generated API key for user ID %s.", user_id)
+        return response.json()

{specklia-1.9.101.dist-info → specklia-1.9.102.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: specklia
-Version: 1.9.101
+Version: 1.9.102
 Summary: Python client for Specklia, a geospatial point cloud database by Earthwave.
 Home-page: https://specklia.earthwave.co.uk/
 Author: Earthwave Ltd

specklia-1.9.102.dist-info/RECORD

@@ -0,0 +1,10 @@
+specklia/__init__.py,sha256=ePVHqq642NocoE8tS0cNTd0B5wJdUB7r3y815oQXD6A,51
+specklia/chunked_transfer.py,sha256=pTm-x5Vwy9YtVTXcV7i0cYAo1LaSA_3qr1Of16R1u40,7732
+specklia/client.py,sha256=oHL0-MbKoj9qMBKZOii_xEkby-RPPSjoZkPK6peNk3Q,40828
+specklia/internal_admin_client.py,sha256=w3OyXjlWPivgd5lOmnISc6B6rjLbkGoRtmd2kO7lelA,2127
+specklia/utilities.py,sha256=AjgDOM_UTDCY1QTb0yv83qXVuLSwi_CDKGs0vWen1oM,5087
+specklia-1.9.102.dist-info/LICENCE,sha256=kjWTA-TtT_rJtsWuAgWvesvu01BytVXgt_uCbeQgjOg,1061
+specklia-1.9.102.dist-info/METADATA,sha256=oHwCA1PqL7e1QgT3QErJXfCPARZ8AMo50jPQr5F5jg0,3083
+specklia-1.9.102.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+specklia-1.9.102.dist-info/top_level.txt,sha256=XgU53UpAJbqEni5EjJaPdQPYuNx16Geg2I5A9lo1BQw,9
+specklia-1.9.102.dist-info/RECORD,,

specklia-1.9.101.dist-info/RECORD

@@ -1,9 +0,0 @@
-specklia/__init__.py,sha256=ePVHqq642NocoE8tS0cNTd0B5wJdUB7r3y815oQXD6A,51
-specklia/chunked_transfer.py,sha256=pTm-x5Vwy9YtVTXcV7i0cYAo1LaSA_3qr1Of16R1u40,7732
-specklia/client.py,sha256=6JYcjSpKtg_Lu2VnXAPwUuQuqUQF0ShvSuQU5Mk-p8c,42173
-specklia/utilities.py,sha256=AjgDOM_UTDCY1QTb0yv83qXVuLSwi_CDKGs0vWen1oM,5087
-specklia-1.9.101.dist-info/LICENCE,sha256=kjWTA-TtT_rJtsWuAgWvesvu01BytVXgt_uCbeQgjOg,1061
-specklia-1.9.101.dist-info/METADATA,sha256=Lm0Jf8dRPvUaXlwPM32ogrp2SH291mZSniB0t5ceWWo,3083
-specklia-1.9.101.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-specklia-1.9.101.dist-info/top_level.txt,sha256=XgU53UpAJbqEni5EjJaPdQPYuNx16Geg2I5A9lo1BQw,9
-specklia-1.9.101.dist-info/RECORD,,