Merge pull request #140 from specklesystems/izzy/bump-deps

chore: update deps

.circleci/config.yml

@@ -2,14 +2,15 @@ version: 2.1
 
 orbs:
   python: circleci/python@1.3.2
+  codecov: codecov/codecov@3.2.2
 
 jobs:
   test:
     docker:
       - image: "cimg/python:<<parameters.tag>>"
-      - image: "circleci/node:12"
-      - image: "circleci/redis:6"
-      - image: "circleci/postgres:12"
+      - image: 'cimg/node:14.18'
+      - image: 'circleci/redis:6'
+      - image: 'cimg/postgres:12.8'
         environment:
           POSTGRES_DB: speckle2_test
           POSTGRES_PASSWORD: speckle
@@ -38,7 +39,15 @@ jobs:
           name: upgrade pip
       - python/install-packages:
           pkg-manager: poetry
-      - run: poetry run pytest
+      - run: poetry run pytest --cov --cov-report xml:reports/coverage.xml --junitxml=reports/test-results.xml
+
+      - store_test_results:
+          path: reports
+
+      - store_artifacts:
+          path: reports
+
+      - codecov/upload
 
   deploy:
     docker:

.gitignore

@@ -1,3 +1,7 @@
+.tool-versions
+.envrc
+reports/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

README.md

@@ -8,7 +8,9 @@
 <p align="center"><b>Speckle</b> is the data infrastructure for the AEC industry.</p><br/>
 
 <p align="center"><a href="https://twitter.com/SpeckleSystems"><img src="https://img.shields.io/twitter/follow/SpeckleSystems?style=social" alt="Twitter Follow"></a> <a href="https://speckle.community"><img src="https://img.shields.io/discourse/users?server=https%3A%2F%2Fspeckle.community&amp;style=flat-square&amp;logo=discourse&amp;logoColor=white" alt="Community forum users"></a> <a href="https://speckle.systems"><img src="https://img.shields.io/badge/https://-speckle.systems-royalblue?style=flat-square" alt="website"></a> <a href="https://speckle.guide/dev/"><img src="https://img.shields.io/badge/docs-speckle.guide-orange?style=flat-square&amp;logo=read-the-docs&amp;logoColor=white" alt="docs"></a></p>
-<p align="center"><a href="https://github.com/specklesystems/specklepy/"><img src="https://circleci.com/gh/specklesystems/specklepy.svg?style=svg&amp;circle-token=76eabd350ea243575cbb258b746ed3f471f7ac29" alt="Speckle-Next"></a> </p>
+<p align="center"><a href="https://github.com/specklesystems/specklepy/"><img src="https://circleci.com/gh/specklesystems/specklepy.svg?style=svg&amp;circle-token=76eabd350ea243575cbb258b746ed3f471f7ac29" alt="Speckle-Next"></a><a href="https://codecov.io/gh/specklesystems/specklepy">
+  <img src="https://codecov.io/gh/specklesystems/specklepy/branch/main/graph/badge.svg?token=8KQFL5N0YF"/>
+</a> </p>
 
 # About Speckle
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "specklepy"
-version = "2.1.0"
+version = "2.4.0"
 description = "The Python SDK for Speckle 2.0"
 readme = "README.md"
 authors = ["Speckle Systems <devops@speckle.systems>"]
@@ -12,16 +12,17 @@ homepage = "https://speckle.systems/"
 
 [tool.poetry.dependencies]
 python = "^3.6.5"
-pydantic = "^1.7.3"
+pydantic = "^1.8.2"
 appdirs = "^1.4.4"
-gql = {version = ">=3.0.0a6", extras = ["all"], allow-prereleases = true}
-ujson = "^4.1.0"
+gql = {version = ">=3.0.0b1", extras = ["all"], allow-prereleases = true}
+ujson = "^4.3.0"
 
 [tool.poetry.dev-dependencies]
 black = "^20.8b1"
 isort = "^5.7.0"
 pytest = "^6.2.2"
 pytest-ordering = "^0.6"
+pytest-cov = "^3.0.0"
 
 
 [tool.black]

specklepy/api/credentials.py

@@ -1,12 +1,13 @@
 import os
-from specklepy.transports.server.server import ServerTransport
 from warnings import warn
 from pydantic import BaseModel
 from typing import List, Optional
 from urllib.parse import urlparse, unquote
+from specklepy.logging import metrics
 from specklepy.api.models import ServerInfo
 from specklepy.api.client import SpeckleClient
 from specklepy.transports.sqlite import SQLiteTransport
+from specklepy.transports.server.server import ServerTransport
 from specklepy.logging.exceptions import SpeckleException, SpeckleWarning
 
 
@@ -41,6 +42,7 @@ def get_local_accounts(base_path: str = None) -> List[Account]:
     Returns:
         List[Account] -- list of all local accounts or an empty list if no accounts were found
     """
+    metrics.track(metrics.ACCOUNT_LIST)
     account_storage = SQLiteTransport(scope="Accounts", base_path=base_path)
     json_path = os.path.join(account_storage._base_path, "Accounts")
     os.makedirs(json_path, exist_ok=True)
@@ -73,6 +75,7 @@ def get_default_account(base_path: str = None) -> Account:
     Returns:
         Account -- the default account or None if no local accounts were found
     """
+    metrics.track(metrics.ACCOUNT_DEFAULT)
     accounts = get_local_accounts(base_path=base_path)
     if not accounts:
         return None
@@ -86,6 +89,28 @@ def get_default_account(base_path: str = None) -> Account:
 
 
 class StreamWrapper:
