specklia 1.9.65__py3-none-any.whl → 1.9.67__py3-none-any.whl

specklia/chunked_transfer.py

@@ -20,25 +20,24 @@ IMPORTANT: THE VERSION HERE IN THE SPECKLIA PACKAGE MUST NOT BE MADE DEPENDENT U
 IS PRIVATE BUT THIS PACKAGE IS PUBLIC!
 """
 
+import struct
+import time
 from enum import Enum
 from io import BytesIO
 from logging import Logger
-import struct
-import time
 from typing import List, Tuple, Union
 
+import requests
 from geopandas import GeoDataFrame
 from geopandas import read_feather as read_geofeather
-from pandas import DataFrame
-from pandas import read_feather
-import requests
+from pandas import DataFrame, read_feather
 
 log = Logger(__name__)
 
 CHUNK_DB_NAME = "data_transfer_chunks"
 CHUNK_METADATA_COLLECTION_NAME = "chunk_metadata"
 MAX_CHUNK_AGE_SECONDS = 3600
-MAX_CHUNK_SIZE_BYTES = 5 * 1024 ** 2  # must be small enough to fit into an HTTP GET Request
+MAX_CHUNK_SIZE_BYTES = 5 * 1024**2  # must be small enough to fit into an HTTP GET Request
 CHUNK_DOWNLOAD_RETRIES = 10
 CHUNK_DOWNLOAD_TIMEOUT_S = 10
 
@@ -74,19 +73,16 @@ def upload_chunks(api_address: str, chunks: List[Tuple[int, bytes]]) -> str:
         The chunk set uuid of the uploaded chunks
     """
     # post the first chunk to start the upload
-    response = requests.post(
-        api_address + f"/chunk/upload/{chunks[0][0]}-of-{len(chunks)}",
-        data=chunks[0][1])
+    response = requests.post(api_address + f"/chunk/upload/{chunks[0][0]}-of-{len(chunks)}", data=chunks[0][1])
     response.raise_for_status()
-    log.info("response from very first /chunk/upload was '%s'", response.json())
-    chunk_set_uuid = response.json()['chunk_set_uuid']
+    log.debug("response from very first /chunk/upload was '%s'", response.json())
+    chunk_set_uuid = response.json()["chunk_set_uuid"]
 
     # post the rest of the chunks in a random order
     for i, chunk in chunks[1:]:
-        response = requests.post(
-            api_address + f"/chunk/upload/{chunk_set_uuid}/{i}-of-{len(chunks)}", data=chunk)
+        response = requests.post(api_address + f"/chunk/upload/{chunk_set_uuid}/{i}-of-{len(chunks)}", data=chunk)
         response.raise_for_status()
-        log.info("response from subsequent /chunk/upload/uuid call was '%s'", response.text)
+        log.debug("response from subsequent /chunk/upload/uuid call was '%s'", response.text)
 
     return chunk_set_uuid
 
@@ -123,31 +119,29 @@ def download_chunks(api_address: str, chunk_set_uuid: str, num_chunks: int) -> b
         while retries < CHUNK_DOWNLOAD_RETRIES and not success:
             try:
                 this_chunk_response = requests.get(
-                    f"{api_address}/chunk/download/{chunk_set_uuid}/{chunk_ordinal}",
-                    timeout=CHUNK_DOWNLOAD_TIMEOUT_S
+                    f"{api_address}/chunk/download/{chunk_set_uuid}/{chunk_ordinal}", timeout=CHUNK_DOWNLOAD_TIMEOUT_S
                 )
                 this_chunk_response.raise_for_status()
-                ordinal = struct.unpack('i', this_chunk_response.content[:4])[0]
+                ordinal = struct.unpack("i", this_chunk_response.content[:4])[0]
                 chunk = this_chunk_response.content[4:]
-                assert ordinal == chunk_ordinal, (
-                    f"Chunk ordinal mismatch: expected {chunk_ordinal}, got {ordinal}")
+                assert ordinal == chunk_ordinal, f"Chunk ordinal mismatch: expected {chunk_ordinal}, got {ordinal}"
                 chunks.append(chunk)
                 success = True
             except (requests.Timeout, requests.ConnectionError) as e:
                 retries += 1
-                log.warning(
-                    "Request failed with %s. Retrying (%s/%s)...", e, retries, CHUNK_DOWNLOAD_RETRIES)
+                log.warning("Request failed with %s. Retrying (%s/%s)...", e, retries, CHUNK_DOWNLOAD_RETRIES)
                 time.sleep(1)  # Small backoff before retrying
         if not success:
             error_message = (
-                f"Failed to download from chunk set {chunk_set_uuid} after {CHUNK_DOWNLOAD_TIMEOUT_S} attempts.")
+                f"Failed to download from chunk set {chunk_set_uuid} after {CHUNK_DOWNLOAD_TIMEOUT_S} attempts."
+            )
             log.error(error_message)
             raise RuntimeError(error_message)
 
     # Let the server know that we are done with this data and it can be deleted.
