fix(base): remove default units to Base (#193)

* fix(base): remove default units to `Base`

change in sharp that wasn't propagated to py!

* fix(objects): add `None` to unit encodings

.circleci/config.yml

@@ -1,15 +1,16 @@
 version: 2.1
 
 orbs:
-  python: circleci/python@1.3.2
+  python: circleci/python@2.0.3
+  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:16.15"
+      - image: "cimg/redis:6.2"
+      - image: "cimg/postgres:14.2"
         environment:
           POSTGRES_DB: speckle2_test
           POSTGRES_PASSWORD: speckle
@@ -26,6 +27,7 @@ jobs:
           STRATEGY_LOCAL: "true"
           CANONICAL_URL: "http://localhost:3000"
           WAIT_HOSTS: localhost:5432, localhost:6379
+          DISABLE_FILE_UPLOADS: "true"
     parameters:
       tag:
         default: "3.8"
@@ -38,11 +40,19 @@ 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:
-      - image: "circleci/python:3.8"
+      - image: "cimg/python:3.8"
     steps:
       - checkout
       - run: python patch_version.py $CIRCLE_TAG
@@ -51,17 +61,17 @@ jobs:
 
 workflows:
   main:
-    jobs: 
+    jobs:
       - test:
           matrix:
             parameters:
-              tag: ["3.6", "3.7", "3.8", "3.9"]
+              tag: ["3.7", "3.8", "3.9", "3.10"]
           filters:
             tags:
               only: /.*/
       - deploy:
           requires:
-            - test 
+            - test
           filters:
             tags:
               only: /[0-9]+(\.[0-9]+)*/

.devcontainer/Dockerfile

@@ -0,0 +1,27 @@
+# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.191.1/containers/python-3/.devcontainer/base.Dockerfile
+
+# [Choice] Python version: 3, 3.9, 3.8, 3.7, 3.6
+ARG VARIANT="3.9"
+FROM mcr.microsoft.com/vscode/devcontainers/python:0-${VARIANT}
+
+# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10
+ARG NODE_VERSION="none"
+RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi
+
+# [Optional] If your pip requirements rarely change, uncomment this section to add them to the image.
+# COPY requirements.txt /tmp/pip-tmp/
+# RUN pip3 --disable-pip-version-check --no-cache-dir install -r /tmp/pip-tmp/requirements.txt \
+#    && rm -rf /tmp/pip-tmp
+
+# [Optional] Uncomment this section to install additional OS packages.
+# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+#     && apt-get -y install --no-install-recommends <your-package-list-here>
+
+# [Optional] Uncomment this line to install global node packages.
+# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1
+
+USER vscode
+
+RUN curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
+
+ENV PATH=$PATH:$HOME/.poetry/env

.devcontainer/devcontainer.json

@@ -0,0 +1,52 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.191.1/containers/python-3
+{
+	"name": "Python 3",
+	// "build": {
+	// 	"dockerfile": "Dockerfile",
+	// 	"context": "..",
+	// 	"args": {
+	// 		// Update 'VARIANT' to pick a Python version: 3, 3.6, 3.7, 3.8, 3.9
+	// 		"VARIANT": "3.6",
+	// 		// Options
+	// 		"NODE_VERSION": "lts/*"
+	// 	}
+	// },
+	"dockerComposeFile": "./docker-compose.yaml",
+	"service": "specklepy",
+	"workspaceFolder": "/workspaces/specklepy",
+	"shutdownAction": "stopCompose",
+	// Set *default* container specific settings.json values on container create.
+	"settings": {
+		"python.pythonPath": "/usr/local/bin/python",
+		"python.languageServer": "Pylance",
+		"python.linting.enabled": true,
+		"python.linting.pylintEnabled": true,
+		"python.formatting.autopep8Path": "/usr/local/py-utils/bin/autopep8",
+		"python.formatting.blackPath": "/usr/local/py-utils/bin/black",
+		"python.formatting.yapfPath": "/usr/local/py-utils/bin/yapf",
+		"python.linting.banditPath": "/usr/local/py-utils/bin/bandit",
+		"python.linting.flake8Path": "/usr/local/py-utils/bin/flake8",
+		"python.linting.mypyPath": "/usr/local/py-utils/bin/mypy",
+		"python.linting.pycodestylePath": "/usr/local/py-utils/bin/pycodestyle",
+		"python.linting.pydocstylePath": "/usr/local/py-utils/bin/pydocstyle",
+		"python.linting.pylintPath": "/usr/local/py-utils/bin/pylint",
+		"python.testing.pytestArgs": [
+			"tests/",
+			"-s"
+		],
+		"python.testing.pytestEnabled": true,
+		"editor.formatOnSave": true,
+	},
+	// Add the IDs of extensions you want installed when the container is created.
+	"extensions": [
+		"ms-python.python",
+		"ms-python.vscode-pylance"
+	],
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+	// Use 'postCreateCommand' to run commands after the container is created.
+	"postCreateCommand": "poetry config virtualenvs.create false && poetry install",
+	// Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+	"remoteUser": "vscode"
+}

.devcontainer/docker-compose.yaml

@@ -0,0 +1,50 @@
+version: "3.3"  # optional since v1.27.0
+services:
+  postgres:
+    image: cimg/postgres:14.2
+    environment:
+      POSTGRES_DB: speckle2_test
+      POSTGRES_PASSWORD: speckle
+      POSTGRES_USER: speckle
+      # ports:
+      #   - "5432:5432"
+    network_mode: host
+  redis:
+    image: cimg/redis:6.2
+    # ports:
+    #   - "6379:6379"
+    network_mode: host
+  speckle-server:
+    image: speckle/speckle-server
+    command: ["bash", "-c", "/wait && node bin/www"]
+    environment:
+      POSTGRES_URL: "localhost"
+      POSTGRES_USER: "speckle"
+      POSTGRES_PASSWORD: "speckle"
+      POSTGRES_DB: "speckle2_test"
+      REDIS_URL: "redis://localhost"
+      SESSION_SECRET: "keyboard cat"
+      STRATEGY_LOCAL: "true"
+      CANONICAL_URL: "http://localhost:3000"
+      WAIT_HOSTS: localhost:5432, localhost:6379
+      DISABLE_FILE_UPLOADS: "true"
+    # ports:
+    #   - "3000:3000"
+    network_mode: host
+
+  specklepy:
+    build:
+      dockerfile: Dockerfile
+      context: .
+      args:
+        VARIANT: 3.9
+        NODE_VERSION: lts/*
+    volumes:
+      # Mounts the project folder to '/workspace'. While this file is in .devcontainer,
+      # mounts are relative to the first file in the list, which is a level up.
+      - ..:/workspaces/specklepy:cached
+    # Overrides default command so things don't shut down after the process ends.
+    command: /bin/sh -c "while sleep 1000; do :; done"
+    network_mode: host
+# networks:
+#     default:

.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.{cmd,[cC][mM][dD]} text eol=crlf
+*.{bat,[bB][aA][tT]} text eol=crlf

.gitignore

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

.vscode/launch.json

@@ -4,6 +4,7 @@
   // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
   "version": "0.2.0",
   "configurations": [
+    
     {
       "name": "Python: Current File",
       "type": "python",
@@ -13,10 +14,13 @@
       "justMyCode": false
     },
     {
-      "name": "Python: Test debug config",
+      "name": "Pytest",
       "type": "python",
-      "request": "test",
+      "request": "launch",
+      "program": "poetry",
+      "args": ["run", "pytest"],
       "console": "integratedTerminal",
+      "justMyCode": true
     }
   ]
 }

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
 

example/many_children.py

@@ -0,0 +1,63 @@
+from typing import List
+from specklepy.objects import Base
+from specklepy.api import operations
+from specklepy.transports.sqlite import SQLiteTransport
+import time
+from pathlib import Path
+import os
+import string
+import random
+
+
+class Sub(Base):
+    bar: List[str]
+
+
+def random_string():
+    letters = string.ascii_lowercase
+    return "".join(random.choice(letters) for _ in range(10))
+
+
+BASE_PATH = SQLiteTransport.get_base_path("Speckle")
+
+
+def clean_db():
+    os.remove(Path(BASE_PATH, "Objects.db"))
+
+
+def one_pass(clean: bool, randomize: bool, child_count: int):
+
+    foo = Base()
+    for i in range(child_count):
+        stuff = random_string() if randomize else "stuff"
+        foo[f"@child_{i}"] = Sub(bar=["asdf", "bar", i, stuff])
+
+    if clean:
+        clean_db()
+    transport = SQLiteTransport()
+    start = time.time()
+    hash = operations.send(base=foo, transports=[transport])
+    send_time = time.time() - start
+
+    receive_start = time.time()
+    operations.receive(hash, transport)
+    receive_time = time.time() - receive_start
+    return send_time, receive_time
+
+
+if __name__ == "__main__":
+    sample_size = 4
+
+    test_permutations = [
+        (True, True),
+        (False, False),
+        (False, True),
+        (True, False),
+    ]
+    for clean, randomize in test_permutations:
+        print(f"CLEAN: {clean}, RANDOMIZE: {randomize}")
+        for child_count in [10, 100, 1000, 10000]:
+            print(f"\tCHILD COUNT: {child_count}")
+            for _ in range(sample_size):
+                send_time, receive_time = one_pass(clean, randomize, child_count)
+                print(f"\t\tSend: {send_time} Receive: {receive_time}")

example/using_speckle_base.py

@@ -50,10 +50,10 @@ if __name__ == "__main__":
     )
     # support for dynamic attributes
     custom_sub.extra_extra = "what is this?"
-    debug(custom_sub.json())
+    debug(custom_sub)
 
     serialized = operations.serialize(custom_sub)
     deserialized = operations.deserialize(serialized)
     # the only difference should be between the two data is that the deserialized
     # instance id attribute is not None.
-    debug(deserialized.json())
+    debug(deserialized)

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>"]
@@ -11,17 +11,20 @@ homepage = "https://speckle.systems/"
 
 
 [tool.poetry.dependencies]
-python = "^3.6.5"
-pydantic = "^1.7.3"
+python = ">=3.7.0, <4.0"
+pydantic = "^1.8.2"
 appdirs = "^1.4.4"
-gql = {version = ">=3.0.0a6", extras = ["all"], allow-prereleases = true}
-ujson = "^4.1.0"
+gql = {extras = ["requests", "websockets"], version = "^3.3.0"}
+ujson = "^5.3.0"
+Deprecated = "^1.2.13"
 
 [tool.poetry.dev-dependencies]
 black = "^20.8b1"
 isort = "^5.7.0"
 pytest = "^6.2.2"
 pytest-ordering = "^0.6"
+pytest-cov = "^3.0.0"
+devtools = "^0.8.0"
 
 
 [tool.black]

specklepy/api/client.py

@@ -1,6 +1,12 @@
 import re
-from gql.client import SyncClientSession
-from specklepy.logging.exceptions import SpeckleException
+from warnings import warn
+from deprecated import deprecated
+from specklepy.api.credentials import Account, get_account_from_token
+from specklepy.logging import metrics
+from specklepy.logging.exceptions import (
+    SpeckleException,
+    SpeckleWarning,
+)
 from typing import Dict
 
 from specklepy.api import resources
@@ -14,9 +20,8 @@ from specklepy.api.resources import (
     subscriptions,
 )
 from specklepy.api.models import ServerInfo
-from gql import Client, gql
+from gql import Client
 from gql.transport.requests import RequestsHTTPTransport
-from gql.transport.aiohttp import AIOHTTPTransport
 from gql.transport.websockets import WebsocketsTransport
 
 
@@ -36,9 +41,9 @@ class SpeckleClient:
     client = SpeckleClient(host="speckle.xyz") # or whatever your host is
     # client = SpeckleClient(host="localhost:3000", use_ssl=False) or use local server
 
-    # authenticate the client with a token (account has been added in Speckle Manager)
+    # authenticate the client with an account (account has been added in Speckle Manager)
     account = get_default_account()
-    client.authenticate(token=account.token)
+    client.authenticate_with_account(account)
 
     # create a new stream. this returns the stream id
     new_stream_id = client.stream.create(name="a shiny new stream")
@@ -52,6 +57,7 @@ class SpeckleClient:
     USE_SSL = True
 
     def __init__(self, host: str = DEFAULT_HOST, use_ssl: bool = USE_SSL) -> None:
+        metrics.track(metrics.CLIENT, custom_props={"name": "create"})
         ws_protocol = "ws"
         http_protocol = "http"
 
@@ -63,9 +69,9 @@ class SpeckleClient:
         host = re.sub(r"((^\w+:|^)\/\/)|(\/$)", "", host)
 
         self.url = f"{http_protocol}://{host}"
-        self.graphql = self.url + "/graphql"
+        self.graphql = f"{self.url}/graphql"
         self.ws_url = f"{ws_protocol}://{host}/graphql"
-        self.me = None
+        self.account = Account()
 
         self.httpclient = Client(
             transport=RequestsHTTPTransport(url=self.graphql, verify=True, retries=3)
@@ -74,19 +80,25 @@ class SpeckleClient:
 
         self._init_resources()
 
-        # Check compatibility with the server
-        try:
-            serverInfo = self.server.get()
-            if not isinstance(serverInfo, ServerInfo):
-                raise Exception("Couldn't get ServerInfo")
-        except Exception as ex:
-            raise SpeckleException(f"{self.url} is not a compatible Speckle Server", ex)
+        # ? Check compatibility with the server - i think we can skip this at this point? save a request
+        # try:
+        #     server_info = self.server.get()
+        #     if isinstance(server_info, Exception):
+        #         raise server_info
+        #     if not isinstance(server_info, ServerInfo):
+        #         raise Exception("Couldn't get ServerInfo")
+        # except Exception as ex:
+        #     raise SpeckleException(
+        #         f"{self.url} is not a compatible Speckle Server", ex
+        #     ) from ex
 
     def __repr__(self):
-        return (
-            f"SpeckleClient( server: {self.url}, authenticated: {self.me is not None} )"
-        )
+        return f"SpeckleClient( server: {self.url}, authenticated: {self.account.token is not None} )"
 
+    @deprecated(
+        version="2.6.0",
+        reason="Renamed: please use `authenticate_with_account` or `authenticate_with_token` instead.",
+    )
     def authenticate(self, token: str) -> None:
         """Authenticate the client using a personal access token
         The token is saved in the client object and a synchronous GraphQL entrypoint is created
@@ -94,9 +106,35 @@ class SpeckleClient:
         Arguments:
             token {str} -- an api token
         """
-        self.me = {"token": token}
+        self.authenticate_with_token(token)
+        self._set_up_client()
+
+    def authenticate_with_token(self, token: str) -> None:
+        """Authenticate the client using a personal access token
+        The token is saved in the client object and a synchronous GraphQL entrypoint is created
+
+        Arguments:
+            token {str} -- an api token
+        """
+        self.account = get_account_from_token(token, self.url)
+        metrics.track(metrics.CLIENT, self.account, {"name": "authenticate with token"})
+        self._set_up_client()
+
+    def authenticate_with_account(self, account: Account) -> None:
+        """Authenticate the client using an Account object
+        The account is saved in the client object and a synchronous GraphQL entrypoint is created
+
+        Arguments:
+            account {Account} -- the account object which can be found with `get_default_account` or `get_local_accounts`
+        """
+        metrics.track(metrics.CLIENT, account, {"name": "authenticate with account"})
+        self.account = account
+        self._set_up_client()
+
+    def _set_up_client(self) -> None:
+        metrics.track(metrics.CLIENT, self.account, {"name": "set up client"})
         headers = {
-            "Authorization": f"Bearer {self.me['token']}",
+            "Authorization": f"Bearer {self.account.token}",
             "Content-Type": "application/json",
         }
         httptransport = RequestsHTTPTransport(
@@ -104,35 +142,44 @@ class SpeckleClient:
         )
         wstransport = WebsocketsTransport(
             url=self.ws_url,
-            init_payload={"Authorization": f"Bearer {self.me['token']}"},
+            init_payload={"Authorization": f"Bearer {self.account.token}"},
         )
         self.httpclient = Client(transport=httptransport)
         self.wsclient = Client(transport=wstransport)
 
         self._init_resources()
 
+        if self.user.get() is None:
+            warn(
+                SpeckleWarning(
+                    f"Possibly invalid token - could not authenticate Speckle Client for server {self.url}"
+                )
+            )
+
     def execute_query(self, query: str) -> Dict:
         return self.httpclient.execute(query)
 
     def _init_resources(self) -> None:
         self.stream = stream.Resource(
-            me=self.me, basepath=self.url, client=self.httpclient
+            account=self.account, basepath=self.url, client=self.httpclient
         )
         self.commit = commit.Resource(
-            me=self.me, basepath=self.url, client=self.httpclient
+            account=self.account, basepath=self.url, client=self.httpclient
         )
         self.branch = branch.Resource(
-            me=self.me, basepath=self.url, client=self.httpclient
+            account=self.account, basepath=self.url, client=self.httpclient
         )
         self.object = object.Resource(
-            me=self.me, basepath=self.url, client=self.httpclient
+            account=self.account, basepath=self.url, client=self.httpclient
         )
         self.server = server.Resource(
-            me=self.me, basepath=self.url, client=self.httpclient
+            account=self.account, basepath=self.url, client=self.httpclient
+        )
+        self.user = user.Resource(
+            account=self.account, basepath=self.url, client=self.httpclient
         )
-        self.user = user.Resource(me=self.me, basepath=self.url, client=self.httpclient)
         self.subscribe = subscriptions.Resource(
-            me=self.me,
+            account=self.account,
             basepath=self.ws_url,
             client=self.wsclient,
         )
@@ -140,7 +187,9 @@ class SpeckleClient:
     def __getattr__(self, name):
         try:
             attr = getattr(resources, name)
-            return attr.Resource(me=self.me, basepath=self.url, client=self.httpclient)
+            return attr.Resource(
+                account=self.account, basepath=self.url, client=self.httpclient
+            )
         except:
             raise SpeckleException(
                 f"Method {name} is not supported by the SpeckleClient class"

specklepy/api/credentials.py

@@ -1,29 +1,25 @@
 import os
-from warnings import warn
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 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
+from specklepy.logging.exceptions import SpeckleException
 
 
 class UserInfo(BaseModel):
-    name: str
-    email: str
+    name: Optional[str]
+    email: Optional[str]
     company: Optional[str]
-    id: str
+    id: Optional[str]
 
 
 class Account(BaseModel):
-    isDefault: bool = None
-    token: str
+    isDefault: bool = False
+    token: str = None
     refreshToken: str = None
-    serverInfo: ServerInfo
-    userInfo: UserInfo
+    serverInfo: ServerInfo = Field(default_factory=ServerInfo)
+    userInfo: UserInfo = Field(default_factory=UserInfo)
     id: str = None
 
     def __repr__(self) -> str:
@@ -32,6 +28,12 @@ class Account(BaseModel):
     def __str__(self) -> str:
         return self.__repr__()
 
+    @classmethod
+    def from_token(cls, token: str, server_url: str = None):
+        acct = cls(token=token)
+        acct.serverInfo.url = server_url
+        return acct
+
 
 def get_local_accounts(base_path: str = None) -> List[Account]:
     """Gets all the accounts present in this environment
@@ -42,7 +44,6 @@ 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)
@@ -63,6 +64,13 @@ def get_local_accounts(base_path: str = None) -> List[Account]:
                 "Invalid json accounts could not be read. Please fix or remove them.",
                 ex,
             )
+    metrics.track(
+        metrics.ACCOUNTS,
+        next(
+            (acc for acc in accounts if acc.isDefault),
+            accounts[0] if accounts else None,
+        ),
+    )
 
     return accounts
 
@@ -75,7 +83,6 @@ 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
@@ -84,103 +91,41 @@ def get_default_account(base_path: str = None) -> Account:
     if not default:
         default = accounts[0]
         default.isDefault = True
+    metrics.initialise_tracker(default)
 
     return default
 
 
-class StreamWrapper:
-    stream_url: str = None
-    use_ssl: bool = True
-    host: str = None
-    stream_id: str = None
-    commit_id: str = None
-    object_id: str = None
-    branch_name: str = None
-    client: SpeckleClient = None
-    account: Account = None
+def get_account_from_token(token: str, server_url: str = None) -> Account:
+    """Gets the local account for the token if it exists
+    Arguments:
+        token {str} -- the api token
 
-    def __repr__(self):
-        return f"StreamWrapper( server: {self.host}, stream_id: {self.stream_id}, type: {self.type} )"
+    Returns:
+        Account -- the local account with this token or a shell account containing just the token and url if no local account is found
+    """
+    accounts = get_local_accounts()
+    if not accounts:
+        return Account.from_token(token, server_url)
 
-    def __str__(self) -> str:
-        return self.__repr__()
+    acct = next((acc for acc in accounts if acc.token == token), None)
+    if acct:
+        return acct
 
-    @property
-    def type(self) -> str:
-        if self.object_id:
-            return "object"
-        elif self.commit_id:
-            return "commit"
-        elif self.branch_name:
-            return "branch"
-        else:
-            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("/")
-
-        if not segments or len(segments) > 4 or len(segments) < 2:
-            raise SpeckleException(
-                f"Cannot parse {url} into a stream wrapper class - invalid URL provided."
-            )
-
-        while segments:
-            segment = segments.pop(0)
-            if segments and segment.lower() == "streams":
-                self.stream_id = segments.pop(0)
-            elif segments and segment.lower() == "commits":
-                self.commit_id = segments.pop(0)
-            elif segments and segment.lower() == "branches":
-                self.branch_name = unquote(segments.pop(0))
-            elif segments and segment.lower() == "objects":
-                self.object_id = segments.pop(0)
-            elif segment.lower() == "globals":
-                self.branch_name = "globals"
-                if segments:
-                    self.commit_id = segments.pop(0)
-            else:
-                raise SpeckleException(
-                    f"Cannot parse {url} into a stream wrapper class - invalid URL provided."
-                )
-
-        if not self.stream_id:
-            raise SpeckleException(
-                f"Cannot parse {url} into a stream wrapper class - no stream id found."
-            )
-
-    def get_account(self) -> Account:
-        if self.account:
-            return self.account
-
-        self.account = next(
-            (a for a in get_local_accounts() if self.host in a.serverInfo.url),
-            None,
+    if server_url:
+        url = server_url.lower()
+        acct = next(
+            (acc for acc in accounts if url in acc.serverInfo.url.lower()), None
         )
+        if acct:
+            return acct
 
-        return self.account
+    return Account.from_token(token, server_url)
 
-    def get_client(self) -> SpeckleClient:
-        if self.client:
-            return self.client
 
-        if not self.account:
-            self.get_account()
-
-        self.client = SpeckleClient(host=self.host, use_ssl=self.use_ssl)
-
-        if self.account is None:
-            warn(f"No local account found for server {self.host}", SpeckleWarning)
-            return self.client
-
-        self.client.authenticate(self.account.token)
-        return self.client
-
-    def get_transport(self) -> ServerTransport:
-        if not self.client:
-            self.get_client()
-        return ServerTransport(self.client, self.stream_id)
+class StreamWrapper:
+    def __init__(self, url: str = None) -> None:
+        raise SpeckleException(
+            message="The StreamWrapper has moved as of v2.6.0! Please import from specklepy.api.wrapper",
+            exception=DeprecationWarning,
+        )

specklepy/api/models.py

@@ -23,14 +23,14 @@ class Commit(BaseModel):
     authorId: Optional[str]
     authorAvatar: Optional[str]
     branchName: Optional[str]
-    createdAt: Optional[str]
+    createdAt: Optional[datetime]
     sourceApplication: Optional[str]
     referencedObject: Optional[str]
     totalChildrenCount: Optional[int]
     parents: Optional[List[str]]
 
     def __repr__(self) -> str:
-        return f"Commit( id: {self.id}, message: {self.message}, referencedObject: {self.referencedObject}, authorName: {self.authorName}, createdAt: {self.createdAt} )"
+        return f"Commit( id: {self.id}, message: {self.message}, referencedObject: {self.referencedObject}, authorName: {self.authorName}, branchName: {self.branchName}, createdAt: {self.createdAt} )"
 
     def __str__(self) -> str:
         return self.__repr__()
@@ -38,7 +38,7 @@ class Commit(BaseModel):
 
 class Commits(BaseModel):
     totalCount: Optional[int]
-    cursor: Optional[Any]
+    cursor: Optional[datetime]
     items: List[Commit] = []
 
 
@@ -47,7 +47,7 @@ class Object(BaseModel):
     speckleType: Optional[str]
     applicationId: Optional[str]
     totalChildrenCount: Optional[int]
-    createdAt: Optional[str]
+    createdAt: Optional[datetime]
 
 
 class Branch(BaseModel):
@@ -66,14 +66,18 @@ class Branches(BaseModel):
 class Stream(BaseModel):
     id: Optional[str]
     name: Optional[str]
-    description: Optional[str]
+    role: Optional[str]
     isPublic: Optional[bool]
-    createdAt: Optional[str]
-    updatedAt: Optional[str]
+    description: Optional[str]
+    createdAt: Optional[datetime]
+    updatedAt: Optional[datetime]
     collaborators: List[Collaborator] = []
     branches: Optional[Branches]
     commit: Optional[Commit]
     object: Optional[Object]
+    commentCount: Optional[int]
+    favoritedDate: Optional[datetime]
+    favoritesCount: Optional[int]
 
     def __repr__(self):
         return f"Stream( id: {self.id}, name: {self.name}, description: {self.description}, isPublic: {self.isPublic})"
@@ -106,6 +110,35 @@ class User(BaseModel):
         return self.__repr__()
 
 
+class Activity(BaseModel):
+    actionType: Optional[str]
+    info: Optional[dict]
+    userId: Optional[str]
+    streamId: Optional[str]
+    resourceId: Optional[str]
+    resourceType: Optional[str]
+    message: Optional[str]
+    time: Optional[datetime]
+
+    def __repr__(self) -> str:
+        return f"Activity( streamId: {self.streamId}, actionType: {self.actionType}, message: {self.message}, userId: {self.userId} )"
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+
+class ActivityCollection(BaseModel):
+    totalCount: Optional[int]
+    items: Optional[List[Activity]]
+    cursor: Optional[datetime]
+
+    def __repr__(self) -> str:
+        return f"ActivityCollection( totalCount: {self.totalCount}, items: {len(self.items) if self.items else 0}, cursor: {self.cursor.isoformat()} )"
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+
 class ServerInfo(BaseModel):
     name: Optional[str]
     company: Optional[str]

specklepy/api/operations.py

@@ -2,6 +2,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
@@ -9,7 +10,7 @@ from specklepy.serialization.base_object_serializer import BaseObjectSerializer
 
 def send(
     base: Base,
-    transports: List[AbstractTransport] = [],
+    transports: List[AbstractTransport] = None,
     use_default_cache: bool = True,
 ):
     """Sends an object via the provided transports. Defaults to the local cache.
@@ -22,24 +23,26 @@ def send(
     Returns:
         str -- the object id of the sent object
     """
-    metrics.track(metrics.RECEIVE)
+
     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"
         )
+
+    if transports is None:
+        metrics.track(metrics.SEND)
+        transports = []
+    else:
+        metrics.track(metrics.SEND, getattr(transports[0], "account", None))
+
     if use_default_cache:
         transports.insert(0, SQLiteTransport())
 
     serializer = BaseObjectSerializer(write_transports=transports)
 
-    for t in transports:
-        t.begin_write()
-    hash, _ = serializer.write_json(base=base)
+    obj_hash, _ = serializer.write_json(base=base)
 
-    for t in transports:
-        t.end_write()
-
-    return hash
+    return obj_hash
 
 
 def receive(
@@ -58,13 +61,13 @@ def receive(
     Returns:
         Base -- the base object
     """
-    metrics.track(metrics.RECEIVE)
+    metrics.track(metrics.RECEIVE, getattr(remote_transport, "account", None))
     if not local_transport:
         local_transport = SQLiteTransport()
 
     serializer = BaseObjectSerializer(read_transport=local_transport)
 
-    # try local transport first. if the parent is there, we assume all the children are there and continue wth deserialisation using the local transport
+    # try local transport first. if the parent is there, we assume all the children are there and continue with deserialisation using the local transport
     obj_string = local_transport.get_object(obj_id)
     if obj_string:
         return serializer.read_json(obj_string=obj_string)

specklepy/api/resource.py

@@ -1,3 +1,4 @@
+from specklepy.api.credentials import Account
 from specklepy.transports.sqlite import SQLiteTransport
 from typing import Dict, List
 from gql.client import Client
@@ -10,13 +11,13 @@ from specklepy.serialization.base_object_serializer import BaseObjectSerializer
 class ResourceBase(object):
     def __init__(
         self,
-        me: Dict,
+        account: Account,
         basepath: str,
         client: Client,
         name: str,
         methods: list,
     ) -> None:
-        self.me = me
+        self.account = account
         self.basepath = basepath
         self.client = client
         self.name = name

specklepy/api/resources/branch.py

@@ -1,9 +1,7 @@
-from specklepy.api.resources import stream
-from typing import List, Optional
 from gql import gql
-from pydantic.main import BaseModel
 from specklepy.api.resource import ResourceBase
 from specklepy.api.models import Branch
+from specklepy.logging import metrics
 
 NAME = "branch"
 METHODS = ["create"]
@@ -12,9 +10,13 @@ METHODS = ["create"]
 class Resource(ResourceBase):
     """API Access class for branches"""
 
-    def __init__(self, me, basepath, client) -> None:
+    def __init__(self, account, basepath, client) -> None:
         super().__init__(
-            me=me, basepath=basepath, client=client, name=NAME, methods=METHODS
+            account=account,
+            basepath=basepath,
+            client=client,
+            name=NAME,
+            methods=METHODS,
         )
         self.schema = Branch
 
@@ -30,7 +32,7 @@ class Resource(ResourceBase):
         Returns:
             id {str} -- the newly created branch's id
         """
-
+        metrics.track(metrics.BRANCH, self.account, {"name": "create"})
         query = gql(
             """
             mutation BranchCreate($branch: BranchCreateInput!) {
@@ -61,7 +63,7 @@ class Resource(ResourceBase):
         Returns:
             Branch -- the fetched branch with its latest commits
         """
-
+        metrics.track(metrics.BRANCH, self.account, {"name": "get"})
         query = gql(
             """
             query BranchGet($stream_id: String!, $name: String!, $commits_limit: Int!) {
@@ -109,6 +111,7 @@ class Resource(ResourceBase):
         Returns:
             List[Branch] -- the branches on the stream
         """
+        metrics.track(metrics.BRANCH, self.account, {"name": "get"})
         query = gql(
             """
             query BranchesGet($stream_id: String!, $branches_limit: Int!, $commits_limit: Int!) {
@@ -161,8 +164,9 @@ class Resource(ResourceBase):
             description {str} -- optional: the updated branch description
 
         Returns:
-            bool -- True if update is successfull
+            bool -- True if update is successful
         """
+        metrics.track(metrics.BRANCH, self.account, {"name": "update"})
         query = gql(
             """
             mutation  BranchUpdate($branch: BranchUpdateInput!) {
@@ -196,7 +200,7 @@ class Resource(ResourceBase):
         Returns:
             bool -- True if deletion is successful
         """
-
+        metrics.track(metrics.BRANCH, self.account, {"name": "delete"})
         query = gql(
             """
             mutation BranchDelete($branch: BranchDeleteInput!) {

specklepy/api/resources/commit.py

@@ -2,6 +2,7 @@ from typing import Optional, List
 from gql import gql
 from specklepy.api.resource import ResourceBase
 from specklepy.api.models import Commit
+from specklepy.logging import metrics
 
 
 NAME = "commit"
@@ -11,9 +12,13 @@ METHODS = []
 class Resource(ResourceBase):
     """API Access class for commits"""
 
-    def __init__(self, me, basepath, client) -> None:
+    def __init__(self, account, basepath, client) -> None:
         super().__init__(
-            me=me, basepath=basepath, client=client, name=NAME, methods=METHODS
+            account=account,
+            basepath=basepath,
+            client=client,
+            name=NAME,
+            methods=METHODS,
         )
         self.schema = Commit
 
@@ -34,8 +39,8 @@ class Resource(ResourceBase):
                 stream(id: $stream_id) {
                     commit(id: $commit_id) {
                         id
-                        referencedObject
                         message
+                        referencedObject
                         authorId
                         authorName
                         authorAvatar
@@ -66,6 +71,7 @@ class Resource(ResourceBase):
         Returns:
             List[Commit] -- a list of the most recent commit objects
         """
+        metrics.track(metrics.COMMIT, self.account, {"name": "get"})
         query = gql(
             """
             query Commits($stream_id: String!, $limit: Int!) {
@@ -79,6 +85,7 @@ class Resource(ResourceBase):
                             authorId
                             authorName
                             authorAvatar
+                            branchName
                             createdAt
                             sourceApplication
                             totalChildrenCount
@@ -118,6 +125,7 @@ class Resource(ResourceBase):
         Returns:
             str -- the id of the created commit
         """
+        metrics.track(metrics.COMMIT, self.account, {"name": "create"})
         query = gql(
             """
             mutation CommitCreate ($commit: CommitCreateInput!){ commitCreate(commit: $commit)}
@@ -151,6 +159,7 @@ class Resource(ResourceBase):
         Returns:
             bool -- True if the operation succeeded
         """
+        metrics.track(metrics.COMMIT, self.account, {"name": "update"})
         query = gql(
             """
             mutation CommitUpdate($commit: CommitUpdateInput!){ commitUpdate(commit: $commit)}
@@ -175,6 +184,7 @@ class Resource(ResourceBase):
         Returns:
             bool -- True if the operation succeeded
         """
+        metrics.track(metrics.COMMIT, self.account, {"name": "delete"})
         query = gql(
             """
             mutation CommitDelete($commit: CommitDeleteInput!){ commitDelete(commit: $commit)}
@@ -185,3 +195,41 @@ 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.
+        """
+        metrics.track(metrics.COMMIT, self.account, {"name": "received"})
+        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/object.py

@@ -1,6 +1,5 @@
 from typing import Dict, List
 from gql import gql
-from graphql.language import parser
 from specklepy.api.resource import ResourceBase
 from specklepy.objects.base import Base
 
@@ -11,9 +10,13 @@ METHODS = []
 class Resource(ResourceBase):
     """API Access class for objects"""
 
-    def __init__(self, me, basepath, client) -> None:
+    def __init__(self, account, basepath, client) -> None:
         super().__init__(
-            me=me, basepath=basepath, client=client, name=NAME, methods=METHODS
+            account=account,
+            basepath=basepath,
+            client=client,
+            name=NAME,
+            methods=METHODS,
         )
         self.schema = Base
 
@@ -49,7 +52,9 @@ class Resource(ResourceBase):
         params = {"stream_id": stream_id, "object_id": object_id}
 
         return self.make_request(
-            query=query, params=params, return_type=["stream", "object", "data"]
+            query=query,
+            params=params,
+            return_type=["stream", "object", "data"],
         )
 
     def create(self, stream_id: str, objects: List[Dict]) -> str:

specklepy/api/resources/server.py

@@ -1,8 +1,8 @@
 from typing import Dict, List
 from gql import gql
-from gql.client import Client
 from specklepy.api.models import ServerInfo
 from specklepy.api.resource import ResourceBase
+from specklepy.logging import metrics
 
 
 NAME = "server"
@@ -12,9 +12,13 @@ METHODS = ["get", "apps"]
 class Resource(ResourceBase):
     """API Access class for the server"""
 
-    def __init__(self, me, basepath, client) -> None:
+    def __init__(self, account, basepath, client) -> None:
         super().__init__(
-            me=me, basepath=basepath, client=client, name=NAME, methods=METHODS
+            account=account,
+            basepath=basepath,
+            client=client,
+            name=NAME,
+            methods=METHODS,
         )
 
     def get(self) -> ServerInfo:
@@ -23,6 +27,7 @@ class Resource(ResourceBase):
         Returns:
             dict -- the server info in dictionary form
         """
+        metrics.track(metrics.SERVER, self.account, {"name": "get"})
         query = gql(
             """
             query Server {
@@ -62,6 +67,7 @@ class Resource(ResourceBase):
         Returns:
             dict -- a dictionary of apps registered on the server
         """
+        metrics.track(metrics.SERVER, self.account, {"name": "apps"})
         query = gql(
             """
             query Apps {
@@ -95,6 +101,7 @@ class Resource(ResourceBase):
         Returns:
             str -- the new API token. note: this is the only time you'll see the token!
         """
+        metrics.track(metrics.SERVER, self.account, {"name": "create_token"})
         query = gql(
             """
             mutation TokenCreate($token: ApiTokenCreateInput!) {
@@ -120,6 +127,7 @@ class Resource(ResourceBase):
         Returns:
             bool -- True if the token was successfully deleted
         """
+        metrics.track(metrics.SERVER, self.account, {"name": "revoke_token"})
         query = gql(
             """
             mutation TokenRevoke($token: String!) {

specklepy/api/resources/stream.py

@@ -1,27 +1,26 @@
+from datetime import datetime, timezone
 from gql import gql
-from typing import Dict, List, Optional
+from typing import List
 from specklepy.logging import metrics
-from specklepy.api.models import Stream
+from specklepy.api.models import ActivityCollection, Stream
 from specklepy.api.resource import ResourceBase
+from specklepy.logging.exceptions import SpeckleException
 
 
 NAME = "stream"
-METHODS = [
-    "list",
-    "create",
-    "get",
-    "update",
-    "delete",
-    "search",
-]
+METHODS = ["list", "create", "get", "update", "delete", "search", "activity"]
 
 
 class Resource(ResourceBase):
     """API Access class for streams"""
 
-    def __init__(self, me, basepath, client) -> None:
+    def __init__(self, account, basepath, client) -> None:
         super().__init__(
-            me=me, basepath=basepath, client=client, name=NAME, methods=METHODS
+            account=account,
+            basepath=basepath,
+            client=client,
+            name=NAME,
+            methods=METHODS,
         )
 
         self.schema = Stream
@@ -37,45 +36,49 @@ class Resource(ResourceBase):
         Returns:
             Stream -- the retrieved stream
         """
-        metrics.track(metrics.STREAM_GET)
+        metrics.track(metrics.STREAM, self.account, {"name": "get"})
         query = gql(
             """
             query Stream($id: String!, $branch_limit: Int!, $commit_limit: Int!) {
-              stream(id: $id) {
-                id
-                name
-                description
-                isPublic
-                createdAt
-                updatedAt
-                collaborators {
-                  id
-                  name
-                  role
-                  avatar
-                }
-                branches(limit: $branch_limit) {
-                  totalCount
-                  cursor
-                  items {
+                stream(id: $id) {
                     id
                     name
+                    role
                     description
-                    commits(limit: $commit_limit) {
-                      totalCount
-                      cursor
-                      items {
+                    isPublic
+                    createdAt
+                    updatedAt
+                    commentCount
+                    favoritesCount
+                    collaborators {
                         id
-                        referencedObject
-                        message
-                        authorName
-                        authorId
-                        createdAt
-                      }
+                        name
+                        role
+                        avatar
                     }
-                  }
+                    branches(limit: $branch_limit) {
+                        totalCount
+                        cursor
+                        items {
+                            id
+                            name
+                            description
+                            commits(limit: $commit_limit) {
+                                totalCount
+                                cursor
+                                items {
+                                    id
+                                    message
+                                    authorId
+                                    createdAt
+                                    authorName
+                                    referencedObject
+                                    sourceApplication
+                                }
+                              }
+                          }
+                      }
                 }
-              }
             }
           """
         )
@@ -93,38 +96,41 @@ class Resource(ResourceBase):
         Returns:
             List[Stream] -- A list of Stream objects
         """
-        metrics.track(metrics.STREAM_LIST)
+        metrics.track(metrics.STREAM, self.account, {"name": "get"})
         query = gql(
             """
             query User($stream_limit: Int!) {
-              user {
-                id
-                email
-                name
-                bio
-                company
-                avatar
-                verified
-                profiles
-                role
-                streams(limit: $stream_limit) {
-                  totalCount
-                  cursor
-                  items {
+                user {
                     id
+                    bio
                     name
-                    description
-                    isPublic
-                    createdAt
-                    updatedAt
-                    collaborators {
-                      id
-                      name
-                      role
-                    }
+                    email
+                    avatar
+                    company
+                    verified
+                    profiles
+                    role
+                    streams(limit: $stream_limit) {
+                        totalCount
+                        cursor
+                        items {
+                            id
+                            name
+                            role
+                            isPublic
+                            createdAt
+                            updatedAt
+                            description
+                            commentCount
+                            favoritesCount
+                            collaborators {
+                                id
+                                name
+                                role
+                            }
+                          }
+                      }
                   }
-                }
-              }
             }
           """
         )
@@ -151,7 +157,7 @@ class Resource(ResourceBase):
         Returns:
             id {str} -- the id of the newly created stream
         """
-        metrics.track(metrics.STREAM_CREATE)
+        metrics.track(metrics.STREAM, self.account, {"name": "create"})
         query = gql(
             """
             mutation StreamCreate($stream: StreamCreateInput!) {
@@ -182,11 +188,11 @@ class Resource(ResourceBase):
         Returns:
             bool -- whether the stream update was successful
         """
-        metrics.track(metrics.STREAM_UPDATE)
+        metrics.track(metrics.STREAM, self.account, {"name": "update"})
         query = gql(
             """
             mutation StreamUpdate($stream: StreamUpdateInput!) {
-              streamUpdate(stream: $stream)
+                streamUpdate(stream: $stream)
             }
         """
         )
@@ -213,13 +219,13 @@ class Resource(ResourceBase):
         Returns:
             bool -- whether the deletion was successful
         """
-        metrics.track(metrics.STREAM_DELETE)
+        metrics.track(metrics.STREAM, self.account, {"name": "delete"})
         query = gql(
             """
             mutation StreamDelete($id: String!) {
-              streamDelete(id: $id)
+                streamDelete(id: $id)
             }
-        """
+            """
         )
 
         params = {"id": id}
@@ -246,47 +252,48 @@ class Resource(ResourceBase):
         Returns:
             List[Stream] -- a list of Streams that match the search query
         """
-        metrics.track(metrics.STREAM_SEARCH)
+        metrics.track(metrics.STREAM, self.account, {"name": "search"})
         query = gql(
             """
             query StreamSearch($search_query: String!,$limit: Int!, $branch_limit:Int!, $commit_limit:Int!) {
-              streams(query: $search_query, limit: $limit) {
-                items {
-                  id
-                  name
-                  description
-                  isPublic
-                  createdAt
-                  updatedAt
-                  collaborators {
-                    id
-                    name
-                    role
-                    avatar
-                  }
-                  branches(limit: $branch_limit) {
-                    totalCount
-                    cursor
+                streams(query: $search_query, limit: $limit) {
                     items {
-                      id
-                      name
-                      description
-                      commits(limit: $commit_limit) {
-                        totalCount
-                        cursor
-                        items {
-                          id
-                          referencedObject
-                          message
-                          authorName
-                          authorId
-                          createdAt
+                        id
+                        name
+                        role
+                        description
+                        isPublic
+                        createdAt
+                        updatedAt
+                        collaborators {
+                            id
+                            name
+                            role
+                            avatar
+                        }
+                        branches(limit: $branch_limit) {
+                            totalCount
+                            cursor
+                            items {
+                                id
+                                name
+                                description
+                                commits(limit: $commit_limit) {
+                                    totalCount
+                                    cursor
+                                    items {
+                                        id
+                                        referencedObject
+                                        message
+                                        authorName
+                                        authorId
+                                        createdAt
+                                    }
+                                }
+                            }
                         }
-                      }
                     }
-                  }
                 }
-              }
             }
           """
         )
@@ -302,6 +309,39 @@ class Resource(ResourceBase):
             query=query, params=params, return_type=["streams", "items"]
         )
 
+    def favorite(self, stream_id: str, favorited: bool = True):
+        """Favorite or unfavorite the given stream.
+
+        Arguments:
+            stream_id {str} -- the id of the stream to favorite / unfavorite
+            favorited {bool} -- whether to favorite (True) or unfavorite (False) the stream
+
+        Returns:
+            Stream -- the stream with its `id`, `name`, and `favoritedDate`
+        """
+        metrics.track(metrics.STREAM, self.account, {"name": "favorite"})
+        query = gql(
+            """
+            mutation StreamFavorite($stream_id: String!, $favorited: Boolean!) {
+                streamFavorite(streamId: $stream_id, favorited: $favorited) {
+                    id
+                    name
+                    favoritedDate
+                    favoritesCount
+                }
+            }
+            """
+        )
+
+        params = {
+            "stream_id": stream_id,
+            "favorited": favorited,
+        }
+
+        return self.make_request(
+            query=query, params=params, return_type=["streamFavorite"]
+        )
+
     def grant_permission(self, stream_id: str, user_id: str, role: str):
         """Grant permissions to a user on a given stream
 
@@ -313,6 +353,7 @@ class Resource(ResourceBase):
         Returns:
             bool -- True if the operation was successful
         """
+        metrics.track(metrics.PERMISSION, self.account, {"name": "add", "role": role})
         query = gql(
             """
             mutation StreamGrantPermission($permission_params: StreamGrantPermissionInput !) {
@@ -346,6 +387,7 @@ class Resource(ResourceBase):
         Returns:
             bool -- True if the operation was successful
         """
+        metrics.track(metrics.PERMISSION, self.account, {"name": "revoke"})
         query = gql(
             """
             mutation StreamRevokePermission($permission_params: StreamRevokePermissionInput !) {
@@ -362,3 +404,72 @@ class Resource(ResourceBase):
             return_type="streamRevokePermission",
             parse_response=False,
         )
+
+    def activity(
+        self,
+        stream_id: str,
+        action_type: str = None,
+        limit: int = 20,
+        before: datetime = None,
+        after: datetime = None,
+        cursor: datetime = None,
+    ):
+        """
+        Get the activity from a given stream in an Activity collection. Step into the activity `items` for the list of activity.
+
+        Note: all timestamps arguments should be `datetime` of any tz as they will be converted to UTC ISO format strings
+
+        stream_id {str} -- the id of the stream to get activity from
+        action_type {str} -- filter results to a single action type (eg: `commit_create` or `commit_receive`)
+        limit {int} -- max number of Activity items to return
+        before {datetime} -- latest cutoff for activity (ie: return all activity _before_ this time)
+        after {datetime} -- oldest cutoff for activity (ie: return all activity _after_ this time)
+        cursor {datetime} -- timestamp cursor for pagination
+        """
+        query = gql(
+            """
+            query StreamActivity($stream_id: String!, $action_type: String, $before:DateTime, $after: DateTime, $cursor: DateTime, $limit: Int){
+                stream(id: $stream_id) {
+                    activity(actionType: $action_type, before: $before, after: $after, cursor: $cursor, limit: $limit) {
+                        totalCount
+                        cursor
+                        items {
+                            actionType
+                            info
+                            userId
+                            streamId
+                            resourceId
+                            resourceType
+                            message
+                            time
+                        }
+                    }
+                }
+            }
+            """
+        )
+        try:
+            params = {
+                "stream_id": stream_id,
+                "limit": limit,
+                "action_type": action_type,
+                "before": before.astimezone(timezone.utc).isoformat()
+                if before
+                else before,
+                "after": after.astimezone(timezone.utc).isoformat() if after else after,
+                "cursor": cursor.astimezone(timezone.utc).isoformat()
+                if cursor
+                else cursor,
+            }
+        except AttributeError as e:
+            raise SpeckleException(
+                "Could not get stream activity - `before`, `after`, and `cursor` must be in `datetime` format if provided",
+                ValueError,
+            ) from e
+
+        return self.make_request(
+            query=query,
+            params=params,
+            return_type=["stream", "activity"],
+            schema=ActivityCollection,
+        )

specklepy/api/resources/subscriptions.py

@@ -1,9 +1,9 @@
-from typing import Callable, Dict, List, Optional, Any
+from typing import Callable, Dict, List
 from functools import wraps
 from gql import gql
 from specklepy.api.resource import ResourceBase
 from specklepy.api.resources.stream import Stream
-from specklepy.logging.exceptions import GraphQLException, SpeckleException
+from specklepy.logging.exceptions import SpeckleException
 
 NAME = "subscribe"
 METHODS = [
@@ -29,9 +29,13 @@ def check_wsclient(function):
 class Resource(ResourceBase):
     """API Access class for subscriptions"""
 
-    def __init__(self, me, basepath, client) -> None:
+    def __init__(self, account, basepath, client) -> None:
         super().__init__(
-            me=me, basepath=basepath, client=client, name=NAME, methods=METHODS
+            account=account,
+            basepath=basepath,
+            client=client,
+            name=NAME,
+            methods=METHODS,
         )
 
     @check_wsclient

specklepy/api/resources/user.py

@@ -1,20 +1,25 @@
+from datetime import datetime, timezone
+from specklepy.logging import metrics
 from specklepy.logging.exceptions import SpeckleException
-from typing import List, Optional
+from typing import List
 from gql import gql
-from pydantic.main import BaseModel
 from specklepy.api.resource import ResourceBase
-from specklepy.api.models import User
+from specklepy.api.models import ActivityCollection, User
 
 NAME = "user"
-METHODS = ["get"]
+METHODS = ["get", "search", "update", "activity"]
 
 
 class Resource(ResourceBase):
     """API Access class for users"""
 
-    def __init__(self, me, basepath, client) -> None:
+    def __init__(self, account, basepath, client) -> None:
         super().__init__(
-            me=me, basepath=basepath, client=client, name=NAME, methods=METHODS
+            account=account,
+            basepath=basepath,
+            client=client,
+            name=NAME,
+            methods=METHODS,
         )
         self.schema = User
 
@@ -27,6 +32,7 @@ class Resource(ResourceBase):
         Returns:
             User -- the retrieved user
         """
+        metrics.track(metrics.USER, self.account, {"name": "get"})
         query = gql(
             """
             query User($id: String) {
@@ -63,6 +69,7 @@ class Resource(ResourceBase):
                 message="User search query must be at least 3 characters"
             )
 
+        metrics.track(metrics.USER, self.account, {"name": "search"})
         query = gql(
             """
             query UserSearch($search_query: String!, $limit: Int!) {
@@ -99,6 +106,7 @@ class Resource(ResourceBase):
         Returns:
             bool -- True if your profile was updated successfully
         """
+        metrics.track(metrics.USER, self.account, {"name": "update"})
         query = gql(
             """
             mutation UserUpdate($user: UserUpdateInput!) {
@@ -118,3 +126,65 @@ class Resource(ResourceBase):
         return self.make_request(
             query=query, params=params, return_type="userUpdate", parse_response=False
         )
+
+    def activity(
+        self,
+        user_id: str = None,
+        limit: int = 20,
+        action_type: str = None,
+        before: datetime = None,
+        after: datetime = None,
+        cursor: datetime = None,
+    ):
+        """
+        Get the activity from a given stream in an Activity collection. Step into the activity `items` for the list of activity.
+        If no id argument is provided, will return the current authenticated user's activity (as extracted from the authorization header).
+
+        Note: all timestamps arguments should be `datetime` of any tz as they will be converted to UTC ISO format strings
+
+        user_id {str} -- the id of the user to get the activity from
+        action_type {str} -- filter results to a single action type (eg: `commit_create` or `commit_receive`)
+        limit {int} -- max number of Activity items to return
+        before {datetime} -- latest cutoff for activity (ie: return all activity _before_ this time)
+        after {datetime} -- oldest cutoff for activity (ie: return all activity _after_ this time)
+        cursor {datetime} -- timestamp cursor for pagination
+        """
+
+        query = gql(
+            """
+            query UserActivity($user_id: String, $action_type: String, $before:DateTime, $after: DateTime, $cursor: DateTime, $limit: Int){
+                user(id: $user_id) {
+                    activity(actionType: $action_type, before: $before, after: $after, cursor: $cursor, limit: $limit) {
+                        totalCount
+                        cursor
+                        items {
+                            actionType
+                            info
+                            userId
+                            streamId
+                            resourceId
+                            resourceType
+                            message
+                            time
+                        }
+                    }
+                }
+            }
+            """
+        )
+
+        params = {
+            "user_id": user_id,
+            "limit": limit,
+            "action_type": action_type,
+            "before": before.astimezone(timezone.utc).isoformat() if before else before,
+            "after": after.astimezone(timezone.utc).isoformat() if after else after,
+            "cursor": cursor.astimezone(timezone.utc).isoformat() if cursor else cursor,
+        }
+
+        return self.make_request(
+            query=query,
+            params=params,
+            return_type=["user", "activity"],
+            schema=ActivityCollection,
+        )

specklepy/api/speckle2schema.graphql

@@ -445,7 +445,7 @@ input ServerInfoUpdateInput {
   stream( id: String! ): Stream
 
   """
-  All the streams of the current user, pass in the `query` parameter to seach by name, description or ID.
+  All the streams of the current user, pass in the `query` parameter to search by name, description or ID.
   """
   streams( query: String, limit: Int = 25, cursor: String ): StreamCollection
     @hasScope(scope: "streams:read")

specklepy/api/wrapper.py

@@ -0,0 +1,166 @@
+from warnings import warn
+from urllib.parse import urlparse, unquote
+from specklepy.api.credentials import (
+    Account,
+    get_account_from_token,
+    get_local_accounts,
+)
+from specklepy.logging import metrics
+from specklepy.api.client import SpeckleClient
+from specklepy.transports.server.server import ServerTransport
+from specklepy.logging.exceptions import SpeckleException, SpeckleWarning
+
+
+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.wrapper 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
+    stream_id: str = None
+    commit_id: str = None
+    object_id: str = None
+    branch_name: str = None
+    _client: SpeckleClient = None
+    _account: Account = None
+
+    def __repr__(self):
+        return f"StreamWrapper( server: {self.host}, stream_id: {self.stream_id}, type: {self.type} )"
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    @property
+    def type(self) -> str:
+        if self.object_id:
+            return "object"
+        elif self.commit_id:
+            return "commit"
+        elif self.branch_name:
+            return "branch"
+        else:
+            return "stream" if self.stream_id else "invalid"
+
+    def __init__(self, url: str) -> None:
+        self.stream_url = url
+        parsed = urlparse(url)
+        self.host = parsed.netloc
+        self.use_ssl = parsed.scheme == "https"
+        segments = parsed.path.strip("/").split("/", 3)
+        metrics.track(metrics.STREAM_WRAPPER, self.get_account())
+
+        if not segments or len(segments) < 2:
+            raise SpeckleException(
+                f"Cannot parse {url} into a stream wrapper class - invalid URL provided."
+            )
+
+        while segments:
+            segment = segments.pop(0)
+            if segments and segment.lower() == "streams":
+                self.stream_id = segments.pop(0)
+            elif segments and segment.lower() == "commits":
+                self.commit_id = segments.pop(0)
+            elif segments and segment.lower() == "branches":
+                self.branch_name = unquote(segments.pop(0))
+            elif segments and segment.lower() == "objects":
+                self.object_id = segments.pop(0)
+            elif segment.lower() == "globals":
+                self.branch_name = "globals"
+                if segments:
+                    self.commit_id = segments.pop(0)
+            else:
+                raise SpeckleException(
+                    f"Cannot parse {url} into a stream wrapper class - invalid URL provided."
+                )
+
+        if not self.stream_id:
+            raise SpeckleException(
+                f"Cannot parse {url} into a stream wrapper class - no stream id found."
+            )
+
+    @property
+    def server_url(self):
+        return f"{'https' if self.use_ssl else 'http'}://{self.host}"
+
+    def get_account(self, token: str = None) -> Account:
+        """
+        Gets an account object for this server from the local accounts db (added via Speckle Manager or a json file)
+        """
+        if self._account and self._account.token:
+            return self._account
+
+        self._account = next(
+            (a for a in get_local_accounts() if self.host in a.serverInfo.url),
+            None,
+        )
+
+        if not self._account:
+            self._account = get_account_from_token(token, self.server_url)
+
+        if self._client:
+            self._client.authenticate_with_account(self._account)
+
+        return self._account
+
+    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 or not self._account.token:
+            self.get_account(token)
+
+        if not self._client:
+            self._client = SpeckleClient(host=self.host, use_ssl=self.use_ssl)
+
+        if self._account.token is None and token is None:
+            warn(f"No local account found for server {self.host}", SpeckleWarning)
+            return self._client
+
+        if self._account.token:
+            self._client.authenticate_with_account(self._account)
+        else:
+            self._client.authenticate_with_token(token)
+
+        return self._client
+
+    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._account or not self._account.token:
+            self.get_account(token)
+        return ServerTransport(self.stream_id, account=self._account)

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

@@ -1,10 +1,10 @@
-import os
+import socket
+import sys
 import queue
+import hashlib
 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.
@@ -12,25 +12,25 @@ This really helps us to deliver a better open source project and product!
 """
 TRACK = True
 HOST_APP = "python"
+HOST_APP_VERSION = f"python {'.'.join(map(str, sys.version_info[:3]))}"
+PLATFORMS = {"win32": "Windows", "cygwin": "Windows", "darwin": "Mac OS X"}
 
 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"
+RECEIVE = "Receive"
+SEND = "Send"
+STREAM = "Stream Action"
+PERMISSION = "Permission Action"
+COMMIT = "Commit Action"
+BRANCH = "Branch Action"
+USER = "User Action"
+SERVER = "Server Action"
+CLIENT = "Speckle Client"
+STREAM_WRAPPER = "Stream Wrapper"
 
-ACCOUNT_DEFAULT = "account/default"
-ACCOUNT_DETAILS = "account/details"
-ACCOUNT_LIST = "account/list"
+ACCOUNTS = "Get Local Accounts"
 
 SERIALIZE = "serialization/serialize"
 DESERIALIZE = "serialization/deserialize"
@@ -41,44 +41,54 @@ def disable():
     TRACK = False
 
 
-def set_host_app(host_app: str):
-    global HOST_APP
+def enable():
+    global TRACK
+    TRACK = True
+
+
+def set_host_app(host_app: str, host_app_version: str = None):
+    global HOST_APP, HOST_APP_VERSION
     HOST_APP = host_app
+    HOST_APP_VERSION = host_app_version or HOST_APP_VERSION
 
 
-def track(action: str):
+def track(action: str, account: "Account" = None, custom_props: dict = None):
     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]},
-        }
-
+        initialise_tracker(account)
         event_params = {
-            "rec": 1,
-            "idsite": METRICS_TRACKER.site_id,
-            "uid": MetricsTracker.suuid,
-            "_cvar": {"1": ["hostApplication", HOST_APP]},
-            "e_c": HOST_APP,
-            "e_a": action,
+            "event": action,
+            "properties": {
+                "distinct_id": METRICS_TRACKER.last_user,
+                "server_id": METRICS_TRACKER.last_server,
+                "token": METRICS_TRACKER.analytics_token,
+                "hostApp": HOST_APP,
+                "hostAppVersion": HOST_APP_VERSION,
+                "$os": METRICS_TRACKER.platform,
+                "type": "action",
+            },
         }
+        if custom_props:
+            event_params["properties"].update(custom_props)
 
-        METRICS_TRACKER.queue.put_nowait([event_params, page_params])
+        METRICS_TRACKER.queue.put_nowait(event_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))
 
 
+def initialise_tracker(account: "Account" = None):
+    global METRICS_TRACKER
+    if not METRICS_TRACKER:
+        METRICS_TRACKER = MetricsTracker()
+
+    if account and account.userInfo.email:
+        METRICS_TRACKER.set_last_user(account.userInfo.email)
+    if account and account.serverInfo.url:
+        METRICS_TRACKER.set_last_server(account.userInfo.email)
+
+
 class Singleton(type):
     _instances = {}
 
@@ -89,10 +99,11 @@ class Singleton(type):
 
 
 class MetricsTracker(metaclass=Singleton):
-    matomo_url = "https://speckle.matomo.cloud/matomo.php"
-    site_id = 2
-    host_app = "python"
-    suuid = None
+    analytics_url = "https://analytics.speckle.systems/track?ip=1"
+    analytics_token = "acd87c5a50b56df91a795e999812a3a4"
+    last_user = None
+    last_server = None
+    platform = None
     sending_thread = None
     queue = queue.Queue(1000)
 
@@ -100,26 +111,30 @@ class MetricsTracker(metaclass=Singleton):
         self.sending_thread = threading.Thread(
             target=self._send_tracking_requests, daemon=True
         )
-        self.set_suuid()
+        self.platform = PLATFORMS.get(sys.platform, "linux")
         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 set_last_user(self, email: str):
+        if not email:
+            return
+        self.last_user = "@" + self.hash(email)
+
+    def set_last_server(self, server: str):
+        if not server:
+            return
+        self.last_server = self.hash(server)
+
+    def hash(self, value: str):
+        return hashlib.md5(value.lower().encode("utf-8")).hexdigest().upper()
 
     def _send_tracking_requests(self):
         session = requests.Session()
         while True:
-            params = self.queue.get()
+            event_params = [self.queue.get()]
 
             try:
-                session.post(self.matomo_url, params=params[0])
-                session.post(self.matomo_url, params=params[1])
+                session.post(self.analytics_url, json=event_params)
             except Exception as ex:
                 LOG.error("Error sending metrics request: " + str(ex))
 
-            self.queue.task_done()
+            self.queue.task_done()

specklepy/objects/base.py

@@ -1,6 +1,17 @@
-import typing
-from typing import (Any, Callable, ClassVar, Dict, List, Optional, Set, Type,
-                    get_type_hints)
+from typing import (
+    Any,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Union,
+    Set,
+    Type,
+    get_type_hints,
+)
+
+import contextlib
+from enum import EnumMeta
 from warnings import warn
 
 from specklepy.logging.exceptions import SpeckleException
@@ -118,14 +129,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)
 
 
@@ -133,7 +142,7 @@ class Base(_RegisteringBase):
     id: Optional[str] = None
     totalChildrenCount: Optional[int] = None
     applicationId: Optional[str] = None
-    _units: str = "m"
+    _units: str = None
     # dict of chunkable props and their max chunk size
     _chunkable: Dict[str, int] = {}
     _chunk_size_default: int = 1000
@@ -200,7 +209,7 @@ class Base(_RegisteringBase):
             try:
                 attr.__set__(self, value)
             except AttributeError:
-                pass  # the prop probably doesn't have a setter
+                return  # the prop probably doesn't have a setter
         super().__setattr__(name, value)
 
     @classmethod
@@ -215,15 +224,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 '@'",
@@ -244,12 +251,23 @@ class Base(_RegisteringBase):
         types = getattr(self, "_attr_types", {})
         t = types.get(name, None)
 
-        if t is None:
+        if t is None or t is Any:
             return value
 
+        if value is None:
+            return None
+
+        if isinstance(t, EnumMeta) and (value in t._value2member_map_):
+            return t(value)
+
         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 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 +278,14 @@ 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]
+
+        with contextlib.suppress(ValueError):
+            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)
 
         raise SpeckleException(
             f"Cannot set '{self.__class__.__name__}.{name}': it expects type '{t.__name__}', but received type '{type(value).__name__}'"
@@ -297,7 +316,9 @@ class Base(_RegisteringBase):
 
     @units.setter
     def units(self, value: str):
-        self._units = get_units_from_string(value)
+        units = get_units_from_string(value)
+        if units:
+            self._units = units
 
     def get_member_names(self) -> List[str]:
         """Get all of the property names on this object, dynamic or not"""
@@ -327,7 +348,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 +359,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:
@@ -388,4 +409,5 @@ class DataChunk(Base, speckle_type="Speckle.Core.Models.DataChunk"):
     data: List[Any] = None
 
     def __init__(self) -> None:
+        super().__init__()
         self.data = []

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 = int(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/fakemesh.py

@@ -1,5 +1,6 @@
-from specklepy.objects.geometry import Point
+from enum import Enum
 from typing import List
+from specklepy.objects.geometry import Point
 
 from .base import Base
 
@@ -19,11 +20,19 @@ class FakeGeo(Base, chunkable={"dots": 50}, detachable={"pointslist"}):
     dots: List[int] = None
 
 
+class FakeDirection(Enum):
+    NORTH = 1
+    EAST = 2
+    SOUTH = 3
+    WEST = 4
+
+
 class FakeMesh(FakeGeo, chunkable=CHUNKABLE_PROPS, detachable=DETACHABLE):
     vertices: List[float] = None
     faces: List[int] = None
     colors: List[int] = None
     textureCoordinates: List[float] = None
+    cardinal_dir: FakeDirection = None
     test_bases: List[Base] = None
     detach_this: Base = None
     detached_list: List[Base] = None

specklepy/objects/geometry.py

@@ -33,6 +33,7 @@ class Point(Base, speckle_type=GEOMETRY + "Point"):
 
     @classmethod
     def from_list(cls, args: List[float]) -> "Point":
+        """Create a new Point from a list of three floats representing the x, y, and z coordinates"""
         return cls(x=args[0], y=args[1], z=args[2])
 
     def to_list(self) -> List[Any]:
@@ -40,6 +41,7 @@ class Point(Base, speckle_type=GEOMETRY + "Point"):
 
     @classmethod
     def from_coords(cls, x: float = 0.0, y: float = 0.0, z: float = 0.0):
+        """Create a new Point from x, y, and z values"""
         pt = Point()
         pt.x, pt.y, pt.z = x, y, z
         return pt
@@ -216,6 +218,7 @@ class Polyline(Base, speckle_type=GEOMETRY + "Polyline", chunkable={"value": 200
 
     @classmethod
     def from_points(cls, points: List[Point]):
+        """Create a new Polyline from a list of Points"""
         polyline = cls()
         polyline.units = points[0].units
         polyline.value = []
@@ -290,9 +293,9 @@ class Curve(
 
     @classmethod
     def from_list(cls, args: List[Any]) -> "Curve":
-        point_count = args[7]
-        weights_count = args[8]
-        knots_count = args[9]
+        point_count = int(args[7])
+        weights_count = int(args[8])
+        knots_count = int(args[9])
 
         points_start = 10
         weights_start = 10 + point_count
@@ -300,7 +303,7 @@ class Curve(
         knots_end = knots_start + knots_count
 
         return cls(
-            degree=args[1],
+            degree=int(args[1]),
             periodic=bool(args[2]),
             rational=bool(args[3]),
             closed=bool(args[4]),
@@ -391,6 +394,28 @@ class Mesh(
     area: float = None
     volume: float = None
 
+    @classmethod
+    def create(
+        cls,
+        vertices: List[float],
+        faces: List[int],
+        colors: List[int] = None,
+        texture_coordinates: List[float] = None,
+    ) -> "Mesh":
+        """
+        Create a new Mesh from lists representing its vertices, faces,
+        colors (optional), and texture coordinates (optional).
+
+        This will initialise empty lists for colors and texture coordinates
+        if you do not provide any.
+        """
+        return cls(
+            vertices=vertices,
+            faces=faces,
+            colors=colors or [],
+            textureCoordinates=texture_coordinates or [],
+        )
+
 
 class Surface(Base, speckle_type=GEOMETRY + "Surface"):
     degreeU: int = None
@@ -607,7 +632,7 @@ class Brep(
     bbox: Box = None
     area: float = None
     volume: float = None
-    displayValue: Mesh = None
+    _displayValue: List[Mesh] = None
     Surfaces: List[Surface] = None
     Curve3D: List[Base] = None
     Curve2D: List[Base] = None
@@ -623,6 +648,18 @@ class Brep(
             child._Brep = self
         return children
 
+    # set as prop for now for backwards compatibility
+    @property
+    def displayValue(self) -> List[Mesh]:
+        return self._displayValue
+
+    @displayValue.setter
+    def displayValue(self, value):
+        if isinstance(value, Mesh):
+            self._displayValue = [value]
+        elif isinstance(value, list):
+            self._displayValue = value
+
     @property
     def Edges(self) -> List[BrepEdge]:
         return self._inject_self_into_children(self._Edges)

specklepy/objects/other.py

@@ -1,7 +1,28 @@
+from typing import Any, List
+from specklepy.objects.geometry import Point, Vector
 from .base import Base
 
 OTHER = "Objects.Other."
 
+IDENTITY_TRANSFORM = [
+    1.0,
+    0.0,
+    0.0,
+    0.0,
+    0.0,
+    1.0,
+    0.0,
+    0.0,
+    0.0,
+    0.0,
+    1.0,
+    0.0,
+    0.0,
+    0.0,
+    0.0,
+    1.0,
+]
+
 
 class RenderMaterial(Base, speckle_type=OTHER + "RenderMaterial"):
     name: str = None
@@ -10,3 +31,184 @@ class RenderMaterial(Base, speckle_type=OTHER + "RenderMaterial"):
     roughness: float = 1
     diffuse: int = -2894893  # light gray arbg
     emissive: int = -16777216  # black arbg
+
+
+class Transform(
+    Base,
+    speckle_type=OTHER + "Transform",
+    serialize_ignore={"translation", "scaling", "is_identity"},
+):
+    """The 4x4 transformation matrix
+
+    The 3x3 sub-matrix determines scaling.
+    The 4th column defines translation, where the last value is a divisor (usually equal to 1).
+    """
+
+    _value: List[float] = None
+
+    @property
+    def value(self) -> List[float]:
+        """The transform matrix represented as a flat list of 16 floats"""
+        return self._value
+
+    @value.setter
+    def value(self, value: List[float]) -> None:
+        try:
+            value = [float(x) for x in value]
+        except (ValueError, TypeError) as error:
+            raise ValueError(
+                f"Could not create a Transform object with the requested value. Input must be a 16 element list of numbers. Value provided: {value}"
+            ) from error
+
+        if len(value) != 16:
+            raise ValueError(
+                f"Could not create a Transform object: input list should be 16 floats long, but was {len(value)} long"
+            )
+
+        self._value = value
+
+    @property
+    def translation(self) -> List[float]:
+        """The final column of the matrix which defines the translation"""
+        return [self._value[i] for i in (3, 7, 11, 15)]
+
+    @property
+    def scaling(self) -> List[float]:
+        """The 3x3 scaling sub-matrix"""
+        return [self._value[i] for i in (0, 1, 2, 4, 5, 6, 8, 9, 10)]
+
+    @property
+    def is_identity(self) -> bool:
+        return self.value == IDENTITY_TRANSFORM
+
+    def apply_to_point(self, point: Point) -> Point:
+        """Transform a single speckle Point
+
+        Arguments:
+            point {Point} -- the speckle Point to transform
+
+        Returns:
+            Point -- a new transformed point
+        """
+        coords = self.apply_to_point_value([point.x, point.y, point.z])
+        return Point(x=coords[0], y=coords[1], z=coords[2], units=point.units)
+
+    def apply_to_point_value(self, point_value: List[float]) -> List[float]:
+        """Transform a list of three floats representing a point
+
+        Arguments:
+            point_value {List[float]} -- a list of 3 floats
+
+        Returns:
+            List[float] -- the list with the transform applied
+        """
+        transformed = [
+            point_value[0] * self._value[i]
+            + point_value[1] * self._value[i + 1]
+            + point_value[2] * self._value[i + 2]
+            + self._value[i + 3]
+            for i in range(0, 15, 4)
+        ]
+
+        return [transformed[i] / transformed[3] for i in range(3)]
+
+    def apply_to_points(self, points: List[Point]) -> List[Point]:
+        """Transform a list of speckle Points
+
+        Arguments:
+            points {List[Point]} -- the list of speckle Points to transform
+
+        Returns:
+            List[Point] -- a new list of transformed points
+        """
+        return [self.apply_to_point(point) for point in points]
+
+    def apply_to_points_values(self, points_value: List[float]) -> List[float]:
+        """Transform a list of speckle Points
+
+        Arguments:
+            points {List[float]} -- a flat list of floats representing points to transform
+
+        Returns:
+            List[float] -- a new transformed list
+        """
+        if len(points_value) % 3 != 0:
+            raise ValueError(
+                "Cannot apply transform as the points list is malformed: expected length to be multiple of 3"
+            )
+        transformed = []
+        for i in range(0, len(points_value), 3):
+            transformed.extend(self.apply_to_point_value(points_value[i : i + 3]))
+
+        return transformed
+
+    def apply_to_vector(self, vector: Vector) -> Vector:
+        """Transform a single speckle Vector
+
+        Arguments:
+            point {Vector} -- the speckle Vector to transform
+
+        Returns:
+            Vector -- a new transformed point
+        """
+        coords = self.apply_to_vector_value([vector.x, vector.y, vector.z])
+        return Vector(x=coords[0], y=coords[1], z=coords[2], units=vector.units)
+
+    def apply_to_vector_value(self, vector_value: List[float]) -> List[float]:
+        """Transform a list of three floats representing a vector
+
+        Arguments:
+            vector_value {List[float]} -- a list of 3 floats
+
+        Returns:
+            List[float] -- the list with the transform applied
+        """
+        return [
+            vector_value[0] * self._value[i]
+            + vector_value[1] * self._value[i + 1]
+            + vector_value[2] * self._value[i + 2]
+            for i in range(0, 15, 4)
+        ][:3]
+
+    @classmethod
+    def from_list(cls, value: List[float] = None) -> "Transform":
+        """Returns a Transform object from a list of 16 numbers. If no value is provided, an identity transform will be returned.
+
+        Arguments:
+            value {List[float]} -- the matrix as a flat list of 16 numbers (defaults to the identity transform)
+
+        Returns:
+            Transform -- a complete transform object
+        """
+        if not value:
+            value = IDENTITY_TRANSFORM
+        return cls(value=value)
+
+
+class BlockDefinition(
+    Base, speckle_type=OTHER + "BlockDefinition", detachable={"geometry"}
+):
+    name: str = None
+    basePoint: Point = None
+    geometry: List[Base] = None
+
+
+class BlockInstance(
+    Base, speckle_type=OTHER + "BlockInstance", detachable={"blockDefinition"}
+):
+    blockDefinition: BlockDefinition = None
+    transform: Transform = None
+
+
+# TODO: prob move this into a built elements module, but just trialling this for now
+class RevitParameter(Base, speckle_type="Objects.BuiltElements.Revit.Parameter"):
+    name: str = None
+    value: Any = None
+    applicationUnitType: str = None  # eg UnitType UT_Length
+    applicationUnit: str = None  # DisplayUnitType eg DUT_MILLIMITERS
+    applicationInternalName: str = (
+        None  # BuiltInParameterName or GUID for shared parameter
+    )
+    isShared: bool = False
+    isReadOnly: bool = False
+    isTypeParameter: bool = False

specklepy/objects/structural/__init__.py

@@ -0,0 +1,40 @@
+"""Builtin Speckle object kit."""
+
+from specklepy.objects.structural.analysis import *
+from specklepy.objects.structural.properties import *
+from specklepy.objects.structural.material import *
+from specklepy.objects.structural.geometry import *
+from specklepy.objects.structural.loading import *
+from specklepy.objects.structural.axis import Axis
+
+__all__ = [
+    "Element1D",
+    "Element2D",
+    "Element3D",
+    "Axis",
+    "Node",
+    "Restraint",
+    "Load",
+    "LoadBeam",
+    "LoadCase",
+    "LoadCombinations",
+    "LoadFace",
+    "LoadGravity",
+    "LoadNode",
+    "Model",
+    "ModelInfo",
+    "ModelSettings",
+    "ModelUnits",
+    "Concrete",
+    "Material",
+    "Steel",
+    "Timber",
+    "Property",
+    "Property1D",
+    "Property2D",
+    "Property3D",
+    "PropertyDamper",
+    "PropertyMass",
+    "PropertySpring",
+    "SectionProfile",
+]

specklepy/objects/structural/analysis.py

@@ -0,0 +1,51 @@
+from typing import List
+
+from ..base import Base
+from ..geometry import *
+from .properties import *
+
+STRUCTURAL_ANALYSIS = "Objects.Structural.Analysis."
+
+
+class ModelUnits(Base, speckle_type=STRUCTURAL_ANALYSIS + "ModelUnits"):
+    length: str = None
+    sections: str = None
+    displacements: str = None
+    stress: str = None
+    force: str = None
+    mass: str = None
+    time: str = None
+    temperature: str = None
+    velocity: str = None
+    acceleration: str = None
+    energy: str = None
+    angle: str = None
+    strain: str = None
+
+
+class ModelSettings(Base, speckle_type=STRUCTURAL_ANALYSIS + "ModelSettings"):
+    modelUnits: ModelUnits = None
+    steelCode: str = None
+    concreteCode: str = None
+    coincidenceTolerance: float = 0.0
+
+
+class ModelInfo(Base, speckle_type=STRUCTURAL_ANALYSIS + "ModelInfo"):
+    name: str = None
+    description: str = None
+    projectNumber: str = None
+    projectName: str = None
+    settings: ModelSettings = None
+    initials: str = None
+    application: str = None
+
+
+class Model(Base, speckle_type=STRUCTURAL_ANALYSIS + "Model"):
+    specs: ModelInfo = None
+    nodes: List = None
+    elements: List = None
+    loads: List = None
+    restraints: List = None
+    properties: List = None
+    materials: List = None
+    layerDescription: str = None

specklepy/objects/structural/axis.py

@@ -0,0 +1,8 @@
+from ..base import Base
+from ..geometry import Plane
+
+
+class Axis(Base, speckle_type="Objects.Structural.Geometry.Axis"):
+    name: str = None
+    axisType: str = None
+    plane: Plane = None

specklepy/objects/structural/geometry.py

@@ -0,0 +1,108 @@
+from enum import Enum
+from typing import List
+
+from ..base import Base
+from ..geometry import *
+from .properties import *
+from .axis import Axis
+
+STRUCTURAL_GEOMETRY = "Objects.Structural.Geometry"
+
+
+class ElementType1D(int, Enum):
+    Beam = 0
+    Brace = 1
+    Bar = 2
+    Column = 3
+    Rod = 4
+    Spring = 5
+    Tie = 6
+    Strut = 7
+    Link = 8
+    Damper = 9
+    Cable = 10
+    Spacer = 11
+    Other = 12
+    Null = 13
+
+
+class ElementType2D(int, Enum):
+    Quad4 = 0
+    Quad8 = 1
+    Triangle3 = 2
+    Triangle6 = 3
+
+
+class ElementType3D(int, Enum):
+    Brick8 = 0
+    Wedge6 = 1
+    Pyramid5 = 2
+    Tetra4 = 3
+
+
+class Restraint(Base, speckle_type=STRUCTURAL_GEOMETRY + ".Restraint"):
+    code: str = None
+    stiffnessX: float = 0.0
+    stiffnessY: float = 0.0
+    stiffnessZ: float = 0.0
+    stiffnessXX: float = 0.0
+    stiffnessYY: float = 0.0
+    stiffnessZZ: float = 0.0
+    units: str = None
+
+
+class Node(Base, speckle_type=STRUCTURAL_GEOMETRY + ".Node"):
+    name: str = None
+    basePoint: Point = None
+    constraintAxis: Axis = None
+    restraint: Restraint = None
+    springProperty: PropertySpring = None
+    massProperty: PropertyMass = None
+    damperProperty: PropertyDamper = None
+    units: str = None
+
+
+class Element1D(Base, speckle_type=STRUCTURAL_GEOMETRY + ".Element1D"):
+    name: str = None
+    baseLine: Line = None
+    property: Property1D = None
+    type: ElementType1D = None
+    end1Releases: Restraint = None
+    end2Releases: Restraint = None
+    end1Offset: Vector = None
+    end2Offset: Vector = None
+    orientationNode: Node = None
+    orinetationAngle: float = 0.0
+    localAxis: Plane = None
+    parent: Base = None
+    end1Node: Node = Node
+    end2Node: Node = Node
+    topology: List = None
+    displayMesh: Mesh = None
+    units: str = None
+
+
+class Element2D(Base, speckle_type=STRUCTURAL_GEOMETRY + ".Element2D"):
+    name: str = None
+    property: Property2D = None
+    type: ElementType2D = None
+    offset: float = 0.0
+    orientationAngle: float = 0.0
+    parent: Base = None
+    topology: List = None
+    displayMesh: Mesh = None
+    units: str = None
+
+
+class Element3D(Base, speckle_type=STRUCTURAL_GEOMETRY + ".Element3D"):
+    name: str = None
+    baseMesh: Mesh = None
+    property: Property3D = None
+    type: ElementType3D = None
+    orientationAngle: float = 0.0
+    parent: Base = None
+    topology: List
+    units: str = None
+
+
+# class Storey needs ependency on built elements first

specklepy/objects/structural/loading.py

@@ -0,0 +1,144 @@
+from enum import Enum
+from typing import List
+
+from ..base import Base
+from .geometry import *
+
+STRUCTURAL_LOADING = "Objects.Structural.Loading."
+
+
+class LoadType(int, Enum):
+
+    none = 0
+    Dead = 1
+    SuperDead = 2
+    Soil = 3
+    Live = 4
+    LiveRoof = 5
+    ReducibleLive = 6
+    Wind = 7
+    Snow = 8
+    Rain = 9
+    Thermal = 10
+    Notional = 11
+    Prestress = 12
+    Equivalent = 13
+    Accidental = 14
+    SeismicRSA = 15
+    SeismicAccTorsion = 16
+    SeismicStatic = 17
+    Other = 18
+
+
+class ActionType(int, Enum):
+
+    none = 0
+    Permanent = 1
+    Variable = 2
+    Accidental = 3
+
+
+class BeamLoadType(int, Enum):
+
+    Point = 0
+    Uniform = 1
+    Linear = 2
+    Patch = 3
+    TriLinear = 4
+
+
+class FaceLoadType(int, Enum):
+
+    Constant = 0
+    Variable = 1
+    Point = 2
+
+
+class LoadDirection2D(int, Enum):
+
+    X = 0
+    Y = 1
+    Z = 2
+
+
+class LoadDirection(int, Enum):
+
+    X = 0
+    Y = 1
+    Z = 2
+    XX = 3
+    YY = 4
+    ZZ = 5
+
+
+class LoadAxisType(int, Enum):
+    Global = 0
+    Local = 1  # local element axes
+    DeformedLocal = (
+        2  # element local axis that is embedded in the element as it deforms
+    )
+
+
+class CombinationType(int, Enum):
+
+    LinearAdd = 0
+    Envelope = 1
+    AbsoluteAdd = 2
+    SRSS = 3
+    RangeAdd = 4
+
+
+class LoadCase(Base, speckle_type=STRUCTURAL_LOADING + "LoadCase"):
+    name: str = None
+    loadType: LoadType = None
+    group: str = None
+    actionType: ActionType = None
+    description: str = None
+
+
+class Load(Base, speckle_type=STRUCTURAL_LOADING + "Load"):
+    name: str = None
+    units: str = None
+    loadCase: LoadCase = None
+
+
+class LoadBeam(Load, speckle_type=STRUCTURAL_LOADING + "LoadBeam"):
+    elements: List = None
+    loadType: BeamLoadType = None
+    direction: LoadDirection = None
+    loadAxis: Axis = None
+    loadAxisType: LoadAxisType = None
+    isProjected: bool = None
+    values: List = None
+    positions: List = None
+
+
+class LoadCombinations(Base, speckle_type=STRUCTURAL_LOADING + "LoadCombination"):
+    name: str = None
+    loadCases: List
+    loadFactors: List
+    combinationType: CombinationType
+
+
+class LoadFace(Load, speckle_type=STRUCTURAL_LOADING + "LoadFace"):
+    elements: List = None
+    loadType: FaceLoadType = None
+    direction: LoadDirection2D = None
+    loadAxis: Axis = None
+    loadAxisType: LoadAxisType = None
+    isProjected: bool = None
+    values: List = None
+    positions: List = None
+
+
+class LoadGravity(Load, speckle_type=STRUCTURAL_LOADING + "LoadGravity"):
+    elements: List = None
+    nodes: List = None
+    gravityFactors: Vector = None
+
+
+class LoadNode(Load, speckle_type=STRUCTURAL_LOADING + "LoadNode"):
+    nodes: List = None
+    loadAxis: Axis = None
+    direction: LoadDirection = None
+    value: float = 0.0

specklepy/objects/structural/material.py

@@ -0,0 +1,59 @@
+from enum import Enum
+
+from ..base import Base
+
+
+STRUCTURAL_MATERIALS = "Objects.Structural.Materials"
+
+
+class MaterialType(int, Enum):
+    Concrete = 0
+    Steel = 1
+    Timber = 2
+    Aluminium = 3
+    Masonry = 4
+    FRP = 5
+    Glass = 6
+    Fabric = 7
+    Rebar = 8
+    Tendon = 9
+    ColdFormed = 10
+    Other = 11
+
+
+class Material(Base, speckle_type=STRUCTURAL_MATERIALS):
+    name: str = None
+    grade: str = None
+    materialType: MaterialType = None
+    designCode: str = None
+    codeYear: str = None
+    strength: float = 0.0
+    elasticModulus: float = 0.0
+    poissonsRatio: float = 0.0
+    shearModulus: float = 0.0
+    density: float = 0.0
+    thermalExpansivity: float = 0.0
+    dampingRatio: float = 0.0
+    cost: float = 0.0
+    materialSafetyFactor: float = 0.0
+
+
+class Concrete(Material, speckle_type=STRUCTURAL_MATERIALS + ".Concrete"):
+    compressiveStrength: float = 0.0
+    tensileStrength: float = 0.0
+    flexuralStrength: float = 0.0
+    maxCompressiveStrength: float = 0.0
+    maxTensileStrength: float = 0.0
+    maxAggregateSize: float = 0.0
+    lightweight: bool = None
+
+
+class Steel(Material, speckle_type=STRUCTURAL_MATERIALS + ".Steel"):
+    yieldStrength: float = 0.0
+    ultimateStrength: float = 0.0
+    maxStrain: float = 0.0
+    strainHardeningModulus: float = 0.0
+
+
+class Timber(Material, speckle_type=STRUCTURAL_MATERIALS + ".Timber"):
+    species: str = None

specklepy/objects/structural/properties.py

@@ -0,0 +1,212 @@
+from enum import Enum
+
+from ..base import Base
+
+from .material import *
+from .axis import Axis
+
+
+STRUCTURAL_PROPERTY = "Objectives.Structural.Properties"
+
+
+class MemberType(int, Enum):
+    Beam = 0
+    Column = 1
+    Generic1D = 2
+    Slab = 3
+    Wall = 4
+    Generic2D = 5
+    VoidCutter1D = 6
+    VoidCutter2D = 7
+
+
+class BaseReferencePoint(int, Enum):
+    Centroid = 0
+    TopLeft = 1
+    TopCentre = 2
+    TopRight = 3
+    MidLeft = 4
+    MidRight = 5
+    BotLeft = 6
+    BotCentre = 7
+    BotRight = 8
+
+
+class ReferenceSurface(int, Enum):
+    Top = 0
+    Middle = 1
+    Bottom = 2
+
+
+class PropertyType2D(int, Enum):
+
+    Stress = 0
+    Fabric = 1
+    Plate = 2
+    Shell = 3
+    Curved = 4
+    Wall = 5
+    Strain = 6
+    Axi = 7
+    Load = 8
+
+
+class PropertyType3D(int, Enum):
+    Solid = 0
+    Infinite = 1
+
+
+class ShapeType(int, Enum):
+    Rectangular = 0
+    Circular = 1
+    I = 2
+    Tee = 3
+    Angle = 4
+    Channel = 5
+    Perimeter = 6
+    Box = 7
+    Catalogue = 8
+    Explicit = 9
+
+
+class PropertyTypeSpring(int, Enum):
+    Axial = 0
+    Torsional = 1
+    General = 2
+    Matrix = 3
+    TensionOnly = 4
+    CompressionOnly = 5
+    Connector = 6
+    LockUp = 7
+    Gap = 8
+    Friction = 9
+
+
+class PropertyTypeDamper(int, Enum):
+    Axial = 0
+    Torsional = 1
+    General = 2
+
+
+class Property(Base, speckle_type=STRUCTURAL_PROPERTY):
+    name: str = None
+
+
+class SectionProfile(Base, speckle_type=STRUCTURAL_PROPERTY + ".SectionProfile"):
+    name: str = None
+    shapeType: ShapeType = None
+    area: float = 0.0
+    Iyy: float = 0.0
+    Izz: float = 0.0
+    J: float = 0.0
+    Ky: float = 0.0
+    weight: float = 0.0
+    units: str = None
+
+
+class Property1D(Property, speckle_type=STRUCTURAL_PROPERTY + ".Property1D"):
+    memberType: MemberType = None
+    Material: Material = None
+    SectionProfile: SectionProfile = None
+    BaseReferencePoint: BaseReferencePoint = None
+    offsetY: float = 0.0
+    offsetZ: float = 0.0
+
+
+class Property2D(Property, speckle_type=STRUCTURAL_PROPERTY + ".Property2D"):
+    PropertyType2D: PropertyType2D = None
+    thickness: float = 0.0
+    Material: Material = None
+    axis: Axis = None
+    referenceSurface: ReferenceSurface = None
+    zOffset: float = 0.0
+    modifierInPlane: float = 0.0
+    modifierBending: float = 0.0
+    modifierShear: float = 0.0
+    modifierVolume: float = 0.0
+
+
+class Property3D(Property, speckle_type=STRUCTURAL_PROPERTY + ".Property3D"):
+    PropertyType3D: PropertyType3D = None
+    Material: Material = None
+    axis: Axis = None
+
+
+class PropertyDamper(Property, speckle_type=STRUCTURAL_PROPERTY + ".PropertyDamper"):
+    damperType: PropertyTypeDamper = None
+    dampingX: float = 0.0
+    dampingY: float = 0.0
+    dampingZ: float = 0.0
+    dampingXX: float = 0.0
+    dampingYY: float = 0.0
+    dampingZZ: float = 0.0
+
+
+class PropertyMass(Property, speckle_type=STRUCTURAL_PROPERTY + ".PropertyMass"):
+    mass: float = 0.0
+    inertiaXX: float = 0.0
+    inertiaYY: float = 0.0
+    inertiaZZ: float = 0.0
+    inertiaXY: float = 0.0
+    inertiaYZ: float = 0.0
+    inertiaZX: float = 0.0
+    massModified: bool = None
+    massModifierX: float = 0.0
+    massModifierY: float = 0.0
+    massModifierZ: float = 0.0
+
+
+class PropertySpring(Property, speckle_type=STRUCTURAL_PROPERTY + ".PropertySpring"):
+    springType: PropertyTypeSpring = None
+    springCurveX: float = 0.0
+    stiffnessX: float = 0.0
+    springCurveY: float = 0.0
+    stiffnessY: float = 0.0
+    springCurveZ: float = 0.0
+    stiffnessZ: float = 0.0
+    springCurveXX: float = 0.0
+    stiffnessXX: float = 0.0
+    springCurveYY: float = 0.0
+    stiffnessYY: float = 0.0
+    springCurveZZ: float = 0.0
+    stiffnessZZ: float = 0.0
+    dampingRatio: float = 0.0
+    dampingX: float = 0.0
+    dampingY: float = 0.0
+    dampingZ: float = 0.0
+    dampingXX: float = 0.0
+    dampingYY: float = 0.0
+    dampingZZ: float = 0.0
+    matrix: float = 0.0
+    postiveLockup: float = 0.0
+    frictionCoefficient: float = 0.0
+
+
+class ReferenceSurfaceEnum(int, Enum):
+    Concrete = 0
+    Steel = 1
+    Timber = 2
+    Aluminium = 3
+    Masonry = 4
+    FRP = 5
+    Glass = 6
+    Fabric = 7
+    Rebar = 8
+    Tendon = 9
+    ColdFormed = 10
+    Other = 11
+
+
+class shapeType(int, Enum):
+    Concrete = 0
+    Steel = 1
+    Timber = 2
+    Aluminium = 3
+    Masonry = 4
+    FRP = 5
+    Glass = 6
+    Fabric = 7
+    Rebar = 8
+    Tendon = 9
+    ColdFormed = 10
+    Other = 11

specklepy/objects/structural/results.py

@@ -0,0 +1,174 @@
+from typing import List
+
+from ..base import Base
+from ..geometry import *
+from .loading import *
+from .geometry import *
+from .analysis import Model
+
+STRUCTURAL_RESULTS = "Objects.Structural.Results."
+
+
+class Result(Base, speckle_type=STRUCTURAL_RESULTS + "Result"):
+    resultCase: Base = None
+    permutation: str = None
+    description: str = None
+
+
+class ResultSet1D(Result, speckle_type=STRUCTURAL_RESULTS + "ResultSet1D"):
+    results1D: List
+
+
+class Result1D(Result, speckle_type=STRUCTURAL_RESULTS + "Result1D"):
+    element: Element1D = None
+    position: float = 0.0
+    dispX: float = 0.0
+    dispY: float = 0.0
+    dispZ: float = 0.0
+    rotXX: float = 0.0
+    rotYY: float = 0.0
+    rotZZ: float = 0.0
+    forceX: float = 0.0
+    forceY: float = 0.0
+    forceZ: float = 0.0
+    momentXX: float = 0.0
+    momentYY: float = 0.0
+    momentZZ: float = 0.0
+    axialStress: float = 0.0
+    shearStressY: float = 0.0
+    shearStressZ: float = 0.0
+    bendingStressYPos: float = 0.0
+    bendingStressYNeg: float = 0.0
+    bendingStressZPos: float = 0.0
+    bendingStressZNeg: float = 0.0
+    combinedStressMax: float = 0.0
+    combinedStressMin: float = 0.0
+
+
+class ResultSet2D(Result, speckle_type=STRUCTURAL_RESULTS + "ResultSet2D"):
+    results2D: List
+
+
+class Result2D(Result, speckle_type=STRUCTURAL_RESULTS + "Result2D"):
+    element: Element2D = None
+    position: List
+    dispX: float = 0.0
+    dispY: float = 0.0
+    dispZ: float = 0.0
+    forceXX: float = 0.0
+    forceYY: float = 0.0
+    forceXY: float = 0.0
+    momentXX: float = 0.0
+    momentYY: float = 0.0
+    momentXY: float = 0.0
+    shearX: float = 0.0
+    shearY: float = 0.0
+    stressTopXX: float = 0.0
+    stressTopYY: float = 0.0
+    stressTopZZ: float = 0.0
+    stressTopXY: float = 0.0
+    stressTopYZ: float = 0.0
+    stressTopZX: float = 0.0
+    stressMidXX: float = 0.0
+    stressMidYY: float = 0.0
+    stressMidZZ: float = 0.0
+    stressMidXY: float = 0.0
+    stressMidYZ: float = 0.0
+    stressMidZX: float = 0.0
+    stressBotXX: float = 0.0
+    stressBotYY: float = 0.0
+    stressBotZZ: float = 0.0
+    stressBotXY: float = 0.0
+    stressBotYZ: float = 0.0
+    stressBotZX: float = 0.0
+
+
+class ResultSet3D(Result, speckle_type=STRUCTURAL_RESULTS + "ResultSet3D"):
+    results3D: List
+
+
+class Result3D(Result, speckle_type=STRUCTURAL_RESULTS + "Result3D"):
+    element: Element3D = None
+    position: List
+    dispX: float = 0.0
+    dispY: float = 0.0
+    dispZ: float = 0.0
+    stressXX: float = 0.0
+    stressYY: float = 0.0
+    stressZZ: float = 0.0
+    stressXY: float = 0.0
+    stressYZ: float = 0.0
+    stressZX: float = 0.0
+
+
+class ResultGlobal(Result, speckle_type=STRUCTURAL_RESULTS + "ResultGlobal"):
+    model: Model = None
+    loadX: float = 0.0
+    loadY: float = 0.0
+    loadZ: float = 0.0
+    loadXX: float = 0.0
+    loadYY: float = 0.0
+    loadZZ: float = 0.0
+    reactionX: float = 0.0
+    reactionY: float = 0.0
+    reactionZ: float = 0.0
+    reactionXX: float = 0.0
+    reactionYY: float = 0.0
+    reactionZZ: float = 0.0
+    mode: float = 0.0
+    frequency: float = 0.0
+    loadFactor: float = 0.0
+    modalStiffness: float = 0.0
+    modalGeoStiffness: float = 0.0
+    effMassX: float = 0.0
+    effMassY: float = 0.0
+    effMassZ: float = 0.0
+    effMassXX: float = 0.0
+    effMassYY: float = 0.0
+    effMassZZ: float = 0.0
+
+
+class ResultSetNode(Result, speckle_type=STRUCTURAL_RESULTS + "ResultSetNode"):
+    resultsNode: List
+
+
+class ResultNode(Result, speckle_type=STRUCTURAL_RESULTS + " ResultNode"):
+    node: Node = None
+    dispX: float = 0.0
+    dispY: float = 0.0
+    dispZ: float = 0.0
+    rotXX: float = 0.0
+    rotYY: float = 0.0
+    rotZZ: float = 0.0
+    reactionX: float = 0.0
+    reactionY: float = 0.0
+    reactionZ: float = 0.0
+    reactionXX: float = 0.0
+    reactionYY: float = 0.0
+    reactionZZ: float = 0.0
+    constraintX: float = 0.0
+    constraintY: float = 0.0
+    constraintZ: float = 0.0
+    constraintXX: float = 0.0
+    constraintYY: float = 0.0
+    constraintZZ: float = 0.0
+    velX: float = 0.0
+    velY: float = 0.0
+    velZ: float = 0.0
+    velXX: float = 0.0
+    velYY: float = 0.0
+    velZZ: float = 0.0
+    accX: float = 0.0
+    accY: float = 0.0
+    accZ: float = 0.0
+    accXX: float = 0.0
+    accYY: float = 0.0
+    accZZ: float = 0.0
+
+
+class ResultSetAll(Base, speckle_type=None):
+    resultSet1D: ResultSet1D = None
+    resultSet2D: ResultSet2D = None
+    resultSet3D: ResultSet3D = None
+    resultsGlobal: ResultGlobal = None
+    resultsNode: ResultSetNode = None

specklepy/objects/units.py

@@ -1,4 +1,5 @@
-from specklepy.logging.exceptions import SpeckleException
+from warnings import warn
+from specklepy.logging.exceptions import SpeckleException, SpeckleWarning
 
 UNITS = ["mm", "cm", "m", "in", "ft", "yd", "mi"]
 
@@ -15,6 +16,8 @@ UNITS_STRINGS = {
 }
 
 UNITS_ENCODINGS = {
+    None: 0,
+    "none": 0,
     "mm": 1,
     "cm": 2,
     "m": 3,
@@ -27,6 +30,12 @@ UNITS_ENCODINGS = {
 
 
 def get_units_from_string(unit: str):
+    if not isinstance(unit, str):
+        warn(
+            f"Invalid units: expected type str but received {type(unit)} ({unit}). Skipping - no units will be set.",
+            SpeckleWarning,
+        )
+        return
     unit = str.lower(unit)
     for name, alternates in UNITS_STRINGS.items():
         if unit in alternates:
@@ -50,7 +59,5 @@ def get_units_from_encoding(unit: int):
 def get_encoding_from_units(unit: str):
     try:
         return UNITS_ENCODINGS[unit]
-    except KeyError:
-        raise SpeckleException(
-            message=f"No encoding exists for unit {unit}. Please enter a valid unit to encode (eg {UNITS_ENCODINGS})."
-        )
+    except KeyError as e:
+        raise SpeckleException(message=f"No encoding exists for unit {unit}. Please enter a valid unit to encode (eg {UNITS_ENCODINGS}).") from e

specklepy/serialization/base_object_serializer.py

@@ -1,12 +1,19 @@
+import re
 import ujson
 import hashlib
-import re
-
+import warnings
 from uuid import uuid4
+from enum import Enum
+from warnings import warn
 from typing import Any, Dict, List, Tuple
 from specklepy.objects.base import Base, DataChunk
-from specklepy.logging.exceptions import SerializationException, SpeckleException
+from specklepy.logging.exceptions import (
+    SpeckleException,
+    SpeckleWarning,
+)
 from specklepy.transports.abstract_transport import AbstractTransport
+
+# import for serialization
 import specklepy.objects.geometry
 import specklepy.objects.other
 
@@ -17,6 +24,19 @@ def hash_obj(obj: Any) -> str:
     return hashlib.sha256(ujson.dumps(obj).encode()).hexdigest()[:32]
 
 
+def safe_json_loads(obj: str, obj_id=None) -> Any:
+    try:
+        return ujson.loads(obj)
+    except ValueError as err:
+        import json
+
+        warn(
+            f"Failed to deserialise object (id: {obj_id}). This is likely a ujson big int error - falling back to json. \nError: {err}",
+            SpeckleWarning,
+        )
+        return json.loads(obj)
+
+
 class BaseObjectSerializer:
     read_transport: AbstractTransport
     write_transports: List[AbstractTransport]
@@ -32,9 +52,16 @@ class BaseObjectSerializer:
         self.read_transport = read_transport
 
     def write_json(self, base: Base):
-        self.__reset_writer()
-        self.detach_lineage = [True]
+        """Serializes a given base object into a json string
+        Arguments:
+            base {Base} -- the base object to be decomposed and serialized
+
+        Returns:
+            (str, str) -- a tuple containing the hash (id) of the base object and the serialized object string
+        """
+
         hash, obj = self.traverse_base(base)
+
         return hash, ujson.dumps(obj)
 
     def traverse_base(self, base: Base) -> Tuple[str, Dict]:
@@ -46,6 +73,21 @@ class BaseObjectSerializer:
         Returns:
             (str, dict) -- a tuple containing the hash (id) of the base object and the constructed serializable dictionary
         """
+        self.__reset_writer()
+
+        if self.write_transports:
+            for wt in self.write_transports:
+                wt.begin_write()
+
+        hash, obj = self._traverse_base(base)
+
+        if self.write_transports:
+            for wt in self.write_transports:
+                wt.end_write()
+
+        return hash, obj
+
+    def _traverse_base(self, base: Base) -> Tuple[str, Dict]:
         if not self.detach_lineage:
             self.detach_lineage = [True]
 
@@ -60,14 +102,19 @@ class BaseObjectSerializer:
             chunkable = False
             detach = False
 
-            # skip nulls or props marked to be ignored with "__" or "_"
-            if value is None or prop.startswith(("__", "_")):
+            # skip props marked to be ignored with "__" or "_"
+            if prop.startswith(("__", "_")):
                 continue
 
             # don't prepopulate id as this will mess up hashing
             if prop == "id":
                 continue
 
+            # allow serialisation of nulls
+            if value is None:
+                object_builder[prop] = value
+                continue
+
             # only bother with chunking and detaching if there is a write transport
             if self.write_transports:
                 dynamic_chunk_match = prop.startswith("@") and re.match(
@@ -89,6 +136,11 @@ class BaseObjectSerializer:
                 object_builder[prop] = value
                 continue
 
+            # NOTE: for dynamic props, this won't be re-serialised as an enum but as an int
+            if isinstance(value, Enum):
+                object_builder[prop] = value.value
+                continue
+
             # 2. handle Base objects
             elif isinstance(value, Base):
                 child_obj = self.traverse_value(value, detach=detach)
@@ -113,7 +165,7 @@ class BaseObjectSerializer:
                 chunk_refs = []
                 for c in chunks:
                     self.detach_lineage.append(detach)
-                    ref_hash, _ = self.traverse_base(c)
+                    ref_hash, _ = self._traverse_base(c)
                     ref_obj = self.detach_helper(ref_hash=ref_hash)
                     chunk_refs.append(ref_obj)
                 object_builder[prop] = chunk_refs
@@ -160,6 +212,10 @@ class BaseObjectSerializer:
         if isinstance(obj, PRIMITIVES):
             return obj
 
+        # NOTE: for dynamic props, this won't be re-serialised as an enum but as an int
+        if isinstance(obj, Enum):
+            return obj.value
+
         elif isinstance(obj, (list, tuple, set)):
             if not detach:
                 return [self.traverse_value(o) for o in obj]
@@ -168,7 +224,7 @@ class BaseObjectSerializer:
             for o in obj:
                 if isinstance(o, Base):
                     self.detach_lineage.append(detach)
-                    hash, _ = self.traverse_base(o)
+                    hash, _ = self._traverse_base(o)
                     detached_list.append(self.detach_helper(ref_hash=hash))
                 else:
                     detached_list.append(self.traverse_value(o, detach))
@@ -176,7 +232,7 @@ class BaseObjectSerializer:
 
         elif isinstance(obj, dict):
             for k, v in obj.items():
-                if isinstance(v, PRIMITIVES):
+                if isinstance(v, PRIMITIVES) or v is None:
                     continue
                 else:
                     obj[k] = self.traverse_value(v)
@@ -184,17 +240,18 @@ class BaseObjectSerializer:
 
         elif isinstance(obj, Base):
             self.detach_lineage.append(detach)
-            _, base_obj = self.traverse_base(obj)
+            _, base_obj = self._traverse_base(obj)
             return base_obj
 
         else:
             try:
                 return obj.dict()
             except:
-                SerializationException(
-                    message=f"Failed to handle {type(obj)} in `BaseObjectSerializer.traverse_value`",
-                    object=obj,
+                warn(
+                    f"Failed to handle {type(obj)} in `BaseObjectSerializer.traverse_value`",
+                    SpeckleWarning,
                 )
+
                 return str(obj)
 
     def detach_helper(self, ref_hash: str) -> Dict[str, str]:
@@ -222,7 +279,7 @@ class BaseObjectSerializer:
 
     def __reset_writer(self) -> None:
         """Reinitializes the lineage, and other variables that get used during the json writing process"""
-        self.detach_lineage = []
+        self.detach_lineage = [True]
         self.lineage = []
         self.family_tree = {}
         self.closure_table = {}
@@ -238,7 +295,7 @@ class BaseObjectSerializer:
         """
         if not obj_string:
             return None
-        obj = ujson.loads(obj_string)
+        obj = safe_json_loads(obj_string)
         return self.recompose_base(obj=obj)
 
     def recompose_base(self, obj: dict) -> Base:
@@ -254,7 +311,7 @@ class BaseObjectSerializer:
         if not obj:
             return
         if isinstance(obj, str):
-            obj = ujson.loads(obj)
+            obj = safe_json_loads(obj)
 
         if "speckle_type" in obj and obj["speckle_type"] == "reference":
             obj = self.get_child(obj=obj)
@@ -288,12 +345,15 @@ class BaseObjectSerializer:
             elif "referencedId" in value:
                 ref_hash = value["referencedId"]
                 ref_obj_str = self.read_transport.get_object(id=ref_hash)
-                if not ref_obj_str:
-                    raise SpeckleException(
-                        f"Could not find the referenced child object of id `{ref_hash}` in the given read transport: {self.read_transport.name}"
+                if ref_obj_str:
+                    ref_obj = safe_json_loads(ref_obj_str, ref_hash)
+                    base.__setattr__(prop, self.recompose_base(obj=ref_obj))
+                else:
+                    warnings.warn(
+                        f"Could not find the referenced child object of id `{ref_hash}` in the given read transport: {self.read_transport.name}",
+                        SpeckleWarning,
                     )
-                ref_obj = ujson.loads(ref_obj_str)
-                base.__setattr__(prop, self.recompose_base(obj=ref_obj))
+                    base.__setattr__(prop, self.handle_value(value))
 
             # 3. handle all other cases (base objects, lists, and dicts)
             else:
@@ -347,7 +407,10 @@ class BaseObjectSerializer:
         ref_hash = obj["referencedId"]
         ref_obj_str = self.read_transport.get_object(id=ref_hash)
         if not ref_obj_str:
-            raise SpeckleException(
-                f"Could not find the referenced child object of id `{ref_hash}` in the given read transport: {self.read_transport.name}"
+            warnings.warn(
+                f"Could not find the referenced child object of id `{ref_hash}` in the given read transport: {self.read_transport.name}",
+                SpeckleWarning,
             )
-        return ujson.loads(ref_obj_str)
+            return obj
+
+        return safe_json_loads(ref_obj_str, ref_hash)

specklepy/transports/abstract_transport.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from typing import Any, Optional, List, Dict
+from typing import Optional, List, Dict
 from pydantic import BaseModel
 from pydantic.main import Extra
 

specklepy/transports/memory.py

@@ -1,6 +1,4 @@
-import json
 from typing import Any, List, Dict
-from specklepy.logging.exceptions import SpeckleException
 from specklepy.transports.abstract_transport import AbstractTransport
 
 
@@ -28,10 +26,7 @@ class MemoryTransport(AbstractTransport):
         raise NotImplementedError
 
     def get_object(self, id: str) -> str or None:
-        if id in self.objects:
-            return self.objects[id]
-        else:
-            return None
+        return self.objects[id] if id in self.objects else None
 
     def has_objects(self, id_list: List[str]) -> Dict[str, bool]:
         return {id: (id in self.objects) for id in id_list}

specklepy/transports/server/batch_sender.py

@@ -2,7 +2,6 @@ import json
 import logging
 import threading
 import queue
-import time
 import gzip
 
 import requests
@@ -92,10 +91,15 @@ class BatchSender(object):
 
     def _bg_send_batch(self, session, batch):
         object_ids = [obj[0] for obj in batch]
-        server_has_object = session.post(
-            url=f"{self.server_url}/api/diff/{self.stream_id}",
-            data={"objects": json.dumps(object_ids)},
-        ).json()
+        try:
+            server_has_object = session.post(
+                url=f"{self.server_url}/api/diff/{self.stream_id}",
+                data={"objects": json.dumps(object_ids)},
+            ).json()
+        except Exception as ex:
+            raise SpeckleException(
+                f"Invalid credentials - cannot send objects to server {self.server_url}"
+            ) from ex
 
         new_object_ids = [x for x in object_ids if not server_has_object[x]]
         new_object_ids = set(new_object_ids)

specklepy/transports/server/server.py

@@ -1,40 +1,97 @@
 import json
-import time
-
 import requests
+from warnings import warn
 
-from typing import Any, Dict, List, Type
+from typing import Any, Dict, List
 
 from specklepy.api.client import SpeckleClient
-from specklepy.logging.exceptions import SpeckleException
+from specklepy.api.credentials import Account, get_account_from_token
+from specklepy.logging.exceptions import SpeckleException, SpeckleWarning
 from specklepy.transports.abstract_transport import AbstractTransport
 
 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 an `Account`
+        3. 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
+    account: Account = 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,
+        account: Account = 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 account 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 account:
+            self.account = account
+            url = account.serverInfo.url
+        elif client:
+            url = client.url
+            if not client.account.token:
+                warn(
+                    SpeckleWarning(
+                        f"Unauthenticated Speckle Client provided to Server Transport for {self.url}. Receiving from private streams will fail."
+                    )
+                )
+            else:
+                self.account = client.account
+        else:
+            self.account = get_account_from_token(token, 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
+            self.url, self.stream_id, self.account.token, max_batch_size_mb=1
         )
 
         self.session = requests.Session()
         self.session.headers.update(
-            {"Authorization": f"Bearer {token}", "Accept": "text/plain"}
+            {"Authorization": f"Bearer {self.account.token}", "Accept": "text/plain"}
         )
 
     def begin_write(self) -> None:
@@ -73,8 +130,7 @@ class ServerTransport(AbstractTransport):
     ) -> str:
         endpoint = f"{self.url}/objects/{self.stream_id}/{id}/single"
         r = self.session.get(endpoint)
-        if r.encoding is None:
-            r.encoding = "utf-8"
+        r.encoding = "utf-8"
 
         if r.status_code != 200:
             raise SpeckleException(
@@ -96,8 +152,7 @@ class ServerTransport(AbstractTransport):
         r = self.session.post(
             endpoint, data={"objects": json.dumps(new_children_ids)}, stream=True
         )
-        if r.encoding is None:
-            r.encoding = "utf-8"
+        r.encoding = "utf-8"
         lines = r.iter_lines(decode_unicode=True)
 
         # iter through returned objects saving them as we go

specklepy/transports/sqlite.py

@@ -3,7 +3,7 @@ import sys
 import time
 import sched
 import sqlite3
-from typing import Any, List, Dict
+from typing import Any, List, Dict, Tuple
 from appdirs import user_data_dir
 from contextlib import closing
 from specklepy.transports.abstract_transport import AbstractTransport
@@ -14,25 +14,29 @@ class SQLiteTransport(AbstractTransport):
     _name = "SQLite"
     _base_path: str = None
     _root_path: str = None
-    _is_writing: bool = False
-    _scheduler = sched.scheduler(time.time, time.sleep)
-    _polling_interval = 0.5  # seconds
     __connection: sqlite3.Connection = None
     app_name: str = ""
     scope: str = ""
     saved_obj_count: int = 0
+    max_size: int = None
+    _current_batch: List[Tuple[str, str]] = None
+    _current_batch_size: int = None
 
     def __init__(
         self,
         base_path: str = None,
         app_name: str = None,
         scope: str = None,
+        max_batch_size_mb: float = 10.0,
         **data: Any,
     ) -> None:
         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.app_name)
+        self.max_size = int(max_batch_size_mb * 1000 * 1000)
+        self._current_batch = []
+        self._current_batch_size = 0
 
         try:
             os.makedirs(self._base_path, exist_ok=True)
@@ -50,12 +54,6 @@ class SQLiteTransport(AbstractTransport):
     def __repr__(self) -> str:
         return f"SQLiteTransport(app: '{self.app_name}', scope: '{self.scope}')"
 
-    # def __write_timer_elapsed(self):
-    #     print("WRITE TIMER ELAPSED")
-    #     proc = Process(target=_run_queue, args=(self.__queue, self._root_path))
-    #     proc.start()
-    #     proc.join()
-
     @staticmethod
     def get_base_path(app_name):
         # from appdirs https://github.com/ActiveState/appdirs/blob/master/appdirs.py
@@ -74,36 +72,6 @@ class SQLiteTransport(AbstractTransport):
         path = os.path.expanduser("~/.config/")
         return os.path.join(path, app_name)
 
-    # def __consume_queue(self):
-    #     if self._is_writing or self.__queue.empty():
-    #         return
-    #     print("CONSUME QUEUE")
-    #     self._is_writing = True
-    #     while not self.__queue.empty():
-    #         data = self.__queue.get()
-    #         self.save_object(data[0], data[1])
-    #     self._is_writing = False
-
-    #     self._scheduler.enter(
-    #         delay=self._polling_interval, priority=1, action=self.__consume_queue
-    #     )
-    #     self._scheduler.run(blocking=True)
-
-    # def save_object(self, id: str, serialized_object: str) -> None:
-    #     """Adds an object to the queue and schedules it to be saved.
-
-    #     Arguments:
-    #         id {str} -- the object id
-    #         serialized_object {str} -- the full string representation of the object
-    #     """
-    #     print("SAVE OBJECT")
-    #     self.__queue.put((id, serialized_object))
-
-    #     self._scheduler.enter(
-    #         delay=self._polling_interval, priority=1, action=self.__consume_queue
-    #     )
-    #     self._scheduler.run(blocking=True)
-
     def save_object_from_transport(
         self, id: str, source_transport: AbstractTransport
     ) -> None:
@@ -117,23 +85,41 @@ class SQLiteTransport(AbstractTransport):
         self.save_object(id, serialized_object)
 
     def save_object(self, id: str, serialized_object: str) -> None:
-        """Directly saves an object into the database.
+        """
+        Adds an object to the current batch to be written to the db. If the current batch is full,
+        the batch is written to the db and the current batch is reset.
 
         Arguments:
             id {str} -- the object id
             serialized_object {str} -- the full string representation of the object
         """
+        obj_size = len(serialized_object)
+        if (
+            not self._current_batch
+            or self._current_batch_size + obj_size < self.max_size
+        ):
+            self._current_batch.append((id, serialized_object))
+            self._current_batch_size += obj_size
+            return
+
+        self.save_current_batch()
+        self._current_batch = [(id, serialized_object)]
+        self._current_batch_size = obj_size
+
+    def save_current_batch(self) -> None:
+        """Save the current batch of objects to the local db"""
         self.__check_connection()
         try:
             with closing(self.__connection.cursor()) as c:
-                c.execute(
+                c.executemany(
                     "INSERT OR IGNORE INTO objects(hash, content) VALUES(?,?)",
-                    (id, serialized_object),
+                    self._current_batch,
                 )
                 self.__connection.commit()
         except Exception as ex:
             raise SpeckleException(
-                f"Could not save the object to the local db. Inner exception: {ex}", ex
+                f"Could not save the batch of objects to the local db. Inner exception: {ex}",
+                ex,
             )
 
     def get_object(self, id: str) -> str or None:
@@ -156,10 +142,14 @@ class SQLiteTransport(AbstractTransport):
         return ret
 
     def begin_write(self):
+        self._object_cache = []
         self.saved_obj_count = 0
 
     def end_write(self):
-        pass
+        if self._current_batch:
+            self.save_current_batch()
+        self._current_batch = []
+        self._current_batch_size = 0
 
     def copy_object_and_children(
         self, id: str, target_transport: AbstractTransport
@@ -199,19 +189,3 @@ class SQLiteTransport(AbstractTransport):
 
     def __del__(self):
         self.__connection.close()
-
-
-# def _run_queue(queue: Queue, root_path: str):
-#     if queue.empty():
-#         return
-#     print("RUN QUEUE")
-#     conn = sqlite3.connect(root_path)
-#     while not queue.empty():
-#         data = queue.get()
-#         with closing(conn.cursor()) as c:
-#             c.execute(
-#                 "INSERT OR IGNORE INTO objects(hash, content) VALUES(?,?)",
-#                 (data[0], data[1]),
-#             )
-#             conn.commit()
-#     conn.close()

tests/conftest.py

@@ -6,7 +6,7 @@ from specklepy.api.models import Stream
 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.objects.fakemesh import FakeDirection, FakeMesh
 from specklepy.logging import metrics
 
 metrics.disable()
@@ -61,7 +61,7 @@ def second_user_dict(host):
 @pytest.fixture(scope="session")
 def client(host, user_dict):
     client = SpeckleClient(host=host, use_ssl=False)
-    client.authenticate(user_dict["token"])
+    client.authenticate_with_token(user_dict["token"])
     return client
 
 
@@ -81,9 +81,10 @@ def mesh():
     mesh = FakeMesh()
     mesh.name = "my_mesh"
     mesh.vertices = [random.uniform(0, 10) for _ in range(1, 210)]
-    mesh.faces = [i for i in range(1, 210)]
+    mesh.faces = list(range(1, 210))
     mesh["@(100)colours"] = [random.uniform(0, 10) for _ in range(1, 210)]
     mesh["@()default_chunk"] = [random.uniform(0, 10) for _ in range(1, 210)]
+    mesh.cardinal_dir = FakeDirection.WEST
     mesh.test_bases = [Base(name=f"test {i}") for i in range(1, 22)]
     mesh.detach_this = Base(name="predefined detached base")
     mesh["@detach"] = Base(name="detached base")
@@ -102,6 +103,10 @@ def base():
     base = Base()
     base.name = "my_base"
     base.units = "millimetres"
+    base.null_val = None
+    base.null_dict = {"a null val": None}
+    base.tuple = (1, 2, "3")
+    base.set = {1, 2, "3"}
     base.vertices = [random.uniform(0, 10) for _ in range(1, 120)]
     base.test_bases = [Base(name=i) for i in range(1, 22)]
     base["@detach"] = Base(name="detached base")

tests/test_base.py

@@ -1,5 +1,6 @@
+from enum import Enum
+from typing import Dict, List, Optional
 from contextlib import ExitStack as does_not_raise
-from typing import Dict, List
 
 import pytest
 from specklepy.api import operations
@@ -77,20 +78,39 @@ def test_speckle_type_cannot_be_set(base: Base) -> None:
     assert base.speckle_type == "Base"
 
 
+def test_setting_units():
+    b = Base(units="foot")
+    assert b.units == "ft"
+
+    with pytest.raises(SpeckleException):
+        b.units = "big"
+
+    b.units = None  # invalid args are skipped
+    b.units = 7
+    assert b.units == "ft"
+
+
 def test_base_of_custom_speckle_type() -> None:
     b1 = Base.of_type("BirdHouse", name="Tweety's Crib")
     assert b1.speckle_type == "BirdHouse"
     assert b1.name == "Tweety's Crib"
 
 
+class DietaryRestrictions(Enum):
+    VEGAN = 1
+    GLUTEN_FREE = 2
+    NUT_FREE = 3
+
+
 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
+    dietary: DietaryRestrictions
 
 
 def test_type_checking() -> None:
@@ -99,6 +119,7 @@ def test_type_checking() -> None:
     order.servings = 2
     order.price = "7"  # will get converted
     order.customer = "izzy"
+    order.dietary = DietaryRestrictions.VEGAN
 
     with pytest.raises(SpeckleException):
         order.flavours = "not a list"
@@ -106,10 +127,10 @@ def test_type_checking() -> None:
         order.servings = "five"
     with pytest.raises(SpeckleException):
         order.add_ons = ["sprinkles"]
+    with pytest.raises(SpeckleException):
+        order.dietary = "no nuts plz"
 
     order.add_ons = {"sprinkles": 0.2, "chocolate": 1.0}
     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_client_and_ops.py

@@ -0,0 +1,48 @@
+import pytest
+from specklepy.api import operations
+from specklepy.api.client import SpeckleClient
+from specklepy.objects.base import Base
+from specklepy.transports.server import ServerTransport
+from specklepy.api.credentials import Account, get_account_from_token
+from specklepy.logging.exceptions import SpeckleException, SpeckleWarning
+
+
+def test_invalid_authentication():
+    client = SpeckleClient()
+
+    with pytest.warns(SpeckleWarning):
+        client.authenticate_with_token("fake token")
+
+
+def test_invalid_send():
+    client = SpeckleClient()
+    client.account = Account(token="fake_token")
+    transport = ServerTransport("3073b96e86", client)
+
+    with pytest.raises(SpeckleException):
+        operations.send(Base(), [transport])
+
+
+def test_invalid_receive():
+    client = SpeckleClient()
+    client.account = Account(token="fake_token")
+    transport = ServerTransport("fake stream", client)
+
+    with pytest.raises(SpeckleException):
+        operations.receive("fake object", transport)
+
+
+def test_account_from_token():
+    token = "fake token"
+    acct = get_account_from_token(token)
+
+    assert acct.token == token
+
+
+def test_account_from_token_and_url():
+    token = "fake token"
+    url = "fake.server"
+    acct = get_account_from_token(token, url)
+
+    assert acct.token == token
+    assert acct.serverInfo.url == url

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

@@ -3,13 +3,31 @@ from typing import Callable
 
 import pytest
 from specklepy.api import operations
+from specklepy.logging.exceptions import SpeckleException
 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 +89,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 +106,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 +121,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 +136,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 +155,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 +170,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 +205,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 +236,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 +249,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 +257,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 +290,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 +355,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 +389,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 +447,19 @@ 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()
+
+
+def test_mesh_create():
+    vertices = [2, 1, 2, 4, 77.3, 5, 33, 4, 2]
+    faces = [1, 2, 3, 4, 5, 6, 7]
+    mesh = Mesh.create(vertices, faces)
+
+    with pytest.raises(SpeckleException):
+        bad_mesh = Mesh.create(vertices=7, faces=faces)
+
+    assert mesh.vertices == vertices
+    assert mesh.textureCoordinates == []

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.account.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,10 @@ class TestSerialization:
         untyped = '{"foo": "bar"}'
         deserialised = operations.deserialize(untyped)
 
-        assert deserialised == {"foo": "bar"}
+        assert deserialised == {"foo": "bar"}
+
+    def test_big_int(self):
+        big_int = '{"big": ' + str(2 ** 64) + "}"
+        deserialised = operations.deserialize(big_int)
+
+        assert deserialised == {"big": 2 ** 64}

tests/test_stream.py

@@ -1,5 +1,7 @@
 import pytest
-from specklepy.api.models import Stream
+from datetime import datetime
+from specklepy.api.models import ActivityCollection, Activity, Stream
+from specklepy.api.client import SpeckleClient
 from specklepy.logging.exceptions import GraphQLException
 
 
@@ -67,6 +69,16 @@ class TestStream:
         assert len(search_results) == 1
         assert search_results[0].name == updated_stream.name
 
+    def test_stream_favorite(self, client, stream):
+        favorited = client.stream.favorite(stream.id)
+
+        assert isinstance(favorited, Stream)
+        assert favorited.favoritedDate is not None
+
+        unfavorited = client.stream.favorite(stream.id, False)
+        assert isinstance(favorited, Stream)
+        assert unfavorited.favoritedDate is None
+
     def test_stream_grant_permission(self, client, stream, second_user_dict):
         granted = client.stream.grant_permission(
             stream_id=stream.id,
@@ -87,9 +99,22 @@ class TestStream:
 
         fetched_stream = client.stream.get(stream.id)
 
-        assert revoked == True
+        assert revoked is True
         assert len(fetched_stream.collaborators) == 1
 
+    def test_stream_activity(self, client: SpeckleClient, stream: Stream):
+        activity = client.stream.activity(stream.id)
+
+        older_activity = client.stream.activity(
+            stream.id, before=activity.items[0].time
+        )
+
+        assert isinstance(activity, ActivityCollection)
+        assert isinstance(older_activity, ActivityCollection)
+        assert older_activity.totalCount < activity.totalCount
+        assert activity.items is not None
+        assert isinstance(activity.items[0], Activity)
+
     def test_stream_delete(self, client, stream):
         deleted = client.stream.delete(stream.id)
 

tests/test_transforms.py

@@ -0,0 +1,132 @@
+from typing import List
+import pytest
+from specklepy.api import operations
+from specklepy.objects.geometry import Point, Vector
+from specklepy.objects.other import (
+    Transform,
+    BlockInstance,
+    BlockDefinition,
+    IDENTITY_TRANSFORM,
+)
+
+
+@pytest.fixture()
+def point():
+    return Point(x=1, y=10, z=2)
+
+
+@pytest.fixture()
+def points():
+    return [Point(x=1 + i, y=10 + i, z=2 + i) for i in range(5)]
+
+
+@pytest.fixture()
+def point_value():
+    return [1, 10, 2]
+
+
+@pytest.fixture()
+def points_values():
+    coords = []
+    for i in range(5):
+        coords.extend([1 + i, 10 + i, 2 + 1])
+    return coords
+
+
+@pytest.fixture()
+def vector():
+    return Vector(x=1, y=10, z=2)
+
+
+@pytest.fixture()
+def vector_value():
+    return [1, 1, 2]
+
+
+@pytest.fixture()
+def transform():
+    """Translates to [1, 2, 0] and scales z by 0.5"""
+    return Transform.from_list(
+        [
+            1.0,
+            0.0,
+            0.0,
+            1.0,
+            0.0,
+            1.0,
+            0.0,
+            2.0,
+            0.0,
+            0.0,
+            0.5,
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+            1.0,
+        ]
+    )
+
+
+def test_point_transform(point: Point, transform: Transform):
+    new_point = transform.apply_to_point(point)
+
+    assert new_point.x == point.x + 1
+    assert new_point.y == point.y + 2
+    assert new_point.z == point.z * 0.5
+
+
+def test_points_transform(points: List[Point], transform: Transform):
+    new_points = transform.apply_to_points(points)
+
+    for (i, new_point) in enumerate(new_points):
+        assert new_point.x == points[i].x + 1
+        assert new_point.y == points[i].y + 2
+        assert new_point.z == points[i].z * 0.5
+
+
+def test_point_value_transform(point_value: List[float], transform: Transform):
+    new_coords = transform.apply_to_point_value(point_value)
+
+    assert new_coords[0] == point_value[0] + 1
+    assert new_coords[1] == point_value[1] + 2
+    assert new_coords[2] == point_value[2] * 0.5
+
+
+def test_points_values_transform(points_values: List[float], transform: Transform):
+    new_coords = transform.apply_to_points_values(points_values)
+
+    for i in range(0, len(points_values), 3):
+        assert new_coords[i] == points_values[i] + 1
+        assert new_coords[i + 1] == points_values[i + 1] + 2
+        assert new_coords[i + 2] == points_values[i + 2] * 0.5
+
+
+def test_vector_transform(vector: Vector, transform: Transform):
+    new_vector = transform.apply_to_vector(vector)
+
+    assert new_vector.x == vector.x
+    assert new_vector.y == vector.y
+    assert new_vector.z == vector.z * 0.5
+
+
+def test_vector_value_transform(vector_value: List[float], transform: Transform):
+    new_coords = transform.apply_to_vector_value(vector_value)
+
+    assert new_coords[0] == vector_value[0]
+    assert new_coords[1] == vector_value[1]
+    assert new_coords[2] == vector_value[2] * 0.5
+
+
+def test_transform_fails_with_malformed_value():
+    with pytest.raises(ValueError):
+        Transform.from_list("asdf")
+    with pytest.raises(ValueError):
+        Transform.from_list([7, 8, 9])
+
+
+def test_transform_serialisation(transform: Transform):
+    serialized = operations.serialize(transform)
+    deserialized = operations.deserialize(serialized)
+
+    assert transform.get_id() == deserialized.get_id()

tests/test_user.py

@@ -1,6 +1,7 @@
-from specklepy.logging.exceptions import SpeckleException
-from specklepy.api.models import User
 import pytest
+from specklepy.api.client import SpeckleClient
+from specklepy.api.models import Activity, ActivityCollection, User
+from specklepy.logging.exceptions import SpeckleException
 
 
 @pytest.mark.run(order=1)
@@ -43,3 +44,17 @@ class TestUser:
         assert isinstance(failed_update, SpeckleException)
         assert updated is True
         assert me.bio == bio
+
+    def test_user_activity(self, client: SpeckleClient, second_user_dict):
+        my_activity = client.user.activity(limit=10)
+        their_activity = client.user.activity(second_user_dict["id"])
+
+        assert isinstance(my_activity, ActivityCollection)
+        assert isinstance(my_activity.items[0], Activity)
+        assert my_activity.totalCount > 0
+        assert isinstance(their_activity, ActivityCollection)
+
+        older_activity = client.user.activity(before=my_activity.items[0].time)
+
+        assert isinstance(older_activity, ActivityCollection)
+        assert older_activity.totalCount < my_activity.totalCount

tests/test_wrapper.py

@@ -1,41 +1,81 @@
 import pytest
-from specklepy.api.credentials import StreamWrapper
+from specklepy.api.wrapper import StreamWrapper
 
 
-class TestWrapper:
-    def test_parse_stream(self):
-        wrap = StreamWrapper("https://testing.speckle.dev/streams/a75ab4f10f")
-        assert wrap.type == "stream"
+def test_parse_stream():
+    wrap = StreamWrapper("https://testing.speckle.dev/streams/a75ab4f10f")
+    assert wrap.type == "stream"
 
-    def test_parse_branch(self):
-        wacky_wrap = StreamWrapper(
-            "https://testing.speckle.dev/streams/4c3ce1459c/branches/%F0%9F%8D%95%E2%AC%85%F0%9F%8C%9F%20you%20wat%3F"
-        )
-        wrap = StreamWrapper(
-            "https://testing.speckle.dev/streams/4c3ce1459c/branches/next%20level"
-        )
-        assert wacky_wrap.type == "branch"
-        assert wacky_wrap.branch_name == "🍕⬅🌟 you wat?"
-        assert wrap.type == "branch"
 
-    def test_parse_commit(self):
-        wrap = StreamWrapper(
-            "https://testing.speckle.dev/streams/4c3ce1459c/commits/8b9b831792"
-        )
-        assert wrap.type == "commit"
+def test_parse_branch():
+    wacky_wrap = StreamWrapper(
+        "https://testing.speckle.dev/streams/4c3ce1459c/branches/%F0%9F%8D%95%E2%AC%85%F0%9F%8C%9F%20you%20wat%3F"
+    )
+    wrap = StreamWrapper(
+        "https://testing.speckle.dev/streams/4c3ce1459c/branches/next%20level"
+    )
+    assert wacky_wrap.type == "branch"
+    assert wacky_wrap.branch_name == "🍕⬅🌟 you wat?"
+    assert wrap.type == "branch"
 
-    def test_parse_object(self):
-        wrap = StreamWrapper(
-            "https://testing.speckle.dev/streams/a75ab4f10f/objects/5530363e6d51c904903dafc3ea1d2ec6"
-        )
-        assert wrap.type == "object"
 
-    def test_parse_globals_as_branch(self):
-        wrap = StreamWrapper("https://testing.speckle.dev/streams/0c6ad366c4/globals/")
-        assert wrap.type == "branch"
+def test_parse_nested_branch():
+    wrap = StreamWrapper(
+        "https://testing.speckle.dev/streams/4c3ce1459c/branches/izzy/dev"
+    )
 
-    def test_parse_globals_as_commit(self):
-        wrap = StreamWrapper(
-            "https://testing.speckle.dev/streams/0c6ad366c4/globals/abd3787893"
-        )
-        assert wrap.type == "commit"
+    assert wrap.branch_name == "izzy/dev"
+    assert wrap.type == "branch"
+
+
+def test_parse_commit():
+    wrap = StreamWrapper(
+        "https://testing.speckle.dev/streams/4c3ce1459c/commits/8b9b831792"
+    )
+    assert wrap.type == "commit"
+
+
+def test_parse_object():
+    wrap = StreamWrapper(
+        "https://testing.speckle.dev/streams/a75ab4f10f/objects/5530363e6d51c904903dafc3ea1d2ec6"
+    )
+    assert wrap.type == "object"
+
+
+def test_parse_globals_as_branch():
+    wrap = StreamWrapper("https://testing.speckle.dev/streams/0c6ad366c4/globals/")
+    assert wrap.type == "branch"
+
+
+def test_parse_globals_as_commit():
+    wrap = StreamWrapper(
+        "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():
+    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():
+    wrap = StreamWrapper("https://speckle.xyz/streams/4c3ce1459c/commits/8b9b831792")
+    client = wrap.get_client()
+    client = wrap.get_client(token="super-secret-token")
+
+    assert client.account.token == "super-secret-token"
+
+
+def test_get_transport_with_token():
+    wrap = StreamWrapper("https://speckle.xyz/streams/4c3ce1459c/commits/8b9b831792")
+    client = wrap.get_client()
+    assert not client.account.token  # unauthenticated bc no local accounts
+
+    transport = wrap.get_transport(token="super-secret-token")
+
+    assert transport is not None
+    assert client.account.token == "super-secret-token"