+    """
+    The `StreamWrapper` gives you some handy helpers to deal with urls and get authenticated clients and transports.
+
+    Construct a `StreamWrapper` with a stream, branch, commit, or object URL. The corresponding ids will be stored
+    in the wrapper. If you have local accounts on the machine, you can use the `get_account` and `get_client` methods
+    to get a local account for the server. You can also pass a token into `get_client` if you don't have a corresponding
+    local account for the server.
+
+    ```py
+    from specklepy.api.credentials import StreamWrapper
+
+    # provide any stream, branch, commit, object, or globals url
+    wrapper = StreamWrapper("https://speckle.xyz/streams/3073b96e86/commits/604bea8cc6")
+
+    # get an authenticated SpeckleClient if you have a local account for the server
+    client = wrapper.get_client()
+
+    # get an authenticated ServerTransport if you have a local account for the server
+    transport = wrapper.get_transport()
+    ```
+    """
+
     stream_url: str = None
     use_ssl: bool = True
     host: str = None
@@ -114,13 +139,14 @@ class StreamWrapper:
             return "stream" if self.stream_id else "invalid"
 
     def __init__(self, url: str) -> None:
+        metrics.track("streamwrapper")
         self.stream_url = url
         parsed = urlparse(url)
         self.host = parsed.netloc
         self.use_ssl = parsed.scheme == "https"
-        segments = parsed.path.strip("/").split("/")
+        segments = parsed.path.strip("/").split("/", 3)
 
-        if not segments or len(segments) > 4 or len(segments) < 2:
+        if not segments or len(segments) < 2:
             raise SpeckleException(
                 f"Cannot parse {url} into a stream wrapper class - invalid URL provided."
             )
@@ -150,6 +176,9 @@ class StreamWrapper:
             )
 
     def get_account(self) -> Account:
+        """
+        Gets an account object for this server from the local accounts db (added via Speckle Manager or a json file)
+        """
         if self.account:
             return self.account
 
@@ -160,23 +189,42 @@ class StreamWrapper:
 
         return self.account
 
-    def get_client(self) -> SpeckleClient:
-        if self.client:
+    def get_client(self, token: str = None) -> SpeckleClient:
+        """
+        Gets an authenticated client for this server. You may provide a token if there aren't any local accounts on this
+        machine. If no account is found and no token is provided, an unauthenticated client is returned.
+
+        Arguments:
+            token {str} -- optional token if no local account is available (defaults to None)
+
+        Returns:
+            SpeckleClient -- authenticated with a corresponding local account or the provided token
+        """
+        if self.client and token is None:
             return self.client
 
         if not self.account:
             self.get_account()
 
-        self.client = SpeckleClient(host=self.host, use_ssl=self.use_ssl)
+        if not self.client:
+            self.client = SpeckleClient(host=self.host, use_ssl=self.use_ssl)
 
-        if self.account is None:
+        if self.account is None and token is None:
             warn(f"No local account found for server {self.host}", SpeckleWarning)
             return self.client
 
-        self.client.authenticate(self.account.token)
+        self.client.authenticate(self.account.token if self.account else token)
+
         return self.client
 
-    def get_transport(self) -> ServerTransport:
-        if not self.client:
-            self.get_client()
-        return ServerTransport(self.client, self.stream_id)
+    def get_transport(self, token: str = None) -> ServerTransport:
+        """
+        Gets a server transport for this stream using an authenticated client. If there is no local account for this
+        server and the client was not authenticated with a token, this will throw an exception.
+
+        Returns:
+            ServerTransport -- constructed for this stream with a pre-authenticated client
+        """
+        if not self.client or not self.client.me:
+            self.get_client(token)
+        return ServerTransport(self.stream_id, self.client)

specklepy/api/operations.py

@@ -1,7 +1,7 @@
 from typing import List
+from specklepy.logging import metrics
 from specklepy.objects.base import Base
 from specklepy.transports.sqlite import SQLiteTransport
-from specklepy.transports.server import ServerTransport
 from specklepy.logging.exceptions import SpeckleException
 from specklepy.transports.abstract_transport import AbstractTransport
 from specklepy.serialization.base_object_serializer import BaseObjectSerializer