-    requests.delete(f'{api_address}/chunk/delete/{chunk_set_uuid}')
+    requests.delete(f"{api_address}/chunk/delete/{chunk_set_uuid}")
 
-    return b''.join(chunks)
+    return b"".join(chunks)
 
 
 def split_into_chunks(data: bytes, chunk_size: int = MAX_CHUNK_SIZE_BYTES) -> List[Tuple[int, bytes]]:
@@ -166,8 +160,7 @@ def split_into_chunks(data: bytes, chunk_size: int = MAX_CHUNK_SIZE_BYTES) -> Li
     List[Tuple[int, bytes]]
         A list of tuples containing the ordinal number of the chunk and each chunk
     """
-    return list(
-        enumerate((data[i:i + chunk_size] for i in range(0, len(data), chunk_size)), start=1))
+    return list(enumerate((data[i : i + chunk_size] for i in range(0, len(data), chunk_size)), start=1))
 
 
 def deserialise_dataframe(data: bytes) -> Union[DataFrame, GeoDataFrame]:
@@ -211,7 +204,7 @@ def serialise_dataframe(df: Union[DataFrame, GeoDataFrame]) -> bytes:
 
     Parameters
     ----------
-    df : DataFrame
+    df: Union[DataFrame, GeoDataFrame]
         Input dataframe
 
     Returns
@@ -221,6 +214,6 @@ def serialise_dataframe(df: Union[DataFrame, GeoDataFrame]) -> bytes:
     """
     feather_buffer = BytesIO()
     # Browser implementations of feather do not support compressed feather formats.
-    df.to_feather(feather_buffer, compression='uncompressed')
+    df.to_feather(feather_buffer, compression="uncompressed")
     feather_buffer.seek(0)
     return feather_buffer.getvalue()

specklia/client.py

@@ -1,21 +1,25 @@
-"""This file contains the Specklia python client. It is designed to talk to the Specklia webservice."""
+"""File contains the Specklia python client. It is designed to talk to the Specklia webservice."""
+
 from __future__ import annotations
 
-from datetime import datetime
 import json
 import logging
-from typing import cast, Dict, List, Literal, Optional, Tuple, Union
 import warnings
+from typing import TYPE_CHECKING, Dict, List, Literal, Optional, Tuple, Union, cast
 
-from dateutil import parser
 import geopandas as gpd
 import pandas as pd
 import requests
+from dateutil import parser
 from shapely import MultiPolygon, Polygon, to_geojson
 from shapely.geometry import shape
 
 from specklia import chunked_transfer, utilities
-from specklia.utilities import NewPoints
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+    from specklia.utilities import NewPoints
 
 _log = logging.getLogger(__name__)
 
@@ -26,49 +30,43 @@ class Specklia:
 
     Specklia is a geospatial point cloud database designed for Academic use.
     Further details are available at https://specklia.earthwave.co.uk.
-    """
 
-    def __init__(
-            self: Specklia,
-            auth_token: str,
-            url: str = 'https://specklia-api.earthwave.co.uk') -> None:
-        """
-        Create a new Specklia client object.
+    This object is a Python client for connecting to Specklia's API.
 
-        This object is a Python client for connecting to Specklia's API.
+    Giving the value of this object's user_id to another user will allow them to add you to private groups.
+    Please quote your user_id when contacting support@earthwave.co.uk.
 
-        Giving the value of this object's user_id to another user will allow them to add you to private groups.
-        Please quote your user_id when contacting support@earthwave.co.uk.
+    Parameters
+    ----------
+    auth_token : str
+        The authentication token to use to authorise calls to Specklia.
+        Obtained via https://specklia.earthwave.co.uk.
+    url : str
+        The url where Specklia is running, by default the URL of the Specklia server.
 
-        Parameters
-        ----------
-        auth_token : str
-            The authentication token to use to authorise calls to Specklia.
-            Obtained via https://specklia.earthwave.co.uk.
-        url : str
-            The url where Specklia is running, by default the URL of the Specklia server.
+    Examples
+    --------
+    To start using Specklia, we first need to navigate to https://specklia.earthwave.co.uk and follow the
+    instructions to generate a Specklia API key.
 
-        Examples
-        --------
-        To start using Specklia, we first need to navigate to https://specklia.earthwave.co.uk and follow the
-        instructions to generate a Specklia API key.
+    The key should then be kept somewhere safe where only we can access it, and needs to be passed each time we
+    instantiate our Specklia client.
 
