specklia 1.8.218__py3-none-any.whl → 1.9.0__py3-none-any.whl

specklia/chunked_transfer.py

@@ -0,0 +1,214 @@
+"""
+Interface to Mongo for using Mongo as a buffer for chunked data transfer.
+
+We use Mongo as a buffer because we cannot guarantee that all of the requests
+for individual chunks will hit the same worker. While we could use streamed responses for the download,
+they're not available for upload, so for simplicity we use the same approach in both directions.
+
+The intended usage pattern is that a single message is stored as a single "chunk set".
+The chunk set is first "filled" (either by the client or the server), then "emptied" to obtain the data
+(again, by either the client or the server).
+
+Note that while this can be used for pagination, it is not in itself pagination.
+
+We plan to gather most of this material into ew_common after the chunked transfer interface has been rolled out
+to its three main users (ew_geostore, ew_specklia, ew_online_processing_service) and proven effective for each.
+At that point, this entire module will move into ew_common. Note that the chunked transfer interface will always
+require MongoDB or a similar provision to work correctly.
+
+IMPORTANT: THE VERSION HERE IN THE SPECKLIA PACKAGE MUST NOT BE MADE DEPENDENT UPON EW_COMMON SINCE EW_COMMON
+IS PRIVATE BUT THIS PACKAGE IS PUBLIC!
+"""
+
+from enum import Enum
+from http import HTTPStatus
+from io import BytesIO
+from logging import Logger
+import struct
+from typing import List, Tuple, Union
+
+from geopandas import GeoDataFrame, read_feather as read_geofeather
+from pandas import DataFrame, read_feather
+import requests
+
+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
+
+
+class ChunkSetStatus(Enum):
+    """
+    Chunk set status.
+
+    Prevents the accidental access of chunk sets that have not yet received all of their data.
+    """
+
+    FILLING = 0
+    EMPTYING = 1
+
+
+def upload_chunks(api_address: str, chunks: List[Tuple[int, bytes]], logger: Logger) -> str:
+    """
+    Upload data chunks.
+
+    Upload a series of data chunks through the chunked transfer mechanism.
+    This method is for use on the client, not the server.
+
+    Parameters
+    ----------
+    api_address : str
+        The full URL of the API, including port but not including endpoint, e.g. "http://127.0.0.1:9999"
+    chunks : List[Tuple[int, bytes]]
+        A list of tuples containing the ordinal number of the chunk and each chunk
+    logger : Logger
+        A logger with which to log the upload.
+
+    Returns
+    -------
+    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])
+    logger.info("response from very first /chunk/upload was '%s'", response.json())
+    assert response.status_code == HTTPStatus.OK, response.text
+    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)
+        logger.info("response from subsequent /chunk/upload/uuid call was '%s'", response.text)
+        assert response.status_code == HTTPStatus.OK, response.text
+
+    return chunk_set_uuid
+
+
+def download_chunks(api_address: str, chunk_set_uuid: str) -> List[Tuple[int, bytes]]:
+    """
+    Download data chunks.
+
+    Download a series of data chunks through the chunked transfer mechanism.
+    This method is for use on the client, not the server.
+
+    Parameters
+    ----------
+    api_address : str
+        The full URL of the API, including port but not including endpoint, e.g. "http://127.0.0.1:9999"
+    chunk_set_uuid : str
+        The uuid of the chunk set to download.
+
+    Returns
+    -------
+    chunks : List[Tuple[int, bytes]]
+        A list of tuples containing the ordinal number of the chunk and each chunk
+    """
+    # fetch the data
+    data_chunks = []
+    finished = False
+    while not finished:
+        this_chunk_response = requests.get(api_address + f"/chunk/download/{chunk_set_uuid}")
+        if this_chunk_response.status_code == HTTPStatus.NO_CONTENT:
+            finished = True
+        else:
+            data_chunks.append((
+                struct.unpack('i', this_chunk_response.content[:4])[0],
+                this_chunk_response.content[4:]))
+
+    return data_chunks
+
+
+def split_into_chunks(data: bytes, chunk_size: int = MAX_CHUNK_SIZE_BYTES) -> List[Tuple[int, bytes]]:
+    """
+    Split data into compressed chunks for transport.
+
+    Parameters
+    ----------
+    data : bytes
+        The data to be split into chunks.
+    chunk_size: int
+        The maximum number of bytes allowed in each chunk.
+
+    Returns
+    -------
+    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))
+
+
+def merge_from_chunks(chunks: List[Tuple[int, bytes]]) -> bytes:
+    """
+    Merge data that has been split into compressed chunks back into a single message.
+
+    Parameters
+    ----------
+    chunks : List[Tuple[int, bytes]]
+        A list of tuples containing the ordinal number of the chunk and each chunk
+
+    Returns
+    -------
+    bytes
+        The merged data
+    """
+    return b''.join([dc[1] for dc in sorted(chunks, key=lambda x: x[0])])
+
+
+def deserialise_dataframe(data: bytes) -> Union[DataFrame, GeoDataFrame]:
+    """
+    Convert a binary serialised feather table to pandas dataframe.
+
+    Parameters
+    ----------
+    data : bytes
+        Binary serialised feather table.
+
+    Returns
+    -------
+    Union[DataFrame, GeoDataFrame]
+        Input table converted to a pandas dataframe.
+
+    Raises
+    ------
+    ValueError
+        When bytes can't be interpreted as meaningful dataframe.
+    """
+    try:
+        buffer = BytesIO(data)
+        df = read_geofeather(buffer)
+    except ValueError as e:
+        # First attempt to deserialise as a geodataframe. If geo meta is missing, we expect a clear ValueError
+        # and we then load as a plain dataframe instead.
+        if "Missing geo meta" in e.args[0] or "'geo' metadata" in e.args[0]:
+            try:
+                df = read_feather(BytesIO(data))
+            except ValueError as e:
+                raise ValueError("Couldn't deserialise table format") from e
+        else:
+            raise ValueError("Couldn't deserialise table format") from e
+    return df
+
+
+def serialise_dataframe(df: Union[DataFrame, GeoDataFrame]) -> bytes:
+    """
+    Serialise a dataframe using the feather table format.
+
+    Parameters
+    ----------
+    df : DataFrame
+        Input dataframe
+
+    Returns
+    -------
+    bytes
+        Serialised feather table.
+    """
+    feather_buffer = BytesIO()
+    # Browser implementations of feather do not support compressed feather formats.
+    df.to_feather(feather_buffer, compression='uncompressed')
+    feather_buffer.seek(0)
+    return feather_buffer.getvalue()