@@ -22,6 +22,7 @@ def send(
     Returns:
         str -- the object id of the sent object
     """
+    metrics.track(metrics.SEND)
     if not transports and not use_default_cache:
         raise SpeckleException(
             message="You need to provide at least one transport: cannot send with an empty transport list and no default cache"
@@ -57,7 +58,7 @@ def receive(
     Returns:
         Base -- the base object
     """
-
+    metrics.track(metrics.RECEIVE)
     if not local_transport:
         local_transport = SQLiteTransport()
 
@@ -92,6 +93,7 @@ def serialize(base: Base, write_transports: List[AbstractTransport] = []) -> str
     Returns:
         str -- the serialized object
     """
+    metrics.track(metrics.SERIALIZE)
     serializer = BaseObjectSerializer(write_transports=write_transports)
 
     return serializer.write_json(base)[1]
@@ -109,6 +111,7 @@ def deserialize(obj_string: str, read_transport: AbstractTransport = None) -> Ba
     Returns:
         Base -- the deserialized object
     """
+    metrics.track(metrics.DESERIALIZE)
     if not read_transport:
         read_transport = SQLiteTransport()
 

specklepy/api/resources/commit.py

@@ -185,3 +185,40 @@ class Resource(ResourceBase):
         return self.make_request(
             query=query, params=params, return_type="commitDelete", parse_response=False
         )
+
+    def received(
+        self,
+        stream_id: str,
+        commit_id: str,
+        source_application: str = "python",
+        message: Optional[str] = None,
+    ) -> bool:
+        """
+        Mark a commit object a received by the source application.
+        """
+        query = gql(
+            """
+            mutation CommitReceive($receivedInput:CommitReceivedInput!){
+                commitReceive(input:$receivedInput)
+            }
+            """
+        )
+        params = {
+            "receivedInput": {
+                "sourceApplication": source_application,
+                "streamId": stream_id,
+                "commitId": commit_id,
+                "message": "message",
+            }
+        }
+
+        try:
+            return self.make_request(
+                query=query,
+                params=params,
+                return_type="commitReceive",
+                parse_response=False,
+            )
+        except Exception as ex:
+            print(ex.with_traceback)
+            return False

specklepy/api/resources/stream.py

@@ -1,7 +1,9 @@
-from typing import Dict, List, Optional
 from gql import gql
-from specklepy.api.resource import ResourceBase
+from typing import Dict, List, Optional
+from specklepy.logging import metrics
 from specklepy.api.models import Stream
+from specklepy.api.resource import ResourceBase
+
 
 NAME = "stream"
 METHODS = [
@@ -35,6 +37,7 @@ class Resource(ResourceBase):
         Returns:
             Stream -- the retrieved stream
         """
+        metrics.track(metrics.STREAM_GET)
         query = gql(
             """
             query Stream($id: String!, $branch_limit: Int!, $commit_limit: Int!) {
@@ -90,6 +93,7 @@ class Resource(ResourceBase):
         Returns:
             List[Stream] -- A list of Stream objects
         """
+        metrics.track(metrics.STREAM_LIST)
         query = gql(
             """
             query User($stream_limit: Int!) {
@@ -147,6 +151,7 @@ class Resource(ResourceBase):
         Returns:
             id {str} -- the id of the newly created stream
         """
+        metrics.track(metrics.STREAM_CREATE)
         query = gql(
             """
             mutation StreamCreate($stream: StreamCreateInput!) {
@@ -177,6 +182,7 @@ class Resource(ResourceBase):
         Returns:
             bool -- whether the stream update was successful
         """
+        metrics.track(metrics.STREAM_UPDATE)
         query = gql(
             """
             mutation StreamUpdate($stream: StreamUpdateInput!) {
@@ -207,6 +213,7 @@ class Resource(ResourceBase):
         Returns:
             bool -- whether the deletion was successful
         """
+        metrics.track(metrics.STREAM_DELETE)
         query = gql(
             """
             mutation StreamDelete($id: String!) {
@@ -239,6 +246,7 @@ class Resource(ResourceBase):
         Returns:
             List[Stream] -- a list of Streams that match the search query
         """
+        metrics.track(metrics.STREAM_SEARCH)
         query = gql(
             """
             query StreamSearch($search_query: String!,$limit: Int!, $branch_limit:Int!, $commit_limit:Int!) {

specklepy/logging/exceptions.py

@@ -32,4 +32,4 @@ class GraphQLException(SpeckleException):
 
 class SpeckleWarning(Warning):
     def __init__(self, *args: object) -> None:
-        super().__init__(*args)
+        super().__init__(*args)

specklepy/logging/metrics.py

@@ -0,0 +1,125 @@
+import os
+import queue
+import logging
+import requests
+import threading
+from requests.sessions import session
+from specklepy.transports.sqlite import SQLiteTransport
+
+"""
+Anonymous telemetry to help us understand how to make a better Speckle.
+This really helps us to deliver a better open source project and product!
+"""
+TRACK = True
+HOST_APP = "python"
+
+LOG = logging.getLogger(__name__)
+METRICS_TRACKER = None
+
+# actions
+RECEIVE = "receive"
+SEND = "send"
+STREAM_CREATE = "stream/create"
+STREAM_GET = "stream/get"
+STREAM_UPDATE = "stream/update"
+STREAM_DELETE = "stream/delete"
+STREAM_DETAILS = "stream/details"
+STREAM_LIST = "stream/list"
+STREAM_VIEW = "stream/view"
+STREAM_SEARCH = "stream/search"
+
+ACCOUNT_DEFAULT = "account/default"
+ACCOUNT_DETAILS = "account/details"
+ACCOUNT_LIST = "account/list"
+
+SERIALIZE = "serialization/serialize"
+DESERIALIZE = "serialization/deserialize"
+
+
+def disable():
+    global TRACK
+    TRACK = False
+
+
+def set_host_app(host_app: str):
+    global HOST_APP
+    HOST_APP = host_app
+
+
+def track(action: str):
+    if not TRACK:
+        return
+    try:
+        global METRICS_TRACKER
+        if not METRICS_TRACKER:
+            METRICS_TRACKER = MetricsTracker()
+
+        page_params = {
+            "rec": 1,
+            "idsite": METRICS_TRACKER.site_id,
+            "uid": METRICS_TRACKER.suuid,
+            "action_name": action,
+            "url": f"http://connectors/{HOST_APP}/{action}",
+            "urlref": f"http://connectors/{HOST_APP}/{action}",
+            "_cvar": {"1": ["hostApplication", HOST_APP]},
+        }
+
+        event_params = {
+            "rec": 1,
+            "idsite": METRICS_TRACKER.site_id,
+            "uid": MetricsTracker.suuid,
+            "_cvar": {"1": ["hostApplication", HOST_APP]},
+            "e_c": HOST_APP,
+            "e_a": action,
+        }
+
+        METRICS_TRACKER.queue.put_nowait([event_params, page_params])
+    except Exception as ex:
+        # wrapping this whole thing in a try except as we never want a failure here to annoy users!
+        LOG.error("Error queueing metrics request: " + str(ex))
+
+
+class Singleton(type):
+    _instances = {}
+
+    def __call__(cls, *args, **kwargs):
+        if cls not in cls._instances:
+            cls._instances[cls] = super(Singleton, cls).__call__(*args, **kwargs)
+        return cls._instances[cls]
+
+
+class MetricsTracker(metaclass=Singleton):
+    matomo_url = "https://speckle.matomo.cloud/matomo.php"
+    site_id = 2
+    host_app = "python"
+    suuid = None
+    sending_thread = None
+    queue = queue.Queue(1000)
+
+    def __init__(self) -> None:
+        self.sending_thread = threading.Thread(
+            target=self._send_tracking_requests, daemon=True
+        )
+        self.set_suuid()
+        self.sending_thread.start()
+
+    def set_suuid(self):
+        try:
+            file_path = os.path.join(SQLiteTransport.get_base_path("Speckle"), "suuid")
+            with open(file_path, "r") as file:
+                self.suuid = file.read()
+        except:
+            self.suuid = "unknown-suuid"
+
+    def _send_tracking_requests(self):
+        session = requests.Session()
+        while True:
+            params = self.queue.get()
+
+            try:
+                session.post(self.matomo_url, params=params[0])
+                session.post(self.matomo_url, params=params[1])
+            except Exception as ex:
+                LOG.error("Error sending metrics request: " + str(ex))
+
+            self.queue.task_done()

specklepy/objects/base.py

@@ -1,6 +1,15 @@
 import typing
-from typing import (Any, Callable, ClassVar, Dict, List, Optional, Set, Type,
-                    get_type_hints)
+from typing import (
+    Any,
+    Callable,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Set,
+    Type,
+    get_type_hints,
+)
 from warnings import warn
 
 from specklepy.logging.exceptions import SpeckleException
@@ -118,14 +127,12 @@ class _RegisteringBase:
         except Exception:
             cls._attr_types = getattr(cls, "__annotations__", {})
         if chunkable:
-            chunkable = {k: v for k, v in chunkable.items()
-                         if isinstance(v, int)}
+            chunkable = {k: v for k, v in chunkable.items() if isinstance(v, int)}
             cls._chunkable = dict(cls._chunkable, **chunkable)
         if detachable:
             cls._detachable = cls._detachable.union(detachable)
         if serialize_ignore:
-            cls._serialize_ignore = cls._serialize_ignore.union(
-                serialize_ignore)
+            cls._serialize_ignore = cls._serialize_ignore.union(serialize_ignore)
         super().__init_subclass__(**kwargs)
 
 
@@ -215,15 +222,13 @@ class Base(_RegisteringBase):
         try:
             cls._attr_types = get_type_hints(cls)
         except Exception as e:
-            warn(
-                f"Could not update forward refs for class {cls.__name__}: {e}")
+            warn(f"Could not update forward refs for class {cls.__name__}: {e}")
 
     @classmethod
     def validate_prop_name(cls, name: str) -> None:
         """Validator for dynamic attribute names."""
         if name in {"", "@"}:
-            raise ValueError(
-                "Invalid Name: Base member names cannot be empty strings")
+            raise ValueError("Invalid Name: Base member names cannot be empty strings")
         if name.startswith("@@"):
             raise ValueError(
                 "Invalid Name: Base member names cannot start with more than one '@'",
@@ -249,7 +254,12 @@ class Base(_RegisteringBase):
 
         if t.__module__ == "typing":
             origin = getattr(t, "__origin__")
-            t = t.__args__ if origin is typing.Union else origin
+            t = (
+                tuple(getattr(sub_t, "__origin__", sub_t) for sub_t in t.__args__)
+                if origin is typing.Union
+                else origin
+            )
+
             if not isinstance(t, (type, tuple)):
                 warn(
                     f"Unrecognised type '{t}' provided for attribute '{name}'. Type will not been validated."
@@ -260,13 +270,16 @@ class Base(_RegisteringBase):
 
         # to be friendly, we'll parse ints and strs into floats, but not the other way around
         # (to avoid unexpected rounding)
-        if t is float and isinstance(value, (int, str, float)):
-            try:
+        if isinstance(t, tuple):
+            t = t[0]
+
+        try:
+            if t is float:
                 return float(value)
-            except ValueError:
-                pass
-        if t is str and value is not None:
-            return str(value)
+            if t is str and value:
+                return str(value)
+        except ValueError:
+            pass
 
         raise SpeckleException(
             f"Cannot set '{self.__class__.__name__}.{name}': it expects type '{t.__name__}', but received type '{type(value).__name__}'"
@@ -327,7 +340,8 @@ class Base(_RegisteringBase):
 
     def get_id(self, decompose: bool = False) -> str:
         """
-        Gets the id (a unique hash) of this object. ⚠️ This method fully serializes the object, which in the case of large objects (with many sub-objects), has a tangible cost. Avoid using it!
+        Gets the id (a unique hash) of this object. ⚠️ This method fully serializes the object which,
+        in the case of large objects (with many sub-objects), has a tangible cost. Avoid using it!
 
         Note: the hash of a decomposed object differs from that of a non-decomposed object
 
@@ -337,8 +351,7 @@ class Base(_RegisteringBase):
         Returns:
             str -- the hash (id) of the fully serialized object
         """
-        from specklepy.serialization.base_object_serializer import \
-            BaseObjectSerializer
+        from specklepy.serialization.base_object_serializer import BaseObjectSerializer
 
         serializer = BaseObjectSerializer()
         if decompose:

specklepy/objects/encoding.py

@@ -17,6 +17,7 @@ class CurveTypeEncoding(int, Enum):
     @property
     def object_class(self) -> Type:
         from . import geometry
+
         if self == self.Arc:
             return geometry.Arc
         elif self == self.Circle:
@@ -32,7 +33,8 @@ class CurveTypeEncoding(int, Enum):
         elif self == self.Polycurve:
             return geometry.Polycurve
         raise SpeckleException(
-            f'No corresponding object class for CurveTypeEncoding: {self}')
+            f"No corresponding object class for CurveTypeEncoding: {self}"
+        )
 
 
 def curve_from_list(args: List[float]):
@@ -41,61 +43,68 @@ def curve_from_list(args: List[float]):
 
 
 class ObjectArray:
-
     def __init__(self) -> None:
         self.data = []
 
     @classmethod
-    def from_objects(cls, objects: List[Base]) -> 'ObjectArray':
-        data_chunk = cls()
-        if len(objects) == 0:
-            return data_chunk
+    def from_objects(cls, objects: List[Base]) -> "ObjectArray":
+        data_list = cls()
+        if not objects:
+            return data_list
 
         speckle_type = objects[0].speckle_type
 
         for obj in objects:
             if speckle_type != obj.speckle_type:
                 raise SpeckleException(
-                    'All objects in chunk should have the same speckle_type. '
-                    f'Found {speckle_type} and {obj.speckle_type}'
+                    "All objects in chunk should have the same speckle_type. "
+                    f"Found {speckle_type} and {obj.speckle_type}"
                 )
-            data_chunk.encode_object(object=obj)
+            data_list.encode_object(object=obj)
 
-        return data_chunk
+        return data_list
 
     @staticmethod
-    def decode_data(data: List[Any], decoder: Callable[[List[Any]], Base]) -> List[Base]:
+    def decode_data(
+        data: List[Any], decoder: Callable[[List[Any]], Base]
+    ) -> List[Base]:
+        bases = []
+        if not data:
+            return bases
+
         index = 0
-        unchunked_data = []
         while index < len(data):
-            chunk_length = data[index]
-            chunk_start = int(index + 1)
-            chunk_end = int(chunk_start + chunk_length)
-            chunk_data = data[chunk_start:chunk_end]
-            decoded_data = decoder(chunk_data)
-            unchunked_data.append(decoded_data)
-            index = chunk_end
-        return unchunked_data
+            item_length = data[index]
+            item_start = index + 1
+            item_end = item_start + item_length
+            item_data = data[item_start:item_end]
+            index = item_end
+            # TODO: investigate what's going on w this fail
+            try:
+                decoded_data = decoder(item_data)
+                bases.append(decoded_data)
+            except ValueError:
+                continue
+        return bases
 
     def decode(self, decoder: Callable[[List[Any]], Any]):
         return self.decode_data(data=self.data, decoder=decoder)
 
     def encode_object(self, object: Base):
-        chunk = object.to_list()
-        chunk.insert(0, len(chunk))
-        self.data.extend(chunk)
+        encoded = object.to_list()
+        encoded.insert(0, len(encoded))
+        self.data.extend(encoded)
 
 
 class CurveArray(ObjectArray):
-
     @classmethod
-    def from_curve(cls, curve: Base) -> 'CurveArray':
+    def from_curve(cls, curve: Base) -> "CurveArray":
         crv_array = cls()
         crv_array.data = curve.to_list()
         return crv_array
 
     @classmethod
-    def from_curves(cls, curves: List[Base]) -> 'CurveArray':
+    def from_curves(cls, curves: List[Base]) -> "CurveArray":
         data = []
         for curve in curves:
             curve_list = curve.to_list()

specklepy/objects/units.py

@@ -15,6 +15,7 @@ UNITS_STRINGS = {
 }
 
 UNITS_ENCODINGS = {
+    "none": 0,
     "mm": 1,
     "cm": 2,
     "m": 3,

specklepy/transports/server/server.py

@@ -13,21 +13,68 @@ from .batch_sender import BatchSender
 
 
 class ServerTransport(AbstractTransport):
+    """
+    The `ServerTransport` is the vehicle through which you transport objects to and from a Speckle Server. Provide it to
+    `operations.send()` or `operations.receive()`.
+
+    The `ServerTransport` can be authenticted two different ways:
+        1. by providing a `SpeckleClient`
+        2. by providing a `token` and `url`
+
+    ```py
+    from specklepy.api import operations
+    from specklepy.transports.server import ServerTransport
+
+    # here's the data you want to send
+    block = Block(length=2, height=4)
+
+    # next create the server transport - this is the vehicle through which you will send and receive
+    transport = ServerTransport(stream_id=new_stream_id, client=client)
+
+    # this serialises the block and sends it to the transport
+    hash = operations.send(base=block, transports=[transport])
+
+    # you can now create a commit on your stream with this object
+    commid_id = client.commit.create(
+        stream_id=new_stream_id,
+        obj_id=hash,
+        message="this is a block I made in speckle-py",
+    )
+    ```
+    """
+
     _name = "RemoteTransport"
     url: str = None
     stream_id: str = None
     saved_obj_count: int = 0
     session: requests.Session = None
 
-    def __init__(self, client: SpeckleClient, stream_id: str, **data: Any) -> None:
+    def __init__(
+        self,
+        stream_id: str,
+        client: SpeckleClient = None,
+        token: str = None,
+        url: str = None,
+        **data: Any,
+    ) -> None:
         super().__init__(**data)
         # TODO: replace client with account or some other auth avenue
-        if not client.me:
-            raise SpeckleException("The provided SpeckleClient was not authenticated.")
-        self.url = client.url
-        self.stream_id = stream_id
+        if client is None and token is None and url is None:
+            raise SpeckleException(
+                "You must provide either a client or a token and url to construct a ServerTransport."
+            )
+
+        if client:
+            if not client.me:
+                raise SpeckleException(
+                    "The provided SpeckleClient was not authenticated."
+                )
+            token = client.me["token"]
+            url = client.url
+
+        self.stream_id = stream_id
+        self.url = url
 
-        token = client.me["token"]
         self._batch_sender = BatchSender(
             self.url, self.stream_id, token, max_batch_size_mb=1
         )

specklepy/transports/sqlite.py

@@ -32,7 +32,7 @@ class SQLiteTransport(AbstractTransport):
         super().__init__(**data)
         self.app_name = app_name or "Speckle"
         self.scope = scope or "Objects"
-        self._base_path = base_path or self.__get_base_path()
+        self._base_path = base_path or self.get_base_path(self.app_name)
 
         try:
             os.makedirs(self._base_path, exist_ok=True)
@@ -56,7 +56,8 @@ class SQLiteTransport(AbstractTransport):
     #     proc.start()
     #     proc.join()
 
-    def __get_base_path(self):
+    @staticmethod
+    def get_base_path(app_name):
         # from appdirs https://github.com/ActiveState/appdirs/blob/master/appdirs.py
         # default mac path is not the one we use (we use unix path), so using special case for this
         system = sys.platform
@@ -68,10 +69,10 @@ class SQLiteTransport(AbstractTransport):
                 system = "darwin"
 
         if system != "darwin":
-            return user_data_dir(appname=self.app_name, appauthor=False, roaming=True)
+            return user_data_dir(appname=app_name, appauthor=False, roaming=True)
 
         path = os.path.expanduser("~/.config/")
-        return os.path.join(path, self.app_name)
+        return os.path.join(path, app_name)
 
     # def __consume_queue(self):
     #     if self._is_writing or self.__queue.empty():

tests/conftest.py

@@ -7,6 +7,9 @@ from specklepy.api.client import SpeckleClient
 from specklepy.objects.base import Base
 from specklepy.objects.geometry import Point
 from specklepy.objects.fakemesh import FakeMesh
+from specklepy.logging import metrics
+
+metrics.disable()
 
 
 @pytest.fixture(scope="session")

tests/test_base.py

@@ -1,5 +1,5 @@
 from contextlib import ExitStack as does_not_raise
-from typing import Dict, List
+from typing import Dict, List, Optional
 
 import pytest
 from specklepy.api import operations
@@ -87,9 +87,9 @@ class FrozenYoghurt(Base):
     """Testing type checking"""
 
     servings: int
-    flavours: List[str] = None  # list item types won't be checked
+    flavours: List[str]  # list item types won't be checked
     customer: str
-    add_ons: Dict[str, float]  # dict item types won't be checked
+    add_ons: Optional[Dict[str, float]]  # dict item types won't be checked
     price: float = 0.0
 
 
@@ -111,5 +111,3 @@ def test_type_checking() -> None:
     order.flavours = ["strawberry", "lychee", "peach", "pineapple"]
 
     assert order.price == 7.0
-
-

tests/test_branch.py

@@ -58,7 +58,7 @@ class TestBranch:
         assert isinstance(branches, list)
         assert len(branches) == 2
         assert isinstance(branches[0], Branch)
-        assert branches[0].name == branch.name
+        assert branches[1].name == branch.name
 
     def test_branch_update(self, client, stream, branch, updated_branch):
         updated = client.branch.update(

tests/test_commit.py

@@ -68,3 +68,20 @@ class TestCommit:
         deleted = client.commit.delete(stream_id=stream.id, commit_id=commit_id)
 
         assert deleted is True
+
+    def test_commit_marked_as_received(self, client, stream, mesh) -> None:
+        commit = Commit(message="this commit should be received")
+        commit.id = client.commit.create(
+            stream_id=stream.id,
+            object_id=mesh.id,
+            message=commit.message,
+        )
+
+        commit_marked_received = client.commit.received(
+            stream.id,
+            commit.id,
+            source_application="pytest",
+            message="testing received",
+        )
+
+        assert commit_marked_received == True

tests/test_geometry.py

@@ -5,11 +5,28 @@ import pytest
 from specklepy.api import operations
 from specklepy.objects.base import Base
 from specklepy.objects.encoding import CurveArray, ObjectArray
-from specklepy.objects.geometry import (Arc, Box, Brep, BrepEdge, BrepFace,
-                                        BrepLoop, BrepTrim, BrepTrimTypeEnum,
-                                        Circle, Curve, Ellipse, Interval, Line,
-                                        Mesh, Plane, Point, Polycurve,
-                                        Polyline, Surface, Vector)
+from specklepy.objects.geometry import (
+    Arc,
+    Box,
+    Brep,
+    BrepEdge,
+    BrepFace,
+    BrepLoop,
+    BrepTrim,
+    BrepTrimTypeEnum,
+    Circle,
+    Curve,
+    Ellipse,
+    Interval,
+    Line,
+    Mesh,
+    Plane,
+    Point,
+    Polycurve,
+    Polyline,
+    Surface,
+    Vector,
+)
 from specklepy.transports.memory import MemoryTransport
 
 
@@ -71,7 +88,7 @@ def arc(plane, interval):
         angleRadians=33,
         plane=plane,
         domain=interval,
-        units='m',
+        units="m",
         # These attributes are not handled in C#
         # bbox=None,
         # area=None,
@@ -88,7 +105,7 @@ def circle(plane, interval):
         radius=22,
         plane=plane,
         domain=interval,
-        units='m',
+        units="m",
         # These attributes are not handled in C#
         # bbox=None,
         # area=None,
@@ -103,7 +120,7 @@ def ellipse(plane, interval):
         secondRadius=22,
         plane=plane,
         domain=interval,
-        units='m',
+        units="m",
         # These attributes are not handled in C#
         # trimDomain=None,
         # bbox=None,
@@ -118,7 +135,7 @@ def polyline(interval):
         value=[22, 44, 54.3, 99, 232, 21],
         closed=True,
         domain=interval,
-        units='m',
+        units="m",
         # These attributes are not handled in C#
         # bbox=None,
         # area=None,
@@ -137,7 +154,7 @@ def curve(interval):
         points=[23, 21, 44, 43, 56, 76, 1, 3, 2],
         weights=[23, 11, 23],
         knots=[22, 45, 76, 11],
-        units='m',
+        units="m",
         # These attributes are not handled in C#
         # displayValue=None,
         # bbox=None,
@@ -152,7 +169,7 @@ def polycurve(interval, curve, polyline):
         segments=[curve, polyline],
         domain=interval,
         closed=True,
-        units='m',
+        units="m",
         # These attributes are not handled in C#
         # bbox=None,
         # area=None,
@@ -187,7 +204,7 @@ def surface(interval):
         domainV=interval,
         knotsU=[1.1, 2.2, 3.3, 4.4],
         knotsV=[9, 8, 7, 6, 5, 4.4],
-        units='m',
+        units="m",
         # These attributes are not handled in C#
         # bbox=None,
         # area=None,
@@ -218,11 +235,7 @@ def brep_edge(interval):
 
 @pytest.fixture()
 def brep_loop():
-    return BrepLoop(
-        FaceIndex=5,
-        TrimIndices=[3, 4, 5],
-        Type='unknown'
-    )
+    return BrepLoop(FaceIndex=5, TrimIndices=[3, 4, 5], Type="unknown")
 
 
 @pytest.fixture()
@@ -235,7 +248,7 @@ def brep_trim():
         LoopIndex=4,
         CurveIndex=7,
         IsoStatus=6,
-        TrimType='Mated',
+        TrimType="Mated",
         IsReversed=False,
         # These attributes are not handled in C#
         # Domain=None,
@@ -243,10 +256,21 @@ def brep_trim():
 
 
 @pytest.fixture
-def brep(mesh, box, surface, curve, polyline, circle, point,
-         brep_edge, brep_loop, brep_trim, brep_face):
+def brep(
+    mesh,
+    box,
+    surface,
+    curve,
+    polyline,
+    circle,
+    point,
+    brep_edge,
+    brep_loop,
+    brep_trim,
+    brep_face,
+):
     return Brep(
-        provenance='pytest',
+        provenance="pytest",
         bbox=box,
         area=32,
         volume=54,
@@ -265,33 +289,57 @@ def brep(mesh, box, surface, curve, polyline, circle, point,
 
 
 @pytest.fixture
-def geometry_objects_dict(point, vector, plane, line, arc,
-                          circle, ellipse, polyline, curve,
-                          polycurve, surface, brep_trim):
+def geometry_objects_dict(
+    point,
+    vector,
+    plane,
+    line,
+    arc,
+    circle,
+    ellipse,
+    polyline,
+    curve,
+    polycurve,
+    surface,
+    brep_trim,
+):
     return {
-        'point': point,
-        'vector': vector,
-        'plane': plane,
-        'line': line,
-        'arc': arc,
-        'circle': circle,
-        'ellipse': ellipse,
-        'polyline': polyline,
-        'curve': curve,
-        'polycurve': polycurve,
-        'surface': surface,
-        'brep_trim': brep_trim
+        "point": point,
+        "vector": vector,
+        "plane": plane,
+        "line": line,
+        "arc": arc,
+        "circle": circle,
+        "ellipse": ellipse,
+        "polyline": polyline,
+        "curve": curve,
+        "polycurve": polycurve,
+        "surface": surface,
+        "brep_trim": brep_trim,
     }
 
 
-@pytest.mark.parametrize('object_name', [
-    'point', 'vector', 'plane', 'line', 'arc', 'circle',
-    'ellipse', 'polyline', 'curve', 'polycurve', 'surface', 'brep_trim'
-])
+@pytest.mark.parametrize(
+    "object_name",
+    [
+        "point",
+        "vector",
+        "plane",
+        "line",
+        "arc",
+        "circle",
+        "ellipse",
+        "polyline",
+        "curve",
+        "polycurve",
+        "surface",
+        "brep_trim",
+    ],
+)
 def test_to_and_from_list(object_name: str, geometry_objects_dict):
     object = geometry_objects_dict[object_name]
-    assert hasattr(object, 'to_list')
-    assert hasattr(object, 'from_list')
+    assert hasattr(object, "to_list")
+    assert hasattr(object, "from_list")
 
     chunks = object.to_list()
     assert isinstance(chunks, list)
@@ -306,8 +354,7 @@ def test_brep_surfaces_value_serialization(surface):
     assert brep.Surfaces == None
     assert brep.SurfacesValue == None
     brep.Surfaces = [surface, surface]
-    assert brep.SurfacesValue == ObjectArray.from_objects(
-        [surface, surface]).data
+    assert brep.SurfacesValue == ObjectArray.from_objects([surface, surface]).data
 
     brep.SurfacesValue = ObjectArray.from_objects([surface]).data
     assert len(brep.Surfaces) == 1
@@ -341,16 +388,32 @@ def test_brep_curve3d_values_serialization(curve, polyline, circle):
 def test_brep_vertices_values_serialization():
     brep = Brep()
     brep.VerticesValue = [1, 1, 1, 1, 2, 2, 2, 3, 3, 3]
-    brep.Vertices[0].get_id() == Point(x=1, y=1, z=1, _units='mm').get_id()
-    brep.Vertices[1].get_id() == Point(x=2, y=2, z=2, _units='mm').get_id()
-    brep.Vertices[2].get_id() == Point(x=3, y=3, z=3, _units='mm').get_id()
+    brep.Vertices[0].get_id() == Point(x=1, y=1, z=1, _units="mm").get_id()
+    brep.Vertices[1].get_id() == Point(x=2, y=2, z=2, _units="mm").get_id()
+    brep.Vertices[2].get_id() == Point(x=3, y=3, z=3, _units="mm").get_id()
 
 
 def test_trims_value_serialization():
     brep = Brep()
     brep.TrimsValue = [
-        0, 0, 0, 0, 0, 0, 1, 1, 1,
-        1, 0, 0, 0, 0, 1, 2, 1, 0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        1,
+        1,
+        1,
+        1,
+        0,
+        0,
+        0,
+        0,
+        1,
+        2,
+        1,
+        0,
     ]
 
     brep.Trims[0].get_id() == BrepTrim(
@@ -383,7 +446,7 @@ def test_serialized_brep_attributes(brep: Brep):
     serialized = operations.serialize(brep, [transport])
     serialized_dict = json.loads(serialized)
 
-    removed_keys = ['Surfaces', 'Curve3D', 'Curve2D', 'Vertices', 'Trims']
+    removed_keys = ["Surfaces", "Curve3D", "Curve2D", "Vertices", "Trims"]
 
     for k in removed_keys:
         assert k not in serialized_dict.keys()

tests/test_objects.py

@@ -21,11 +21,9 @@ class TestObject:
 
     def test_object_create(self, client, stream, base):
         transport = SQLiteTransport()
-        s = BaseObjectSerializer(
-            write_transports=[transport], read_transport=transport)
+        s = BaseObjectSerializer(write_transports=[transport], read_transport=transport)
         _, base_dict = s.traverse_base(base)
-        obj_id = client.object.create(
-            stream_id=stream.id, objects=[base_dict])[0]
+        obj_id = client.object.create(stream_id=stream.id, objects=[base_dict])[0]
 
         assert isinstance(obj_id, str)
         assert base_dict["@detach"]["speckle_type"] == "reference"
@@ -43,12 +41,6 @@ class TestObject:
 
     def test_object_array_decoder(self):
         array = ObjectArray()
-        array.data = [
-            5, 1, 1, 1, 1, 1,
-            4, 1, 1, 1, 1,
-            3, 1, 1, 1,
-            2, 1, 1,
-            1, 1
-        ]
+        array.data = [5, 1, 1, 1, 1, 1, 4, 1, 1, 1, 1, 3, 1, 1, 1, 2, 1, 1, 1, 1]
 
         assert array.decode(decoder=sum) == [5, 4, 3, 2, 1]

tests/test_serialization.py

@@ -1,5 +1,4 @@
 import json
-from attr import has
 import pytest
 from specklepy.api import operations
 from specklepy.transports.server import ServerTransport
@@ -53,6 +52,11 @@ class TestSerialization:
     def test_send_and_receive(self, client, sample_stream, mesh):
         transport = ServerTransport(client=client, stream_id=sample_stream.id)
         hash = operations.send(mesh, transports=[transport])
+
+        # also try constructing server transport with token and url
+        transport = ServerTransport(
+            stream_id=sample_stream.id, token=client.me["token"], url=client.url
+        )
         # use a fresh memory transport to force receiving from remote
         received = operations.receive(
             hash, remote_transport=transport, local_transport=MemoryTransport()
@@ -84,4 +88,4 @@ class TestSerialization:
         untyped = '{"foo": "bar"}'
         deserialised = operations.deserialize(untyped)
 
-        assert deserialised == {"foo": "bar"}
+        assert deserialised == {"foo": "bar"}

tests/test_wrapper.py

@@ -18,6 +18,14 @@ class TestWrapper:
         assert wacky_wrap.branch_name == "🍕⬅🌟 you wat?"
         assert wrap.type == "branch"
 
+    def test_parse_nested_branch(self):
+        wrap = StreamWrapper(
+            "https://testing.speckle.dev/streams/4c3ce1459c/branches/izzy/dev"
+        )
+
+        assert wrap.branch_name == "izzy/dev"
+        assert wrap.type == "branch"
+
     def test_parse_commit(self):
         wrap = StreamWrapper(
             "https://testing.speckle.dev/streams/4c3ce1459c/commits/8b9b831792"
@@ -39,3 +47,33 @@ class TestWrapper:
             "https://testing.speckle.dev/streams/0c6ad366c4/globals/abd3787893"
         )
         assert wrap.type == "commit"
+
+    #! NOTE: the following three tests may not pass locally if you have a `speckle.xyz` account in manager
+    def test_get_client_without_auth(self):
+        wrap = StreamWrapper(
+            "https://speckle.xyz/streams/4c3ce1459c/commits/8b9b831792"
+        )
+        client = wrap.get_client()
+
+        assert client is not None
+
+    def test_get_new_client_with_token(self):
+        wrap = StreamWrapper(
+            "https://speckle.xyz/streams/4c3ce1459c/commits/8b9b831792"
+        )
+        client = wrap.get_client()
+        client = wrap.get_client(token="super-secret-token")
+
+        assert client.me["token"] == "super-secret-token"
+
+    def test_get_transport_with_token(self):
+        wrap = StreamWrapper(
+            "https://speckle.xyz/streams/4c3ce1459c/commits/8b9b831792"
+        )
+        client = wrap.get_client()
+        assert not client.me  # unauthenticated bc no local accounts
+
+        transport = wrap.get_transport(token="super-secret-token")
+
+        assert transport is not None
+        assert client.me["token"] == "super-secret-token"