-        The key should then be kept somewhere safe where only we can access it, and needs to be passed each time we
-        instantiate our Specklia client.
+    If we save our key to a file, we can then utilise it as such::
 
-        If we save our key to a file, we can then utilise it as such::
+        >>> with open("our_auth_token.jwt") as fh:
+        ...     user_auth_token = fh.read()
+        >>> client = Specklia(auth_token=user_auth_token)
+    """
 
-            >>> with open("our_auth_token.jwt") as fh:
-            ...     user_auth_token = fh.read()
-            >>> client = Specklia(auth_token=user_auth_token)
-        """
+    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
         # 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.')
+        _log.info("New Specklia client created.")
 
     def _fetch_user_id(self: Specklia) -> None:
         """
@@ -76,12 +74,10 @@ class Specklia:
 
         We've separated this out for testing reasons.
         """
-        response = requests.post(
-            self.server_url + "/users",
-            headers={"Authorization": "Bearer " + self.auth_token})
+        response = requests.post(self.server_url + "/users", headers={"Authorization": "Bearer " + self.auth_token})
         _check_response_ok(response)
         self.user_id = response.json()
-        _log.info('fetched User ID for client, was %s', self.user_id)
+        _log.info("fetched User ID for client, was %s", self.user_id)
 
     def list_users(self: Specklia, group_id: str) -> pd.DataFrame:
         """
@@ -121,17 +117,22 @@ class Specklia:
         response = requests.get(
             self.server_url + "/users",
             headers={"Authorization": "Bearer " + self.auth_token},
-            params={'group_id': group_id})
+            params={"group_id": group_id},
+        )
         _check_response_ok(response)
-        _log.info('listed users within group_id %s.', group_id)
+        _log.info("listed users within group_id %s.", group_id)
         return pd.DataFrame(response.json()).convert_dtypes()
 
-    def query_dataset(  # noqa: CFQ002
-            self: Specklia, dataset_id: str, epsg4326_polygon: Union[Polygon, MultiPolygon],
-            min_datetime: datetime, max_datetime: datetime,
-            columns_to_return: Optional[List[str]] = None,
-            additional_filters: Optional[List[Dict[str, Union[float, str]]]] = None,
-            source_information_only: bool = False) -> Tuple[gpd.GeoDataFrame, List[Dict]]:
+    def query_dataset(
+        self: Specklia,
+        dataset_id: str,
+        epsg4326_polygon: Union[Polygon, MultiPolygon],
+        min_datetime: datetime,
+        max_datetime: datetime,
+        columns_to_return: Optional[List[str]] = None,
+        additional_filters: Optional[List[Dict[str, Union[float, str]]]] = None,
+        source_information_only: bool = False,
+    ) -> Tuple[gpd.GeoDataFrame, List[Dict]]:
         """
         Query data within a dataset.
 
@@ -209,44 +210,45 @@ class Specklia:
         # note the use of json.loads() here, so effectively converting the geojson
         # back into a dictionary of JSON-compatible types to avoid "double-JSONing" it.
         request = {
-            'dataset_id': dataset_id,
-            'min_timestamp': int(min_datetime.timestamp()),
-            'max_timestamp': int(max_datetime.timestamp()),
-            'epsg4326_search_area': json.loads(to_geojson(epsg4326_polygon)),
-            'columns_to_return': [] if columns_to_return is None else columns_to_return,
-            'additional_filters': [] if additional_filters is None else additional_filters,
-            'source_information_only': source_information_only}
+            "dataset_id": dataset_id,
+            "min_timestamp": int(min_datetime.timestamp()),
+            "max_timestamp": int(max_datetime.timestamp()),
+            "epsg4326_search_area": json.loads(to_geojson(epsg4326_polygon)),
+            "columns_to_return": [] if columns_to_return is None else columns_to_return,
+            "additional_filters": [] if additional_filters is None else additional_filters,
+            "source_information_only": source_information_only,
+        }
 
         # submit the query
         response = requests.post(
-            self.server_url + '/query',
-            data=json.dumps(request),
-            headers={"Authorization": "Bearer " + self.auth_token})
+            self.server_url + "/query", data=json.dumps(request), headers={"Authorization": "Bearer " + self.auth_token}
+        )
         _check_response_ok(response)
 
-        _log.info('queried dataset with ID %s.', dataset_id)
+        _log.info("queried dataset with ID %s.", dataset_id)
 
         response_dict = response.json()
 
         # stream and deserialise the results