specklia/client.py

@@ -2,7 +2,6 @@
 from __future__ import annotations
 
 from datetime import datetime
-from http import HTTPStatus
 import json
 import logging
 from typing import Dict, List, Optional, Tuple, Union
@@ -14,9 +13,8 @@ import pandas as pd
 import requests
 from shapely import MultiPolygon, Polygon, to_geojson
 from shapely.geometry import shape
-import simple_websocket
 
-from specklia import _websocket_helpers
+from specklia import chunked_transfer, utilities
 
 _log = logging.getLogger(__name__)
 
@@ -168,11 +166,6 @@ class Specklia:
         source_information_only: bool
             If True, no geodataframe is returned, only the set of unique sources. By default, False
 
-        Raises
-        ------
-        RuntimeError
-            If the query failed for some reason.
-
         Returns
         -------
         Tuple[gpd.GeoDataFrame, List[Dict]]
@@ -214,26 +207,39 @@ 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.
-        ws = simple_websocket.Client(
-            self.server_url.replace("http://", "ws://") + "/query")
-        # Authorise the connection and then send the requestion dictionary.
-        ws.send(bytes(self.auth_token, encoding="utf-8"))
-        _websocket_helpers.send_object_to_websocket(ws, {
+        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})
+            '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})
+        _check_response_ok(response)
+
+        _log.info('queried dataset with ID %s.', dataset_id)
 
-        response = _websocket_helpers.receive_object_from_websocket(ws, self._data_streaming_timeout_s)
-        if response['status'] == HTTPStatus.OK:
-            _log.info('queried dataset with ID %s.', dataset_id)
-            return response['gdf'], response['sources']
+        response_dict = response.json()
+
+        # stream and deserialise the results
+        if response_dict['num_chunks'] > 0:
+            gdf = chunked_transfer.deserialise_dataframe(
+                chunked_transfer.merge_from_chunks(
+                    chunked_transfer.download_chunks(
+                        self.server_url, response_dict['chunk_set_uuid'])))
         else:
-            _log.error('Failed to interact with Specklia server, error was %s', str(response))
-            raise RuntimeError(str(response))
+            gdf = gpd.GeoDataFrame()
+
+        # perform some light deserialisation of sources for backwards compatibility.
+        sources = utilities.deserialise_sources(response_dict['sources'])
+
+        return gdf, sources
 
     def update_points_in_dataset(
             self: Specklia, _dataset_id: str, _new_points: pd.DataFrame, _source_description: Dict) -> None:
@@ -294,28 +300,20 @@ class Specklia:
             The timestamp column must contain POSIX timestamps.
             The 'geometry' column must contain Points following the (lon, lat) convention.
             The GeoDataFrame must have its CRS specified as EPSG 4326.
-
-        Raises
-        ------
-        RuntimeError
-            If the ingest failed for some reason.
         """
-        ws = simple_websocket.Client(
-            self.server_url.replace("http://", "ws://") + "/ingest",
-            headers={"Authorization": "Bearer " + self.auth_token})
+        # serialise and upload each dataframe
+        for n in new_points:
+            n['chunk_set_uuid'] = chunked_transfer.upload_chunks(
+                self.server_url, chunked_transfer.split_into_chunks(
+                    chunked_transfer.serialise_dataframe(n['gdf'])), _log)
+            del n['gdf']
 
-        # Authorise the connection and then send the requestion dictionary.
-        ws.send(bytes(self.auth_token, encoding="utf-8"))
-        _websocket_helpers.send_object_to_websocket(ws, {
-            'dataset_id': dataset_id,
-            'new_points': new_points})
+        response = requests.post(self.server_url + "/ingest",
+                                 json={'dataset_id': dataset_id, 'new_points': new_points},
+                                 headers={"Authorization": "Bearer " + self.auth_token})
+        _check_response_ok(response)
 
-        response = _websocket_helpers.receive_object_from_websocket(ws, self._data_streaming_timeout_s)
-        if response['status'] == HTTPStatus.OK:
-            _log.info('Added new data to specklia dataset ID %s.', dataset_id)
-        else:
-            _log.error('Failed to interact with Specklia server, error was %s', str(response))
-            raise RuntimeError(str(response))
+        _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:
@@ -453,7 +451,7 @@ class Specklia:
         """
         response = requests.delete(
             self.server_url + "/groups", headers={"Authorization": "Bearer " + self.auth_token},
-            json={'group_id': group_id})
+            params={'group_id': group_id})
         _check_response_ok(response)
         _log.info('deleted group ID %s', group_id)
         return response.text.strip('\n"')
@@ -631,7 +629,7 @@ class Specklia:
         """
         response = requests.delete(
             self.server_url + "/groupmembership", headers={"Authorization": "Bearer " + self.auth_token},
-            json={'group_id': group_id, "user_to_delete_id": user_to_delete_id})
+            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"')
@@ -850,7 +848,7 @@ class Specklia:
         """
         response = requests.delete(
             self.server_url + "/metadata",
-            json={'dataset_id': dataset_id},
+            params={'dataset_id': dataset_id},
             headers={"Authorization": "Bearer " + self.auth_token}
         )
         _check_response_ok(response)

specklia/utilities.py

@@ -1,11 +1,12 @@
 """This file contains client-side utilities provided to make it easier to use Specklia."""
-
+from datetime import datetime
 import os
-from typing import Dict, Optional
+from typing import Dict, List, Optional
 
 import geopandas as gpd
 import numpy as np
 import rasterio