-        if response_dict['num_chunks'] > 0:
+        if response_dict["num_chunks"] > 0:
             gdf = chunked_transfer.deserialise_dataframe(
                 chunked_transfer.download_chunks(
                     self.server_url,
-                    response_dict['chunk_set_uuid'],
-                    response_dict['num_chunks'],
+                    response_dict["chunk_set_uuid"],
+                    response_dict["num_chunks"],
                 )
             )
         else:
             gdf = gpd.GeoDataFrame()
 
         # perform some light deserialisation of sources for backwards compatibility.
-        sources = utilities.deserialise_sources(response_dict['sources'])
+        sources = utilities.deserialise_sources(response_dict["sources"])
 
-        return cast(gpd.GeoDataFrame, gdf), cast(list[dict], sources)
+        return cast("gpd.GeoDataFrame", gdf), cast("list[dict]", sources)
 
     def update_points_in_dataset(
-            self: Specklia, _dataset_id: str, _new_points: pd.DataFrame, _source_description: Dict) -> None:
+        self: Specklia, _dataset_id: str, _new_points: pd.DataFrame, _source_description: Dict
+    ) -> None:
         """
         Update previously existing data within a dataset.
 
@@ -254,7 +256,7 @@ class Specklia:
         Should be called once for each separate source of data.
 
         Parameters
-        ------
+        ----------
         _dataset_id : str
             The UUID of the dataset to update.
         _new_points : pd.DataFrame
@@ -270,12 +272,15 @@ class Specklia:
         NotImplementedError
             This route is not yet implemented.
         """
-        _log.error('this method is not yet implemented.')
+        _log.error("this method is not yet implemented.")
         raise NotImplementedError()
 
     def add_points_to_dataset(
-            self: Specklia, dataset_id: str, new_points: List[NewPoints],
-            duplicate_source_behaviour: Literal['error', 'ignore', 'replace', 'merge'] = 'error') -> None:
+        self: Specklia,
+        dataset_id: str,
+        new_points: List[NewPoints],
+        duplicate_source_behaviour: Literal["error", "ignore", "replace", "merge"] = "error",
+    ) -> None:
         """
         Add new data to a dataset.
 
@@ -297,7 +302,7 @@ class Specklia:
         ----------
         dataset_id : str
             The UUID of the dataset to add data to.
-        new_points : List[Dict[str, Union[Dict, gpd.GeoDataFrame]]]
+        new_points : List[NewPoints]
             A list of dictionaries with the keys 'source' and 'gdf'. Within each dictionary, the value for 'source'
             is a dictionary describing the source of the data.
             The value for 'gdf' is a GeoDataFrame containing the points to add to the dataset.
@@ -315,32 +320,33 @@ class Specklia:
         # serialise and upload each dataframe
         upload_points = []
         for n in new_points:
-            chunks = chunked_transfer.split_into_chunks(
-                chunked_transfer.serialise_dataframe(n['gdf']))
-            chunk_set_uuid = chunked_transfer.upload_chunks(
-                self.server_url, chunks)
-            upload_points.append({
-                'source': n['source'],
-                'chunk_set_uuid': chunk_set_uuid,
-                'num_chunks': len(chunks),
-            })
+            chunks = chunked_transfer.split_into_chunks(chunked_transfer.serialise_dataframe(n["gdf"]))
+            chunk_set_uuid = chunked_transfer.upload_chunks(self.server_url, chunks)
+            upload_points.append(
+                {
+                    "source": n["source"],
+                    "chunk_set_uuid": chunk_set_uuid,
+                    "num_chunks": len(chunks),
+                }
+            )
             del n
 
         response = requests.post(
             self.server_url + "/ingest",
             json={
-                'dataset_id': dataset_id,
-                'new_points': upload_points,
-                'duplicate_source_behaviour': duplicate_source_behaviour,
+                "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)
+        _log.info("Added new data to specklia dataset ID %s.", dataset_id)
 
     def delete_points_in_dataset(
-            self: Specklia, _dataset_id: str, _source_ids_and_source_row_ids_to_delete: List[Tuple[str, str]]) -> None:
+        self: Specklia, _dataset_id: str, _source_ids_and_source_row_ids_to_delete: List[Tuple[str, str]]
+    ) -> None:
         """
         Delete data from a dataset.
 
@@ -360,7 +366,7 @@ class Specklia:
         NotImplementedError
             This route is not yet implemented.
         """
-        _log.error('this method is not yet implemented.')
+        _log.error("this method is not yet implemented.")
         raise NotImplementedError()
 
     def list_all_groups(self: Specklia) -> pd.DataFrame:
@@ -374,10 +380,9 @@ class Specklia:
         pd.DataFrame
             A dataframe describing all groups
         """
-        response = requests.get(
-            self.server_url + "/groups", headers={"Authorization": "Bearer " + self.auth_token})
+        response = requests.get(self.server_url + "/groups", headers={"Authorization": "Bearer " + self.auth_token})
         _check_response_ok(response)
-        _log.info('listing all groups within Specklia.')
+        _log.info("listing all groups within Specklia.")
         return pd.DataFrame(response.json()).convert_dtypes()
 
     def create_group(self: Specklia, group_name: str) -> str:
@@ -408,10 +413,13 @@ 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})
+        response = requests.post(
+            self.server_url + "/groups",
+            json={"group_name": group_name},
+            headers={"Authorization": "Bearer " + self.auth_token},
+        )
         _check_response_ok(response)
-        _log.info('created new group with name %s.', group_name)
+        _log.info("created new group with name %s.", group_name)
         return response.text.strip('\n"')
 
     def update_group_name(self: Specklia, group_id: str, new_group_name: str) -> str:
@@ -442,10 +450,11 @@ class Specklia:
         """
         response = requests.put(
             self.server_url + "/groups",
-            json={'group_id': group_id, 'new_group_name': new_group_name},
-            headers={"Authorization": "Bearer " + self.auth_token})
+            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)
+        _log.info("updated name of group ID %s to %s.", group_id, new_group_name)
         return response.text.strip('\n"')
 
     def delete_group(self: Specklia, group_id: str) -> str:
@@ -474,10 +483,12 @@ class Specklia:
         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})
+            self.server_url + "/groups",
+            headers={"Authorization": "Bearer " + self.auth_token},
+            params={"group_id": group_id},
+        )
         _check_response_ok(response)
-        _log.info('deleted group ID %s', group_id)
+        _log.info("deleted group ID %s", group_id)
         return response.text.strip('\n"')
 
     def list_groups(self: Specklia) -> pd.DataFrame:
@@ -507,9 +518,10 @@ 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})
+            self.server_url + "/groupmembership", headers={"Authorization": "Bearer " + self.auth_token}
+        )
         _check_response_ok(response)
-        _log.info('listed groups that user is part of.')
+        _log.info("listed groups that user is part of.")
         return pd.DataFrame(response.json()).convert_dtypes()
 
     def add_user_to_group(self: Specklia, user_to_add_id: str, group_id: str) -> str:
@@ -548,11 +560,13 @@ 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",
-                                 json={'group_id': group_id, "user_to_add_id": user_to_add_id},
-                                 headers={"Authorization": "Bearer " + self.auth_token})
+        response = requests.post(
+            self.server_url + "/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)
+        _log.info("added user ID %s to group ID %s", user_to_add_id, group_id)
         return response.text.strip('\n"')
 
     def update_user_privileges(self: Specklia, group_id: str, user_to_update_id: str, new_privileges: str) -> str:
@@ -609,13 +623,13 @@ class Specklia:
         """
         response = requests.put(
             self.server_url + "/groupmembership",
-            json={'group_id': group_id,
-                  "user_to_update_id": user_to_update_id,
-                  'new_privileges': new_privileges},
-            headers={"Authorization": "Bearer " + self.auth_token})
+            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)
+        _log.info(
+            "Updated user ID %s privileges to %s within group ID %s.", user_to_update_id, new_privileges, group_id
+        )
         return response.text.strip('\n"')
 
     def delete_user_from_group(self: Specklia, group_id: str, user_to_delete_id: str) -> str:
@@ -652,10 +666,12 @@ class Specklia:
 
         """
         response = requests.delete(
-            self.server_url + "/groupmembership", headers={"Authorization": "Bearer " + self.auth_token},
-            params={'group_id': group_id, "user_to_delete_id": user_to_delete_id})
+            self.server_url + "/groupmembership",
+            headers={"Authorization": "Bearer " + self.auth_token},
+            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)
+        _log.info("Deleted user ID %s from group ID %s.", user_to_delete_id, group_id)
         return response.text.strip('\n"')
 
     def list_datasets(self: Specklia) -> pd.DataFrame:
@@ -669,27 +685,32 @@ class Specklia:
         pd.DataFrame
             A dataframe describing the datasets that the user can read.
         """
-        response = requests.get(
-            self.server_url + "/metadata", headers={"Authorization": "Bearer " + self.auth_token}
-        )
+        response = requests.get(self.server_url + "/metadata", headers={"Authorization": "Bearer " + self.auth_token})
         _check_response_ok(response)
-        _log.info('listed Specklia datasets that the current user can read.')
+        _log.info("listed Specklia datasets that the current user can read.")
 
         datasets_df = pd.DataFrame(response.json())
         # now convert the timestamps and polygons to appropriate dtypes
         for column in datasets_df.columns:
-            if 'timestamp' in column:
+            if "timestamp" in column:
                 datasets_df[column] = datasets_df[column].apply(
-                    lambda x: parser.parse(x, ignoretz=True) if x is not None else None)
-            if column == 'epsg4326_coverage':
+                    lambda x: parser.parse(x, ignoretz=True) if x is not None else None
+                )
+            if column == "epsg4326_coverage":
                 datasets_df[column] = gpd.GeoSeries(
-                    datasets_df[column].apply(lambda x: shape(x) if x is not None else None), crs=4326)  # type: ignore
+                    datasets_df[column].apply(lambda x: shape(x) if x is not None else None),  # type: ignore
+                    crs=4326,
+                )
 
         return datasets_df.convert_dtypes()  # convert the rest of the dtypes to pandas' best guest
 
     def create_dataset(
-            self: Specklia, dataset_name: str, description: str,
-            columns: Optional[List[Dict[str, str]]] = None, storage_technology: str = 'OLAP') -> str:
+        self: Specklia,
+        dataset_name: str,
+        description: str,
+        columns: Optional[List[Dict[str, str]]] = None,
+        storage_technology: str = "OLAP",
+    ) -> str:
         """
         Create a dataset.
 
@@ -705,14 +726,14 @@ class Specklia:
         personal group using Specklia.add_user_to_group().
 
         Parameters
-        ---------
+        ----------
         dataset_name : str
             The name the user provides for the dataset.
             Must contain alphanumeric characters, spaces, underscores and hyphens only.
         description : str
             A description of the dataset.
             Must contain alphanumeric characters, spaces, underscores and hyphens only.
-        columns : Optional[List[Dict[str, str]]],
+        columns : Optional[List[Dict[str, str]]]
             A list where each item is an additional column the user wishes to add to the dataset,
             beyond the mandatory EPSG4326 latitude, longitude and POSIX timestamp.
             A list of columns should follow the format::
@@ -773,27 +794,32 @@ class Specklia:
         If nothing is passed to the optional parameter 'columns', the created dataset will only have three columns: lat,
         long, and time.
         """
-        if columns and any(x in ['lat', 'lon', 'long', 'latitude', 'longitude', 'timestamp', 'posix']
-                           for x in [col['name'].lower() for col in columns]):
-            message = ("Please refrain from creating explicit EPSG4326 or POSIX timestamp columns "
-                       "as these are repetitious of Specklia's default columns.")
+        if columns and any(
+            x in ["lat", "lon", "long", "latitude", "longitude", "timestamp", "posix"]
+            for x in [col["name"].lower() for col in columns]
+        ):
+            message = (
+                "Please refrain from creating explicit EPSG4326 or POSIX timestamp columns "
+                "as these are repetitious of Specklia's default columns."
+            )
             _log.warning(message)
             warnings.warn(message, stacklevel=1)
 
         response = requests.post(
             self.server_url + "/metadata",
-            json={'dataset_name': dataset_name,
-                  'description': description,
-                  'columns': columns,
-                  'storage_technology': storage_technology},
-            headers={"Authorization": "Bearer " + self.auth_token}
+            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"')
 
-    def update_dataset_ownership(
-            self: Specklia, dataset_id: str, new_owning_group_id: str) -> str:
+    def update_dataset_ownership(self: Specklia, dataset_id: str, new_owning_group_id: str) -> str:
         """
         Transfer the ownership of a dataset to a different Specklia group.
 
@@ -801,7 +827,7 @@ class Specklia:
         which you wish to transfer the dataset in order to do this.
 
         Parameters
-        ---------
+        ----------
         dataset_id : str
             The UUID of the dataset the user wishes to update
         new_owning_group_id : str
@@ -836,12 +862,11 @@ class Specklia:
         """
         response = requests.put(
             self.server_url + "/metadata",
-            json={'dataset_id': dataset_id,
-                  'new_owning_group_id': new_owning_group_id},
-            headers={"Authorization": "Bearer " + self.auth_token}
+            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)
+        _log.info("set owning group for dataset ID %s to group ID %s", dataset_id, new_owning_group_id)
         return response.text.strip('\n"')
 
     def delete_dataset(self: Specklia, dataset_id: str) -> str:
@@ -851,7 +876,7 @@ class Specklia:
         You must be an ADMIN of the group that owns the dataset in order to do this.
 
         Parameters
-        ---------
+        ----------
         dataset_id : str
             The UUID of the dataset the user wishes to delete
 
@@ -872,11 +897,11 @@ class Specklia:
         """
         response = requests.delete(
             self.server_url + "/metadata",
-            params={'dataset_id': dataset_id},
-            headers={"Authorization": "Bearer " + self.auth_token}
+            params={"dataset_id": dataset_id},
+            headers={"Authorization": "Bearer " + self.auth_token},
         )
         _check_response_ok(response)
-        _log.info('Deleted dataset with ID %s', dataset_id)
+        _log.info("Deleted dataset with ID %s", dataset_id)
         return response.text.strip('\n"')
 
     def report_usage(self: Specklia, group_id: str) -> List[Dict]:
@@ -916,11 +941,11 @@ class Specklia:
         """
         response = requests.get(
             self.server_url + "/usage",
-            params={'group_id': group_id},
-            headers={"Authorization": "Bearer " + self.auth_token}
+            params={"group_id": group_id},
+            headers={"Authorization": "Bearer " + self.auth_token},
         )
         _check_response_ok(response)
-        _log.info('Usage report queried for group_id %s', group_id)
+        _log.info("Usage report queried for group_id %s", group_id)
         return response.json()
 
 
@@ -946,11 +971,14 @@ def _check_response_ok(response: requests.Response) -> None:
         except requests.exceptions.JSONDecodeError:
             response_content = response.text
         if "The request was aborted because there was no available instance" in response_content:
-            no_instances_message = 'Specklia is over capacity. Additional resources are being '\
-                'brought online, please try again in one minute.'
+            no_instances_message = (
+                "Specklia is over capacity. Additional resources are being "
+                "brought online, please try again in one minute."
+            )
             _log.error(no_instances_message)
-            raise RuntimeError(no_instances_message)
+            raise RuntimeError(no_instances_message) from err
         else:
-            _log.error('Failed to interact with Specklia server, error was: %s, %s', str(err), response_content)
+            _log.error("Failed to interact with Specklia server, error was: %s, %s", str(err), response_content)
             raise RuntimeError(
-                f"Failed to interact with Specklia server, error was: {str(err)}, {response_content}") from None
+                f"Failed to interact with Specklia server, error was: {err!s}, {response_content}"
+            ) from None