+from shapely.geometry import shape
 
 
 def save_gdf_as_tiff(
@@ -87,3 +88,28 @@ def save_gdf_as_tiff(
             compress='lzw',
             nodata=np.nan) as rst:
         rst.write_band(1, np.flipud(gridded_data))
+
+
+def deserialise_sources(sources: List[Dict]) -> List[Dict]:
+    """
+    Reverse some serialisation of sources returned from /query.
+
+    Reverses some serialisation of the sources dictionary returned from the /query endpoint for end-user convenience.
+    Convert the WKB coverage polygon into a Shapely geometry object, and the min and max times into datetimes.
+
+    Parameters
+    ----------
+    sources: List[Dict]
+        A list of sources returned from Specklia
+
+    Returns
+    -------
+    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'])
+
+    return sources

{specklia-1.8.218.dist-info → specklia-1.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: specklia
-Version: 1.8.218
+Version: 1.9.0
 Summary: Python client for Specklia, a geospatial point cloud database by Earthwave.
 Home-page: https://specklia.earthwave.co.uk/
 Author: Earthwave Ltd
@@ -23,14 +23,23 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENCE
 Requires-Dist: blosc
-Requires-Dist: flask
 Requires-Dist: geopandas
 Requires-Dist: pandas
 Requires-Dist: pyarrow
 Requires-Dist: rasterio
 Requires-Dist: requests
 Requires-Dist: shapely
-Requires-Dist: simple-websocket
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 # Specklia
 

specklia-1.9.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+specklia/__init__.py,sha256=ePVHqq642NocoE8tS0cNTd0B5wJdUB7r3y815oQXD6A,51
+specklia/chunked_transfer.py,sha256=hO7luSNjznsH-8s585PFNks1agn3cj6v_Sxg_nLVdM8,7179
+specklia/client.py,sha256=Ga-gJhKb7_LywBzzqR0YF-9NFUfvdlqpOYB4c7mvvc8,41153
+specklia/utilities.py,sha256=0_pgTbcq2RgQhys0-CZ6h5YZJg9ZMPhD_ibGPggFUpE,5018
+specklia-1.9.0.dist-info/LICENCE,sha256=kjWTA-TtT_rJtsWuAgWvesvu01BytVXgt_uCbeQgjOg,1061
+specklia-1.9.0.dist-info/METADATA,sha256=5spwzYbdibg6x3Sj4nEUGwBKSlO2PZLHQotMas4rRf4,3081
+specklia-1.9.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+specklia-1.9.0.dist-info/top_level.txt,sha256=XgU53UpAJbqEni5EjJaPdQPYuNx16Geg2I5A9lo1BQw,9
+specklia-1.9.0.dist-info/RECORD,,

{specklia-1.8.218.dist-info → specklia-1.9.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.1.0)
+Generator: setuptools (75.8.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

specklia/_websocket_helpers.py

@@ -1,401 +0,0 @@
-"""Utilities for exchanging arbitrary python objects over a websocket."""
-from __future__ import annotations
-
-from contextlib import suppress
-from dataclasses import dataclass
-from datetime import date
-from datetime import datetime
-from enum import Enum
-from io import BytesIO
-import json
-import re
-import socket
-from typing import Iterable, List, Tuple, Union
-
-import blosc
-from geopandas import GeoDataFrame
-from geopandas import read_feather as gpd_read_feather
-from pandas import DataFrame
-from pandas import read_feather
-from shapely import from_wkb
-from shapely import Geometry
-import simple_websocket
-
-# The blosc library can only compress up to 2 GiB at a time, so we transmit data in chunks of this size.
-MAX_BLOSC_COMPRESSION_SIZE = 2147483631
-MESSAGE_END_FLAG = b'message_ends'
-SERIALISED_SUBSTITUTION_PREFIX = '__SERIALISED__'
-# Type alias representing either a websocket server or client.
-WebSocketAgent = Union[simple_websocket.Server, simple_websocket.Client]
-
-
-class SerialisationType(str, Enum):
-    """Supported serialisation types and their text representation for use in meta data messages."""
-
-    geometry = "wkb"
-    table = "feather"
-
-
-@dataclass
-class SerialisationData:
-    """Wraps an object to serialise with its serialisation type."""
-
-    serialisation_type: SerialisationType
-    data: object
-
-
-def validate_websocket_endpoint_url(url: str) -> None:
-    """
-    Validate a websocket endpoint URL.
-
-    Correct URLs are of the form "ws://localhost:1234/endpoint" or similar.
-
-    Parameters
-    ----------
-    url : str
-        The URL to be validated.
-
-    Raises
-    ------
-    ValueError
-        If the Websocket URL is invalid
-    """
-    # validate the server_url
-    assert url.startswith("ws://")
-    split_url = re.split(r':|/', url)
-    assert len(split_url) >= 6
-    address = split_url[3]
-    port = int(split_url[4])
-
-    try:
-        socket.gethostbyname(address)
-    except socket.gaierror:
-        raise ValueError(f"{address} does not appear to be a valid address.")
-
-    if port != 9065 and (port <= 1023 or port > 65353 or port % 1 != 0):
-        raise ValueError(f"{port} does not appear to be a valid port.")
-
-
-def _receive_bytes_from_websocket(ws: WebSocketAgent, timeout: float = 30) -> bytes:
-    """
-    Receive arbitrary bytes object over a websocket.
-
-    Bytes are assumed to be sent in chunks terminated by MESSAGE_END_FLAG.
-
-    Works for both the Client and Server objects provided by simple_websocket.
-
-    Parameters
-    ----------
-    ws : WebSocketAgent
-        The Websocket Client or Server.
-    timeout : float
-        If provided, will raise RuntimeError if no message is received within this number of seconds.
-        By default, 30 seconds.
-
-    Returns
-    -------
-    bytes
-        The decompressed bytes received via the websocket.
-
-    Raises
-    ------
-    RuntimeError
-        If the connection times out or is closed without a message being received.
-    """
-    message = b''
-    message_chunk = b''
-    while message_chunk != MESSAGE_END_FLAG and message_chunk is not None:
-        try:
-            if message_chunk is not None:
-                message += message_chunk
-            compressed_message_chunk = ws.receive(timeout)
-            if compressed_message_chunk is None:
-                message_chunk = None
-            else:
-                message_chunk = blosc.decompress(compressed_message_chunk)
-        except simple_websocket.ws.ConnectionClosed:
-            # ensure the input buffer is drained
-            if len(ws.input_buffer) > 0:
-                message_chunk = blosc.decompress(ws.input_buffer.pop(0))
-            else:
-                message_chunk = None
-
-    if len(message) == 0:
-        raise RuntimeError("Attempted to receive from a websocket, but nothing was sent.")
-
-    return message
-
-
-def _send_bytes_to_websocket(ws: WebSocketAgent, message: bytes) -> None:
-    """
-    Send arbitrary bytes object over a websocket.
-
-    Bytes are compressed and then transmitted in MESSAGE_CHUNK_SIZE chunks.
-
-    Works for both the Client and Server objects provided by simple_websocket.
-
-    Parameters
-    ----------
-    ws : WebSocketAgent
-        The Websocket Client or Server.
-    message : bytes
-        The data to be sent over the websocket.
-    """
-    for i in range(0, len(message), MAX_BLOSC_COMPRESSION_SIZE):
-        ws.send(blosc.compress(message[i:i + MAX_BLOSC_COMPRESSION_SIZE]))
-    ws.send(blosc.compress(MESSAGE_END_FLAG))
-
-
-def _serialise_dataframe(df: Union[DataFrame, GeoDataFrame]) -> bytes:
-    """
-    Serialise a dataframe using the feather table format.
-
-    Parameters
-    ----------
-    df : DataFrame
-        Input dataframe
-
-    Returns
-    -------
-    bytes
-        Serialised feather table.
-    """
-    feather_buffer = BytesIO()
-    df.to_feather(feather_buffer)
-    feather_buffer.seek(0)
-    return feather_buffer.getvalue()
-
-
-def _deserialise_feather_bytes_to_dataframe(data: bytes) -> Union[DataFrame, GeoDataFrame]:
-    """
-    Convert a binary serialised feather table to pandas dataframe.
-
-    Parameters
-    ----------
-    data : bytes
-        Binary serialised feather table.
-
-    Returns
-    -------
-    Union[DataFrame, GeoDataFrame]
-        Input table converted to a pandas dataframe.
-
-    Raises
-    ------
-    ValueError
-        When bytes can't be interpreted as meaningful dataframe.
-    """
-    try:
-        buffer = BytesIO(data)
-        df = gpd_read_feather(buffer)
-    except ValueError as e:
-        # First attempt to deserialise as a geodataframe. If geo meta is missing, we expect a clear ValueError
-        # and we then load as a plain dataframe instead.
-        if "Missing geo meta" in e.args[0] or "'geo' metadata" in e.args[0]:
-            try:
-                df = read_feather(BytesIO(data))
-            except ValueError as e:
-                raise ValueError("Couldn't deserialise table format") from e
-        else:
-            raise ValueError("Couldn't deserialise table format") from e
-    return df
-
-
-def _extract_objects_to_serialise(data: object, object_dict: List[SerialisationData] = None) \
-        -> Tuple[object, List[SerialisationData]]:
-    """
-    Iterate through an object, replacing complex objects with a placeholder string.
-
-    This recursively traverses the object if it contains dictionaries or lists/iterables.
-    When an object to be serialised is found, we explicitly:
-       - Replace it with a magic string: SERIALISED_SUBSTITUTION_PREFIX{X} where X is an increasing numeric index.
-       - Store the extracted object in a list, where X (above) is its place in this list. We use the
-         SerialisationData type to keep both the object and the serialisation information.
-
-    Parameters
-    ----------
-    data : object
-        Input data object. Can be a single dataframe or primitive or a dictionary-like structure.
-    object_dict : List[SerialisationData], optional
-        Do not use this parameter! It is used in the recursive calls to store extracted object and related information,
-        by default None
-
-    Returns
-    -------
-    Tuple[object, List[SerialisationData]]
-       - A json-friendly copy of the input object with all complex child items replaced with
-         SERIALISED_SUBSTITUTION_PREFIX{X} where.
-         X refers to the index of object in the objects list.
-       - A list of objects from the input data decorated with a transmission friendly serialisation type.
-    """
-    if object_dict is None:
-        object_dict = []
-
-    return_data = data
-    if isinstance(data, (GeoDataFrame, DataFrame)):
-        object_dict.append(SerialisationData(serialisation_type=SerialisationType.table, data=data))
-        return_data = f"{SERIALISED_SUBSTITUTION_PREFIX}{len(object_dict)}"
-    elif isinstance(data, Geometry):
-        object_dict.append(SerialisationData(serialisation_type=SerialisationType.geometry, data=data))
-        return_data = f"{SERIALISED_SUBSTITUTION_PREFIX}{len(object_dict)}"
-    elif isinstance(data, dict):
-        return_data = data.copy()
-        for key in return_data:
-            return_data[key] = _extract_objects_to_serialise(return_data[key], object_dict)[0]
-    # It's important to handle str before Iterable to avoid infinite recursion!
-    elif isinstance(data, str):
-        pass
-    elif isinstance(data, Iterable):
-        return_data = []
-        for item in data:
-            return_data.append(_extract_objects_to_serialise(item, object_dict)[0])
-    return return_data, object_dict
-
-
-def _insert_deserialised_objects(data: object, object_list: List[object]) -> object:
-    """
-    Iterate through the object, replacing all special placeholder strings with objects.
-
-    This can be a single object or a nested dictionary like structure.
-
-    Parameters
-    ----------
-    data : object
-        Object potentially containing placeholder strings.
-    object_list : List[object]
-        The list of objects to inject.
-
-    Returns
-    -------
-    object
-        The original object with placeholder references replaced by objects.
-    """
-    # Default case is return original object when a primitive type.
-    return_data = data
-
-    if isinstance(data, dict):
-        return_data = data.copy()
-        for key in return_data:
-            return_data[key] = _insert_deserialised_objects(return_data[key], object_list)
-    # It's important to handle str before Iterable to avoid infinite recursion!
-    elif isinstance(data, str):
-        if SERIALISED_SUBSTITUTION_PREFIX in data:
-            # Use regex to extract the id using the expected placeholder pattern.
-            match = re.match(f"{SERIALISED_SUBSTITUTION_PREFIX}(\\w+)", data)
-            if match:
-                item_index = int(match.group(1)) - 1
-                return_data = object_list[item_index]
-        # Also handle datetimes. Convert a string to a datetime whenever possible.
-        else:
-            with suppress(ValueError):
-                # fromisoformat is a sensible level of stict, it allows 2001-01-01 but disallows 2001, 20010101
-                return_data = datetime.fromisoformat(data)
-
-    elif isinstance(data, Iterable):
-        return_data = []
-        for item in data:
-            return_data.append(_insert_deserialised_objects(item, object_list))
-    return return_data
-
-
-def _date_serialiser(item: object) -> str:
-    if isinstance(item, (datetime, date)):
-        return item.isoformat()
-    else:
-        raise TypeError(repr(item) + " is not JSON serializable")
-
-
-def send_object_to_websocket(ws: WebSocketAgent, data: object) -> None:
-    """
-    Send a semi-arbitrary python object over a websocket.
-
-    The object is treated as json-like. When non-json-serialisable objects are encountered, they are treated as follows:
-       - Datetime | Date: serialised, in place, using the isoformat text.
-       - DataFrame | GeoDataFrame: Binary serialised using feather and sent as individual websocket messages.
-       - Geometry [Shapely]: Binary serialised as well-known-binary and sent as individual websocket messages.
-
-    The object is sent as a series of websocket messages as follows:
-       1. Send a meta data message as serialised json. This details which binary objects are to be expected in step 3,
-          after the payload.
-       2. Send the payload as serialised json. This may contain substituted placeholder strings for binary serialised
-          objects. Substituted strings take the form of SERIALISED_SUBSTITUTION_PREFIX{X} where x is an increasing
-          index.
-       3. Send any number of binary serialised objects. Each object will be a separate websocket message. The number of
-          messages is deduced from first interpretting the meta data message sent in step 1.
-
-    See _send_bytes_to_websocket for compression and the chunking of large messages.
-
-    Parameters
-    ----------
-    ws : WebSocketAgent
-        The Websocket Client or Server.
-    data : object
-        The data to be sent over the websocket.
-    """
-    # Traverse the object, pull out anything that needs encoding and replace with a unique key
-    message, objects = _extract_objects_to_serialise(data)
-    message_meta = {"binary_type_mapping": [item.serialisation_type for item in objects]}
-
-    # Serialise all "extracted" objects
-    serialised_objects = []
-    for item in objects:
-        if item.serialisation_type == SerialisationType.geometry:
-            # Use WKB for all shapely geomtery types
-            serialised_objects.append(item.data.wkb)
-        elif item.serialisation_type == SerialisationType.table:
-            serialised_objects.append(_serialise_dataframe(item.data))
-
-    message_meta = json.dumps(message_meta).encode("utf-8")
-    message = json.dumps(message, default=_date_serialiser).encode("utf-8")
-
-    for item in [message_meta, message, *serialised_objects]:
-        _send_bytes_to_websocket(ws, item)
-
-
-def receive_object_from_websocket(ws: WebSocketAgent, timeout: float = 30) -> object:
-    """
-    Receive a semi-arbitrary python object over a websocket.
-
-    This reverses the protocol employed by send_object_to_websocket:
-       - Receive and decode the meta data message. This determines how many binary messages are expected after
-         the payload.
-       - Receive and decode the primary payload.
-       - Receive each binary serialised object.
-       - Deserialise each binary object and re-saturate the payload accordingly replacing any placeholder strings with
-         python objects.
-
-    Parameters
-    ----------
-    ws : WebSocketAgent
-        The Websocket Client or Server.
-    timeout : float
-        If provided, will raise RuntimeError if no message is received within this number of seconds.
-        By default, 30 seconds.
-
-    Returns
-    -------
-    object
-        The python object received via the websocket.
-    """
-    # Receive transmission meta data.
-    message_meta = _receive_bytes_from_websocket(ws, timeout)
-    message_meta = json.loads(message_meta.decode("utf-8"))
-    objects_type_map = message_meta['binary_type_mapping']
-
-    # Receive the main payload excluding binary objects
-    data = _receive_bytes_from_websocket(ws, timeout)
-    data = json.loads(data.decode("utf-8"))
-
-    # Finally receive and deserialised binary objects
-    deserialised_objects = []
-    for object_type in objects_type_map:
-        raw_object = _receive_bytes_from_websocket(ws, timeout)
-        if object_type == SerialisationType.table:
-            deserialised_objects.append(_deserialise_feather_bytes_to_dataframe(raw_object))
-        elif object_type == SerialisationType.geometry:
-            deserialised_objects.append(from_wkb(raw_object))
-        del raw_object
-
-    data = _insert_deserialised_objects(data, object_list=deserialised_objects)
-
-    return data

specklia-1.8.218.dist-info/RECORD

@@ -1,9 +0,0 @@
-specklia/__init__.py,sha256=ePVHqq642NocoE8tS0cNTd0B5wJdUB7r3y815oQXD6A,51
-specklia/_websocket_helpers.py,sha256=eDOJrTZD16mnXqAXhU0NTCVhSa5kULbXOqptIhqNzKw,14714
-specklia/client.py,sha256=oI8NezhxeawQyUU3U7xGnReXZGuuL84ztA_CTquv-vE,41348
-specklia/utilities.py,sha256=6y0J3bbYNBD0cSGNHt1BC6h7QJ7YKSVwOBl5u2CnCgc,4074
-specklia-1.8.218.dist-info/LICENCE,sha256=kjWTA-TtT_rJtsWuAgWvesvu01BytVXgt_uCbeQgjOg,1061
-specklia-1.8.218.dist-info/METADATA,sha256=VUue0yHUBAVpNQhhpKpy1VFGp3BrgG3J84KzcqcR0S8,2901
-specklia-1.8.218.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
-specklia-1.8.218.dist-info/top_level.txt,sha256=XgU53UpAJbqEni5EjJaPdQPYuNx16Geg2I5A9lo1BQw,9
-specklia-1.8.218.dist-info/RECORD,,