specklia/utilities.py

@@ -1,7 +1,8 @@
-"""This file contains client-side utilities provided to make it easier to use Specklia."""
-from datetime import datetime
+"""File contains client-side utilities provided to make it easier to use Specklia."""
+
 import os
-from typing import Dict, List, Optional, TypedDict
+from datetime import datetime
+from typing import Dict, List, TypedDict
 
 import geopandas as gpd
 import numpy as np
@@ -11,8 +12,13 @@ from shapely.geometry import shape
 
 
 def save_gdf_as_tiff(
-        gdf: gpd.GeoDataFrame, data_col: str, bounds: Dict[str, float],
-        output_path: str, xy_proj4: Optional[str] = None, data_type: str = 'float32') -> None:
+    gdf: gpd.GeoDataFrame,
+    data_col: str,
+    bounds: Dict[str, float],
+    output_path: str,
+    xy_proj4: str | None = None,
+    data_type: str = "float32",
+) -> None:
     """
     Save a GeoDataFrame as a GeoTIFF file.
 
@@ -29,12 +35,12 @@ def save_gdf_as_tiff(
         The GeoDataFrame to save to a GeoTIFF file.
     data_col : str
         The name of the column within the GeoDataFrame to save out as a Tiff file.
-    bounds : Dict[str, float]:
+    bounds : Dict[str, float]
         A dictionary containing the keys "min_x", "min_y", "max_x" and "max_y" indicating the bounds of the saved tiff.
         These are provided separately because the data in gdf may not extend to the desired edges of the tiff file.
     output_path : str
         The output path of the GeoTIFF file.
-    xy_proj4 : Optional[str], by default None
+    xy_proj4 : str | None
         If not None, the Proj4 code of the 'x' and 'y' columns in the GeoDataFrame. These columns will then be used
         to generate the raster instead of the GeoDataFrame's geometry.
         If None, the GeoDataFrame's geometry is used to generate the raster instead.
@@ -44,8 +50,8 @@ def save_gdf_as_tiff(
     # we start by working out the desired axes of the output raster
     if xy_proj4 is not None:
         # use the 'x' and 'y' columns in the GeoDataFrame
-        x_col = gdf['x']
-        y_col = gdf['y']
+        x_col = gdf["x"]
+        y_col = gdf["y"]
         crs = xy_proj4
     else:
         # we use the geometry within the GeoDataFrame.
@@ -62,32 +68,32 @@ def save_gdf_as_tiff(
     # generate all of the points we want to end up with in the output raster
     # we need to offset both these axes by one in order to use np.searchsorted() in a manner that matches
     # how the EOLIS Gridded products were loaded into Specklia.
-    desired_x_axis = np.arange(bounds['min_x'], bounds['max_x'], dx) + dx
-    desired_y_axis = np.arange(bounds['min_y'], bounds['max_y'], dy) + dy
+    desired_x_axis = np.arange(bounds["min_x"], bounds["max_x"], dx) + dx
+    desired_y_axis = np.arange(bounds["min_y"], bounds["max_y"], dy) + dy
 
     # create the output raster, but fill it with NaN
     gridded_data = np.full((len(desired_y_axis), len(desired_x_axis)), np.nan)
 
     # set the valid points within it
-    gridded_data[np.searchsorted(desired_y_axis, y_col),
-                 np.searchsorted(desired_x_axis, x_col)] = gdf[data_col]
+    gridded_data[np.searchsorted(desired_y_axis, y_col), np.searchsorted(desired_x_axis, x_col)] = gdf[data_col]
 
     # finally, save the raster to file.
     # There's a lot of wierdness here w.r.t axes orientation that we have to replicate
     # in order to maintain compatibility with the Timeseries Service.
     os.makedirs(os.path.dirname(output_path), exist_ok=True)
     with rasterio.open(
-            output_path,
-            'w',
-            driver='GTiff',
-            height=gridded_data.shape[0],
-            width=gridded_data.shape[1],
-            count=1,
-            dtype=data_type,
-            crs=crs,
-            transform=rasterio.transform.from_origin(bounds['min_x'], bounds['max_y'], dx, dy),
-            compress='lzw',
-            nodata=np.nan) as rst:
+        output_path,
+        "w",
+        driver="GTiff",
+        height=gridded_data.shape[0],
+        width=gridded_data.shape[1],
+        count=1,
+        dtype=data_type,
+        crs=crs,
+        transform=rasterio.transform.from_origin(bounds["min_x"], bounds["max_y"], dx, dy),
+        compress="lzw",
+        nodata=np.nan,
+    ) as rst:
         rst.write_band(1, np.flipud(gridded_data))
 
 
@@ -109,9 +115,9 @@ def deserialise_sources(sources: List[Dict]) -> List[Dict]:
         Sources after the coverage polygon, min_time and max_time have been deserialised.
     """
     for source in sources:
-        source['geospatial_coverage'] = shape(source['geospatial_coverage'])
-        source['min_time'] = datetime.fromisoformat(source['min_time'])
-        source['max_time'] = datetime.fromisoformat(source['max_time'])
+        source["geospatial_coverage"] = shape(source["geospatial_coverage"])
+        source["min_time"] = datetime.fromisoformat(source["min_time"])
+        source["max_time"] = datetime.fromisoformat(source["max_time"])
 
     return sources
 

{specklia-1.9.65.dist-info → specklia-1.9.67.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: specklia
-Version: 1.9.65
+Version: 1.9.67
 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.67.dist-info/RECORD

@@ -0,0 +1,9 @@
+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.67.dist-info/LICENCE,sha256=kjWTA-TtT_rJtsWuAgWvesvu01BytVXgt_uCbeQgjOg,1061
+specklia-1.9.67.dist-info/METADATA,sha256=mdKthiyhdnD5rcKV0xioUjO5Fse9sfL2Sykjzn1Ay7Q,3082
+specklia-1.9.67.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+specklia-1.9.67.dist-info/top_level.txt,sha256=XgU53UpAJbqEni5EjJaPdQPYuNx16Geg2I5A9lo1BQw,9
+specklia-1.9.67.dist-info/RECORD,,

specklia-1.9.65.dist-info/RECORD

@@ -1,9 +0,0 @@
-specklia/__init__.py,sha256=ePVHqq642NocoE8tS0cNTd0B5wJdUB7r3y815oQXD6A,51
-specklia/chunked_transfer.py,sha256=qjGJ976CyW8imYtFhba8-SxxgJzSMptw9TAMtWi8Q50,7818
-specklia/client.py,sha256=ujSkx62VIuOJ3FfTon7rAztXkzZCQl5J6QEmFwK8aP8,42183
-specklia/utilities.py,sha256=fs9DOSq-0hdgOlGAnPY_og5QngDcu3essVAupz6ychM,5170
-specklia-1.9.65.dist-info/LICENCE,sha256=kjWTA-TtT_rJtsWuAgWvesvu01BytVXgt_uCbeQgjOg,1061
-specklia-1.9.65.dist-info/METADATA,sha256=VCENT09A1fx7TEDQYg37Gf9vHQPFDu3QBgrUGe16760,3082
-specklia-1.9.65.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-specklia-1.9.65.dist-info/top_level.txt,sha256=XgU53UpAJbqEni5EjJaPdQPYuNx16Geg2I5A9lo1BQw,9
-specklia-1.9.65.dist-info/RECORD,,