Merge pull request #319 from specklesystems/gergo/automate_report_logging

Gergo/automate report logging

.circleci/config.yml

@@ -6,48 +6,38 @@ orbs:
 
 jobs:
   test:
-    docker:
-      - image: "cimg/python:<<parameters.tag>>"
-      - image: "cimg/node:16.15"
-      - image: "cimg/redis:6.2"
-      - image: "cimg/postgres:14.2"
-        environment:
-          POSTGRES_DB: speckle2_test
-          POSTGRES_PASSWORD: speckle
-          POSTGRES_USER: speckle
-      - 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"
+    machine:
+      image: ubuntu-2204:2023.02.1
+      docker_layer_caching: false
+    resource_class: medium
     parameters:
       tag:
-        default: "3.8"
+        default: "3.11"
         type: string
     steps:
       - checkout
-      - run: python --version
       - run:
-          command: python -m pip install --upgrade pip
-          name: upgrade pip
-      - python/install-packages:
-          pkg-manager: poetry
-      - run: poetry run pytest --cov --cov-report xml:reports/coverage.xml --junitxml=reports/test-results.xml
-
+          name: Install python
+          command: |
+            pyenv install -s << parameters.tag >>
+            pyenv global << parameters.tag >>
+      - run:
+          name: Startup the Speckle Server
+          command: docker compose -f docker-compose.yml up -d
+      - run:
+          name: Install Poetry
+          command: |
+            pip install poetry
+      - run:
+          name: Install packages
+          command: poetry install
+      - run:
+          name: Run tests
+          command: 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:
@@ -57,7 +47,7 @@ jobs:
       - checkout
       - run: python patch_version.py $CIRCLE_TAG
       - run: poetry build
-      - run: poetry publish -u specklesystems -p $PYPI_PASSWORD
+      - run: poetry publish -u __token__ -p $PYPI_TOKEN
 
 workflows:
   main:
@@ -65,11 +55,12 @@ workflows:
       - test:
           matrix:
             parameters:
-              tag: ["3.7", "3.8", "3.9", "3.10"]
+              tag: ["3.11"]
           filters:
             tags:
               only: /.*/
       - deploy:
+          context: pypi
           requires:
             - test
           filters:

.devcontainer/devcontainer.json

@@ -52,4 +52,4 @@
 	"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

@@ -41,4 +41,4 @@ services:
     command: /bin/sh -c "while sleep 1000; do :; done"
     network_mode: host
 # networks:
-#     default:
+#     default:

.gitattributes

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

.github/workflows/close-issue.yml

@@ -1,77 +0,0 @@
-name: Update issue Status
-
-on:
-  issues:
-    types: [closed]
-
-jobs:
-  update_issue:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Get project data
-        env:
-          GITHUB_TOKEN: ${{secrets.GHPROJECT_TOKEN}}
-          ORGANIZATION: specklesystems
-          PROJECT_NUMBER: 9
-        run: |
-          gh api graphql --header 'GraphQL-Features: projects_next_graphql' -f query='
-            query($org: String!, $number: Int!) {
-              organization(login: $org){
-                projectNext(number: $number) {
-                  id
-                  fields(first:20) {
-                    nodes {
-                      id
-                      name
-                      settings
-                    }
-                  }
-                }
-              }
-            }' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json
-
-          echo 'PROJECT_ID='$(jq '.data.organization.projectNext.id' project_data.json) >> $GITHUB_ENV
-          echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $GITHUB_ENV
-
-          echo "$PROJECT_ID"
-          echo "$STATUS_FIELD_ID"
-
-          echo 'DONE_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Status") | .settings | fromjson | .options[] | select(.name== "Done") | .id' project_data.json) >> $GITHUB_ENV
-          echo "$DONE_ID"
-
-      - name: Add Issue to project #it's already in the project, but we do this to get its node id!
-        env:
-          GITHUB_TOKEN: ${{secrets.GHPROJECT_TOKEN}}
-          ISSUE_ID: ${{ github.event.issue.node_id }}
-        run: |
-          item_id="$( gh api graphql --header 'GraphQL-Features: projects_next_graphql' -f query='
-            mutation($project:ID!, $id:ID!) {
-              addProjectNextItem(input: {projectId: $project, contentId: $id}) {
-                projectNextItem {
-                  id
-                }
-              }
-            }' -f project=$PROJECT_ID -f id=$ISSUE_ID --jq '.data.addProjectNextItem.projectNextItem.id')"
-
-          echo 'ITEM_ID='$item_id >> $GITHUB_ENV
-
-      - name: Update Status
-        env:
-          GITHUB_TOKEN: ${{secrets.GHPROJECT_TOKEN}}
-          ISSUE_ID: ${{ github.event.issue.node_id }}
-        run: |
-          gh api graphql --header 'GraphQL-Features: projects_next_graphql' -f query='
-            mutation($project:ID!, $status:ID!, $id:ID!, $value:String!) {
-              set_status: updateProjectNextItemField(
-                input: {
-                  projectId: $project
-                  itemId: $id
-                  fieldId: $status
-                  value: $value
-                }
-              ) {
-                projectNextItem {
-                  id
-                }
-              }
-            }' -f project=$PROJECT_ID -f status=$STATUS_FIELD_ID -f id=$ITEM_ID -f value=${{ env.DONE_ID }}

.github/workflows/open-issue.yml

@@ -1,50 +0,0 @@
-name: Move new issues into Project
-
-on:
-  issues:
-    types: [opened]
-
-jobs:
-  track_issue:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Get project data
-        env:
-          GITHUB_TOKEN: ${{secrets.GHPROJECT_TOKEN}}
-          ORGANIZATION: specklesystems
-          PROJECT_NUMBER: 9
-        run: |
-          gh api graphql --header 'GraphQL-Features: projects_next_graphql' -f query='
-            query($org: String!, $number: Int!) {
-              organization(login: $org){
-                projectNext(number: $number) {
-                  id
-                  fields(first:20) {
-                    nodes {
-                      id
-                      name
-                      settings
-                    }
-                  }
-                }
-              }
-            }' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json
-
-          echo 'PROJECT_ID='$(jq '.data.organization.projectNext.id' project_data.json) >> $GITHUB_ENV
-          echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectNext.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $GITHUB_ENV
-
-      - name: Add Issue to project
-        env:
-          GITHUB_TOKEN: ${{secrets.GHPROJECT_TOKEN}}
-          ISSUE_ID: ${{ github.event.issue.node_id }}
-        run: |
-          item_id="$( gh api graphql --header 'GraphQL-Features: projects_next_graphql' -f query='
-            mutation($project:ID!, $id:ID!) {
-              addProjectNextItem(input: {projectId: $project, contentId: $id}) {
-                projectNextItem {
-                  id
-                }
-              }
-            }' -f project=$PROJECT_ID -f id=$ISSUE_ID --jq '.data.addProjectNextItem.projectNextItem.id')"
-
-          echo 'ITEM_ID='$item_id >> $GITHUB_ENV

.gitignore

@@ -112,4 +112,4 @@ venv.bak/
 
 # other
 scratch.py
-settings.json
+settings.json

.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    hooks:
+      - id: ruff
+    rev: v0.0.186
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    hooks:
+    - id: commitizen
+    - id: commitizen-branch
+      stages:
+      - push
+    rev: v2.38.0
+
+  - repo: https://github.com/pycqa/isort
+    rev: v5.11.3
+    hooks:
+      - id: isort
+
+  - repo: https://github.com/psf/black
+    rev: 22.12.0
+    hooks:
+      - id: black
+        # It is recommended to specify the latest version of Python
+        # supported by your project here, or alternatively use
+        # pre-commit's default_language_version, see
+        # https://pre-commit.com/#top_level-default_language_version
+        # language_version: python3.11
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace

.vscode/launch.json

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

README.md

@@ -34,7 +34,7 @@ What is Speckle? Check our ![YouTube Video Views](https://img.shields.io/youtube
 Give Speckle a try in no time by:
 
 - [![speckle XYZ](https://img.shields.io/badge/https://-speckle.xyz-0069ff?style=flat-square&logo=hackthebox&logoColor=white)](https://speckle.xyz) ⇒ creating an account at our public server
-- [![create a droplet](https://img.shields.io/badge/Create%20a%20Droplet-0069ff?style=flat-square&logo=digitalocean&logoColor=white)](https://marketplace.digitalocean.com/apps/speckle-server?refcode=947a2b5d7dc1) ⇒ deploying an instance in 1 click 
+- [![create a droplet](https://img.shields.io/badge/Create%20a%20Droplet-0069ff?style=flat-square&logo=digitalocean&logoColor=white)](https://marketplace.digitalocean.com/apps/speckle-server?refcode=947a2b5d7dc1) ⇒ deploying an instance in 1 click
 
 ### Resources
 
@@ -47,7 +47,7 @@ Give Speckle a try in no time by:
 
 ## Usage
 
-Send and receive data from a Speckle Server with `operations`, interact with the Speckle API with the `SpeckleClient`, create and extend your own custom Speckle Objects with `Base`, and more! 
+Send and receive data from a Speckle Server with `operations`, interact with the Speckle API with the `SpeckleClient`, create and extend your own custom Speckle Objects with `Base`, and more!
 
 Head to the [**📚 specklepy docs**](https://speckle.guide/dev/python.html) for more information and usage examples.
 
@@ -65,6 +65,12 @@ To execute any python script run `$ poetry run python my_script.py`
 
 > Alternatively you may roll your own virtual-env with either venv, virtualenv, pyenv-virtualenv etc. Poetry will play along an recognize if it is invoked from inside a virtual environment.
 
+### Style guide
+
+All our repo  wide styling linting and other rules are checked and enforced by `pre-commit`, which is included in the dev dependencies.
+It is recommended to set up `pre-commit` after installing the dependencies by running `$ pre-commit install`.
+Commiting code that doesn't adhere to the given rules, will fail the checks in our CI system.
+
 ### Local Data Paths
 
 It may be helpful to know where the local accounts and object cache dbs are stored. Depending on on your OS, you can find the dbs at:
@@ -82,7 +88,7 @@ The Speckle Community hangs out on [the forum](https://discourse.speckle.works),
 
 ## Security
 
-For any security vulnerabilities or concerns, please contact us directly at security[at]speckle.systems. 
+For any security vulnerabilities or concerns, please contact us directly at security[at]speckle.systems.
 
 ## License
 

docker-compose.yml

@@ -0,0 +1,162 @@
+version: "3.9"
+name: "speckle-server"
+
+services:
+  ####
+  # Speckle Server dependencies
+  #######
+  postgres:
+    image: "postgres:14.5-alpine"
+    restart: always
+    environment:
+      POSTGRES_DB: speckle
+      POSTGRES_USER: speckle
+      POSTGRES_PASSWORD: speckle
+    volumes:
+      - postgres-data:/var/lib/postgresql/data/
+    healthcheck:
+      # the -U user has to match the POSTGRES_USER value
+      test: ["CMD-SHELL", "pg_isready -U speckle"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+
+  redis:
+    image: "redis:6.0-alpine"
+    restart: always
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "--raw", "incr", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+
+  minio:
+    image: "minio/minio:RELEASE.2023-10-25T06-33-25Z"
+    command: server /data --console-address ":9001"
+    restart: always
+    volumes:
+      - minio-data:/data
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "curl -s -o /dev/null http://127.0.0.1:9000/minio/index.html",
+        ]
+      interval: 5s
+      timeout: 30s
+      retries: 30
+      start_period: 10s
+
+  ####
+  # Speckle Server
+  #######
+  speckle-frontend:
+    image: speckle/speckle-frontend:latest
+    restart: always
+    ports:
+      - "0.0.0.0:8080:8080"
+    environment:
+      FILE_SIZE_LIMIT_MB: 100
+
+  speckle-server:
+    image: speckle/speckle-server:latest
+    restart: always
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "node",
+          "-e",
+          "require('node:http').request({headers: {'Content-Type': 'application/json'}, port:3000, hostname:'127.0.0.1', path:'/graphql?query={serverInfo{version}}', method: 'GET' }, (res) => { body = ''; res.on('data', (chunk) => {body += chunk;}); res.on('end', () => {process.exit(res.statusCode != 200 || body.toLowerCase().includes('error'));}); }).end();",
+        ]
+      interval: 10s
+      timeout: 3s
+      retries: 30
+    ports:
+      - "0.0.0.0:3000:3000"
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+    environment:
+      # TODO: Change this to the URL of the speckle server, as accessed from the network
+      CANONICAL_URL: "http://127.0.0.1:8080"
+      SPECKLE_AUTOMATE_URL: "http://127.0.0.1:3030"
+
+      # TODO: Change thvolumes:
+      REDIS_URL: "redis://redis"
+
+      S3_ENDPOINT: "http://minio:9000"
+      S3_ACCESS_KEY: "minioadmin"
+      S3_SECRET_KEY: "minioadmin"
+      S3_BUCKET: "speckle-server"
+      S3_CREATE_BUCKET: "true"
+
+      FILE_SIZE_LIMIT_MB: 100
+
+      # TODO: Change this to a unique secret for this server
+      SESSION_SECRET: "TODO:ReplaceWithLongString"
+
+      STRATEGY_LOCAL: "true"
+      DEBUG: "speckle:*"
+
+      POSTGRES_URL: "postgres"
+      POSTGRES_USER: "speckle"
+      POSTGRES_PASSWORD: "speckle"
+      POSTGRES_DB: "speckle"
+      ENABLE_MP: "false"
+
+  preview-service:
+    image: speckle/speckle-preview-service:latest
+    restart: always
+    depends_on:
+      speckle-server:
+        condition: service_healthy
+    mem_limit: "1000m"
+    memswap_limit: "1000m"
+    environment:
+      DEBUG: "preview-service:*"
+      PG_CONNECTION_STRING: "postgres://speckle:speckle@postgres/speckle"
+
+  webhook-service:
+    image: speckle/speckle-webhook-service:latest
+    restart: always
+    depends_on:
+      speckle-server:
+        condition: service_healthy
+    environment:
+      DEBUG: "webhook-service:*"
+      PG_CONNECTION_STRING: "postgres://speckle:speckle@postgres/speckle"
+      WAIT_HOSTS: postgres:5432
+
+  fileimport-service:
+    image: speckle/speckle-fileimport-service:latest
+    restart: always
+    depends_on:
+      speckle-server:
+        condition: service_healthy
+    environment:
+      DEBUG: "fileimport-service:*"
+      PG_CONNECTION_STRING: "postgres://speckle:speckle@postgres/speckle"
+      WAIT_HOSTS: postgres:5432
+
+      S3_ENDPOINT: "http://minio:9000"
+      S3_ACCESS_KEY: "minioadmin"
+      S3_SECRET_KEY: "minioadmin"
+      S3_BUCKET: "speckle-server"
+
+      SPECKLE_SERVER_URL: "http://speckle-server:3000"
+
+networks:
+  default:
+    name: speckle-server
+
+volumes:
+  postgres-data:
+  redis-data:
+  minio-data:

example/many_children.py

@@ -1,12 +1,13 @@
-from typing import List
-from specklepy.objects import Base
-from specklepy.api import operations
-from specklepy.transports.sqlite import SQLiteTransport
+import os
+import random
+import string
 import time
 from pathlib import Path
-import os
-import string
-import random
+from typing import List
+
+from specklepy.api import operations
+from specklepy.objects import Base
+from specklepy.transports.sqlite import SQLiteTransport
 
 
 class Sub(Base):
@@ -26,7 +27,6 @@ def clean_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"

example/send_receive.py

@@ -0,0 +1,15 @@
+from devtools import debug
+
+from specklepy.api import operations
+from specklepy.api.wrapper import StreamWrapper
+
+if __name__ == "__main__":
+    stream_url = "https://latest.speckle.dev/streams/7d051a6449"
+    wrapper = StreamWrapper(stream_url)
+
+    transport = wrapper.get_transport()
+
+    rec = operations.receive("98396753f8bf7fe1cb60c5193e9f9d86", transport)
+
+    # hash = operations.send(base=foo, transports=[transport], use_default_cache=False)
+    debug(rec)

example/stream_objects.py

@@ -0,0 +1,39 @@
+import random
+import string
+from typing import List
+
+from specklepy.api import operations
+from specklepy.api.wrapper import StreamWrapper
+from specklepy.objects import Base
+
+
+class Sub(Base):
+    bar: List[str]
+
+
+def random_string():
+    letters = string.ascii_lowercase
+    return "".join(random.choice(letters) for _ in range(10))
+
+
+def create_object(child_count: int) -> Base:
+    foo = Base()
+    for i in range(child_count):
+        stuff = random_string()
+        foo[f"@child_{i}"] = Sub(bar=["asdf", "bar", i, stuff])
+    return foo
+
+
+if __name__ == "__main__":
+    stream_url = "http://hyperion:3000/streams/2372b54c35"
+
+    child_count = 10
+    foo = create_object(child_count)
+
+    wrapper = StreamWrapper(stream_url)
+    transport = wrapper.get_transport()
+
+    hash = operations.send(base=foo, transports=[transport], use_default_cache=False)
+
+    rec = operations.receive(hash, transport)
+    print(rec)

example/units_none.py

@@ -0,0 +1,36 @@
+from devtools import debug
+
+from specklepy.api import operations
+from specklepy.objects.geometry import Base
+from specklepy.objects.units import Units
+
+dct = {
+    "id": "1234abcd",
+    "units": None,
+    "speckle_type": "Base",
+    "applicationId": None,
+    "totalChildrenCount": 0,
+}
+base = Base()
+for prop, value in dct.items():
+    base.__setattr__(prop, value)
+
+
+debug(base)
+debug(base.units)
+
+base.units = "m"
+debug(base.units)
+base.units = None
+
+debug(base.units)
+
+foo = operations.serialize(base)
+
+base.units = 10
+
+debug(base.units)
+debug(foo)
+
+base.units = Units.mm
+debug(base.units)

example/using_speckle_base.py

@@ -1,10 +1,11 @@
 """This is an example showcasing the usage of speckle `Base` class."""
 
 # the speckle.objects module exposes all speckle provided classes
-from specklepy.objects import Base
-from specklepy.api import operations
 from devtools import debug
 
+from specklepy.api import operations
+from specklepy.objects import Base
+
 
 class ExampleSub(Base):
     """

patch_version.py

@@ -9,7 +9,7 @@ def patch(tag):
         lines = f.readlines()
 
         if "version" not in lines[2]:
-            raise Exception(f"Invalid pyproject.toml. Could not patch version.")
+            raise Exception("Invalid pyproject.toml. Could not patch version.")
 
         lines[2] = f'version = "{tag}"\n'
         with open("pyproject.toml", "w") as file:

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "specklepy"
-version = "2.4.0"
+version = "2.17.8"
 description = "The Python SDK for Speckle 2.0"
 readme = "README.md"
 authors = ["Speckle Systems <devops@speckle.systems>"]
@@ -8,25 +8,38 @@ license = "Apache-2.0"
 repository = "https://github.com/specklesystems/speckle-py"
 documentation = "https://speckle.guide/dev/py-examples.html"
 homepage = "https://speckle.systems/"
+packages = [
+  { include = "specklepy", from = "src" },
+  { include = "speckle_automate", from = "src" },
+]
 
 
 [tool.poetry.dependencies]
-python = ">=3.7.2, <4.0"
-pydantic = "^1.8.2"
+python = ">=3.8.0, <4.0"
+pydantic = "^2.0"
 appdirs = "^1.4.4"
 gql = {extras = ["requests", "websockets"], version = "^3.3.0"}
 ujson = "^5.3.0"
 Deprecated = "^1.2.13"
+stringcase = "^1.2.0"
+attrs = "^23.1.0"
+httpx = "^0.25.0"
 
-[tool.poetry.dev-dependencies]
-black = "^20.8b1"
+[tool.poetry.group.dev.dependencies]
+black = "^22.8.0"
 isort = "^5.7.0"
-pytest = "^6.2.2"
+pytest = "^7.1.3"
 pytest-ordering = "^0.6"
 pytest-cov = "^3.0.0"
 devtools = "^0.8.0"
 pylint = "^2.14.4"
-
+mypy = "^0.982"
+pre-commit = "^2.20.0"
+commitizen = "^2.38.0"
+ruff = "^0.0.187"
+types-deprecated = "^1.2.9"
+types-ujson = "^5.6.0.0"
+types-requests = "^2.28.11.5"
 
 [tool.black]
 exclude = '''
@@ -45,9 +58,16 @@ exclude = '''
 '''
 include = '\.pyi?$'
 line-length = 88
-target-version = ["py37", "py38", "py39", "py310"]
+target-version = ["py37", "py38", "py39", "py310", "py311"]
 
 
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "2.9.2"
+tag_format = "$version"
 [build-system]
 requires = ["poetry-core>=1.0.0"]
 build-backend = "poetry.core.masonry.api"
+
+[tool.isort]
+profile = "black"

specklepy/api/models.py

@@ -1,170 +0,0 @@
-# generated by datamodel-codegen:
-#   filename:  stream_schema.json
-#   timestamp: 2020-11-17T14:33:13+00:00
-
-from datetime import datetime
-from typing import List, Optional
-
-
-from pydantic import BaseModel  # pylint: disable=no-name-in-module
-
-
-class Collaborator(BaseModel):
-    id: Optional[str]
-    name: Optional[str]
-    role: Optional[str]
-    avatar: Optional[str]
-
-
-class Commit(BaseModel):
-    id: Optional[str]
-    message: Optional[str]
-    authorName: Optional[str]
-    authorId: Optional[str]
-    authorAvatar: Optional[str]
-    branchName: 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}, branchName: {self.branchName}, createdAt: {self.createdAt} )"
-
-    def __str__(self) -> str:
-        return self.__repr__()
-
-
-class Commits(BaseModel):
-    totalCount: Optional[int]
-    cursor: Optional[datetime]
-    items: List[Commit] = []
-
-
-class Object(BaseModel):
-    id: Optional[str]
-    speckleType: Optional[str]
-    applicationId: Optional[str]
-    totalChildrenCount: Optional[int]
-    createdAt: Optional[datetime]
-
-
-class Branch(BaseModel):
-    id: Optional[str]
-    name: Optional[str]
-    description: Optional[str]
-    commits: Optional[Commits]
-
-
-class Branches(BaseModel):
-    totalCount: Optional[int]
-    cursor: Optional[datetime]
-    items: List[Branch] = []
-
-
-class Stream(BaseModel):
-    id: Optional[str]
-    name: Optional[str]
-    role: Optional[str]
-    isPublic: Optional[bool]
-    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})"
-
-    def __str__(self) -> str:
-        return self.__repr__()
-
-
-class Streams(BaseModel):
-    totalCount: Optional[int]
-    cursor: Optional[datetime]
-    items: List[Stream] = []
-
-
-class User(BaseModel):
-    id: Optional[str]
-    email: Optional[str]
-    name: Optional[str]
-    bio: Optional[str]
-    company: Optional[str]
-    avatar: Optional[str]
-    verified: Optional[bool]
-    role: Optional[str]
-    streams: Optional[Streams]
-
-    def __repr__(self):
-        return f"User( id: {self.id}, name: {self.name}, email: {self.email}, company: {self.company} )"
-
-    def __str__(self) -> str:
-        return self.__repr__()
-
-
-class PendingStreamCollaborator(BaseModel):
-    id: Optional[str]
-    inviteId: Optional[str]
-    streamId: Optional[str]
-    streamName: Optional[str]
-    title: Optional[str]
-    role: Optional[str]
-    invitedBy: Optional[User]
-    user: Optional[User]
-    token: Optional[str]
-
-    def __repr__(self):
-        return f"PendingStreamCollaborator( inviteId: {self.inviteId}, streamId: {self.streamId}, role: {self.role}, title: {self.title}, invitedBy: {self.user.name if self.user else None})"
-
-    def __str__(self) -> str:
-        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() if self.cursor else None} )"
-
-    def __str__(self) -> str:
-        return self.__repr__()
-
-
-class ServerInfo(BaseModel):
-    name: Optional[str]
-    company: Optional[str]
-    url: Optional[str]
-    description: Optional[str]
-    adminContact: Optional[str]
-    canonicalUrl: Optional[str]
-    roles: Optional[List[dict]]
-    scopes: Optional[List[dict]]
-    authStrategies: Optional[List[dict]]
-    version: Optional[str]

specklepy/api/speckle2schema.graphql

@@ -1,640 +0,0 @@
-
-      
-scalar DateTime
-
-scalar EmailAddress
-
-scalar BigInt
-
-scalar JSONObject
-
-
-      directive @hasScope(scope: String!) on FIELD_DEFINITION
-      directive @hasRole(role: String!) on FIELD_DEFINITION
-
-      type Query {
-      """
-      Stare into the void.
-      """
-        _: String
-      }
-      type Mutation{
-      """
-      The void stares back.
-      """
-      _: String
-      }
-      type Subscription{
-        """
-        It's lonely in the void.
-        """
-        _: String
-      },extend type Query {
-  """
-  Gets a specific app from the server.
-  """
-  app( id: String! ): ServerApp
-
-  """
-  Returns all the publicly available apps on this server.
-  """
-  apps: [ServerAppListItem]
-}
-
-type ServerApp {
-  id: String!
-  secret: String!
-  name: String!
-  description: String
-  termsAndConditionsLink: String
-  logo: String
-  public: Boolean
-  trustByDefault: Boolean
-  author: AppAuthor
-  createdAt: DateTime!
-  redirectUrl: String!
-  scopes: [Scope]!
-}
-
-type ServerAppListItem {
-  id: String!
-  name: String!
-  description: String
-  termsAndConditionsLink: String
-  logo: String
-  author: AppAuthor
-}
-
-type AppAuthor {
-  name: String
-  id: String
-}
-
-extend type User {
-  """
-  Returns the apps you have authorized.
-  """
-  authorizedApps: [ServerAppListItem]
-    @hasRole(role: "server:user")
-    @hasScope(scope: "apps:read")
-
-  """
-  Returns the apps you have created.
-  """
-  createdApps: [ServerAppListItem]
-    @hasRole(role: "server:user")
-    @hasScope(scope: "apps:read")
-}
-
-extend type Mutation {
-  """
-  Register a new third party application.
-  """
-  appCreate(app: AppCreateInput!): String!
-    @hasRole(role: "server:user")
-    @hasScope(scope: "apps:write")
-
-  """
-  Update an existing third party application. **Note: This will invalidate all existing tokens, refresh tokens and access codes and will require existing users to re-authorize it.**
-  """
-  appUpdate(app: AppUpdateInput!): Boolean!
-    @hasRole(role: "server:user")
-    @hasScope(scope: "apps:write")
-
-  """
-  Deletes a thirty party application.
-  """
-  appDelete(appId: String!): Boolean!
-    @hasRole(role: "server:user")
-    @hasScope(scope: "apps:write")
-
-  """
-  Revokes (de-authorizes) an application that you have previously authorized.
-  """
-  appRevokeAccess(appId: String!): Boolean
-    @hasRole(role: "server:user")
-    @hasScope(scope: "apps:write")
-
-}
-
-input AppCreateInput {
-  name: String!
-  description: String!
-  termsAndConditionsLink: String
-  logo: String
-  public: Boolean
-  redirectUrl: String!
-  scopes: [String]!
-}
-
-input AppUpdateInput {
-  id: String!
-  name: String!
-  description: String!
-  termsAndConditionsLink: String
-  logo: String
-  public: Boolean
-  redirectUrl: String!
-  scopes: [String]!
-}
-,extend type ServerInfo {
-  """
-  The authentication strategies available on this server.
-  """
-  authStrategies: [AuthStrategy]
-}
-
-type AuthStrategy {
-  id: String!,
-  name: String!,
-  icon: String!,
-  url: String!,
-  color: String
-}
-,extend type User{
-  """
-  Returns a list of your personal api tokens.
-  """
-  apiTokens: [ApiToken]
-    @hasRole(role: "server:user")
-    @hasScope(scope: "tokens:read")
-}
-
-type ApiToken {
-  id: String!
-  name: String!
-  lastChars: String!
-  scopes: [String]!
-  createdAt: DateTime! #date
-  lifespan: BigInt!
-  lastUsed: String! #date
-}
-
-input ApiTokenCreateInput {
-  scopes: [String!]!,
-  name: String!,
-  lifespan: BigInt
-}
-
-extend type Mutation {
-  """
-  Creates an personal api token.
-  """
-  apiTokenCreate(token: ApiTokenCreateInput!):String!
-    @hasRole(role: "server:user")
-    @hasScope(scope: "tokens:write")
-  """
-  Revokes (deletes) an personal api token.
-  """
-  apiTokenRevoke(token: String!):Boolean!
-    @hasRole(role: "server:user")
-    @hasScope(scope: "tokens:write")
-}
-,extend type Stream {
-  commits(limit: Int! = 25, cursor: String): CommitCollection
-  commit(id: String!): Commit
-  branches(limit: Int! = 25, cursor: String): BranchCollection
-  branch(name: String!): Branch
-}
-
-extend type User {
-  commits(limit: Int! = 25, cursor: String): CommitCollectionUser
-}
-
-type Branch {
-  id: String!
-  name: String!
-  author: User!
-  description: String
-  commits(limit: Int! = 25, cursor: String): CommitCollection
-}
-
-type Commit {
-  id: String!
-  referencedObject: String!
-  message: String
-  authorName: String
-  authorId: String
-  createdAt: DateTime
-}
-
-type CommitCollectionUserNode {
-  id: String!
-  referencedObject: String!
-  message: String
-  streamId: String
-  streamName: String
-  createdAt: DateTime
-}
-
-type BranchCollection {
-  totalCount: Int!
-  cursor: String
-  items: [Branch]
-}
-
-type CommitCollection {
-  totalCount: Int!
-  cursor: String
-  items: [Commit]
-}
-
-type CommitCollectionUser {
-  totalCount: Int!
-  cursor: String
-  items: [CommitCollectionUserNode]
-}
-
-extend type Mutation {
-  branchCreate(branch: BranchCreateInput!): String!
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:write")
-  branchUpdate(branch: BranchUpdateInput!): Boolean!
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:write")
-  branchDelete(branch: BranchDeleteInput!): Boolean!
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:write")
-
-  commitCreate(commit: CommitCreateInput!): String!
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:write")
-  commitUpdate(commit: CommitUpdateInput!): Boolean!
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:write")
-  commitDelete(commit: CommitDeleteInput!): Boolean!
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:write")
-}
-
-extend type Subscription {
-  # TODO: auth for these subscriptions
-  """
-  Subscribe to branch created event
-  """
-  branchCreated(streamId: String!): JSONObject
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:read")
-  """
-  Subscribe to branch updated event.
-  """
-  branchUpdated(streamId: String!, branchId: String): JSONObject
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:read")
-  """
-  Subscribe to branch deleted event
-  """
-  branchDeleted(streamId: String!): JSONObject
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:read")
-
-  """
-  Subscribe to commit created event
-  """
-  commitCreated(streamId: String!): JSONObject
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:read")
-  """
-  Subscribe to commit updated event.
-  """
-  commitUpdated(streamId: String!, commitId: String): JSONObject
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:read")
-  """
-  Subscribe to commit deleted event
-  """
-  commitDeleted(streamId: String!): JSONObject
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:read")
-}
-
-input BranchCreateInput {
-  streamId: String!
-  name: String!
-  description: String
-}
-
-input BranchUpdateInput {
-  streamId: String!
-  id: String!
-  name: String
-  description: String
-}
-
-input BranchDeleteInput {
-  streamId: String!
-  id: String!
-}
-
-input CommitCreateInput {
-  streamId: String!
-  branchName: String!
-  objectId: String!
-  message: String
-  previousCommitIds: [String]
-}
-
-input CommitUpdateInput {
-  streamId: String!
-  id: String!
-  message: String!
-}
-
-input CommitDeleteInput {
-  streamId: String!
-  id: String!
-}
-,extend type Stream {
-  object( id: String! ): Object
-}
-
-type Object {
-  id: String! 
-  speckleType: String!
-  applicationId: String
-  createdAt: DateTime
-  totalChildrenCount: Int
-  """
-  The full object, with all its props & other things. **NOTE:** If you're requesting objects for the purpose of recreating & displaying, you probably only want to request this specific field.
-  """
-  data: JSONObject
-  """
-  Get any objects that this object references. In the case of commits, this will give you a commit's constituent objects.
-  **NOTE**: Providing any of the two last arguments ( `query`, `orderBy` ) will trigger a different code branch that executes a much more expensive SQL query. It is not recommended to do so for basic clients that are interested in purely getting all the objects of a given commit.
-  """
-  children(
-    limit: Int! = 100, 
-    depth: Int! = 50, 
-    select: [String], 
-    cursor: String, 
-    query: [JSONObject!],
-    orderBy: JSONObject  ): ObjectCollection!
-}
-
-type ObjectCollection {
-  totalCount: Int!
-  cursor: String
-  objects: [Object]!
-}
-
-extend type Mutation {
-  objectCreate( objectInput: ObjectCreateInput! ): [String]!
-}
-
-input ObjectCreateInput {
-  """
-  The stream against which these objects will be created. 
-  """
-  streamId: String!
-  """
-  The objects you want to create.
-  """
-  objects: [JSONObject]!
-},extend type Query {
-  serverInfo: ServerInfo!
-}
-
-"""
-Information about this server.
-"""
-type ServerInfo {
-  name: String!
-  company: String
-  description: String
-  adminContact: String
-  canonicalUrl: String
-  termsOfService: String
-  roles: [Role]!
-  scopes: [Scope]!
-}
-
-"""
-Available roles.
-"""
-type Role {
-  name: String!
-  description: String!
-  resourceTarget: String!
-}
-
-"""
-Available scopes.
-"""
-type Scope {
-  name: String!
-  description: String!
-}
-
-extend type Mutation {
-  serverInfoUpdate(info: ServerInfoUpdateInput!): Boolean
-    @hasRole(role: "server:admin")
-    @hasScope(scope: "server:setup")
-}
-
-input ServerInfoUpdateInput {
-  name: String!
-  company: String
-  description: String
-  adminContact: String
-  termsOfService: String
-}
-,extend type Query {
-  """
-  Returns a specific stream.
-  """
-  stream( id: String! ): Stream
-
-  """
-  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")
-}
-
-type Stream {
-  id: String!
-  name: String!
-  description: String
-  isPublic: Boolean!
-  createdAt: DateTime!
-  updatedAt: DateTime!
-  collaborators: [ StreamCollaborator ]!
-}
-
-extend type User {
-  """
-  All the streams that a user has access to.
-  """
-  streams( limit: Int! = 25, cursor: String ): StreamCollection
-}
-
-type StreamCollaborator {
-  id: String!
-  name: String!
-  role: String!
-  company: String
-  avatar: String
-}
-
-type StreamCollection {
-  totalCount: Int!
-  cursor: String
-  items: [ Stream ]
-}
-
-
-extend type Mutation {
-  """
-  Creates a new stream.
-  """
-  streamCreate( stream: StreamCreateInput! ): String
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:write")
-  """
-  Updates an existing stream.
-  """
-  streamUpdate( stream: StreamUpdateInput! ): Boolean!
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:write")
-  """
-  Deletes an existing stream.
-  """
-  streamDelete( id: String! ): Boolean!
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:write")
-  """
-  Grants permissions to a user on a given stream.
-  """
-  streamGrantPermission( permissionParams: StreamGrantPermissionInput! ): Boolean
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:write")
-  """
-  Revokes the permissions of a user on a given stream.
-  """
-  streamRevokePermission( permissionParams: StreamRevokePermissionInput! ): Boolean
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:write")
-}
-
-extend type Subscription {
-
-  #
-  # User bound subscriptions that operate on the stream collection of an user
-  # Example relevant view/usecase: updating the list of streams for a user.
-  #
-
-  """
-  Subscribes to new stream added event for your profile. Use this to display an up-to-date list of streams.
-  **NOTE**: If someone shares a stream with you, this subscription will be triggered with an extra value of `sharedBy` in the payload.
-  """
-  userStreamAdded: JSONObject
-    @hasRole(role: "server:user")
-    @hasScope(scope: "profile:read")
-
-  """
-  Subscribes to stream removed event for your profile. Use this to display an up-to-date list of streams for your profile.
-  **NOTE**: If someone revokes your permissions on a stream, this subscription will be triggered with an extra value of `revokedBy` in the payload.
-  """
-  userStreamRemoved: JSONObject
-    @hasRole(role: "server:user")
-    @hasScope(scope: "profile:read")
-
-  #
-  # Stream bound subscriptions that operate on the stream itself.
-  # Example relevant view/usecase: a single stream connector, or view, or component in a web app
-  #
-
-  """
-  Subscribes to stream updated event. Use this in clients/components that pertain only to this stream.
-  """
-  streamUpdated( streamId: String ): JSONObject
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:read")
-
-  """
-  Subscribes to stream deleted event. Use this in clients/components that pertain only to this stream.
-  """
-  streamDeleted( streamId: String ): JSONObject
-    @hasRole(role: "server:user")
-    @hasScope(scope: "streams:read")
-
-}
-
-input StreamCreateInput {
-  name: String
-  description: String
-  isPublic: Boolean
-}
-
-input StreamUpdateInput {
-  id: String!
-  name: String
-  description: String
-  isPublic: Boolean
-}
-
-input StreamGrantPermissionInput {
-  streamId: String!,
-  userId: String!,
-  role: String!
-}
-
-input StreamRevokePermissionInput {
-  streamId: String!,
-  userId: String!
-}
-,extend type Query {
-  """
-  Gets the profile of a user. If no id argument is provided, will return the current authenticated user's profile (as extracted from the authorization header).
-  """
-  user(id: String): User
-  userSearch(
-    query: String!
-    limit: Int! = 25
-    cursor: String
-  ): UserSearchResultCollection
-  userPwdStrength(pwd: String!): JSONObject
-}
-
-"""
-Base user type.
-"""
-type User {
-  id: String!
-  suuid: String
-  email: String
-  name: String
-  bio: String
-  company: String
-  avatar: String
-  verified: Boolean
-  profiles: JSONObject
-  role: String
-}
-
-type UserSearchResultCollection {
-  cursor: String
-  items: [UserSearchResult]
-}
-
-type UserSearchResult {
-  id: String!
-  name: String
-  bio: String
-  company: String
-  avatar: String
-  verified: Boolean
-}
-
-extend type Mutation {
-  """
-  Edits a user's profile.
-  """
-  userUpdate(user: UserUpdateInput!): Boolean!
-}
-
-input UserUpdateInput {
-  name: String
-  company: String
-  bio: String
-}

specklepy/objects/__init__.py

@@ -1,5 +0,0 @@
-"""Builtin Speckle object kit."""
-
-from specklepy.objects.base import Base
-
-__all__ = ["Base"]

specklepy/objects/structural/__init__.py

@@ -1,40 +0,0 @@
-"""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

@@ -1,51 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,108 +0,0 @@
-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/results.py

@@ -1,174 +0,0 @@
-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,63 +0,0 @@
-from warnings import warn
-from specklepy.logging.exceptions import SpeckleException, SpeckleWarning
-
-UNITS = ["mm", "cm", "m", "in", "ft", "yd", "mi"]
-
-UNITS_STRINGS = {
-    "mm": ["mm", "mil", "millimeters", "millimetres"],
-    "cm": ["cm", "centimetre", "centimeter", "centimetres", "centimeters"],
-    "m": ["m", "meter", "meters", "metre", "metres"],
-    "km": ["km", "kilometer", "kilometre", "kilometers", "kilometres"],
-    "in": ["in", "inch", "inches"],
-    "ft": ["ft", "foot", "feet"],
-    "yd": ["yd", "yard", "yards"],
-    "mi": ["mi", "mile", "miles"],
-    "none": ["none", "null"],
-}
-
-UNITS_ENCODINGS = {
-    "none": 0,
-    None: 0,
-    "mm": 1,
-    "cm": 2,
-    "m": 3,
-    "km": 4,
-    "in": 5,
-    "ft": 6,
-    "yd": 7,
-    "mi": 8,
-}
-
-
-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:
-            return name
-
-    raise SpeckleException(
-        message=f"Could not understand what unit {unit} is referring to. Please enter a valid unit (eg {UNITS})."
-    )
-
-
-def get_units_from_encoding(unit: int):
-    for name, encoding in UNITS_ENCODINGS.items():
-        if unit == encoding:
-            return name
-
-    raise SpeckleException(
-        message=f"Could not understand what unit {unit} is referring to. Please enter a valid unit encoding (eg {UNITS_ENCODINGS})."
-    )
-
-
-def get_encoding_from_units(unit: str):
-    try:
-        return UNITS_ENCODINGS[unit]
-    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/transports/server/__init__.py

@@ -1 +0,0 @@
-from .server import ServerTransport

src/speckle_automate/__init__.py

@@ -0,0 +1,23 @@
+"""This module contains an SDK for working with Speckle Automate."""
+from speckle_automate.automation_context import AutomationContext
+from speckle_automate.runner import execute_automate_function, run_function
+from speckle_automate.schema import (
+    AutomateBase,
+    AutomationResult,
+    AutomationRunData,
+    AutomationStatus,
+    ObjectResultLevel,
+    ResultCase,
+)
+
+__all__ = [
+    "AutomationContext",
+    "AutomateBase",
+    "AutomationStatus",
+    "AutomationResult",
+    "AutomationRunData",
+    "ResultCase",
+    "ObjectResultLevel",
+    "run_function",
+    "execute_automate_function",
+]

src/speckle_automate/automation_context.py

@@ -0,0 +1,421 @@
+"""This module provides an abstraction layer above the Speckle Automate runtime."""
+from dataclasses import dataclass, field
+from pathlib import Path
+import time
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import httpx
+from gql import gql
+from specklepy.api import operations
+from specklepy.api.client import SpeckleClient
+from specklepy.core.api.models import Branch
+from specklepy.objects import Base
+from specklepy.transports.memory import MemoryTransport
+from specklepy.transports.server import ServerTransport
+from specklepy.logging.exceptions import SpeckleException
+
+from speckle_automate.schema import (
+    AutomateBase,
+    AutomationResult,
+    AutomationRunData,
+    AutomationStatus,
+    ObjectResultLevel,
+    ResultCase,
+)
+
+
+@dataclass
+class AutomationContext:
+    """A context helper class.
+
+    This class exposes methods to work with the Speckle Automate context inside
+    Speckle Automate functions.
+
+    An instance of AutomationContext is injected into every run of a function.
+    """
+
+    automation_run_data: AutomationRunData
+    speckle_client: SpeckleClient
+    _server_transport: ServerTransport
+    _speckle_token: str
+
+    #: keep a memory transponrt at hand, to speed up things if needed
+    _memory_transport: MemoryTransport = field(default_factory=MemoryTransport)
+
+    #: added for performance measuring
+    _init_time: float = field(default_factory=time.perf_counter)
+    _automation_result: AutomationResult = field(default_factory=AutomationResult)
+
+    @classmethod
+    def initialize(
+        cls, automation_run_data: Union[str, AutomationRunData], speckle_token: str
+    ) -> "AutomationContext":
+        """Bootstrap the AutomateSDK from raw data.
+
+        Todo:
+        ----
+            * bootstrap a structlog logger instance
+            * expose a logger, that ppl can use instead of print
+        """
+        # parse the json value if its not an initialized project data instance
+        automation_run_data = (
+            automation_run_data
+            if isinstance(automation_run_data, AutomationRunData)
+            else AutomationRunData.model_validate_json(automation_run_data)
+        )
+        speckle_client = SpeckleClient(
+            automation_run_data.speckle_server_url,
+            automation_run_data.speckle_server_url.startswith("https"),
+        )
+        speckle_client.authenticate_with_token(speckle_token)
+        if not speckle_client.account:
+            msg = (
+                f"Could not autenticate to {automation_run_data.speckle_server_url}",
+                "with the provided token",
+            )
+            raise ValueError(msg)
+        server_transport = ServerTransport(
+            automation_run_data.project_id, speckle_client
+        )
+        return cls(automation_run_data, speckle_client, server_transport, speckle_token)
+
+    @property
+    def run_status(self) -> AutomationStatus:
+        """Get the status of the automation run."""
+        return self._automation_result.run_status
+
+    @property
+    def status_message(self) -> Optional[str]:
+        """Get the current status message."""
+        return self._automation_result.status_message
+
+    def elapsed(self) -> float:
+        """Return the elapsed time in seconds since the initialization time."""
+        return time.perf_counter() - self._init_time
+
+    def receive_version(self) -> Base:
+        """Receive the Speckle project version that triggered this automation run."""
+        commit = self.speckle_client.commit.get(
+            self.automation_run_data.project_id, self.automation_run_data.version_id
+        )
+        if not commit.referencedObject:
+            raise ValueError("The commit has no referencedObject, cannot receive it.")
+        base = operations.receive(
+            commit.referencedObject, self._server_transport, self._memory_transport
+        )
+        print(
+            f"It took {self.elapsed():.2f} seconds to receive",
+            f" the speckle version {self.automation_run_data.version_id}",
+        )
+        return base
+
+    def create_new_version_in_project(
+        self, root_object: Base, model_name: str, version_message: str = ""
+    ) -> Tuple[str, str]:
+        """Save a base model to a new version on the project.
+
+        Args:
+            root_object (Base): The Speckle base object for the new version.
+            model_id (str): For now please use a `branchName`!
+            version_message (str): The message for the new version.
+        """
+
+        if model_name == self.automation_run_data.branch_name:
+            raise ValueError(
+                f"The target model: {model_name} cannot match the model"
+                f" that triggered this automation:"
+                f" {self.automation_run_data.model_id} /"
+                f" {self.automation_run_data.branch_name}"
+            )
+
+        branch = self.speckle_client.branch.get(
+            self.automation_run_data.project_id, model_name, 1
+        )
+        # we just check if it exists
+        if (not branch) or isinstance(branch, SpeckleException):
+            branch_create = self.speckle_client.branch.create(
+                self.automation_run_data.project_id,
+                model_name,
+            )
+            if isinstance(branch_create, Exception):
+                raise branch_create
+            model_id = branch_create
+        else:
+            model_id = branch.id
+
+        root_object_id = operations.send(
+            root_object,
+            [self._server_transport, self._memory_transport],
+            use_default_cache=False,
+        )
+
+        version_id = self.speckle_client.commit.create(
+            stream_id=self.automation_run_data.project_id,
+            object_id=root_object_id,
+            branch_name=model_name,
+            message=version_message,
+            source_application="SpeckleAutomate",
+        )
+
+        if isinstance(version_id, SpeckleException):
+            raise version_id
+
+        self._automation_result.result_versions.append(version_id)
+        return model_id, version_id
+
+    @property
+    def context_view(self) -> Optional[str]:
+        return self._automation_result.result_view
+
+    def set_context_view(
+        self,
+        # f"{model_id}@{version_id} or {model_id} "
+        resource_ids: Optional[List[str]] = None,
+        include_source_model_version: bool = True,
+    ) -> None:
+        link_resources = (
+            [
+                f"{self.automation_run_data.model_id}@{self.automation_run_data.version_id}"
+            ]
+            if include_source_model_version
+            else []
+        )
+        if resource_ids:
+            link_resources.extend(resource_ids)
+        if not link_resources:
+            raise Exception(
+                "We do not have enough resource ids to compose a context view"
+            )
+        self._automation_result.result_view = (
+            f"/projects/{self.automation_run_data.project_id}"
+            f"/models/{','.join(link_resources)}"
+        )
+
+    def report_run_status(self) -> None:
+        """Report the current run status to the project of this automation."""
+        query = gql(
+            """
+            mutation ReportFunctionRunStatus(
+                $automationId: String!, 
+                $automationRevisionId: String!, 
+                $automationRunId: String!,
+                $versionId: String!,
+                $functionId: String!,
+                $functionName: String!,
+                $functionLogo: String,
+                $runStatus: AutomationRunStatus!
+                $elapsed: Float!
+                $contextView: String
+                $resultVersionIds: [String!]!
+                $statusMessage: String
+                $objectResults: JSONObject
+            ){
+                automationMutations {
+                    functionRunStatusReport(input: {
+                        automationId: $automationId
+                        automationRevisionId: $automationRevisionId
+                        automationRunId: $automationRunId
+                        versionId: $versionId
+                        functionRuns: [
+                        {
+                            functionId: $functionId
+                            functionName: $functionName
+                            functionLogo: $functionLogo
+                            status: $runStatus,
+                            contextView: $contextView,
+                            elapsed: $elapsed,
+                            resultVersionIds: $resultVersionIds,
+                            statusMessage: $statusMessage
+                            results: $objectResults
+                        }]
+                   })
+                }
+            }
+            """
+        )
+        if self.run_status in [AutomationStatus.SUCCEEDED, AutomationStatus.FAILED]:
+            object_results = {
+                "version": "1.0.0",
+                "values": {
+                    "objectResults": self._automation_result.model_dump(by_alias=True)[
+                        "objectResults"
+                    ],
+                    "blobIds": self._automation_result.blobs,
+                },
+            }
+        else:
+            object_results = None
+
+        params = {
+            "automationId": self.automation_run_data.automation_id,
+            "automationRevisionId": self.automation_run_data.automation_revision_id,
+            "automationRunId": self.automation_run_data.automation_run_id,
+            "versionId": self.automation_run_data.version_id,
+            "functionId": self.automation_run_data.function_id,
+            "functionName": self.automation_run_data.function_name,
+            "functionLogo": self.automation_run_data.function_logo,
+            "runStatus": self.run_status.value,
+            "statusMessage": self._automation_result.status_message,
+            "contextView": self._automation_result.result_view,
+            "elapsed": self.elapsed(),
+            "resultVersionIds": self._automation_result.result_versions,
+            "objectResults": object_results,
+        }
+        print(f"Reporting run status with content: {params}")
+        self.speckle_client.httpclient.execute(query, params)
+
+    def store_file_result(self, file_path: Union[Path, str]) -> None:
+        """Save a file attached to the project of this automation."""
+        path_obj = (
+            Path(file_path).resolve() if isinstance(file_path, str) else file_path
+        )
+
+        class UploadResult(AutomateBase):
+            blob_id: str
+            file_name: str
+            upload_status: int
+
+        class BlobUploadResponse(AutomateBase):
+            upload_results: list[UploadResult]
+
+        if not path_obj.exists():
+            raise ValueError("The given file path doesn't exist")
+        files = {path_obj.name: open(str(path_obj), "rb")}
+
+        url = (
+            f"{self.automation_run_data.speckle_server_url}/api/stream/"
+            f"{self.automation_run_data.project_id}/blob"
+        )
+        data = (
+            httpx.post(
+                url,
+                files=files,
+                headers={"authorization": f"Bearer {self._speckle_token}"},
+            )
+            .raise_for_status()
+            .json()
+        )
+
+        upload_response = BlobUploadResponse.model_validate(data)
+
+        if len(upload_response.upload_results) != 1:
+            raise ValueError("Expecting one upload result.")
+
+        self._automation_result.blobs.extend(
+            [upload_result.blob_id for upload_result in upload_response.upload_results]
+        )
+
+    def mark_run_failed(self, status_message: str) -> None:
+        """Mark the current run a failure."""
+        self._mark_run(AutomationStatus.FAILED, status_message)
+
+    def mark_run_success(self, status_message: Optional[str]) -> None:
+        """Mark the current run a success with an optional message."""
+        self._mark_run(AutomationStatus.SUCCEEDED, status_message)
+
+    def _mark_run(
+        self, status: AutomationStatus, status_message: Optional[str]
+    ) -> None:
+        duration = self.elapsed()
+        self._automation_result.status_message = status_message
+        self._automation_result.run_status = status
+        self._automation_result.elapsed = duration
+
+        msg = f"Automation run {status.value} after {duration:.2f} seconds."
+        print("\n".join([msg, status_message]) if status_message else msg)
+
+    def attach_error_to_objects(
+        self,
+        category: str,
+        object_ids: Union[str, List[str]],
+        message: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        visual_overrides: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Add a new error case to the run results.
+
+        If the error cause has already created an error case,
+        the error will be extended with a new case refering to the causing objects.
+        Args:
+            error_tag (str): A short tag for the error type.
+            causing_object_ids (str[]): A list of object_id-s that are causing the error
+            error_messagge (Optional[str]): Optional error message.
+            metadata: User provided metadata key value pairs
+            visual_overrides: Case specific 3D visual overrides.
+        """
+        self.attach_result_to_objects(
+            ObjectResultLevel.ERROR,
+            category,
+            object_ids,
+            message,
+            metadata,
+            visual_overrides,
+        )
+
+    def attach_warning_to_objects(
+        self,
+        category: str,
+        object_ids: Union[str, List[str]],
+        message: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        visual_overrides: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Add a new warning case to the run results."""
+        self.attach_result_to_objects(
+            ObjectResultLevel.WARNING,
+            category,
+            object_ids,
+            message,
+            metadata,
+            visual_overrides,
+        )
+
+    def attach_info_to_objects(
+        self,
+        category: str,
+        object_ids: Union[str, List[str]],
+        message: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        visual_overrides: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Add a new info case to the run results."""
+        self.attach_result_to_objects(
+            ObjectResultLevel.INFO,
+            category,
+            object_ids,
+            message,
+            metadata,
+            visual_overrides,
+        )
+
+    def attach_result_to_objects(
+        self,
+        level: ObjectResultLevel,
+        category: str,
+        object_ids: Union[str, List[str]],
+        message: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        visual_overrides: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        if isinstance(object_ids, list):
+            if len(object_ids) < 1:
+                raise ValueError(
+                    f"Need atleast one object_id to report a(n) {level.value.upper()}"
+                )
+            id_list = object_ids
+        else:
+            id_list = [object_ids]
+        print(
+            f"Created new {level.value.upper()}"
+            f" category: {category} caused by: {message}"
+        )
+        self._automation_result.object_results.append(
+            ResultCase(
+                category=category,
+                level=level,
+                object_ids=id_list,
+                message=message,
+                metadata=metadata,
+                visual_overrides=visual_overrides,
+            )
+        )

src/speckle_automate/helpers.py

@@ -0,0 +1,54 @@
+"""Some useful helpers for working with automation data."""
+import secrets
+import string
+
+from specklepy.api.client import SpeckleClient
+from gql import gql
+
+
+def register_new_automation(
+    speckle_client: SpeckleClient,
+    project_id: str,
+    model_id: str,
+    automation_id: str,
+    automation_name: str,
+    automation_revision_id: str,
+) -> bool:
+    """Register a new automation in the speckle server."""
+    query = gql(
+        """
+        mutation CreateAutomation(
+            $projectId: String! 
+            $modelId: String! 
+            $automationName: String!
+            $automationId: String! 
+            $automationRevisionId: String!
+        ) {
+                automationMutations {
+                    create(
+                        input: {
+                            projectId: $projectId
+                            modelId: $modelId
+                            automationName: $automationName 
+                            automationId: $automationId
+                            automationRevisionId: $automationRevisionId
+                        }
+                    )
+                }
+            }
+        """
+    )
+    params = {
+        "projectId": project_id,
+        "modelId": model_id,
+        "automationName": automation_name,
+        "automationId": automation_id,
+        "automationRevisionId": automation_revision_id,
+    }
+    return speckle_client.httpclient.execute(query, params)
+
+
+def crypto_random_string(length: int) -> str:
+    """Generate a semi crypto random string of a given length."""
+    alphabet = string.ascii_letters + string.digits
+    return "".join(secrets.choice(alphabet) for _ in range(length)).lower()

src/speckle_automate/runner.py

@@ -0,0 +1,152 @@
+"""Function execution module.
+
+Provides mechanisms to execute any function,
+ that conforms to the AutomateFunction "interface"
+"""
+import json
+import os
+import sys
+import traceback
+from pathlib import Path
+from typing import Callable, Optional, TypeVar, Union, overload
+
+from speckle_automate.automation_context import AutomationContext
+from speckle_automate.schema import AutomateBase, AutomationRunData, AutomationStatus
+
+T = TypeVar("T", bound=AutomateBase)
+
+AutomateFunction = Callable[[AutomationContext, T], None]
+AutomateFunctionWithoutInputs = Callable[[AutomationContext], None]
+
+
+@overload
+def execute_automate_function(
+    automate_function: AutomateFunction[T],
+    input_schema: type[T],
+) -> None:
+    ...
+
+
+@overload
+def execute_automate_function(automate_function: AutomateFunctionWithoutInputs) -> None:
+    ...
+
+
+def execute_automate_function(
+    automate_function: Union[AutomateFunction[T], AutomateFunctionWithoutInputs],
+    input_schema: Optional[type[T]] = None,
+):
+    """Runs the provided automate function with the input schema."""
+    # first arg is the python file name, we do not need that
+    args = sys.argv[1:]
+
+    if len(args) < 2:
+        raise ValueError("too few arguments specified need minimum 2")
+
+    if len(args) > 4:
+        raise ValueError("too many arguments specified, max supported is 4")
+
+    # we rely on a command name convention to decide what to do.
+    # this is here, so that the function authors do not see any of this
+    command = args[0]
+
+    if command == "generate_schema":
+        path = Path(args[1])
+        schema = json.dumps(
+            input_schema.model_json_schema(by_alias=True) if input_schema else {}
+        )
+        path.write_text(schema)
+
+    elif command == "run":
+        automation_run_data = args[1]
+        function_inputs = args[2]
+
+        speckle_token = os.environ.get("SPECKLE_TOKEN", None)
+        if not speckle_token and len(args) != 4:
+            raise ValueError("Cannot get speckle token from arguments or environment")
+
+        speckle_token = speckle_token if speckle_token else args[3]
+        automation_context = AutomationContext.initialize(
+            automation_run_data, speckle_token
+        )
+
+        inputs = (
+            input_schema.model_validate_json(function_inputs)
+            if input_schema
+            else input_schema
+        )
+
+        if inputs:
+            automation_context = run_function(
+                automation_context,
+                automate_function,  # type: ignore
+                inputs,
+            )
+        else:
+            automation_context = run_function(
+                automation_context,
+                automate_function,  # type: ignore
+            )
+
+        exit_code = (
+            0 if automation_context.run_status == AutomationStatus.SUCCEEDED else 1
+        )
+        exit(exit_code)
+
+    else:
+        raise NotImplementedError(f"Command: '{command}' is not supported.")
+
+
+@overload
+def run_function(
+    automation_context: AutomationContext,
+    automate_function: AutomateFunction[T],
+    inputs: T,
+) -> AutomationContext:
+    ...
+
+
+@overload
+def run_function(
+    automation_context: AutomationContext,
+    automate_function: AutomateFunctionWithoutInputs,
+) -> AutomationContext:
+    ...
+
+
+def run_function(
+    automation_context: AutomationContext,
+    automate_function: Union[AutomateFunction[T], AutomateFunctionWithoutInputs],
+    inputs: Optional[T] = None,
+) -> AutomationContext:
+    """Run the provided function with the automate sdk context."""
+    automation_context.report_run_status()
+
+    try:
+        # avoiding complex type gymnastics here on the internals.
+        # the external type overloads make this correct
+        if inputs:
+            automate_function(automation_context, inputs)  # type: ignore
+        else:
+            automate_function(automation_context)  # type: ignore
+
+        # the function author forgot to mark the function success
+        if automation_context.run_status not in [
+            AutomationStatus.FAILED,
+            AutomationStatus.SUCCEEDED,
+        ]:
+            automation_context.mark_run_success(
+                "WARNING: Automate assumed a success status,"
+                " but it was not marked as so by the function."
+            )
+    except Exception:
+        trace = traceback.format_exc()
+        print(trace)
+        automation_context.mark_run_failed(
+            "Function error. Check the automation run logs for details."
+        )
+    finally:
+        if not automation_context.context_view:
+            automation_context.set_context_view()
+        automation_context.report_run_status()
+        return automation_context

src/speckle_automate/schema.py

@@ -0,0 +1,74 @@
+""""""
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+from stringcase import camelcase
+
+
+class AutomateBase(BaseModel):
+    """Use this class as a base model for automate related DTO."""
+
+    model_config = ConfigDict(alias_generator=camelcase, populate_by_name=True)
+
+
+class AutomationRunData(BaseModel):
+    """Values of the project / model that triggered the run of this function."""
+
+    project_id: str
+    model_id: str
+    branch_name: str
+    version_id: str
+    speckle_server_url: str
+
+    automation_id: str
+    automation_revision_id: str
+    automation_run_id: str
+
+    function_id: str
+    function_name: str
+    function_logo: Optional[str]
+
+    model_config = ConfigDict(
+        alias_generator=camelcase, populate_by_name=True, protected_namespaces=()
+    )
+
+
+class AutomationStatus(str, Enum):
+    """Set the status of the automation."""
+
+    INITIALIZING = "INITIALIZING"
+    RUNNING = "RUNNING"
+    FAILED = "FAILED"
+    SUCCEEDED = "SUCCEEDED"
+
+
+class ObjectResultLevel(str, Enum):
+    """Possible status message levels for object reports."""
+
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+
+
+class ResultCase(AutomateBase):
+    """A result case."""
+
+    category: str
+    level: ObjectResultLevel
+    object_ids: List[str]
+    message: Optional[str]
+    metadata: Optional[Dict[str, Any]]
+    visual_overrides: Optional[Dict[str, Any]]
+
+
+class AutomationResult(AutomateBase):
+    """Schema accepted by the Speckle server as a result for an automation run."""
+
+    elapsed: float = 0
+    result_view: Optional[str] = None
+    result_versions: List[str] = Field(default_factory=list)
+    blobs: List[str] = Field(default_factory=list)
+    run_status: AutomationStatus = AutomationStatus.RUNNING
+    status_message: Optional[str] = None
+    object_results: list[ResultCase] = Field(default_factory=list)

src/specklepy/api/client.py

@@ -0,0 +1,159 @@
+from deprecated import deprecated
+from gql.transport.exceptions import TransportServerError
+from gql.transport.requests import RequestsHTTPTransport
+from gql.transport.websockets import WebsocketsTransport
+
+from specklepy.api.credentials import Account, get_account_from_token
+from specklepy.api.resources import (
+    user,
+    active_user,
+    branch,
+    commit,
+    object,
+    other_user,
+    server,
+    stream,
+    subscriptions,
+)
+from specklepy.logging import metrics
+from specklepy.logging.exceptions import SpeckleException, SpeckleWarning
+
+from specklepy.core.api.client import SpeckleClient as CoreSpeckleClient
+
+
+class SpeckleClient(CoreSpeckleClient):
+    """
+    The `SpeckleClient` is your entry point for interacting with
+    your Speckle Server's GraphQL API.
+    You'll need to have access to a server to use it,
+    or you can use our public server `speckle.xyz`.
+
+    To authenticate the client, you'll need to have downloaded
+    the [Speckle Manager](https://speckle.guide/#speckle-manager)
+    and added your account.
+
+    ```py
+    from specklepy.api.client import SpeckleClient
+    from specklepy.api.credentials import get_default_account
+
+    # initialise the client
+    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 an account (account has been added in Speckle Manager)
+    account = get_default_account()
+    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")
+
+    # use that stream id to get the stream from the server
+    new_stream = client.stream.get(id=new_stream_id)
+    ```
+    """
+
+    DEFAULT_HOST = "speckle.xyz"
+    USE_SSL = True
+
+    def __init__(self, host: str = DEFAULT_HOST, use_ssl: bool = USE_SSL) -> None:
+        super().__init__(
+            host=host,
+            use_ssl=use_ssl,
+        )
+        self.account = Account()
+
+    def _init_resources(self) -> None:
+        self.server = server.Resource(
+            account=self.account, basepath=self.url, client=self.httpclient
+        )
+        server_version = None
+        try:
+            server_version = self.server.version()
+        except Exception:
+            pass
+        self.user = user.Resource(
+            account=self.account,
+            basepath=self.url,
+            client=self.httpclient,
+            server_version=server_version,
+        )
+        self.other_user = other_user.Resource(
+            account=self.account,
+            basepath=self.url,
+            client=self.httpclient,
+            server_version=server_version,
+        )
+        self.active_user = active_user.Resource(
+            account=self.account,
+            basepath=self.url,
+            client=self.httpclient,
+            server_version=server_version,
+        )
+        self.stream = stream.Resource(
+            account=self.account,
+            basepath=self.url,
+            client=self.httpclient,
+            server_version=server_version,
+        )
+        self.commit = commit.Resource(
+            account=self.account, basepath=self.url, client=self.httpclient
+        )
+        self.branch = branch.Resource(
+            account=self.account, basepath=self.url, client=self.httpclient
+        )
+        self.object = object.Resource(
+            account=self.account, basepath=self.url, client=self.httpclient
+        )
+        self.subscribe = subscriptions.Resource(
+            account=self.account,
+            basepath=self.ws_url,
+            client=self.wsclient,
+        )
+
+    @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
+
+        Arguments:
+            token {str} -- an api token
+        """
+        metrics.track(
+            metrics.SDK, self.account, {"name": "Client Authenticate_deprecated"}
+        )
+        return super().authenticate(token)
+
+    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
+        """
+        metrics.track(
+            metrics.SDK, self.account, {"name": "Client Authenticate With Token"}
+        )
+        return super().authenticate_with_token(token)
+
+    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.SDK, self.account, {"name": "Client Authenticate With Account"}
+        )
+        return super().authenticate_with_account(account)

src/specklepy/api/credentials.py

@@ -0,0 +1,82 @@
+import os
+from typing import List, Optional
+
+from pydantic import BaseModel, Field  # pylint: disable=no-name-in-module
+
+from specklepy.api.models import ServerInfo
+from specklepy.core.helpers import speckle_path_provider
+from specklepy.logging import metrics
+from specklepy.logging.exceptions import SpeckleException
+from specklepy.transports.sqlite import SQLiteTransport
+
+# following imports seem to be unnecessary, but they need to stay
+# to not break the scripts using these functions as non-core
+from specklepy.core.api.credentials import (
+    Account,
+    UserInfo,
+    StreamWrapper,  # deprecated
+    get_local_accounts as core_get_local_accounts,
+    get_account_from_token as core_get_account_from_token,
+)
+
+
+def get_local_accounts(base_path: Optional[str] = None) -> List[Account]:
+    """Gets all the accounts present in this environment
+
+    Arguments:
+        base_path {str} -- custom base path if you are not using the system default
+
+    Returns:
+        List[Account] -- list of all local accounts or an empty list if
+        no accounts were found
+    """
+    accounts = core_get_local_accounts(base_path)
+
+    metrics.track(
+        metrics.SDK,
+        next(
+            (acc for acc in accounts if acc.isDefault),
+            accounts[0] if accounts else None,
+        ),
+        {"name": "Get Local Accounts"},
+    )
+
+    return accounts
+
+
+def get_default_account(base_path: Optional[str] = None) -> Optional[Account]:
+    """
+    Gets this environment's default account if any. If there is no default,
+    the first found will be returned and set as default.
+    Arguments:
+        base_path {str} -- custom base path if you are not using the system default
+
+    Returns:
+        Account -- the default account or None if no local accounts were found
+    """
+    accounts = core_get_local_accounts(base_path=base_path)
+    if not accounts:
+        return None
+
+    default = next((acc for acc in accounts if acc.isDefault), None)
+    if not default:
+        default = accounts[0]
+        default.isDefault = True
+    metrics.initialise_tracker(default)
+
+    return default
+
+
+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
+
+    Returns:
+        Account -- the local account with this token or a shell account containing
+        just the token and url if no local account is found
+    """
+    account = core_get_account_from_token(token, server_url)
+
+    metrics.track(metrics.SDK, account, {"name": "Get Account From Token"})
+    return account

src/specklepy/api/host_applications.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+from enum import Enum
+from unicodedata import name
+
+# following imports seem to be unnecessary, but they need to stay 
+# to not break the scripts using these functions as non-core
+from specklepy.core.api.host_applications import (HostApplication, HostAppVersion,
+                                                  get_host_app_from_string, 
+                                                  _app_name_host_app_mapping,
+                                                  RHINO,GRASSHOPPER,REVIT,DYNAMO,UNITY,GSA,
+                                                  CIVIL,AUTOCAD,MICROSTATION,OPENROADS,
+                                                  OPENRAIL,OPENBUILDINGS,ETABS,SAP2000,CSIBRIDGE,
+                                                  SAFE,TEKLASTRUCTURES,DXF,EXCEL,UNREAL,POWERBI,
+                                                  BLENDER,QGIS,ARCGIS,SKETCHUP,ARCHICAD,TOPSOLID,
+                                                  PYTHON,NET,OTHER)
+
+if __name__ == "__main__":
+    print(HostAppVersion.v)

src/specklepy/api/models.py

@@ -0,0 +1,12 @@
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+# following imports seem to be unnecessary, but they need to stay 
+# to not break the scripts using these functions as non-core
+from specklepy.core.api.models import (Collaborator, Commit,
+                                       Commits, Object, Branch, Branches,
+                                       Stream, Streams, User, LimitedUser,
+                                       PendingStreamCollaborator, Activity,
+                                       ActivityCollection, ServerInfo)

src/specklepy/api/operations.py

@@ -0,0 +1,100 @@
+from typing import List, Optional
+
+from specklepy.logging import metrics
+from specklepy.logging.exceptions import SpeckleException
+from specklepy.objects.base import Base
+from specklepy.serialization.base_object_serializer import BaseObjectSerializer
+from specklepy.transports.abstract_transport import AbstractTransport
+from specklepy.transports.sqlite import SQLiteTransport
+
+from specklepy.core.api.operations import (send as core_send,
+                                           receive as _untracked_receive,
+                                           serialize as core_serialize,
+                                           deserialize as core_deserialize)
+
+
+def send(
+    base: Base,
+    transports: Optional[List[AbstractTransport]] = None,
+    use_default_cache: bool = True,
+):
+    """Sends an object via the provided transports. Defaults to the local cache.
+
+    Arguments:
+        obj {Base} -- the object you want to send
+        transports {list} -- where you want to send them
+        use_default_cache {bool} -- toggle for the default cache.
+        If set to false, it will only send to the provided transports
+
+    Returns:
+        str -- the object id of the sent object
+    """
+    if transports is None:
+        metrics.track(metrics.SEND)
+    else:
+        metrics.track(metrics.SEND, getattr(transports[0], "account", None))
+
+    return core_send(base, transports, use_default_cache)
+
+
+def receive(
+    obj_id: str,
+    remote_transport: Optional[AbstractTransport] = None,
+    local_transport: Optional[AbstractTransport] = None,
+) -> Base:
+    """Receives an object from a transport.
+
+    Arguments:
+        obj_id {str} -- the id of the object to receive
+        remote_transport {Transport} -- the transport to receive from
+        local_transport {Transport} -- the local cache to check for existing objects
+                                       (defaults to `SQLiteTransport`)
+
+    Returns:
+        Base -- the base object
+    """
+    metrics.track(metrics.RECEIVE, getattr(remote_transport, "account", None))
+    return _untracked_receive(obj_id, remote_transport, local_transport)
+
+
+def serialize(base: Base, write_transports: List[AbstractTransport] = []) -> str:
+    """
+    Serialize a base object. If no write transports are provided,
+    the object will be serialized
+    without detaching or chunking any of the attributes.
+
+    Arguments:
+        base {Base} -- the object to serialize
+        write_transports {List[AbstractTransport]}
+        -- optional: the transports to write to
+
+    Returns:
+        str -- the serialized object
+    """
+    metrics.track(metrics.SDK, custom_props={"name": "Serialize"})
+    return core_serialize(base, write_transports)
+
+def deserialize(
+    obj_string: str, read_transport: Optional[AbstractTransport] = None
+) -> Base:
+    """
+    Deserialize a string object into a Base object.
+
+    If the object contains referenced child objects that are not stored in the local db,
+    a read transport needs to be provided in order to recompose
+    the base with the children objects.
+
+    Arguments:
+        obj_string {str} -- the string object to deserialize
+        read_transport {AbstractTransport}
+            -- the transport to fetch children objects from
+                (defaults to SQLiteTransport)
+
+    Returns:
+        Base -- the deserialized object
+    """
+    metrics.track(metrics.SDK, custom_props={"name": "Deserialize"})
+    return core_deserialize(obj_string, read_transport)
+
+
+__all__ = ["receive", "send", "serialize", "deserialize"]

src/specklepy/api/resource.py

@@ -0,0 +1,38 @@
+from threading import Lock
+from typing import Any, Dict, List, Optional, Tuple, Type, Union
+
+from gql.client import Client
+from gql.transport.exceptions import TransportQueryError
+from graphql import DocumentNode
+
+from specklepy.api.credentials import Account
+from specklepy.logging.exceptions import (
+    GraphQLException,
+    SpeckleException,
+    UnsupportedException,
+)
+from specklepy.serialization.base_object_serializer import BaseObjectSerializer
+from specklepy.transports.sqlite import SQLiteTransport
+
+# following imports seem to be unnecessary, but they need to stay 
+# to not break the scripts using these functions as non-core
+from specklepy.core.api.resource import ResourceBase as CoreResourceBase
+
+
+class ResourceBase(CoreResourceBase):
+    def __init__(
+        self,
+        account: Account,
+        basepath: str,
+        client: Client,
+        name: str,
+        server_version: Optional[Tuple[Any, ...]] = None,
+    ) -> None:
+        super().__init__(
+            account = account,
+            basepath = basepath,
+            client = client,
+            name = name,
+            server_version = server_version
+        )
+    

src/specklepy/api/resources/__init__.py

@@ -1,11 +1,8 @@
-from pathlib import Path
-import sys
 import pkgutil
+import sys
 from importlib import import_module
 
-
-for (_, name, _) in pkgutil.iter_modules(__path__):
-
+for _, name, _ in pkgutil.iter_modules(__path__):
     imported_module = import_module("." + name, package=__name__)
 
     if hasattr(imported_module, "Resource"):

src/specklepy/api/resources/active_user.py

@@ -0,0 +1,120 @@
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from gql import gql
+
+from specklepy.api.models import ActivityCollection, PendingStreamCollaborator, User
+from specklepy.api.resource import ResourceBase
+from specklepy.logging import metrics
+from specklepy.logging.exceptions import SpeckleException
+
+from specklepy.core.api.resources.active_user import Resource as CoreResource
+
+
+class Resource(CoreResource):
+    """API Access class for users"""
+
+    def __init__(self, account, basepath, client, server_version) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+            server_version=server_version,
+        )
+        self.schema = User
+
+    def get(self) -> User:
+        """Gets the profile of a user. If no id argument is provided,
+        will return the current authenticated user's profile
+        (as extracted from the authorization header).
+
+        Arguments:
+            id {str} -- the user id
+
+        Returns:
+            User -- the retrieved user
+        """
+        metrics.track(metrics.SDK, custom_props={"name": "User Active Get"})
+        return super().get()
+
+    def update(
+        self,
+        name: Optional[str] = None,
+        company: Optional[str] = None,
+        bio: Optional[str] = None,
+        avatar: Optional[str] = None,
+    ):
+        """Updates your user profile. All arguments are optional.
+
+        Arguments:
+            name {str} -- your name
+            company {str} -- the company you may or may not work for
+            bio {str} -- tell us about yourself
+            avatar {str} -- a nice photo of yourself
+
+        Returns    @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT):
+            bool -- True if your profile was updated successfully
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "User Active Update"})
+        return super().update(name, company, bio, avatar)
+
+    def activity(
+        self,
+        limit: int = 20,
+        action_type: Optional[str] = None,
+        before: Optional[datetime] = None,
+        after: Optional[datetime] = None,
+        cursor: Optional[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
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "User Active Activity"})
+        return super().activity(limit, action_type, before, after, cursor)
+
+    def get_all_pending_invites(self) -> List[PendingStreamCollaborator]:
+        """Get all of the active user's pending stream invites
+
+        Requires Speckle Server version >= 2.6.4
+
+        Returns:
+            List[PendingStreamCollaborator]
+            -- a list of pending invites for the current user
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "User Active Invites All Get"})
+        return super().get_all_pending_invites()
+
+    def get_pending_invite(
+        self, stream_id: str, token: Optional[str] = None
+    ) -> Optional[PendingStreamCollaborator]:
+        """Get a particular pending invite for the active user on a given stream.
+        If no invite_id is provided, any valid invite will be returned.
+
+        Requires Speckle Server version >= 2.6.4
+
+        Arguments:
+            stream_id {str} -- the id of the stream to look for invites on
+            token {str} -- the token of the invite to look for (optional)
+
+        Returns:
+            PendingStreamCollaborator
+            -- the invite for the given stream (or None if it isn't found)
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "User Active Invite Get"})
+        return super().get_pending_invite(stream_id, token)

src/specklepy/api/resources/branch.py

@@ -0,0 +1,98 @@
+from typing import Optional
+
+from gql import gql
+
+from specklepy.api.models import Branch
+from specklepy.api.resource import ResourceBase
+from specklepy.logging import metrics
+
+from specklepy.core.api.resources.branch import Resource as CoreResource
+
+
+class Resource(CoreResource):
+    """API Access class for branches"""
+
+    def __init__(self, account, basepath, client) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+        )
+        self.schema = Branch
+
+    def create(
+        self, stream_id: str, name: str, description: str = "No description provided"
+    ) -> str:
+        """Create a new branch on this stream
+
+        Arguments:
+            name {str} -- the name of the new branch
+            description {str} -- a short description of the branch
+
+        Returns:
+            id {str} -- the newly created branch's id
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Branch Create"})
+        return super().create(stream_id, name, description)
+
+    def get(self, stream_id: str, name: str, commits_limit: int = 10):
+        """Get a branch by name from a stream
+
+        Arguments:
+            stream_id {str} -- the id of the stream to get the branch from
+            name {str} -- the name of the branch to get
+            commits_limit {int} -- maximum number of commits to get
+
+        Returns:
+            Branch -- the fetched branch with its latest commits
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Branch Get"})
+        return super().get(stream_id, name, commits_limit)
+
+    def list(self, stream_id: str, branches_limit: int = 10, commits_limit: int = 10):
+        """Get a list of branches from a given stream
+
+        Arguments:
+            stream_id {str} -- the id of the stream to get the branches from
+            branches_limit {int} -- maximum number of branches to get
+            commits_limit {int} -- maximum number of commits to get
+
+        Returns:
+            List[Branch] -- the branches on the stream
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Branch List"})
+        return super().list(stream_id, branches_limit, commits_limit)
+
+    def update(
+        self,
+        stream_id: str,
+        branch_id: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+    ):
+        """Update a branch
+
+        Arguments:
+            stream_id {str} -- the id of the stream containing the branch to update
+            branch_id {str} -- the id of the branch to update
+            name {str} -- optional: the updated branch name
+            description {str} -- optional: the updated branch description
+
+        Returns:
+            bool -- True if update is successful
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Branch Update"})
+        return super().update(stream_id, branch_id, name, description)
+
+    def delete(self, stream_id: str, branch_id: str):
+        """Delete a branch
+
+        Arguments:
+            stream_id {str} -- the id of the stream containing the branch to delete
+            branch_id {str} -- the branch to delete
+
+        Returns:
+            bool -- True if deletion is successful
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Branch Delete"})
+        return super().delete(stream_id, branch_id)

src/specklepy/api/resources/commit.py

@@ -0,0 +1,126 @@
+from typing import List, Optional, Union
+
+from gql import gql
+
+from specklepy.api.models import Commit
+from specklepy.api.resource import ResourceBase
+from specklepy.logging import metrics
+
+from specklepy.core.api.resources.commit import Resource as CoreResource
+from specklepy.logging.exceptions import SpeckleException
+
+
+class Resource(CoreResource):
+    """API Access class for commits"""
+
+    def __init__(self, account, basepath, client) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+        )
+        self.schema = Commit
+
+    def get(self, stream_id: str, commit_id: str) -> Commit:
+        """
+        Gets a commit given a stream and the commit id
+
+        Arguments:
+            stream_id {str} -- the stream where we can find the commit
+            commit_id {str} -- the id of the commit you want to get
+
+        Returns:
+            Commit -- the retrieved commit object
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Commit Get"})
+        return super().get(stream_id, commit_id)
+
+    def list(self, stream_id: str, limit: int = 10) -> List[Commit]:
+        """
+        Get a list of commits on a given stream
+
+        Arguments:
+            stream_id {str} -- the stream where the commits are
+            limit {int} -- the maximum number of commits to fetch (default = 10)
+
+        Returns:
+            List[Commit] -- a list of the most recent commit objects
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Commit List"})
+        return super().list(stream_id, limit)
+
+    def create(
+        self,
+        stream_id: str,
+        object_id: str,
+        branch_name: str = "main",
+        message: str = "",
+        source_application: str = "python",
+        parents: Optional[List[str]] = None,
+    ) -> Union[str, SpeckleException]:
+        """
+        Creates a commit on a branch
+
+        Arguments:
+            stream_id {str} -- the stream you want to commit to
+            object_id {str} -- the hash of your commit object
+            branch_name {str}
+                -- the name of the branch to commit to (defaults to "main")
+            message {str}
+                -- optional: a message to give more information about the commit
+            source_application{str}
+                -- optional: the application from which the commit was created
+                (defaults to "python")
+            parents {List[str]} -- optional: the id of the parent commits
+
+        Returns:
+            str -- the id of the created commit
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Commit Create"})
+        return super().create(
+            stream_id, object_id, branch_name, message, source_application, parents
+        )
+
+    def update(self, stream_id: str, commit_id: str, message: str) -> bool:
+        """
+        Update a commit
+
+        Arguments:
+            stream_id {str}
+                -- the id of the stream that contains the commit you'd like to update
+            commit_id {str} -- the id of the commit you'd like to update
+            message {str} -- the updated commit message
+
+        Returns:
+            bool -- True if the operation succeeded
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Commit Update"})
+        return super().update(stream_id, commit_id, message)
+
+    def delete(self, stream_id: str, commit_id: str) -> bool:
+        """
+        Delete a commit
+
+        Arguments:
+            stream_id {str}
+                -- the id of the stream that contains the commit you'd like to delete
+            commit_id {str} -- the id of the commit you'd like to delete
+
+        Returns:
+            bool -- True if the operation succeeded
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Commit Delete"})
+        return super().delete(stream_id, commit_id)
+
+    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.SDK, self.account, {"name": "Commit Received"})
+        return super().received(stream_id, commit_id, source_application, message)

src/specklepy/api/resources/object.py

@@ -0,0 +1,61 @@
+from typing import Dict, List
+
+from gql import gql
+
+from specklepy.api.resource import ResourceBase
+from specklepy.objects.base import Base
+
+from specklepy.logging import metrics
+
+from specklepy.core.api.resources.object import Resource as CoreResource
+
+
+class Resource(CoreResource):
+    """API Access class for objects"""
+
+    def __init__(self, account, basepath, client) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+        )
+        self.schema = Base
+
+    def get(self, stream_id: str, object_id: str) -> Base:
+        """
+        Get a stream object
+
+        Arguments:
+            stream_id {str} -- the id of the stream for the object
+            object_id {str} -- the hash of the object you want to get
+
+        Returns:
+            Base -- the returned Base object
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Object Get"})
+        return super().get(stream_id, object_id)
+
+    def create(self, stream_id: str, objects: List[Dict]) -> str:
+        """
+        Not advised - generally, you want to use `operations.send()`.
+
+        Create a new object on a stream.
+        To send a base object, you can prepare it by running it through the
+        `BaseObjectSerializer.traverse_base()` function to get a valid (serialisable)
+        object to send.
+
+        NOTE: this does not create a commit - you can create one with
+        `SpeckleClient.commit.create`.
+        Dynamic fields will be located in the 'data' dict of the received `Base` object
+
+        Arguments:
+            stream_id {str} -- the id of the stream you want to send the object to
+            objects {List[Dict]}
+            -- a list of base dictionary objects (NOTE: must be json serialisable)
+
+        Returns:
+            str -- the id of the object
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Object Create"})
+        return super().create(stream_id, objects)
+    

src/specklepy/api/resources/other_user.py

@@ -0,0 +1,87 @@
+from datetime import datetime, timezone
+from typing import List, Optional, Union
+
+from gql import gql
+
+from specklepy.api.models import ActivityCollection, LimitedUser
+from specklepy.api.resource import ResourceBase
+from specklepy.logging import metrics
+from specklepy.logging.exceptions import SpeckleException
+
+from specklepy.core.api.resources.other_user import Resource as CoreResource
+
+
+class Resource(CoreResource):
+    """API Access class for other users, that are not the currently active user."""
+
+    def __init__(self, account, basepath, client, server_version) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+            server_version=server_version,
+        )
+        self.schema = LimitedUser
+
+    def get(self, id: str) -> LimitedUser:
+        """
+        Gets the profile of another user.
+
+        Arguments:
+            id {str} -- the user id
+
+        Returns:
+            LimitedUser -- the retrieved profile of another user
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Other User Get"})
+        return super().get(id)
+
+    def search(
+        self, search_query: str, limit: int = 25
+    ) -> Union[List[LimitedUser], SpeckleException]:
+        """Searches for user by name or email. The search query must be at least
+        3 characters long
+
+        Arguments:
+            search_query {str} -- a string to search for
+            limit {int} -- the maximum number of results to return
+        Returns:
+            List[LimitedUser] -- a list of User objects that match the search query
+        """
+        if len(search_query) < 3:
+            return SpeckleException(
+                message="User search query must be at least 3 characters"
+            )
+
+        metrics.track(metrics.SDK, self.account, {"name": "Other User Search"})
+        return super().search(search_query, limit) 
+
+    def activity(
+        self,
+        user_id: str,
+        limit: int = 20,
+        action_type: Optional[str] = None,
+        before: Optional[datetime] = None,
+        after: Optional[datetime] = None,
+        cursor: Optional[datetime] = None,
+    ) -> ActivityCollection:
+        """
+        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
+
+        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
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Other User Activity"})
+        return super().activity(user_id, limit, action_type, before, after, cursor) 
+    

src/specklepy/api/resources/server.py

@@ -0,0 +1,76 @@
+import re
+from typing import Any, Dict, List, Tuple
+
+from gql import gql
+
+from specklepy.api.models import ServerInfo
+from specklepy.api.resource import ResourceBase
+from specklepy.logging import metrics
+from specklepy.logging.exceptions import GraphQLException
+
+from specklepy.core.api.resources.server import Resource as CoreResource
+
+
+class Resource(CoreResource):
+    """API Access class for the server"""
+
+    def __init__(self, account, basepath, client) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+        )
+
+    def get(self) -> ServerInfo:
+        """Get the server info
+
+        Returns:
+            dict -- the server info in dictionary form
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Server Get"})
+        return super().get()
+
+    def version(self) -> Tuple[Any, ...]:
+        """Get the server version
+
+        Returns:
+            the server version in the format (major, minor, patch, (tag, build))
+            eg (2, 6, 3) for a stable build and (2, 6, 4, 'alpha', 4711) for alpha
+        """
+        # not tracking as it will be called along with other mutations / queries as a check
+        return super().version()
+
+    def apps(self) -> Dict:
+        """Get the apps registered on the server
+
+        Returns:
+            dict -- a dictionary of apps registered on the server
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Server Apps"})
+        return super().apps()
+
+    def create_token(self, name: str, scopes: List[str], lifespan: int) -> str:
+        """Create a personal API token
+
+        Arguments:
+            scopes {List[str]} -- the scopes to grant with this token
+            name {str} -- a name for your new token
+            lifespan {int} -- duration before the token expires
+
+        Returns:
+            str -- the new API token. note: this is the only time you'll see the token!
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Server Create Token"})
+        return super().create_token(name, scopes, lifespan)
+
+    def revoke_token(self, token: str) -> bool:
+        """Revokes (deletes) a personal API token
+
+        Arguments:
+            token {str} -- the token to revoke (delete)
+
+        Returns:
+            bool -- True if the token was successfully deleted
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Server Revoke Token"})
+        return super().revoke_token(token) 

src/specklepy/api/resources/stream.py

@@ -0,0 +1,304 @@
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from deprecated import deprecated
+from gql import gql
+
+from specklepy.api.models import ActivityCollection, PendingStreamCollaborator, Stream
+from specklepy.api.resource import ResourceBase
+from specklepy.logging import metrics
+from specklepy.logging.exceptions import SpeckleException, UnsupportedException
+
+from specklepy.core.api.resources.stream import Resource as CoreResource
+
+
+class Resource(CoreResource):
+    """API Access class for streams"""
+
+    def __init__(self, account, basepath, client, server_version) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+            server_version=server_version,
+        )
+
+        self.schema = Stream
+
+    def get(self, id: str, branch_limit: int = 10, commit_limit: int = 10) -> Stream:
+        """Get the specified stream from the server
+
+        Arguments:
+            id {str} -- the stream id
+            branch_limit {int} -- the maximum number of branches to return
+            commit_limit {int} -- the maximum number of commits to return
+
+        Returns:
+            Stream -- the retrieved stream
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Stream Get"})
+        return super().get(id, branch_limit, commit_limit)
+
+    def list(self, stream_limit: int = 10) -> List[Stream]:
+        """Get a list of the user's streams
+
+        Arguments:
+            stream_limit {int} -- The maximum number of streams to return
+
+        Returns:
+            List[Stream] -- A list of Stream objects
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Stream List"})
+        return super().list(stream_limit)
+
+    def create(
+        self,
+        name: str = "Anonymous Python Stream",
+        description: str = "No description provided",
+        is_public: bool = True,
+    ) -> str:
+        """Create a new stream
+
+        Arguments:
+            name {str} -- the name of the string
+            description {str} -- a short description of the stream
+            is_public {bool}
+                -- whether or not the stream can be viewed by anyone with the id
+
+        Returns:
+            id {str} -- the id of the newly created stream
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Stream Create"})
+        return super().create(name, description, is_public)
+
+    def update(
+        self,
+        id: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        is_public: Optional[bool] = None,
+    ) -> bool:
+        """Update an existing stream
+
+        Arguments:
+            id {str} -- the id of the stream to be updated
+            name {str} -- the name of the string
+            description {str} -- a short description of the stream
+            is_public {bool}
+                -- whether or not the stream can be viewed by anyone with the id
+
+        Returns:
+            bool -- whether the stream update was successful
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Stream Update"})
+        return super().update(id, name, description, is_public)
+
+    def delete(self, id: str) -> bool:
+        """Delete a stream given its id
+
+        Arguments:
+            id {str} -- the id of the stream to delete
+
+        Returns:
+            bool -- whether the deletion was successful
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Stream Delete"})
+        return super().delete(id)
+
+    def search(
+        self,
+        search_query: str,
+        limit: int = 25,
+        branch_limit: int = 10,
+        commit_limit: int = 10,
+    ):
+        """Search for streams by name, description, or id
+
+        Arguments:
+            search_query {str} -- a string to search for
+            limit {int} -- the maximum number of results to return
+            branch_limit {int} -- the maximum number of branches to return
+            commit_limit {int} -- the maximum number of commits to return
+
+        Returns:
+            List[Stream] -- a list of Streams that match the search query
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Stream Search"})
+        return super().search(search_query, limit, branch_limit, commit_limit)
+
+    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.SDK, self.account, {"name": "Stream Favorite"})
+        return super().favorite(stream_id, favorited)
+
+    def get_all_pending_invites(
+        self, stream_id: str
+    ) -> List[PendingStreamCollaborator]:
+        """Get all of the pending invites on a stream.
+        You must be a `stream:owner` to query this.
+
+        Requires Speckle Server version >= 2.6.4
+
+        Arguments:
+            stream_id {str} -- the stream id from which to get the pending invites
+
+        Returns:
+            List[PendingStreamCollaborator]
+                -- a list of pending invites for the specified stream
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Stream Invite Get"})
+        return super().get_all_pending_invites(stream_id)
+
+    def invite(
+        self,
+        stream_id: str,
+        email: Optional[str] = None,
+        user_id: Optional[str] = None,
+        role: str = "stream:contributor",  # should default be reviewer?
+        message: Optional[str] = None,
+    ):
+        """Invite someone to a stream using either their email or user id
+
+        Requires Speckle Server version >= 2.6.4
+
+        Arguments:
+            stream_id {str} -- the id of the stream to invite the user to
+            email {str} -- the email of the user to invite (use this OR `user_id`)
+            user_id {str} -- the id of the user to invite (use this OR `email`)
+            role {str}
+                -- the role to assign to the user (defaults to `stream:contributor`)
+            message {str}
+                -- a message to send along with this invite to the specified user
+
+        Returns:
+            bool -- True if the operation was successful
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Stream Invite Create"})
+        return super().invite(stream_id, email, user_id, role, message)
+
+    def invite_batch(
+        self,
+        stream_id: str,
+        emails: Optional[List[str]] = None,
+        user_ids: Optional[List[None]] = None,
+        message: Optional[str] = None,
+    ) -> bool:
+        """Invite a batch of users to a specified stream.
+
+        Requires Speckle Server version >= 2.6.4
+
+        Arguments:
+            stream_id {str} -- the id of the stream to invite the user to
+            emails {List[str]}
+                -- the email of the user to invite (use this and/or `user_ids`)
+            user_id {List[str]}
+                -- the id of the user to invite (use this and/or `emails`)
+            message {str}
+                -- a message to send along with this invite to the specified user
+
+        Returns:
+            bool -- True if the operation was successful
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Stream Invite Batch Create"})
+        return super().invite_batch(stream_id, emails, user_ids, message)
+
+    def invite_cancel(self, stream_id: str, invite_id: str) -> bool:
+        """Cancel an existing stream invite
+
+        Requires Speckle Server version >= 2.6.4
+
+        Arguments:
+            stream_id {str} -- the id of the stream invite
+            invite_id {str} -- the id of the invite to use
+
+        Returns:
+            bool -- true if the operation was successful
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Stream Invite Cancel"})
+        return super().invite_cancel(stream_id, invite_id)
+
+    def invite_use(self, stream_id: str, token: str, accept: bool = True) -> bool:
+        """Accept or decline a stream invite
+
+        Requires Speckle Server version >= 2.6.4
+
+        Arguments:
+            stream_id {str}
+                -- the id of the stream for which the user has a pending invite
+            token {str} -- the token of the invite to use
+            accept {bool} -- whether or not to accept the invite (defaults to True)
+
+        Returns:
+            bool -- true if the operation was successful
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Invite Use"})
+        return super().invite_use(stream_id, token, accept)
+
+    def update_permission(self, stream_id: str, user_id: str, role: str):
+        """Updates permissions for a user on a given stream
+
+        Valid for Speckle Server >=2.6.4
+
+        Arguments:
+            stream_id {str} -- the id of the stream to grant permissions to
+            user_id {str} -- the id of the user to grant permissions for
+            role {str} -- the role to grant the user
+
+        Returns:
+            bool -- True if the operation was successful
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Stream Permission Update", "role": role})
+        return super().update_permission(stream_id, user_id, role)
+
+    def revoke_permission(self, stream_id: str, user_id: str):
+        """Revoke permissions from a user on a given stream
+
+        Arguments:
+            stream_id {str} -- the id of the stream to revoke permissions from
+            user_id {str} -- the id of the user to revoke permissions from
+
+        Returns:
+            bool -- True if the operation was successful
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Stream Permission Revoke"})
+        return super().revoke_permission(stream_id, user_id)
+
+    def activity(
+        self,
+        stream_id: str,
+        action_type: Optional[str] = None,
+        limit: int = 20,
+        before: Optional[datetime] = None,
+        after: Optional[datetime] = None,
+        cursor: Optional[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
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Stream Activity"})
+        return super().activity(stream_id, action_type, limit, before, after, cursor)
+    

src/specklepy/api/resources/subscriptions.py

@@ -0,0 +1,109 @@
+from functools import wraps
+from typing import Callable, Dict, List, Optional, Union
+
+from gql import gql
+from graphql import DocumentNode
+
+from specklepy.api.resource import ResourceBase
+from specklepy.api.resources.stream import Stream
+from specklepy.logging.exceptions import SpeckleException
+
+from specklepy.logging import metrics
+from specklepy.core.api.resources.subscriptions import Resource as CoreResource
+
+def check_wsclient(function):
+    @wraps(function)
+    async def check_wsclient_wrapper(self, *args, **kwargs):
+        if self.client is None:
+            raise SpeckleException(
+                "You must authenticate before you can subscribe to events"
+            )
+        else:
+            return await function(self, *args, **kwargs)
+
+    return check_wsclient_wrapper
+
+
+class Resource(CoreResource):
+    """API Access class for subscriptions"""
+
+    def __init__(self, account, basepath, client) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+        )
+
+    @check_wsclient
+    async def stream_added(self, callback: Optional[Callable] = None):
+        """Subscribes to new stream added event for your profile.
+        Use this to display an up-to-date list of streams.
+
+        Arguments:
+            callback {Callable[Stream]} -- a function that takes the updated stream
+            as an argument and executes each time a stream is added
+
+        Returns:
+            Stream -- the update stream
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Subscription Stream Added"})
+        return super().stream_added(callback)
+
+    @check_wsclient
+    async def stream_updated(self, id: str, callback: Optional[Callable] = None):
+        """
+        Subscribes to stream updated event.
+        Use this in clients/components that pertain only to this stream.
+
+        Arguments:
+            id {str} -- the stream id of the stream to subscribe to
+            callback {Callable[Stream]}
+            -- a function that takes the updated stream
+            as an argument and executes each time the stream is updated
+
+        Returns:
+            Stream -- the update stream
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Subscription Stream Updated"})
+        return super().stream_updated(id, callback)
+
+    @check_wsclient
+    async def stream_removed(self, callback: Optional[Callable] = None):
+        """Subscribes to stream removed event for your profile.
+        Use this to display an up-to-date list of streams for your profile.
+        NOTE: If someone revokes your permissions on a stream,
+        this subscription will be triggered with an extra value of revokedBy
+        in the payload.
+
+        Arguments:
+            callback {Callable[Dict]}
+            -- a function that takes the returned dict as an argument
+            and executes each time a stream is removed
+
+        Returns:
+            dict -- dict containing 'id' of stream removed and optionally 'revokedBy'
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "Subscription Stream Removed"})
+        return super().stream_removed(callback)
+
+    @check_wsclient
+    async def subscribe(
+        self,
+        query: DocumentNode,
+        params: Optional[Dict] = None,
+        callback: Optional[Callable] = None,
+        return_type: Optional[Union[str, List]] = None,
+        schema=None,
+        parse_response: bool = True,
+    ):
+        # if self.client.transport.websocket is None:
+        # TODO: add multiple subs to the same ws connection
+        async with self.client as session:
+            async for res in session.subscribe(query, variable_values=params):
+                res = self._step_into_response(response=res, return_type=return_type)
+                if parse_response:
+                    res = self._parse_response(response=res, schema=schema)
+                if callback is not None:
+                    callback(res)
+                else:
+                    return res

src/specklepy/api/resources/user.py

@@ -0,0 +1,158 @@
+from datetime import datetime, timezone
+from typing import List, Optional, Union
+
+from deprecated import deprecated
+from gql import gql
+
+from specklepy.api.models import ActivityCollection, PendingStreamCollaborator, User
+from specklepy.api.resource import ResourceBase
+
+from specklepy.logging.exceptions import SpeckleException
+
+from specklepy.logging import metrics
+from specklepy.core.api.resources.user import Resource as CoreResource
+
+DEPRECATION_VERSION = "2.9.0"
+DEPRECATION_TEXT = (
+    "The user resource is deprecated, please use the active_user or other_user"
+    " resources"
+)
+
+
+class Resource(CoreResource):
+    """API Access class for users"""
+
+    def __init__(self, account, basepath, client, server_version) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+            server_version=server_version,
+        )
+        self.schema = User
+
+    @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT)
+    def get(self, id: Optional[str] = None) -> User:
+        """
+        Gets the profile of a user.
+        If no id argument is provided, will return the current authenticated
+        user's profile (as extracted from the authorization header).
+
+        Arguments:
+            id {str} -- the user id
+
+        Returns:
+            User -- the retrieved user
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "User Get_deprecated"})
+        return super().get(id)
+        
+    @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT)
+    def search(
+        self, search_query: str, limit: int = 25
+    ) -> Union[List[User], SpeckleException]:
+        """
+        Searches for user by name or email.
+        The search query must be at least 3 characters long
+
+        Arguments:
+            search_query {str} -- a string to search for
+            limit {int} -- the maximum number of results to return
+        Returns:
+            List[User] -- a list of User objects that match the search query
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "User Search_deprecated"})
+        return super().search(search_query, limit)
+
+    @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT)
+    def update(
+        self,
+        name: Optional[str] = None,
+        company: Optional[str] = None,
+        bio: Optional[str] = None,
+        avatar: Optional[str] = None,
+    ):
+        """Updates your user profile. All arguments are optional.
+
+        Arguments:
+            name {str} -- your name
+            company {str} -- the company you may or may not work for
+            bio {str} -- tell us about yourself
+            avatar {str} -- a nice photo of yourself
+
+        Returns:
+            bool -- True if your profile was updated successfully
+        """
+        #metrics.track(metrics.USER, self.account, {"name": "update"})
+        metrics.track(metrics.SDK, self.account, {"name": "User Update_deprecated"})
+        return super().update(name, company, bio, avatar)
+
+    @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT)
+    def activity(
+        self,
+        user_id: Optional[str] = None,
+        limit: int = 20,
+        action_type: Optional[str] = None,
+        before: Optional[datetime] = None,
+        after: Optional[datetime] = None,
+        cursor: Optional[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
+        """
+        metrics.track(metrics.SDK, self.account, {"name": "User Activity_deprecated"})
+        return super().activity(user_id, limit, action_type, before, after, cursor)
+        
+
+    @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT)
+    def get_all_pending_invites(self) -> List[PendingStreamCollaborator]:
+        """Get all of the active user's pending stream invites
+
+        Requires Speckle Server version >= 2.6.4
+
+        Returns:
+            List[PendingStreamCollaborator]
+                -- a list of pending invites for the current user
+        """
+        #metrics.track(metrics.INVITE, self.account, {"name": "get"})
+        metrics.track(metrics.SDK, self.account, {"name": "User GetAllInvites_deprecated"})
+        return super().get_all_pending_invites()
+        
+
+    @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT)
+    def get_pending_invite(
+        self, stream_id: str, token: Optional[str] = None
+    ) -> Optional[PendingStreamCollaborator]:
+        """Get a particular pending invite for the active user on a given stream.
+        If no invite_id is provided, any valid invite will be returned.
+
+        Requires Speckle Server version >= 2.6.4
+
+        Arguments:
+            stream_id {str} -- the id of the stream to look for invites on
+            token {str} -- the token of the invite to look for (optional)
+
+        Returns:
+            PendingStreamCollaborator
+                -- the invite for the given stream (or None if it isn't found)
+        """
+        #metrics.track(metrics.INVITE, self.account, {"name": "get"})
+        metrics.track(metrics.SDK, self.account, {"name": "User GetInvite_deprecated"})
+        return super().get_pending_invite(stream_id, token)
+        

src/specklepy/api/wrapper.py

@@ -0,0 +1,94 @@
+from urllib.parse import unquote, urlparse
+from warnings import warn
+
+from specklepy.api.client import SpeckleClient
+from specklepy.api.credentials import (
+    Account,
+    get_account_from_token,
+    get_local_accounts,
+)
+from specklepy.logging.exceptions import SpeckleException, SpeckleWarning
+from specklepy.transports.server.server import ServerTransport
+
+from specklepy.logging import metrics
+from specklepy.core.api.wrapper import StreamWrapper as CoreStreamWrapper 
+
+class StreamWrapper(CoreStreamWrapper):
+    """
+    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 __init__(self, url: str) -> None:
+        super().__init__(url = url)
+
+    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)
+        """
+        metrics.track(metrics.SDK, custom_props={"name": "Stream Wrapper Get Account"})
+        return super().get_account(token)
+
+    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
+        """
+        metrics.track(metrics.SDK, custom_props={"name": "Stream Wrapper Get Client"})
+        return super().get_client(token)
+
+    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
+        """
+        metrics.track(metrics.SDK, custom_props={"name": "Stream Wrapper Get Transport"})
+        return super().get_transport(token)

src/specklepy/core/__init__.py

@@ -0,0 +1,6 @@
+"""
+This is the Core SDK module of `specklepy`.
+
+This module should be kept in sync with the functionalities of our other SDKs especially
+C# Core https://github.com/specklesystems/speckle-sharp/tree/main/Core/Core
+"""

src/specklepy/core/api/client.py

@@ -1,36 +1,39 @@
 import re
-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 warnings import warn
 
-from specklepy.api import resources
-from specklepy.api.resources import (
-    branch,
-    commit,
-    stream,
-    object,
-    server,
-    user,
-    subscriptions,
-)
-from specklepy.api.models import ServerInfo
+from deprecated import deprecated
 from gql import Client
+from gql.transport.exceptions import TransportServerError
 from gql.transport.requests import RequestsHTTPTransport
 from gql.transport.websockets import WebsocketsTransport
 
+from specklepy.core.api import resources
+from specklepy.core.api.credentials import Account, get_account_from_token
+from specklepy.core.api.resources import (
+    user,
+    active_user,
+    branch,
+    commit,
+    object,
+    other_user,
+    server,
+    stream,
+    subscriptions,
+)
+from specklepy.logging import metrics
+from specklepy.logging.exceptions import SpeckleException, SpeckleWarning
+
 
 class SpeckleClient:
     """
-    The `SpeckleClient` is your entry point for interacting with your Speckle Server's GraphQL API.
-    You'll need to have access to a server to use it, or you can use our public server `speckle.xyz`.
+    The `SpeckleClient` is your entry point for interacting with
+    your Speckle Server's GraphQL API.
+    You'll need to have access to a server to use it,
+    or you can use our public server `speckle.xyz`.
 
-    To authenticate the client, you'll need to have downloaded the [Speckle Manager](https://speckle.guide/#speckle-manager)
+    To authenticate the client, you'll need to have downloaded
+    the [Speckle Manager](https://speckle.guide/#speckle-manager)
     and added your account.
 
     ```py
@@ -57,7 +60,6 @@ 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"
 
@@ -93,15 +95,22 @@ class SpeckleClient:
         #     ) from ex
 
     def __repr__(self):
-        return f"SpeckleClient( server: {self.url}, authenticated: {self.account.token is not None} )"
+        return (
+            f"SpeckleClient( server: {self.url}, authenticated:"
+            f" {self.account.token is not None} )"
+        )
 
     @deprecated(
         version="2.6.0",
-        reason="Renamed: please use `authenticate_with_account` or `authenticate_with_token` instead.",
+        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
+        The token is saved in the client object and a synchronous GraphQL
+        entrypoint is created
 
         Arguments:
             token {str} -- an api token
@@ -110,32 +119,35 @@ class SpeckleClient:
         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
+        """
+        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
+        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`
+            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.account.token}",
             "Content-Type": "application/json",
+            "apollographql-client-name": metrics.HOST_APP,
+            "apollographql-client-version": metrics.HOST_APP_VERSION,
         }
         httptransport = RequestsHTTPTransport(
             url=self.graphql, headers=headers, verify=True, retries=3
@@ -149,12 +161,23 @@ class SpeckleClient:
 
         self._init_resources()
 
-        if self.user.get() is None:
-            warn(
-                SpeckleWarning(
-                    f"Possibly invalid token - could not authenticate Speckle Client for server {self.url}"
+        try:
+            user_or_error = self.active_user.get()
+            if isinstance(user_or_error, SpeckleException):
+                if isinstance(user_or_error.exception, TransportServerError):
+                    raise user_or_error.exception
+                else:
+                    raise user_or_error
+        except TransportServerError as ex:
+            if ex.code == 403:
+                warn(
+                    SpeckleWarning(
+                        "Possibly invalid token - could not authenticate Speckle Client"
+                        f" for server {self.url}"
+                    )
                 )
-            )
+            else:
+                raise ex
 
     def execute_query(self, query: str) -> Dict:
         return self.httpclient.execute(query)
@@ -166,7 +189,7 @@ class SpeckleClient:
         server_version = None
         try:
             server_version = self.server.version()
-        except:
+        except Exception:
             pass
         self.user = user.Resource(
             account=self.account,
@@ -174,6 +197,18 @@ class SpeckleClient:
             client=self.httpclient,
             server_version=server_version,
         )
+        self.other_user = other_user.Resource(
+            account=self.account,
+            basepath=self.url,
+            client=self.httpclient,
+            server_version=server_version,
+        )
+        self.active_user = active_user.Resource(
+            account=self.account,
+            basepath=self.url,
+            client=self.httpclient,
+            server_version=server_version,
+        )
         self.stream = stream.Resource(
             account=self.account,
             basepath=self.url,
@@ -201,7 +236,7 @@ class SpeckleClient:
             return attr.Resource(
                 account=self.account, basepath=self.url, client=self.httpclient
             )
-        except:
+        except AttributeError:
             raise SpeckleException(
                 f"Method {name} is not supported by the SpeckleClient class"
             )

src/specklepy/core/api/credentials.py

@@ -1,17 +1,21 @@
 import os
-from pydantic import BaseModel, Field  # pylint: disable=no-name-in-module
+from pathlib import Path
 from typing import List, Optional
+
+from pydantic import BaseModel, Field  # pylint: disable=no-name-in-module
+
+from specklepy.core.api.models import ServerInfo
+from specklepy.core.helpers import speckle_path_provider
 from specklepy.logging import metrics
-from specklepy.api.models import ServerInfo
-from specklepy.transports.sqlite import SQLiteTransport
 from specklepy.logging.exceptions import SpeckleException
+from specklepy.transports.sqlite import SQLiteTransport
 
 
 class UserInfo(BaseModel):
-    name: Optional[str]
-    email: Optional[str]
-    company: Optional[str]
-    id: Optional[str]
+    name: Optional[str] = None
+    email: Optional[str] = None
+    company: Optional[str] = None
+    id: Optional[str] = None
 
 
 class Account(BaseModel):
@@ -23,7 +27,10 @@ class Account(BaseModel):
     id: Optional[str] = None
 
     def __repr__(self) -> str:
-        return f"Account(email: {self.userInfo.email}, server: {self.serverInfo.url}, isDefault: {self.isDefault})"
+        return (
+            f"Account(email: {self.userInfo.email}, server: {self.serverInfo.url},"
+            f" isDefault: {self.isDefault})"
+        )
 
     def __str__(self) -> str:
         return self.__repr__()
@@ -35,31 +42,45 @@ class Account(BaseModel):
         return acct
 
 
-def get_local_accounts(base_path: str = None) -> List[Account]:
+def get_local_accounts(base_path: Optional[str] = None) -> List[Account]:
     """Gets all the accounts present in this environment
 
     Arguments:
         base_path {str} -- custom base path if you are not using the system default
 
     Returns:
-        List[Account] -- list of all local accounts or an empty list if no accounts were found
+        List[Account] -- list of all local accounts or an empty list if
+        no accounts were found
     """
-    account_storage = SQLiteTransport(scope="Accounts", base_path=base_path)
-    # pylint: disable=protected-access
-    json_path = os.path.join(account_storage._base_path, "Accounts")
-    os.makedirs(json_path, exist_ok=True)
-    json_acct_files = [file for file in os.listdir(json_path) if file.endswith(".json")]
-
     accounts: List[Account] = []
-    res = account_storage.get_all_objects()
-    account_storage.close()
+    try:
+        account_storage = SQLiteTransport(scope="Accounts", base_path=base_path)
+        res = account_storage.get_all_objects()
+        account_storage.close()
+        if res:
+            accounts.extend(Account.model_validate_json(r[1]) for r in res)
+    except SpeckleException:
+        # cannot open SQLiteTransport, probably because of the lack
+        # of disk write permissions
+        pass
+
+    json_acct_files = []
+    json_path = str(speckle_path_provider.accounts_folder_path())
+    try:
+        os.makedirs(json_path, exist_ok=True)
+        json_acct_files.extend(
+            file for file in os.listdir(json_path) if file.endswith(".json")
+        )
+
+    except Exception:
+        # cannot find or get the json account paths
+        pass
 
-    if res:
-        accounts.extend(Account.parse_raw(r[1]) for r in res)
     if json_acct_files:
         try:
             accounts.extend(
-                Account.parse_file(os.path.join(json_path, json_file))
+                Account.model_validate_json(Path(json_path, json_file).read_text())
+                # Account.parse_file(os.path.join(json_path, json_file))
                 for json_file in json_acct_files
             )
         except Exception as ex:
@@ -68,19 +89,13 @@ def get_local_accounts(base_path: str = None) -> List[Account]:
                 ex,
             ) from ex
 
-    metrics.track(
-        metrics.ACCOUNTS,
-        next(
-            (acc for acc in accounts if acc.isDefault),
-            accounts[0] if accounts else None,
-        ),
-    )
-
     return accounts
 
 
-def get_default_account(base_path: str = None) -> Account:
-    """Gets this environment's default account if any. If there is no default, the first found will be returned and set as default.
+def get_default_account(base_path: Optional[str] = None) -> Optional[Account]:
+    """
+    Gets this environment's default account if any. If there is no default,
+    the first found will be returned and set as default.
     Arguments:
         base_path {str} -- custom base path if you are not using the system default
 
@@ -95,7 +110,7 @@ def get_default_account(base_path: str = None) -> Account:
     if not default:
         default = accounts[0]
         default.isDefault = True
-    metrics.initialise_tracker(default)
+    #metrics.initialise_tracker(default)
 
     return default
 
@@ -106,7 +121,8 @@ def get_account_from_token(token: str, server_url: str = None) -> Account:
         token {str} -- the api token
 
     Returns:
-        Account -- the local account with this token or a shell account containing just the token and url if no local account is found
+        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:
@@ -130,6 +146,9 @@ def get_account_from_token(token: str, server_url: str = None) -> Account:
 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,
+            message=(
+                "The StreamWrapper has moved as of v2.6.0! Please import from"
+                " specklepy.api.wrapper"
+            ),
+            exception=DeprecationWarning(),
         )

src/specklepy/core/api/host_applications.py

@@ -0,0 +1,116 @@
+from dataclasses import dataclass
+from enum import Enum
+from unicodedata import name
+
+
+class HostAppVersion(Enum):
+    v = "v"
+    v6 = "v6"
+    v7 = "v7"
+    v2019 = "v2019"
+    v2020 = "v2020"
+    v2021 = "v2021"
+    v2022 = "v2022"
+    v2023 = "v2023"
+    v2024 = "v2024"
+    v2025 = "v2025"
+    vSandbox = "vSandbox"
+    vRevit = "vRevit"
+    vRevit2021 = "vRevit2021"
+    vRevit2022 = "vRevit2022"
+    vRevit2023 = "vRevit2023"
+    vRevit2024 = "vRevit2024"
+    vRevit2025 = "vRevit2025"
+    v25 = "v25"
+    v26 = "v26"
+
+    def __repr__(self) -> str:
+        return self.value
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass
+class HostApplication:
+    name: str
+    slug: str
+
+    def get_version(self, version: HostAppVersion) -> str:
+        return f"{name.replace(' ', '')}{str(version).strip('v')}"
+
+
+RHINO = HostApplication("Rhino", "rhino")
+GRASSHOPPER = HostApplication("Grasshopper", "grasshopper")
+REVIT = HostApplication("Revit", "revit")
+DYNAMO = HostApplication("Dynamo", "dynamo")
+UNITY = HostApplication("Unity", "unity")
+GSA = HostApplication("GSA", "gsa")
+CIVIL = HostApplication("Civil 3D", "civil3d")
+AUTOCAD = HostApplication("AutoCAD", "autocad")
+MICROSTATION = HostApplication("MicroStation", "microstation")
+OPENROADS = HostApplication("OpenRoads", "openroads")
+OPENRAIL = HostApplication("OpenRail", "openrail")
+OPENBUILDINGS = HostApplication("OpenBuildings", "openbuildings")
+ETABS = HostApplication("ETABS", "etabs")
+SAP2000 = HostApplication("SAP2000", "sap2000")
+CSIBRIDGE = HostApplication("CSIBridge", "csibridge")
+SAFE = HostApplication("SAFE", "safe")
+TEKLASTRUCTURES = HostApplication("Tekla Structures", "teklastructures")
+DXF = HostApplication("DXF Converter", "dxf")
+EXCEL = HostApplication("Excel", "excel")
+UNREAL = HostApplication("Unreal", "unreal")
+POWERBI = HostApplication("Power BI", "powerbi")
+BLENDER = HostApplication("Blender", "blender")
+QGIS = HostApplication("QGIS", "qgis")
+ARCGIS = HostApplication("ArcGIS", "arcgis")
+SKETCHUP = HostApplication("SketchUp", "sketchup")
+ARCHICAD = HostApplication("Archicad", "archicad")
+TOPSOLID = HostApplication("TopSolid", "topsolid")
+PYTHON = HostApplication("Python", "python")
+NET = HostApplication(".NET", "net")
+OTHER = HostApplication("Other", "other")
+
+_app_name_host_app_mapping = {
+    "dynamo": DYNAMO,
+    "revit": REVIT,
+    "autocad": AUTOCAD,
+    "civil": CIVIL,
+    "rhino": RHINO,
+    "grasshopper": GRASSHOPPER,
+    "unity": UNITY,
+    "gsa": GSA,
+    "microstation": MICROSTATION,
+    "openroads": OPENROADS,
+    "openrail": OPENRAIL,
+    "openbuildings": OPENBUILDINGS,
+    "etabs": ETABS,
+    "sap": SAP2000,
+    "csibridge": CSIBRIDGE,
+    "safe": SAFE,
+    "teklastructures": TEKLASTRUCTURES,
+    "dxf": DXF,
+    "excel": EXCEL,
+    "unreal": UNREAL,
+    "powerbi": POWERBI,
+    "blender": BLENDER,
+    "qgis": QGIS,
+    "arcgis": ARCGIS,
+    "sketchup": SKETCHUP,
+    "archicad": ARCHICAD,
+    "topsolid": TOPSOLID,
+    "python": PYTHON,
+    "net": NET,
+}
+
+
+def get_host_app_from_string(app_name: str) -> HostApplication:
+    app_name = app_name.lower().replace(" ", "")
+    for partial_app_name, host_app in _app_name_host_app_mapping.items():
+        if partial_app_name in app_name:
+            return host_app
+    return HostApplication(app_name, app_name)
+
+
+if __name__ == "__main__":
+    print(HostAppVersion.v)

src/specklepy/core/api/models.py

@@ -0,0 +1,198 @@
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class Collaborator(BaseModel):
+    id: Optional[str] = None
+    name: Optional[str] = None
+    role: Optional[str] = None
+    avatar: Optional[str] = None
+
+
+class Commit(BaseModel):
+    id: Optional[str] = None
+    message: Optional[str] = None
+    authorName: Optional[str] = None
+    authorId: Optional[str] = None
+    authorAvatar: Optional[str] = None
+    branchName: Optional[str] = None
+    createdAt: Optional[datetime] = None
+    sourceApplication: Optional[str] = None
+    referencedObject: Optional[str] = None
+    totalChildrenCount: Optional[int] = None
+    parents: Optional[List[str]] = None
+
+    def __repr__(self) -> str:
+        return (
+            f"Commit( id: {self.id}, message: {self.message}, referencedObject:"
+            f" {self.referencedObject}, authorName: {self.authorName}, branchName:"
+            f" {self.branchName}, createdAt: {self.createdAt} )"
+        )
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+
+class Commits(BaseModel):
+    totalCount: Optional[int] = None
+    cursor: Optional[datetime] = None
+    items: List[Commit] = []
+
+
+class Object(BaseModel):
+    id: Optional[str] = None
+    speckleType: Optional[str] = None
+    applicationId: Optional[str] = None
+    totalChildrenCount: Optional[int] = None
+    createdAt: Optional[datetime] = None
+
+
+class Branch(BaseModel):
+    id: Optional[str] = None
+    name: Optional[str] = None
+    description: Optional[str] = None
+    commits: Optional[Commits] = None
+
+
+class Branches(BaseModel):
+    totalCount: Optional[int] = None
+    cursor: Optional[datetime] = None
+    items: List[Branch] = []
+
+
+class Stream(BaseModel):
+    id: Optional[str] = None
+    name: Optional[str] = None
+    role: Optional[str] = None
+    isPublic: Optional[bool] = None
+    description: Optional[str] = None
+    createdAt: Optional[datetime] = None
+    updatedAt: Optional[datetime] = None
+    collaborators: List[Collaborator] = Field(default_factory=list)
+    branches: Optional[Branches] = None
+    commit: Optional[Commit] = None
+    object: Optional[Object] = None
+    commentCount: Optional[int] = None
+    favoritedDate: Optional[datetime] = None
+    favoritesCount: Optional[int] = None
+
+    def __repr__(self):
+        return (
+            f"Stream( id: {self.id}, name: {self.name}, description:"
+            f" {self.description}, isPublic: {self.isPublic})"
+        )
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+
+class Streams(BaseModel):
+    totalCount: Optional[int] = None
+    cursor: Optional[datetime] = None
+    items: List[Stream] = []
+
+
+class User(BaseModel):
+    id: Optional[str] = None
+    email: Optional[str] = None
+    name: Optional[str] = None
+    bio: Optional[str] = None
+    company: Optional[str] = None
+    avatar: Optional[str] = None
+    verified: Optional[bool] = None
+    role: Optional[str] = None
+    streams: Optional[Streams] = None
+
+    def __repr__(self):
+        return (
+            f"User( id: {self.id}, name: {self.name}, email: {self.email}, company:"
+            f" {self.company} )"
+        )
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+
+class LimitedUser(BaseModel):
+    """Limited user type, for showing public info about a user to another user."""
+
+    id: str
+    name: Optional[str] = None
+    bio: Optional[str] = None
+    company: Optional[str] = None
+    avatar: Optional[str] = None
+    verified: Optional[bool] = None
+    role: Optional[str] = None
+
+
+class PendingStreamCollaborator(BaseModel):
+    id: Optional[str] = None
+    inviteId: Optional[str] = None
+    streamId: Optional[str] = None
+    streamName: Optional[str] = None
+    title: Optional[str] = None
+    role: Optional[str] = None
+    invitedBy: Optional[User] = None
+    user: Optional[User] = None
+    token: Optional[str] = None
+
+    def __repr__(self):
+        return (
+            f"PendingStreamCollaborator( inviteId: {self.inviteId}, streamId:"
+            f" {self.streamId}, role: {self.role}, title: {self.title}, invitedBy:"
+            f" {self.user.name if self.user else None})"
+        )
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+
+class Activity(BaseModel):
+    actionType: Optional[str] = None
+    info: Optional[dict] = None
+    userId: Optional[str] = None
+    streamId: Optional[str] = None
+    resourceId: Optional[str] = None
+    resourceType: Optional[str] = None
+    message: Optional[str] = None
+    time: Optional[datetime] = None
+
+    def __repr__(self) -> str:
+        return (
+            f"Activity( streamId: {self.streamId}, actionType: {self.actionType},"
+            f" message: {self.message}, userId: {self.userId} )"
+        )
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+
+class ActivityCollection(BaseModel):
+    totalCount: Optional[int] = None
+    items: Optional[List[Activity]] = None
+    cursor: Optional[datetime] = None
+
+    def __repr__(self) -> str:
+        return (
+            f"ActivityCollection( totalCount: {self.totalCount}, items:"
+            f" {len(self.items) if self.items else 0}, cursor:"
+            f" {self.cursor.isoformat() if self.cursor else None} )"
+        )
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+
+class ServerInfo(BaseModel):
+    name: Optional[str] = None
+    company: Optional[str] = None
+    url: Optional[str] = None
+    description: Optional[str] = None
+    adminContact: Optional[str] = None
+    canonicalUrl: Optional[str] = None
+    roles: Optional[List[dict]] = None
+    scopes: Optional[List[dict]] = None
+    authStrategies: Optional[List[dict]] = None
+    version: Optional[str] = None

src/specklepy/core/api/operations.py

@@ -1,16 +1,16 @@
-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 typing import List, Optional
+
+#from specklepy.logging import metrics
 from specklepy.logging.exceptions import SpeckleException
-from specklepy.transports.abstract_transport import AbstractTransport
+from specklepy.objects.base import Base
 from specklepy.serialization.base_object_serializer import BaseObjectSerializer
+from specklepy.transports.abstract_transport import AbstractTransport
+from specklepy.transports.sqlite import SQLiteTransport
 
 
 def send(
     base: Base,
-    transports: List[AbstractTransport] = None,
+    transports: Optional[List[AbstractTransport]] = None,
     use_default_cache: bool = True,
 ):
     """Sends an object via the provided transports. Defaults to the local cache.
@@ -18,7 +18,8 @@ def send(
     Arguments:
         obj {Base} -- the object you want to send
         transports {list} -- where you want to send them
-        use_default_cache {bool} -- toggle for the default cache. If set to false, it will only send to the provided transports
+        use_default_cache {bool} -- toggle for the default cache.
+        If set to false, it will only send to the provided transports
 
     Returns:
         str -- the object id of the sent object
@@ -26,17 +27,17 @@ def send(
 
     if not transports and not use_default_cache:
         raise SpeckleException(
-            message="You need to provide at least one transport: cannot send with an empty transport list and no default cache"
+            message=(
+                "You need to provide at least one transport: cannot send with an empty"
+                " transport list and no default cache"
+            )
         )
 
     if isinstance(transports, AbstractTransport):
         transports = [transports]
 
     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())
@@ -50,8 +51,8 @@ def send(
 
 def receive(
     obj_id: str,
-    remote_transport: AbstractTransport = None,
-    local_transport: AbstractTransport = None,
+    remote_transport: Optional[AbstractTransport] = None,
+    local_transport: Optional[AbstractTransport] = None,
 ) -> Base:
     """Receives an object from a transport.
 
@@ -64,20 +65,22 @@ def receive(
     Returns:
         Base -- the base object
     """
-    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 with deserialisation using the local transport
+    # try local transport first. if the parent is there, we assume all the children are there and continue with deserialization using the local transport
     obj_string = local_transport.get_object(obj_id)
     if obj_string:
         return serializer.read_json(obj_string=obj_string)
 
     if not remote_transport:
         raise SpeckleException(
-            message="Could not find the specified object using the local transport, and you didn't provide a fallback remote from which to pull it."
+            message=(
+                "Could not find the specified object using the local transport, and you"
+                " didn't provide a fallback remote from which to pull it."
+            )
         )
 
     obj_string = remote_transport.copy_object_and_children(
@@ -89,38 +92,48 @@ def receive(
 
 def serialize(base: Base, write_transports: List[AbstractTransport] = []) -> str:
     """
-    Serialize a base object. If no write transports are provided, the object will be serialized
+    Serialize a base object. If no write transports are provided,
+    the object will be serialized
     without detaching or chunking any of the attributes.
 
     Arguments:
         base {Base} -- the object to serialize
-        write_transports {List[AbstractTransport]} -- optional: the transports to write to
+        write_transports {List[AbstractTransport]}
+        -- optional: the transports to write to
 
     Returns:
         str -- the serialized object
     """
-    metrics.track(metrics.SERIALIZE)
     serializer = BaseObjectSerializer(write_transports=write_transports)
 
     return serializer.write_json(base)[1]
 
 
-def deserialize(obj_string: str, read_transport: AbstractTransport = None) -> Base:
+def deserialize(
+    obj_string: str, read_transport: Optional[AbstractTransport] = None
+) -> Base:
     """
-    Deserialize a string object into a Base object. If the object contains referenced child objects that are not stored in the local db, a read transport needs to be provided in order to recompose the base with the children objects.
+    Deserialize a string object into a Base object.
+
+    If the object contains referenced child objects that are not stored in the local db,
+    a read transport needs to be provided in order to recompose
+    the base with the children objects.
 
     Arguments:
         obj_string {str} -- the string object to deserialize
-        read_transport {AbstractTransport} -- the transport to fetch children objects from
-                                              (defaults to SQLiteTransport)
+        read_transport {AbstractTransport}
+            -- the transport to fetch children objects from
+                (defaults to SQLiteTransport)
 
     Returns:
         Base -- the deserialized object
     """
-    metrics.track(metrics.DESERIALIZE)
     if not read_transport:
         read_transport = SQLiteTransport()
 
     serializer = BaseObjectSerializer(read_transport=read_transport)
 
     return serializer.read_json(obj_string=obj_string)
+
+
+__all__ = ["receive", "send", "serialize", "deserialize"]

src/specklepy/core/api/resource.py

@@ -1,15 +1,18 @@
-from graphql import DocumentNode
-from specklepy.api.credentials import Account
-from specklepy.transports.sqlite import SQLiteTransport
+from threading import Lock
 from typing import Any, Dict, List, Optional, Tuple, Type, Union
+
 from gql.client import Client
 from gql.transport.exceptions import TransportQueryError
+from graphql import DocumentNode
+
+from specklepy.core.api.credentials import Account
 from specklepy.logging.exceptions import (
     GraphQLException,
     SpeckleException,
     UnsupportedException,
 )
 from specklepy.serialization.base_object_serializer import BaseObjectSerializer
+from specklepy.transports.sqlite import SQLiteTransport
 
 
 class ResourceBase(object):
@@ -27,6 +30,7 @@ class ResourceBase(object):
         self.name = name
         self.server_version = server_version
         self.schema: Optional[Type] = None
+        self.__lock = Lock()
 
     def _step_into_response(self, response: dict, return_type: Union[str, List, None]):
         """Step into the dict to get the relevant data"""
@@ -46,11 +50,11 @@ class ResourceBase(object):
         if isinstance(response, list):
             return [self._parse_response(response=r, schema=schema) for r in response]
         if schema:
-            return schema.parse_obj(response)
+            return schema.model_validate(response)
         elif self.schema:
             try:
-                return self.schema.parse_obj(response)
-            except:
+                return self.schema.model_validate(response)
+            except Exception:
                 s = BaseObjectSerializer(read_transport=SQLiteTransport())
                 return s.recompose_base(response)
         else:
@@ -59,24 +63,31 @@ class ResourceBase(object):
     def make_request(
         self,
         query: DocumentNode,
-        params: Dict = None,
+        params: Optional[Dict] = None,
         return_type: Union[str, List, None] = None,
         schema=None,
         parse_response: bool = True,
     ) -> Any:
         """Executes the GraphQL query"""
         try:
-            response = self.client.execute(query, variable_values=params)
+            with self.__lock:
+                response = self.client.execute(query, variable_values=params)
         except Exception as ex:
             if isinstance(ex, TransportQueryError):
                 return GraphQLException(
-                    message=f"Failed to execute the GraphQL {self.name} request. Errors: {ex.errors}",
+                    message=(
+                        f"Failed to execute the GraphQL {self.name} request. Errors:"
+                        f" {ex.errors}"
+                    ),
                     errors=ex.errors,
                     data=ex.data,
                 )
             else:
                 return SpeckleException(
-                    message=f"Failed to execute the GraphQL {self.name} request. Inner exception: {ex}",
+                    message=(
+                        f"Failed to execute the GraphQL {self.name} request. Inner"
+                        f" exception: {ex}"
+                    ),
                     exception=ex,
                 )
 
@@ -88,16 +99,23 @@ class ResourceBase(object):
             return response
 
     def _check_server_version_at_least(
-        self, target_version: Tuple[Any, ...], unsupported_message: str = None
+        self, target_version: Tuple[Any, ...], unsupported_message: Optional[str] = None
     ):
         """Use this check to guard against making unsupported requests on older servers.
 
         Arguments:
-            target_version {tuple} -- the minimum server version in the format (major, minor, patch, (tag, build))
-                                      eg (2, 6, 3) for a stable build and (2, 6, 4, 'alpha', 4711) for alpha
+            target_version {tuple}
+            the minimum server version in the format (major, minor, patch, (tag, build))
+            eg (2, 6, 3) for a stable build and (2, 6, 4, 'alpha', 4711) for alpha
         """
         if not unsupported_message:
-            unsupported_message = f"The client method used is not supported on Speckle Server versios prior to v{'.'.join(target_version)}"
+            unsupported_message = (
+                "The client method used is not supported on Speckle Server versions"
+                f" prior to v{'.'.join(target_version)}"
+            )
+        # if version is dev, it should be supported... (or not)
+        if self.server_version == ("dev",):
+            return
         if self.server_version and self.server_version < target_version:
             raise UnsupportedException(unsupported_message)
 
@@ -107,8 +125,7 @@ class ResourceBase(object):
         """
         self._check_server_version_at_least(
             (2, 6, 4),
-            (
-                "Stream invites are only supported as of Speckle Server v2.6.4. "
-                "Please update your Speckle Server to use this method or use the `grant_permission` flow instead."
-            ),
+            "Stream invites are only supported as of Speckle Server v2.6.4. Please"
+            " update your Speckle Server to use this method or use the"
+            " `grant_permission` flow instead.",
         )

src/specklepy/core/api/resources/active_user.py

@@ -0,0 +1,264 @@
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from gql import gql
+
+from specklepy.core.api.models import ActivityCollection, PendingStreamCollaborator, User
+from specklepy.core.api.resource import ResourceBase
+from specklepy.logging.exceptions import SpeckleException
+
+NAME = "active_user"
+
+
+class Resource(ResourceBase):
+    """API Access class for users"""
+
+    def __init__(self, account, basepath, client, server_version) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+            name=NAME,
+            server_version=server_version,
+        )
+        self.schema = User
+
+    def get(self) -> User:
+        """Gets the profile of a user. If no id argument is provided,
+        will return the current authenticated user's profile
+        (as extracted from the authorization header).
+
+        Arguments:
+            id {str} -- the user id
+
+        Returns:
+            User -- the retrieved user
+        """
+        query = gql(
+            """
+            query User {
+                activeUser {
+                    id
+                    email
+                    name
+                    bio
+                    company
+                    avatar
+                    verified
+                    profiles
+                    role
+                }
+            }
+          """
+        )
+
+        params = {}
+
+        return self.make_request(query=query, params=params, return_type="activeUser")
+
+    def update(
+        self,
+        name: Optional[str] = None,
+        company: Optional[str] = None,
+        bio: Optional[str] = None,
+        avatar: Optional[str] = None,
+    ):
+        """Updates your user profile. All arguments are optional.
+
+        Arguments:
+            name {str} -- your name
+            company {str} -- the company you may or may not work for
+            bio {str} -- tell us about yourself
+            avatar {str} -- a nice photo of yourself
+
+        Returns    @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT):
+            bool -- True if your profile was updated successfully
+        """
+        query = gql(
+            """
+            mutation UserUpdate($user: UserUpdateInput!) {
+                userUpdate(user: $user)
+            }
+            """
+        )
+        params = {"name": name, "company": company, "bio": bio, "avatar": avatar}
+
+        params = {"user": {k: v for k, v in params.items() if v is not None}}
+
+        if not params["user"]:
+            return SpeckleException(
+                message=(
+                    "You must provide at least one field to update your user profile"
+                )
+            )
+
+        return self.make_request(
+            query=query, params=params, return_type="userUpdate", parse_response=False
+        )
+
+    def activity(
+        self,
+        limit: int = 20,
+        action_type: Optional[str] = None,
+        before: Optional[datetime] = None,
+        after: Optional[datetime] = None,
+        cursor: Optional[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(
+                $action_type: String,
+                $before:DateTime,
+                $after: DateTime,
+                $cursor: DateTime,
+                $limit: Int
+                ){
+                activeUser {
+                    activity(
+                        actionType: $action_type,
+                        before: $before,
+                        after: $after,
+                        cursor: $cursor,
+                        limit: $limit
+                        ) {
+                        totalCount
+                        cursor
+                        items {
+                            actionType
+                            info
+                            userId
+                            streamId
+                            resourceId
+                            resourceType
+                            message
+                            time
+                        }
+                    }
+                }
+            }
+            """
+        )
+
+        params = {
+            "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=["activeUser", "activity"],
+            schema=ActivityCollection,
+        )
+
+    def get_all_pending_invites(self) -> List[PendingStreamCollaborator]:
+        """Get all of the active user's pending stream invites
+
+        Requires Speckle Server version >= 2.6.4
+
+        Returns:
+            List[PendingStreamCollaborator]
+            -- a list of pending invites for the current user
+        """
+        self._check_invites_supported()
+
+        query = gql(
+            """
+            query StreamInvites {
+                streamInvites{
+                    id
+                    token
+                    inviteId
+                    streamId
+                    streamName
+                    title
+                    role
+                    invitedBy {
+                        id
+                        name
+                        company
+                        avatar
+                    }
+                }
+            }
+            """
+        )
+
+        return self.make_request(
+            query=query,
+            return_type="streamInvites",
+            schema=PendingStreamCollaborator,
+        )
+
+    def get_pending_invite(
+        self, stream_id: str, token: Optional[str] = None
+    ) -> Optional[PendingStreamCollaborator]:
+        """Get a particular pending invite for the active user on a given stream.
+        If no invite_id is provided, any valid invite will be returned.
+
+        Requires Speckle Server version >= 2.6.4
+
+        Arguments:
+            stream_id {str} -- the id of the stream to look for invites on
+            token {str} -- the token of the invite to look for (optional)
+
+        Returns:
+            PendingStreamCollaborator
+            -- the invite for the given stream (or None if it isn't found)
+        """
+        self._check_invites_supported()
+
+        query = gql(
+            """
+            query StreamInvite($streamId: String!, $token: String) {
+                streamInvite(streamId: $streamId, token: $token) {
+                    id
+                    token
+                    streamId
+                    streamName
+                    title
+                    role
+                    invitedBy {
+                        id
+                        name
+                        company
+                        avatar
+                    }
+                }
+            }
+            """
+        )
+
+        params = {"streamId": stream_id}
+        if token:
+            params["token"] = token
+
+        return self.make_request(
+            query=query,
+            params=params,
+            return_type="streamInvite",
+            schema=PendingStreamCollaborator,
+        )

src/specklepy/core/api/resources/branch.py

@@ -1,7 +1,9 @@
+from typing import Optional
+
 from gql import gql
-from specklepy.api.resource import ResourceBase
-from specklepy.api.models import Branch
-from specklepy.logging import metrics
+
+from specklepy.core.api.models import Branch
+from specklepy.core.api.resource import ResourceBase
 
 NAME = "branch"
 
@@ -30,7 +32,6 @@ 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 +62,6 @@ 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!) {
@@ -86,7 +86,7 @@ class Resource(ResourceBase):
                               createdAt
                             }
                         }
-                    }                      
+                    }
                 }
             }
             """
@@ -109,10 +109,13 @@ 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!) {
+            query BranchesGet(
+                    $stream_id: String!,
+                    $branches_limit: Int!,
+                    $commits_limit: Int!
+                ) {
                 stream(id: $stream_id) {
                     branches(limit: $branches_limit) {
                         items {
@@ -151,7 +154,11 @@ class Resource(ResourceBase):
         )
 
     def update(
-        self, stream_id: str, branch_id: str, name: str = None, description: str = None
+        self,
+        stream_id: str,
+        branch_id: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
     ):
         """Update a branch
 
@@ -164,7 +171,6 @@ class Resource(ResourceBase):
         Returns:
             bool -- True if update is successful
         """
-        metrics.track(metrics.BRANCH, self.account, {"name": "update"})
         query = gql(
             """
             mutation  BranchUpdate($branch: BranchUpdateInput!) {
@@ -198,7 +204,6 @@ class Resource(ResourceBase):
         Returns:
             bool -- True if deletion is successful
         """
-        metrics.track(metrics.BRANCH, self.account, {"name": "delete"})
         query = gql(
             """
             mutation BranchDelete($branch: BranchDeleteInput!) {

src/specklepy/core/api/resources/commit.py

@@ -1,9 +1,10 @@
-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
+from typing import List, Optional, Union
 
+from gql import gql
+
+from specklepy.core.api.models import Commit
+from specklepy.core.api.resource import ResourceBase
+from specklepy.logging.exceptions import SpeckleException
 
 NAME = "commit"
 
@@ -69,7 +70,6 @@ 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!) {
@@ -107,26 +107,30 @@ class Resource(ResourceBase):
         branch_name: str = "main",
         message: str = "",
         source_application: str = "python",
-        parents: List[str] = None,
-    ) -> str:
+        parents: Optional[List[str]] = None,
+    ) -> Union[str, SpeckleException]:
         """
         Creates a commit on a branch
 
         Arguments:
             stream_id {str} -- the stream you want to commit to
             object_id {str} -- the hash of your commit object
-            branch_name {str} -- the name of the branch to commit to (defaults to "main")
-            message {str} -- optional: a message to give more information about the commit
-            source_application{str} -- optional: the application from which the commit was created (defaults to "python")
+            branch_name {str}
+                -- the name of the branch to commit to (defaults to "main")
+            message {str}
+                -- optional: a message to give more information about the commit
+            source_application{str}
+                -- optional: the application from which the commit was created
+                (defaults to "python")
             parents {List[str]} -- optional: the id of the parent commits
 
         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)}
+            mutation CommitCreate ($commit: CommitCreateInput!)
+                { commitCreate(commit: $commit)}
             """
         )
         params = {
@@ -150,17 +154,18 @@ class Resource(ResourceBase):
         Update a commit
 
         Arguments:
-            stream_id {str} -- the id of the stream that contains the commit you'd like to update
+            stream_id {str}
+                -- the id of the stream that contains the commit you'd like to update
             commit_id {str} -- the id of the commit you'd like to update
             message {str} -- the updated commit message
 
         Returns:
             bool -- True if the operation succeeded
         """
-        metrics.track(metrics.COMMIT, self.account, {"name": "update"})
         query = gql(
             """
-            mutation CommitUpdate($commit: CommitUpdateInput!){ commitUpdate(commit: $commit)}
+            mutation CommitUpdate($commit: CommitUpdateInput!)
+                { commitUpdate(commit: $commit)}
             """
         )
         params = {
@@ -176,16 +181,17 @@ class Resource(ResourceBase):
         Delete a commit
 
         Arguments:
-            stream_id {str} -- the id of the stream that contains the commit you'd like to delete
+            stream_id {str}
+                -- the id of the stream that contains the commit you'd like to delete
             commit_id {str} -- the id of the commit you'd like to delete
 
         Returns:
             bool -- True if the operation succeeded
         """
-        metrics.track(metrics.COMMIT, self.account, {"name": "delete"})
         query = gql(
             """
-            mutation CommitDelete($commit: CommitDeleteInput!){ commitDelete(commit: $commit)}
+            mutation CommitDelete($commit: CommitDeleteInput!)
+                { commitDelete(commit: $commit)}
             """
         )
         params = {"commit": {"streamId": stream_id, "id": commit_id}}
@@ -204,7 +210,6 @@ class Resource(ResourceBase):
         """
         Mark a commit object a received by the source application.
         """
-        metrics.track(metrics.COMMIT, self.account, {"name": "received"})
         query = gql(
             """
             mutation CommitReceive($receivedInput:CommitReceivedInput!){

src/specklepy/core/api/resources/object.py

@@ -1,6 +1,8 @@
 from typing import Dict, List
+
 from gql import gql
-from specklepy.api.resource import ResourceBase
+
+from specklepy.core.api.resource import ResourceBase
 from specklepy.objects.base import Base
 
 NAME = "object"
@@ -59,21 +61,28 @@ class Resource(ResourceBase):
         """
         Not advised - generally, you want to use `operations.send()`.
 
-        Create a new object on a stream. To send a base object, you can prepare it by running it through the
-        `BaseObjectSerializer.traverse_base()` function to get a valid (serialisable) object to send.
+        Create a new object on a stream.
+        To send a base object, you can prepare it by running it through the
+        `BaseObjectSerializer.traverse_base()` function to get a valid (serialisable)
+        object to send.
 
-        NOTE: this does not create a commit - you can create one with `SpeckleClient.commit.create`. Dynamic fields will be located in the 'data' dict of the received `Base` object
+        NOTE: this does not create a commit - you can create one with
+        `SpeckleClient.commit.create`.
+        Dynamic fields will be located in the 'data' dict of the received `Base` object
 
         Arguments:
             stream_id {str} -- the id of the stream you want to send the object to
-            objects {List[Dict]} -- a list of base dictionary objects (NOTE: must be json serialisable)
+            objects {List[Dict]}
+            -- a list of base dictionary objects (NOTE: must be json serialisable)
 
         Returns:
             str -- the id of the object
         """
         query = gql(
             """
-          mutation ObjectCreate($object_input: ObjectCreateInput!) { objectCreate(objectInput: $object_input) }
+          mutation ObjectCreate($object_input: ObjectCreateInput!) {
+            objectCreate(objectInput: $object_input)
+        }
           """
         )
         params = {"object_input": {"streamId": stream_id, "objects": objects}}

src/specklepy/core/api/resources/other_user.py

@@ -0,0 +1,172 @@
+from datetime import datetime, timezone
+from typing import List, Optional, Union
+
+from gql import gql
+
+from specklepy.core.api.models import ActivityCollection, LimitedUser
+from specklepy.core.api.resource import ResourceBase
+from specklepy.logging.exceptions import SpeckleException
+
+NAME = "other_user"
+
+
+class Resource(ResourceBase):
+    """API Access class for other users, that are not the currently active user."""
+
+    def __init__(self, account, basepath, client, server_version) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+            name=NAME,
+            server_version=server_version,
+        )
+        self.schema = LimitedUser
+
+    def get(self, id: str) -> LimitedUser:
+        """
+        Gets the profile of another user.
+
+        Arguments:
+            id {str} -- the user id
+
+        Returns:
+            LimitedUser -- the retrieved profile of another user
+        """
+        query = gql(
+            """
+            query OtherUser($id: String!) {
+                otherUser(id: $id) {
+                    id
+                    name
+                    bio
+                    company
+                    avatar
+                    verified
+                    role
+                }
+            }
+          """
+        )
+
+        params = {"id": id}
+
+        return self.make_request(query=query, params=params, return_type="otherUser")
+
+    def search(
+        self, search_query: str, limit: int = 25
+    ) -> Union[List[LimitedUser], SpeckleException]:
+        """Searches for user by name or email. The search query must be at least
+        3 characters long
+
+        Arguments:
+            search_query {str} -- a string to search for
+            limit {int} -- the maximum number of results to return
+        Returns:
+            List[LimitedUser] -- a list of User objects that match the search query
+        """
+        if len(search_query) < 3:
+            return SpeckleException(
+                message="User search query must be at least 3 characters"
+            )
+
+        query = gql(
+            """
+            query UserSearch($search_query: String!, $limit: Int!) {
+                userSearch(query: $search_query, limit: $limit) {
+                    items {
+                        id
+                        name
+                        bio
+                        company
+                        avatar
+                        verified
+                    }
+                }
+            }
+          """
+        )
+        params = {"search_query": search_query, "limit": limit}
+
+        return self.make_request(
+            query=query, params=params, return_type=["userSearch", "items"]
+        )
+
+    def activity(
+        self,
+        user_id: str,
+        limit: int = 20,
+        action_type: Optional[str] = None,
+        before: Optional[datetime] = None,
+        after: Optional[datetime] = None,
+        cursor: Optional[datetime] = None,
+    ) -> ActivityCollection:
+        """
+        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
+
+        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
+                ){
+                otherUser(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=["otherUser", "activity"],
+            schema=ActivityCollection,
+        )

src/specklepy/core/api/resources/server.py

@@ -1,11 +1,11 @@
 import re
 from typing import Any, Dict, List, Tuple
-from gql import gql
-from specklepy.api.models import ServerInfo
-from specklepy.api.resource import ResourceBase
-from specklepy.logging import metrics
-from specklepy.logging.exceptions import GraphQLException
 
+from gql import gql
+
+from specklepy.core.api.models import ServerInfo
+from specklepy.core.api.resource import ResourceBase
+from specklepy.logging.exceptions import GraphQLException
 
 NAME = "server"
 
@@ -27,7 +27,6 @@ class Resource(ResourceBase):
         Returns:
             dict -- the server info in dictionary form
         """
-        metrics.track(metrics.SERVER, self.account, {"name": "get"})
         query = gql(
             """
             query Server {
@@ -65,8 +64,8 @@ class Resource(ResourceBase):
         """Get the server version
 
         Returns:
-            tuple -- the server version in the format (major, minor, patch, (tag, build))
-                     eg (2, 6, 3) for a stable build and (2, 6, 4, 'alpha', 4711) for alpha
+            the server version in the format (major, minor, patch, (tag, build))
+            eg (2, 6, 3) for a stable build and (2, 6, 4, 'alpha', 4711) for alpha
         """
         # not tracking as it will be called along with other mutations / queries as a check
         query = gql(
@@ -100,7 +99,6 @@ 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 {
@@ -134,7 +132,6 @@ 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!) {
@@ -160,7 +157,6 @@ 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!) {

src/specklepy/core/api/resources/stream.py

@@ -1,12 +1,12 @@
 from datetime import datetime, timezone
 from typing import List, Optional
+
 from deprecated import deprecated
 from gql import gql
-from specklepy.logging import metrics
-from specklepy.api.models import ActivityCollection, PendingStreamCollaborator, Stream
-from specklepy.api.resource import ResourceBase
-from specklepy.logging.exceptions import UnsupportedException, SpeckleException
 
+from specklepy.core.api.models import ActivityCollection, PendingStreamCollaborator, Stream
+from specklepy.core.api.resource import ResourceBase
+from specklepy.logging.exceptions import SpeckleException, UnsupportedException
 
 NAME = "stream"
 
@@ -36,7 +36,6 @@ class Resource(ResourceBase):
         Returns:
             Stream -- the retrieved stream
         """
-        metrics.track(metrics.STREAM, self.account, {"name": "get"})
         query = gql(
             """
             query Stream($id: String!, $branch_limit: Int!, $commit_limit: Int!) {
@@ -96,7 +95,6 @@ class Resource(ResourceBase):
         Returns:
             List[Stream] -- A list of Stream objects
         """
-        metrics.track(metrics.STREAM, self.account, {"name": "get"})
         query = gql(
             """
             query User($stream_limit: Int!) {
@@ -152,12 +150,12 @@ class Resource(ResourceBase):
         Arguments:
             name {str} -- the name of the string
             description {str} -- a short description of the stream
-            is_public {bool} -- whether or not the stream can be viewed by anyone with the id
+            is_public {bool}
+                -- whether or not the stream can be viewed by anyone with the id
 
         Returns:
             id {str} -- the id of the newly created stream
         """
-        metrics.track(metrics.STREAM, self.account, {"name": "create"})
         query = gql(
             """
             mutation StreamCreate($stream: StreamCreateInput!) {
@@ -175,7 +173,11 @@ class Resource(ResourceBase):
         )
 
     def update(
-        self, id: str, name: str = None, description: str = None, is_public: bool = None
+        self,
+        id: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        is_public: Optional[bool] = None,
     ) -> bool:
         """Update an existing stream
 
@@ -183,12 +185,12 @@ class Resource(ResourceBase):
             id {str} -- the id of the stream to be updated
             name {str} -- the name of the string
             description {str} -- a short description of the stream
-            is_public {bool} -- whether or not the stream can be viewed by anyone with the id
+            is_public {bool}
+                -- whether or not the stream can be viewed by anyone with the id
 
         Returns:
             bool -- whether the stream update was successful
         """
-        metrics.track(metrics.STREAM, self.account, {"name": "update"})
         query = gql(
             """
             mutation StreamUpdate($stream: StreamUpdateInput!) {
@@ -219,7 +221,6 @@ class Resource(ResourceBase):
         Returns:
             bool -- whether the deletion was successful
         """
-        metrics.track(metrics.STREAM, self.account, {"name": "delete"})
         query = gql(
             """
             mutation StreamDelete($id: String!) {
@@ -252,10 +253,14 @@ class Resource(ResourceBase):
         Returns:
             List[Stream] -- a list of Streams that match the search query
         """
-        metrics.track(metrics.STREAM, self.account, {"name": "search"})
         query = gql(
             """
-            query StreamSearch($search_query: String!,$limit: Int!, $branch_limit:Int!, $commit_limit:Int!) {
+            query StreamSearch(
+                $search_query: String!,
+                $limit: Int!,
+                $branch_limit:Int!,
+                $commit_limit:Int!
+            ) {
                 streams(query: $search_query, limit: $limit) {
                     items {
                         id
@@ -314,12 +319,12 @@ class Resource(ResourceBase):
 
         Arguments:
             stream_id {str} -- the id of the stream to favorite / unfavorite
-            favorited {bool} -- whether to favorite (True) or unfavorite (False) the stream
+            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!) {
@@ -342,59 +347,6 @@ class Resource(ResourceBase):
             query=query, params=params, return_type=["streamFavorite"]
         )
 
-    @deprecated(
-        version="2.6.4",
-        reason=(
-            "As of Speckle Server v2.6.4, this method is deprecated. "
-            "Users need to be invited and accept the invite before being added to a stream"
-        ),
-    )
-    def grant_permission(self, stream_id: str, user_id: str, role: str):
-        """Grant permissions to a user on a given stream
-
-        Valid for Speckle Server version < 2.6.4
-
-        Arguments:
-            stream_id {str} -- the id of the stream to grant permissions to
-            user_id {str} -- the id of the user to grant permissions for
-            role {str} -- the role to grant the user
-
-        Returns:
-            bool -- True if the operation was successful
-        """
-        metrics.track(metrics.PERMISSION, self.account, {"name": "add", "role": role})
-        if self.server_version and self.server_version >= (2, 6, 4):
-            raise UnsupportedException(
-                (
-                    "Server mutation `grant_permission` is no longer supported as of Speckle Server v2.6.4. "
-                    "Please use the new `update_permission` method to change an existing user's permission "
-                    "or use the `invite` method to invite a user to a stream."
-                )
-            )
-
-        query = gql(
-            """
-            mutation StreamGrantPermission($permission_params: StreamGrantPermissionInput !) {
-                streamGrantPermission(permissionParams: $permission_params)
-            }
-            """
-        )
-
-        params = {
-            "permission_params": {
-                "streamId": stream_id,
-                "userId": user_id,
-                "role": role,
-            }
-        }
-
-        return self.make_request(
-            query=query,
-            params=params,
-            return_type="streamGrantPermission",
-            parse_response=False,
-        )
-
     def get_all_pending_invites(
         self, stream_id: str
     ) -> List[PendingStreamCollaborator]:
@@ -407,9 +359,9 @@ class Resource(ResourceBase):
             stream_id {str} -- the stream id from which to get the pending invites
 
         Returns:
-            List[PendingStreamCollaborator] -- a list of pending invites for the specified stream
+            List[PendingStreamCollaborator]
+                -- a list of pending invites for the specified stream
         """
-        metrics.track(metrics.INVITE, self.account, {"name": "get"})
         self._check_invites_supported()
 
         query = gql(
@@ -453,10 +405,10 @@ class Resource(ResourceBase):
     def invite(
         self,
         stream_id: str,
-        email: str = None,
-        user_id: str = None,
+        email: Optional[str] = None,
+        user_id: Optional[str] = None,
         role: str = "stream:contributor",  # should default be reviewer?
-        message: str = None,
+        message: Optional[str] = None,
     ):
         """Invite someone to a stream using either their email or user id
 
@@ -466,18 +418,20 @@ class Resource(ResourceBase):
             stream_id {str} -- the id of the stream to invite the user to
             email {str} -- the email of the user to invite (use this OR `user_id`)
             user_id {str} -- the id of the user to invite (use this OR `email`)
-            role {str} -- the role to assing to the user (defaults to `stream:contributor`)
-            message {str} -- a message to send along with this invite to the specified user
+            role {str}
+                -- the role to assign to the user (defaults to `stream:contributor`)
+            message {str}
+                -- a message to send along with this invite to the specified user
 
         Returns:
             bool -- True if the operation was successful
         """
-        metrics.track(metrics.INVITE, self.account, {"name": "create"})
         self._check_invites_supported()
 
         if email is None and user_id is None:
             raise SpeckleException(
-                "You must provide either an email or a user id to use the `stream.invite` method"
+                "You must provide either an email or a user id to use the"
+                " `stream.invite` method"
             )
 
         query = gql(
@@ -507,9 +461,9 @@ class Resource(ResourceBase):
     def invite_batch(
         self,
         stream_id: str,
-        emails: List[str] = None,
-        user_ids: List[None] = None,
-        message: str = None,
+        emails: Optional[List[str]] = None,
+        user_ids: Optional[List[None]] = None,
+        message: Optional[str] = None,
     ) -> bool:
         """Invite a batch of users to a specified stream.
 
@@ -517,18 +471,21 @@ class Resource(ResourceBase):
 
         Arguments:
             stream_id {str} -- the id of the stream to invite the user to
-            emails {List[str]} -- the email of the user to invite (use this and/or `user_ids`)
-            user_id {List[str]} -- the id of the user to invite (use this and/or `emails`)
-            message {str} -- a message to send along with this invite to the specified user
+            emails {List[str]}
+                -- the email of the user to invite (use this and/or `user_ids`)
+            user_id {List[str]}
+                -- the id of the user to invite (use this and/or `emails`)
+            message {str}
+                -- a message to send along with this invite to the specified user
 
         Returns:
             bool -- True if the operation was successful
         """
-        metrics.track(metrics.INVITE, self.account, {"name": "batch create"})
         self._check_invites_supported()
         if emails is None and user_ids is None:
             raise SpeckleException(
-                "You must provide either an email or a user id to use the `stream.invite` method"
+                "You must provide either an email or a user id to use the"
+                " `stream.invite` method"
             )
 
         query = gql(
@@ -541,16 +498,17 @@ class Resource(ResourceBase):
 
         email_invites = [
             {"streamId": stream_id, "message": message, "email": email}
-            for email in emails
-            if emails is not None
+            for email in (emails if emails is not None else [])
+            if email is not None
         ]
 
         user_invites = [
             {"streamId": stream_id, "message": message, "userId": user_id}
-            for user_id in user_ids
-            if user_ids is not None
+            for user_id in (user_ids if user_ids is not None else []) 
+            if user_id is not None
         ]
 
+
         params = {"input": [*email_invites, *user_invites]}
 
         return self.make_request(
@@ -572,7 +530,6 @@ class Resource(ResourceBase):
         Returns:
             bool -- true if the operation was successful
         """
-        metrics.track(metrics.INVITE, self.account, {"name": "cancel"})
         self._check_invites_supported()
 
         query = gql(
@@ -598,19 +555,23 @@ class Resource(ResourceBase):
         Requires Speckle Server version >= 2.6.4
 
         Arguments:
-            stream_id {str} -- the id of the stream for which the user has a pending invite
+            stream_id {str}
+                -- the id of the stream for which the user has a pending invite
             token {str} -- the token of the invite to use
             accept {bool} -- whether or not to accept the invite (defaults to True)
 
         Returns:
             bool -- true if the operation was successful
         """
-        metrics.track(metrics.INVITE, self.account, {"name": "use"})
         self._check_invites_supported()
 
         query = gql(
             """
-            mutation StreamInviteUse($accept: Boolean!, $streamId: String!, $token: String!) {
+            mutation StreamInviteUse(
+                $accept: Boolean!,
+                $streamId: String!,
+                $token: String!
+                ) {
                 streamInviteUse(accept: $accept, streamId: $streamId, token: $token)
             }
             """
@@ -638,19 +599,19 @@ class Resource(ResourceBase):
         Returns:
             bool -- True if the operation was successful
         """
-        metrics.track(
-            metrics.PERMISSION, self.account, {"name": "update", "role": role}
-        )
-        if self.server_version and self.server_version < (2, 6, 4):
+        if self.server_version and (
+            self.server_version != ("dev",) and self.server_version < (2, 6, 4)
+        ):
             raise UnsupportedException(
-                (
-                    "Server mutation `update_permission` is only supported as of Speckle Server v2.6.4. "
-                    "Please update your Speckle Server to use this method or use the `grant_permission` method instead."
-                )
+                "Server mutation `update_permission` is only supported as of Speckle"
+                " Server v2.6.4. Please update your Speckle Server to use this method"
+                " or use the `grant_permission` method instead."
             )
         query = gql(
             """
-            mutation StreamUpdatePermission($permission_params: StreamUpdatePermissionInput !) {
+            mutation StreamUpdatePermission(
+                $permission_params: StreamUpdatePermissionInput!
+                ) {
                 streamUpdatePermission(permissionParams: $permission_params)
             }
             """
@@ -681,10 +642,11 @@ 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 !) {
+            mutation StreamRevokePermission(
+                $permission_params: StreamRevokePermissionInput!
+                ) {
                 streamRevokePermission(permissionParams: $permission_params)
             }
             """
@@ -702,29 +664,48 @@ class Resource(ResourceBase):
     def activity(
         self,
         stream_id: str,
-        action_type: str = None,
+        action_type: Optional[str] = None,
         limit: int = 20,
-        before: datetime = None,
-        after: datetime = None,
-        cursor: datetime = None,
+        before: Optional[datetime] = None,
+        after: Optional[datetime] = None,
+        cursor: Optional[datetime] = None,
     ):
         """
-        Get the activity from a given stream in an Activity collection. Step into the activity `items` for the list of activity.
+        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
+        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`)
+        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)
+        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){
+            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) {
+                    activity(
+                        actionType: $action_type,
+                        before: $before,
+                        after: $after,
+                        cursor: $cursor,
+                        limit: $limit
+                        ) {
                         totalCount
                         cursor
                         items {
@@ -757,8 +738,9 @@ class Resource(ResourceBase):
             }
         except AttributeError as e:
             raise SpeckleException(
-                "Could not get stream activity - `before`, `after`, and `cursor` must be in `datetime` format if provided",
-                ValueError,
+                "Could not get stream activity - `before`, `after`, and `cursor` must"
+                " be in `datetime` format if provided",
+                ValueError(),
             ) from e
 
         return self.make_request(

src/specklepy/core/api/resources/subscriptions.py

@@ -1,9 +1,11 @@
-from typing import Callable, Dict, List, Union
 from functools import wraps
+from typing import Callable, Dict, List, Optional, Union
+
 from gql import gql
 from graphql import DocumentNode
-from specklepy.api.resource import ResourceBase
-from specklepy.api.resources.stream import Stream
+
+from specklepy.core.api.resource import ResourceBase
+from specklepy.core.api.resources.stream import Stream
 from specklepy.logging.exceptions import SpeckleException
 
 NAME = "subscribe"
@@ -34,11 +36,13 @@ class Resource(ResourceBase):
         )
 
     @check_wsclient
-    async def stream_added(self, callback: Callable = None):
-        """Subscribes to new stream added event for your profile. Use this to display an up-to-date list of streams.
+    async def stream_added(self, callback: Optional[Callable] = None):
+        """Subscribes to new stream added event for your profile.
+        Use this to display an up-to-date list of streams.
 
         Arguments:
-            callback {Callable[Stream]} -- a function that takes the updated stream as an argument and executes each time a stream is added
+            callback {Callable[Stream]} -- a function that takes the updated stream
+            as an argument and executes each time a stream is added
 
         Returns:
             Stream -- the update stream
@@ -53,12 +57,16 @@ class Resource(ResourceBase):
         )
 
     @check_wsclient
-    async def stream_updated(self, id: str, callback: Callable = None):
-        """Subscribes to stream updated event. Use this in clients/components that pertain only to this stream.
+    async def stream_updated(self, id: str, callback: Optional[Callable] = None):
+        """
+        Subscribes to stream updated event.
+        Use this in clients/components that pertain only to this stream.
 
         Arguments:
             id {str} -- the stream id of the stream to subscribe to
-            callback {Callable[Stream]} -- a function that takes the updated stream as an argument and executes each time the stream is updated
+            callback {Callable[Stream]}
+            -- a function that takes the updated stream
+            as an argument and executes each time the stream is updated
 
         Returns:
             Stream -- the update stream
@@ -79,11 +87,17 @@ class Resource(ResourceBase):
         )
 
     @check_wsclient
-    async def stream_removed(self, callback: Callable = None):
-        """Subscribes to stream removed event for your profile. Use this to display an up-to-date list of streams for your profile. NOTE: If someone revokes your permissions on a stream, this subscription will be triggered with an extra value of revokedBy in the payload.
+    async def stream_removed(self, callback: Optional[Callable] = None):
+        """Subscribes to stream removed event for your profile.
+        Use this to display an up-to-date list of streams for your profile.
+        NOTE: If someone revokes your permissions on a stream,
+        this subscription will be triggered with an extra value of revokedBy
+        in the payload.
 
         Arguments:
-            callback {Callable[Dict]} -- a function that takes the returned dict as an argument and executes each time a stream is removed
+            callback {Callable[Dict]}
+            -- a function that takes the returned dict as an argument
+            and executes each time a stream is removed
 
         Returns:
             dict -- dict containing 'id' of stream removed and optionally 'revokedBy'
@@ -105,9 +119,9 @@ class Resource(ResourceBase):
     async def subscribe(
         self,
         query: DocumentNode,
-        params: Dict = None,
-        callback: Callable = None,
-        return_type: Union[str, List] = None,
+        params: Optional[Dict] = None,
+        callback: Optional[Callable] = None,
+        return_type: Optional[Union[str, List]] = None,
         schema=None,
         parse_response: bool = True,
     ):

src/specklepy/core/api/resources/user.py

@@ -1,13 +1,22 @@
-from typing import List, Optional, Union
 from datetime import datetime, timezone
+from typing import List, Optional, Union
+
+from deprecated import deprecated
 from gql import gql
-from specklepy.logging import metrics
+
+from specklepy.core.api.models import ActivityCollection, PendingStreamCollaborator, User
+from specklepy.core.api.resource import ResourceBase
+
 from specklepy.logging.exceptions import SpeckleException
-from specklepy.api.resource import ResourceBase
-from specklepy.api.models import ActivityCollection, PendingStreamCollaborator, User
 
 NAME = "user"
 
+DEPRECATION_VERSION = "2.9.0"
+DEPRECATION_TEXT = (
+    "The user resource is deprecated, please use the active_user or other_user"
+    " resources"
+)
+
 
 class Resource(ResourceBase):
     """API Access class for users"""
@@ -22,8 +31,12 @@ class Resource(ResourceBase):
         )
         self.schema = User
 
-    def get(self, id: str = None) -> User:
-        """Gets the profile of a user. If no id argument is provided, will return the current authenticated user's profile (as extracted from the authorization header).
+    @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT)
+    def get(self, id: Optional[str] = None) -> User:
+        """
+        Gets the profile of a user.
+        If no id argument is provided, will return the current authenticated
+        user's profile (as extracted from the authorization header).
 
         Arguments:
             id {str} -- the user id
@@ -31,7 +44,6 @@ class Resource(ResourceBase):
         Returns:
             User -- the retrieved user
         """
-        metrics.track(metrics.USER, self.account, {"name": "get"})
         query = gql(
             """
             query User($id: String) {
@@ -54,10 +66,13 @@ class Resource(ResourceBase):
 
         return self.make_request(query=query, params=params, return_type="user")
 
+    @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT)
     def search(
         self, search_query: str, limit: int = 25
     ) -> Union[List[User], SpeckleException]:
-        """Searches for user by name or email. The search query must be at least 3 characters long
+        """
+        Searches for user by name or email.
+        The search query must be at least 3 characters long
 
         Arguments:
             search_query {str} -- a string to search for
@@ -70,7 +85,6 @@ 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!) {
@@ -93,8 +107,13 @@ class Resource(ResourceBase):
             query=query, params=params, return_type=["userSearch", "items"]
         )
 
+    @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT)
     def update(
-        self, name: str = None, company: str = None, bio: str = None, avatar: str = None
+        self,
+        name: Optional[str] = None,
+        company: Optional[str] = None,
+        bio: Optional[str] = None,
+        avatar: Optional[str] = None,
     ):
         """Updates your user profile. All arguments are optional.
 
@@ -107,7 +126,6 @@ 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!) {
@@ -121,41 +139,63 @@ class Resource(ResourceBase):
 
         if not params["user"]:
             return SpeckleException(
-                message="You must provide at least one field to update your user profile"
+                message=(
+                    "You must provide at least one field to update your user profile"
+                )
             )
 
         return self.make_request(
             query=query, params=params, return_type="userUpdate", parse_response=False
         )
 
+    @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT)
     def activity(
         self,
-        user_id: str = None,
+        user_id: Optional[str] = None,
         limit: int = 20,
-        action_type: str = None,
-        before: datetime = None,
-        after: datetime = None,
-        cursor: datetime = None,
+        action_type: Optional[str] = None,
+        before: Optional[datetime] = None,
+        after: Optional[datetime] = None,
+        cursor: Optional[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).
+        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
+        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`)
+        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)
+        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){
+            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) {
+                    activity(
+                        actionType: $action_type,
+                        before: $before,
+                        after: $after,
+                        cursor: $cursor,
+                        limit: $limit
+                        ) {
                         totalCount
                         cursor
                         items {
@@ -190,15 +230,16 @@ class Resource(ResourceBase):
             schema=ActivityCollection,
         )
 
+    @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT)
     def get_all_pending_invites(self) -> List[PendingStreamCollaborator]:
         """Get all of the active user's pending stream invites
 
         Requires Speckle Server version >= 2.6.4
 
         Returns:
-            List[PendingStreamCollaborator] -- a list of pending invites for the current user
+            List[PendingStreamCollaborator]
+                -- a list of pending invites for the current user
         """
-        metrics.track(metrics.INVITE, self.account, {"name": "get"})
         self._check_invites_supported()
 
         query = gql(
@@ -229,8 +270,9 @@ class Resource(ResourceBase):
             schema=PendingStreamCollaborator,
         )
 
+    @deprecated(version=DEPRECATION_VERSION, reason=DEPRECATION_TEXT)
     def get_pending_invite(
-        self, stream_id: str, token: str = None
+        self, stream_id: str, token: Optional[str] = None
     ) -> Optional[PendingStreamCollaborator]:
         """Get a particular pending invite for the active user on a given stream.
         If no invite_id is provided, any valid invite will be returned.
@@ -242,9 +284,9 @@ class Resource(ResourceBase):
             token {str} -- the token of the invite to look for (optional)
 
         Returns:
-            PendingStreamCollaborator -- the invite for the given stream (or None if it isn't found)
+            PendingStreamCollaborator
+                -- the invite for the given stream (or None if it isn't found)
         """
-        metrics.track(metrics.INVITE, self.account, {"name": "get"})
         self._check_invites_supported()
 
         query = gql(

src/specklepy/core/api/wrapper.py

@@ -1,23 +1,28 @@
+from urllib.parse import unquote, urlparse
 from warnings import warn
-from urllib.parse import urlparse, unquote
-from specklepy.api.credentials import (
+from gql import gql
+
+from specklepy.core.api.client import SpeckleClient
+from specklepy.core.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
+from specklepy.transports.server.server import ServerTransport
 
 
 class StreamWrapper:
     """
-    The `StreamWrapper` gives you some handy helpers to deal with urls and get authenticated clients and transports.
+    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
+    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
@@ -45,7 +50,10 @@ class StreamWrapper:
     _account: Account = None
 
     def __repr__(self):
-        return f"StreamWrapper( server: {self.host}, stream_id: {self.stream_id}, type: {self.type} )"
+        return (
+            f"StreamWrapper( server: {self.host}, stream_id: {self.stream_id}, type:"
+            f" {self.type} )"
+        )
 
     def __str__(self) -> str:
         return self.__repr__()
@@ -67,20 +75,32 @@ class StreamWrapper:
         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."
+                f"Cannot parse {url} into a stream wrapper class - invalid URL"
+                " provided."
             )
 
+        # check for fe2 URL
+        if "/projects/" in parsed.path:
+            use_fe2 = True
+        else:
+            use_fe2 = False
+
         while segments:
             segment = segments.pop(0)
-            if segments and segment.lower() == "streams":
+            if segments and (
+                (use_fe2 is False and segment.lower() == "streams")
+                or (use_fe2 is True and segment.lower() == "projects")
+            ):
                 self.stream_id = segments.pop(0)
             elif segments and segment.lower() == "commits":
                 self.commit_id = segments.pop(0)
-            elif segments and segment.lower() == "branches":
+            elif segments and (
+                (use_fe2 is False and segment.lower() == "branches")
+                or (use_fe2 is True and segment.lower() == "models")
+            ):
                 self.branch_name = unquote(segments.pop(0))
             elif segments and segment.lower() == "objects":
                 self.object_id = segments.pop(0)
@@ -90,9 +110,42 @@ class StreamWrapper:
                     self.commit_id = segments.pop(0)
             else:
                 raise SpeckleException(
-                    f"Cannot parse {url} into a stream wrapper class - invalid URL provided."
+                    f"Cannot parse {url} into a stream wrapper class - invalid URL"
+                    " provided."
                 )
 
+        if use_fe2 is True and self.branch_name is not None:
+            if "," in self.branch_name:
+                raise SpeckleException("Multi-model urls are not supported yet")
+
+            if "@" in self.branch_name:
+                model_id = self.branch_name.split("@")[0]
+                self.commit_id = self.branch_name.split("@")[1]
+            else:
+                model_id = self.branch_name
+
+            # get branch name
+            query = gql(
+                """
+                query Project($project_id: String!, $model_id: String!) {
+                    project(id: $project_id) {
+                        id
+                        model(id: $model_id) {
+                            name
+                        }
+                    }
+                }
+            """
+            )
+            self._client = self.get_client()
+            params = {"project_id": self.stream_id, "model_id": model_id}
+            project = self._client.httpclient.execute(query, params)
+
+            try:
+                self.branch_name = project["project"]["model"]["name"]
+            except KeyError as ke:
+                raise SpeckleException("Project model name is not found", ke)
+
         if not self.stream_id:
             raise SpeckleException(
                 f"Cannot parse {url} into a stream wrapper class - no stream id found."
@@ -104,13 +157,18 @@ class StreamWrapper:
 
     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)
+        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),
+            (
+                a
+                for a in get_local_accounts()
+                if self.host == urlparse(a.serverInfo.url).netloc
+            ),
             None,
         )
 
@@ -124,14 +182,18 @@ class StreamWrapper:
 
     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.
+        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)
+            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
+            SpeckleClient
+            -- authenticated with a corresponding local account or the provided token
         """
         if self._client and token is None:
             return self._client
@@ -155,11 +217,14 @@ class StreamWrapper:
 
     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.
+        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
+            ServerTransport -- constructed for this stream
+            with a pre-authenticated client
         """
         if not self._account or not self._account.token:
             self.get_account(token)

src/specklepy/core/helpers/__init__.py

@@ -0,0 +1 @@
+"""Common helpers module for Core."""

src/specklepy/core/helpers/speckle_path_provider.py

@@ -0,0 +1,127 @@
+"""
+Provides uniform and consistent path helpers for `specklepy`
+"""
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+from specklepy.logging.exceptions import SpeckleException
+
+_user_data_env_var = "SPECKLE_USERDATA_PATH"
+
+
+def _path() -> Optional[Path]:
+    """Read the user data path override setting."""
+    path_override = os.environ.get(_user_data_env_var)
+    if path_override:
+        return Path(path_override)
+    return None
+
+
+_application_name = "Speckle"
+
+
+def override_application_name(application_name: str) -> None:
+    """Override the global Speckle application name."""
+    global _application_name
+    _application_name = application_name
+
+
+def override_application_data_path(path: Optional[str]) -> None:
+    """
+    Override the global Speckle application data path.
+
+    If the value of path is `None` the environment variable gets deleted.
+    """
+    if path:
+        os.environ[_user_data_env_var] = path
+    else:
+        os.environ.pop(_user_data_env_var, None)
+
+
+_blob_folder_name = "Blobs"
+
+
+def override_blob_storage_folder(blob_folder_name: str) -> None:
+    """Override the global Blob storage folder name."""
+    global _blob_folder_name
+    _blob_folder_name = blob_folder_name
+
+
+_accounts_folder_name = "Accounts"
+
+
+def override_accounts_folder_name(accounts_folder_name: str) -> None:
+    """Override the global Accounts folder name."""
+    global _accounts_folder_name
+    _accounts_folder_name = accounts_folder_name
+
+
+_objects_folder_name = "Objects"
+
+
+def override_objects_folder_name(objects_folder_name: str) -> None:
+    """Override global Objects folder name."""
+    global _objects_folder_name
+    _objects_folder_name = objects_folder_name
+
+
+def _ensure_folder_exists(base_path: Path, folder_name: str) -> Path:
+    path = base_path.joinpath(folder_name)
+    path.mkdir(exist_ok=True, parents=True)
+    return path
+
+
+def user_application_data_path() -> Path:
+    """Get the platform specific user configuration folder path"""
+    path_override = _path()
+    if path_override:
+        return path_override
+
+    try:
+        if sys.platform.startswith("win"):
+            app_data_path = os.getenv("APPDATA")
+            if not app_data_path:
+                raise SpeckleException(
+                    message="Cannot get appdata path from environment."
+                )
+            return Path(app_data_path)
+        else:
+            # try getting the standard XDG_DATA_HOME value
+            # as that is used as an override
+            app_data_path = os.getenv("XDG_DATA_HOME")
+            if app_data_path:
+                return Path(app_data_path)
+            else:
+                return _ensure_folder_exists(Path.home(), ".config")
+    except Exception as ex:
+        raise SpeckleException(
+            message="Failed to initialize user application data path.", exception=ex
+        )
+
+
+def user_speckle_folder_path() -> Path:
+    """Get the folder where the user's Speckle data should be stored."""
+    return _ensure_folder_exists(user_application_data_path(), _application_name)
+
+
+def user_speckle_connector_installation_path(host_application: str) -> Path:
+    """
+    Gets a connector specific installation folder.
+
+    In this folder we can put our connector installation and all python packages.
+    """
+    return _ensure_folder_exists(
+        _ensure_folder_exists(user_speckle_folder_path(), "connector_installations"),
+        host_application,
+    )
+
+
+def accounts_folder_path() -> Path:
+    """Get the folder where the Speckle accounts data should be stored."""
+    return _ensure_folder_exists(user_speckle_folder_path(), _accounts_folder_name)
+
+
+def blob_storage_path(path: Optional[Path] = None) -> Path:
+    return _ensure_folder_exists(path or user_speckle_folder_path(), _blob_folder_name)

src/specklepy/logging/exceptions.py

@@ -11,6 +11,17 @@ class SpeckleException(Exception):
         return f"SpeckleException: {self.message}"
 
 
+class SpeckleInvalidUnitException(SpeckleException):
+    def __init__(self, invalid_unit: Any) -> None:
+        super().__init__(
+            message=(
+                "Invalid units: expected type str but received"
+                f" {type(invalid_unit)} ({invalid_unit})."
+            ),
+            exception=None,
+        )
+
+
 class SerializationException(SpeckleException):
     def __init__(self, message: str, obj: Any, exception: Exception = None) -> None:
         super().__init__(message=message, exception=exception)
@@ -18,7 +29,10 @@ class SerializationException(SpeckleException):
         self.unhandled_type = type(obj)
 
     def __str__(self) -> str:
-        return f"SpeckleException: Could not serialize object of type {self.unhandled_type}"
+        return (
+            "SpeckleException: Could not serialize object of type"
+            f" {self.unhandled_type}"
+        )
 
 
 class GraphQLException(SpeckleException):

src/specklepy/logging/metrics.py

@@ -1,13 +1,14 @@
-import sys
-import queue
-import hashlib
-import getpass
-import logging
-import requests
-import threading
-import platform
 import contextlib
+import getpass
+import hashlib
+import logging
+import platform
+import queue
+import sys
+import threading
+from typing import Optional
 
+import requests
 
 """
 Anonymous telemetry to help us understand how to make a better Speckle.
@@ -22,22 +23,25 @@ LOG = logging.getLogger(__name__)
 METRICS_TRACKER = None
 
 # actions
+SDK = "SDK Action"
+CONNECTOR = "Connector Action"
 RECEIVE = "Receive"
 SEND = "Send"
-STREAM = "Stream Action"
-PERMISSION = "Permission Action"
-INVITE = "Invite Action"
-COMMIT = "Commit Action"
-BRANCH = "Branch Action"
-USER = "User Action"
-SERVER = "Server Action"
-CLIENT = "Speckle Client"
-STREAM_WRAPPER = "Stream Wrapper"
 
+# not in use since 2.15  
 ACCOUNTS = "Get Local Accounts"
-
-SERIALIZE = "serialization/serialize"
+BRANCH = "Branch Action"
+CLIENT = "Speckle Client"
+COMMIT = "Commit Action"
 DESERIALIZE = "serialization/deserialize"
+INVITE = "Invite Action"
+OTHER_USER = "Other User Action"
+PERMISSION = "Permission Action"
+SERIALIZE = "serialization/serialize"
+SERVER = "Server Action"
+STREAM = "Stream Action"
+STREAM_WRAPPER = "Stream Wrapper"
+USER = "User Action"
 
 
 def disable():
@@ -50,13 +54,17 @@ def enable():
     TRACK = True
 
 
-def set_host_app(host_app: str, host_app_version: str = None):
+def set_host_app(host_app: str, host_app_version: Optional[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, account: "Account" = None, custom_props: dict = None):
+def track(
+    action: str,
+    account=None,
+    custom_props: Optional[dict] = None,
+):
     if not TRACK:
         return
     try:
@@ -79,10 +87,10 @@ def track(action: str, account: "Account" = None, custom_props: dict = None):
         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(f"Error queueing metrics request: {str(ex)}")
+        LOG.debug(f"Error queueing metrics request: {str(ex)}")
 
 
-def initialise_tracker(account: "Account" = None):
+def initialise_tracker(account=None):
     global METRICS_TRACKER
     if not METRICS_TRACKER:
         METRICS_TRACKER = MetricsTracker()
@@ -90,7 +98,7 @@ def initialise_tracker(account: "Account" = None):
     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)
+        METRICS_TRACKER.set_last_server(account.serverInfo.url)
 
 
 class Singleton(type):
@@ -133,7 +141,9 @@ class MetricsTracker(metaclass=Singleton):
         self.last_server = self.hash(server)
 
     def hash(self, value: str):
-        return hashlib.md5(value.lower().encode("utf-8")).hexdigest().upper()
+        inputList = value.lower().split("://")
+        input = inputList[len(inputList)-1].split("/")[0].split('?')[0]
+        return hashlib.md5(input.encode("utf-8")).hexdigest().upper()
 
     def _send_tracking_requests(self):
         session = requests.Session()
@@ -143,6 +153,6 @@ class MetricsTracker(metaclass=Singleton):
             try:
                 session.post(self.analytics_url, json=event_params)
             except Exception as ex:
-                LOG.error(f"Error sending metrics request: {str(ex)}")
+                LOG.debug(f"Error sending metrics request: {str(ex)}")
 
             self.queue.task_done()

src/specklepy/objects/GIS/CRS.py

@@ -0,0 +1,16 @@
+from typing import Optional
+from specklepy.objects import Base
+
+
+class CRS(Base, speckle_type="Objects.GIS.CRS"):
+    """A Coordinate Reference System stored in wkt format"""
+
+    name: Optional[str] = None
+    authority_id: Optional[str] = None
+    wkt: Optional[str] = None
+    units_native: Optional[str] = None 
+    offset_x: Optional[float] = None
+    offset_y: Optional[float] = None
+    rotation: Optional[float] = None
+
+

src/specklepy/objects/GIS/__init__.py

@@ -0,0 +1,22 @@
+"""Builtin Speckle object kit."""
+
+from specklepy.objects.GIS.layers import (
+    VectorLayer,
+    RasterLayer,
+)
+
+from specklepy.objects.GIS.geometry import (
+    GisPolygonGeometry,
+    GisPolygonElement,
+    GisLineElement,
+    GisPointElement,
+    GisRasterElement,
+)
+
+from specklepy.objects.GIS.CRS import (
+    CRS,
+)
+
+__all__ = ["VectorLayer", "RasterLayer", 
+           "GisPolygonGeometry", "GisPolygonElement", "GisLineElement", "GisPointElement", "GisRasterElement", 
+           "CRS"]

src/specklepy/objects/GIS/geometry.py

@@ -0,0 +1,53 @@
+
+from typing import Optional, Union, List 
+from specklepy.objects.geometry import Point, Line, Polyline, Circle, Arc, Polycurve, Mesh 
+from specklepy.objects import Base
+from deprecated import deprecated
+
+class GisPolygonGeometry(Base, speckle_type="Objects.GIS.PolygonGeometry", detachable={"displayValue"}):
+    """GIS Polygon Geometry"""
+
+    boundary: Optional[Union[Polyline, Arc, Line, Circle, Polycurve]] = None
+    voids: Optional[List[Union[Polyline, Arc, Line, Circle, Polycurve]] ] = None
+    displayValue: Optional[List[Mesh]] = None
+
+class GisPolygonElement(Base, speckle_type="Objects.GIS.PolygonElement"):
+    """GIS Polygon element"""
+
+    geometry: Optional[List[GisPolygonGeometry]] = None
+    attributes: Optional[Base] = None
+
+class GisLineElement(Base, speckle_type="Objects.GIS.LineElement"):
+    """GIS Polyline element"""
+
+    geometry: Optional[List[Union[Polyline, Arc, Line, Circle, Polycurve]]] = None,
+    attributes: Optional[Base] = None,
+
+class GisPointElement(Base, speckle_type="Objects.GIS.PointElement"):
+    """GIS Point element"""
+
+    geometry: Optional[List[Point]] = None,
+    attributes: Optional[Base] = None,
+
+class GisRasterElement(Base, speckle_type="Objects.GIS.RasterElement", detachable={"displayValue"}):
+    """GIS Raster element"""
+
+    band_count: Optional[int] = None
+    band_names: Optional[List[str]] = None
+    x_origin: Optional[float] = None
+    y_origin: Optional[float] = None
+    x_size: Optional[int] = None
+    y_size: Optional[int] = None
+    x_resolution: Optional[float] = None
+    y_resolution: Optional[float] = None
+    noDataValue: Optional[List[float]] = None
+    displayValue: Optional[List[Mesh]] = None
+
+class GisTopography(GisRasterElement, speckle_type="Objects.GIS.GisTopography", detachable={"displayValue"}):
+    """GIS Raster element with 3d Topography representation"""
+
+class GisNonGeometryElement(Base, speckle_type="Objects.GIS.NonGeometryElement"):
+    """GIS Table feature"""
+
+    attributes: Optional[Base] = None
+

src/specklepy/objects/GIS/layers.py

@@ -0,0 +1,138 @@
+from typing import Any, Dict, List, Union, Optional
+from specklepy.objects.base import Base
+from specklepy.objects.other import Collection
+
+from specklepy.objects.GIS.CRS import CRS
+from deprecated import deprecated
+
+@deprecated(version="2.15", reason="Use VectorLayer or RasterLayer instead")
+class Layer(Base, detachable={"features"}):
+    """A GIS Layer"""
+    def __init__(
+        self,
+        name:str=None,
+        crs:CRS=None,
+        units: str = "m",
+        features: Optional[List[Base]] = None,
+        layerType: str = "None",
+        geomType: str = "None",
+        renderer: Optional[dict[str, Any]] = None,
+        **kwargs
+    ) -> None:
+        super().__init__(**kwargs)
+        self.name = name
+        self.crs = crs
+        self.units = units
+        self.type = layerType
+        self.features = features or []
+        self.geomType = geomType
+        self.renderer = renderer or {} 
+
+@deprecated(version="2.16", reason="Use VectorLayer or RasterLayer instead")
+class VectorLayer(
+    Collection, 
+    detachable={"elements"}, 
+    speckle_type="VectorLayer", 
+    serialize_ignore={"features"}):
+
+    """GIS Vector Layer"""
+    name: Optional[str]=None
+    crs: Optional[Union[CRS, Base]]=None
+    units: Optional[str] = None
+    elements: Optional[List[Base]] = None
+    attributes: Optional[Base] = None
+    geomType: Optional[str] = "None"
+    renderer: Optional[Dict[str, Any]] = None
+    collectionType = "VectorLayer"
+    
+    @property
+    @deprecated(version="2.14", reason="Use elements")
+    def features(self) -> Optional[List[Base]]:
+        return self.elements
+
+    @features.setter
+    def features(self, value: Optional[List[Base]]) -> None:
+        self.elements = value
+
+@deprecated(version="2.16", reason="Use VectorLayer or RasterLayer instead")
+class RasterLayer(
+    Collection, 
+    detachable={"elements"}, 
+    speckle_type="RasterLayer", 
+    serialize_ignore={"features"}):
+
+    """GIS Raster Layer"""
+
+    name: Optional[str] = None
+    crs: Optional[Union[CRS, Base]]=None
+    units: Optional[str] = None
+    rasterCrs: Optional[Union[CRS, Base]]=None
+    elements: Optional[List[Base]] = None
+    geomType: Optional[str] = "None"
+    renderer: Optional[Dict[str, Any]] = None
+    collectionType = "RasterLayer"
+
+    
+    @property
+    @deprecated(version="2.14", reason="Use elements")
+    def features(self) -> Optional[List[Base]]:
+        return self.elements
+
+    @features.setter
+    def features(self, value: Optional[List[Base]]) -> None:
+        self.elements = value
+
+
+class VectorLayer(
+    Collection, 
+    detachable={"elements"}, 
+    speckle_type="Objects.GIS.VectorLayer", 
+    serialize_ignore={"features"}):
+
+    """GIS Vector Layer"""
+
+    name: Optional[str]=None
+    crs: Optional[Union[CRS, Base]]=None
+    units: Optional[str] = None
+    elements: Optional[List[Base]] = None
+    attributes: Optional[Base] = None
+    geomType: Optional[str] = "None"
+    renderer: Optional[Dict[str, Any]] = None
+    collectionType = "VectorLayer"
+    
+    @property
+    @deprecated(version="2.14", reason="Use elements")
+    def features(self) -> Optional[List[Base]]:
+        return self.elements
+
+    @features.setter
+    def features(self, value: Optional[List[Base]]) -> None:
+        self.elements = value
+
+class RasterLayer(
+    Collection, 
+    detachable={"elements"}, 
+    speckle_type="Objects.GIS.RasterLayer", 
+    serialize_ignore={"features"}):
+
+    """GIS Raster Layer"""
+
+    name: Optional[str] = None
+    crs: Optional[Union[CRS, Base]]=None
+    units: Optional[str] = None
+    rasterCrs: Optional[Union[CRS, Base]]=None
+    elements: Optional[List[Base]] = None
+    geomType: Optional[str] = "None"
+    renderer: Optional[Dict[str, Any]] = None
+    collectionType = "RasterLayer"
+
+    
+    @property
+    @deprecated(version="2.14", reason="Use elements")
+    def features(self) -> Optional[List[Base]]:
+        return self.elements
+
+    @features.setter
+    def features(self, value: Optional[List[Base]]) -> None:
+        self.elements = value
+

src/specklepy/objects/__init__.py

@@ -0,0 +1,6 @@
+"""Builtin Speckle object kit."""
+
+from specklepy.objects import encoding, geometry, other, primitive, structural, units
+from specklepy.objects.base import Base
+
+__all__ = ["Base", "encoding", "geometry", "other", "units", "structural", "primitive"]

src/specklepy/objects/base.py

@@ -1,21 +1,25 @@
+import contextlib
+from enum import Enum
+from inspect import isclass
 from typing import (
     Any,
     ClassVar,
     Dict,
+    ForwardRef,
     List,
     Optional,
-    Union,
     Set,
+    Tuple,
     Type,
+    Union,
     get_type_hints,
 )
-
-import contextlib
-from enum import EnumMeta
 from warnings import warn
 
-from specklepy.logging.exceptions import SpeckleException
-from specklepy.objects.units import get_units_from_string
+from stringcase import pascalcase
+
+from specklepy.logging.exceptions import SpeckleException, SpeckleInvalidUnitException
+from specklepy.objects.units import Units, get_units_from_string
 from specklepy.transports.memory import MemoryTransport
 
 PRIMITIVES = (int, float, str, bool)
@@ -90,7 +94,9 @@ class _RegisteringBase:
     """
 
     speckle_type: ClassVar[str]
-    _type_registry: ClassVar[Dict[str, "Base"]] = {}
+    _speckle_type_override: ClassVar[Optional[str]] = None
+    _speckle_namespace: ClassVar[Optional[str]] = None
+    _type_registry: ClassVar[Dict[str, Type["Base"]]] = {}
     _attr_types: ClassVar[Dict[str, Type]] = {}
     # dict of chunkable props and their max chunk size
     _chunkable: Dict[str, int] = {}
@@ -98,22 +104,61 @@ class _RegisteringBase:
     _detachable: Set[str] = set()  # list of defined detachable props
     _serialize_ignore: Set[str] = set()
 
-    class Config:
-        validate_assignment = True
+    @classmethod
+    def get_registered_type(cls, speckle_type: str) -> Optional[Type["Base"]]:
+        """Get the registered type from the protected mapping via the `speckle_type`"""
+        for full_name in reversed(speckle_type.split(":")):
+            maybe_type = cls._type_registry.get(full_name, None)
+            if maybe_type:
+                return maybe_type
+        return None
 
     @classmethod
-    def get_registered_type(
-        cls, speckle_type: str
-    ) -> Union["Base", Type["Base"], None]:
-        """Get the registered type from the protected mapping via the `speckle_type`"""
-        return cls._type_registry.get(speckle_type, None)
+    def _determine_speckle_type(cls) -> str:
+        """
+        This method brings the speckle_type construction in par with peckle-sharp/Core.
+
+        The implementation differs, because in Core the basis of the speckle_type if
+        type.FullName, which includes the dotnet namespace name too.
+        Copying that behavior is hard in python, where the concept of namespaces
+        means something entirely different.
+
+        So we enabled a speckle_type override mechanism, that enables
+        """
+        base_name = "Base"
+        if cls.__name__ == base_name:
+            return base_name
+
+        bases = [
+            b._full_name()
+            for b in reversed(cls.mro())
+            if issubclass(b, Base) and b.__name__ != base_name
+        ]
+        return ":".join(bases)
+
+    @classmethod
+    def _full_name(cls) -> str:
+        base_name = "Base"
+        if cls.__name__ == base_name:
+            return base_name
+
+        if cls._speckle_type_override:
+            return cls._speckle_type_override
+
+        # convert the module names to PascalCase to match c# namespace naming convention
+        # also drop specklepy from the beginning
+        namespace = ".".join(
+            pascalcase(m)
+            for m in filter(lambda name: name != "specklepy", cls.__module__.split("."))
+        )
+        return f"{namespace}.{cls.__name__}"
 
     def __init_subclass__(
         cls,
-        speckle_type: str = None,
-        chunkable: Dict[str, int] = None,
-        detachable: Set[str] = None,
-        serialize_ignore: Set[str] = None,
+        speckle_type: Optional[str] = None,
+        chunkable: Optional[Dict[str, int]] = None,
+        detachable: Optional[Set[str]] = None,
+        serialize_ignore: Optional[Set[str]] = None,
         **kwargs: Dict[str, Any],
     ):
         """
@@ -123,14 +168,15 @@ class _RegisteringBase:
         initialization. This is reused to register each subclassing type into a class
         level dictionary.
         """
-        if speckle_type in cls._type_registry:
+        cls._speckle_type_override = speckle_type
+        cls.speckle_type = cls._determine_speckle_type()
+        if cls._full_name() in cls._type_registry:
             raise ValueError(
                 f"The speckle_type: {speckle_type} is already registered for type: "
-                f"{cls._type_registry[speckle_type].__name__}. "
-                f"Please choose a different type name."
+                f"{cls._type_registry[cls._full_name()].__name__}. "
+                "Please choose a different type name."
             )
-        cls.speckle_type = speckle_type or cls.__name__
-        cls._type_registry[cls.speckle_type] = cls  # type: ignore
+        cls._type_registry[cls._full_name()] = cls  # type: ignore
         try:
             cls._attr_types = get_type_hints(cls)
         except Exception:
@@ -145,11 +191,138 @@ class _RegisteringBase:
         super().__init_subclass__(**kwargs)
 
 
+# T = TypeVar("T")
+
+# how i wish the code below would be correct, but we're also parsing into floats
+# and converting into strings if the original type is string, but the value isn't
+# def _validate_type(t: type, value: T) -> Tuple[bool, T]:
+
+
+def _validate_type(t: Optional[type], value: Any) -> Tuple[bool, Any]:
+    # this should be reworked. Its only ok to return null for Optionals...
+    # if t is None and value is None:
+    if value is None:
+        return True, value
+
+    # after fixing the None t above, this should be
+    # if t is Any:
+    # if t is None:
+
+    if t is None or t is Any:
+        return True, value
+
+    if isclass(t) and issubclass(t, Enum):
+        if isinstance(value, t):
+            return True, value
+        if value in t._value2member_map_:
+            return True, t(value)
+
+    if getattr(t, "__module__", None) == "typing":
+        if isinstance(t, ForwardRef):
+            return True, value
+
+        origin = getattr(t, "__origin__")
+        # below is what in nicer for >= py38
+        # origin = get_origin(t)
+
+        # recursive validation for Unions on both types preferring the fist type
+        if origin is Union:
+            # below is what in nicer for >= py38
+            # t_1, t_2 = get_args(t)
+            args = t.__args__  # type: ignore
+            for arg_t in args:
+                t_success, t_value = _validate_type(arg_t, value)
+                if t_success:
+                    return True, t_value
+            return False, value
+        if origin is dict:
+            if not isinstance(value, dict):
+                return False, value
+            if value == {}:
+                return True, value
+            if not getattr(t, "__args__", None):
+                return True, value
+            t_key, t_value = t.__args__  # type: ignore
+
+            if (
+                getattr(t_key, "__name__", None),
+                getattr(t_value, "__name__", None),
+            ) == ("KT", "VT"):
+                return True, value
+            # we're only checking the first item, but the for loop and return after
+            # evaluating the first item is the fastest way
+            for dict_key, dict_value in value.items():
+                valid_key, _ = _validate_type(t_key, dict_key)
+                valid_value, _ = _validate_type(t_value, dict_value)
+
+                if valid_key and valid_value:
+                    return True, value
+                return False, value
+
+        if origin is list:
+            if not isinstance(value, list):
+                return False, value
+            if value == []:
+                return True, value
+            if not hasattr(t, "__args__"):
+                return True, value
+            t_items = t.__args__[0]  # type: ignore
+            if getattr(t_items, "__name__", None) == "T":
+                return True, value
+            first_item_valid, _ = _validate_type(t_items, value[0])
+            if first_item_valid:
+                return True, value
+            return False, value
+
+        if origin is tuple:
+            if not isinstance(value, tuple):
+                return False, value
+            if not hasattr(t, "__args__"):
+                return True, value
+            args = t.__args__  # type: ignore
+            if args == tuple():
+                return True, value
+            # we're not checking for empty tuple, cause tuple lengths must match
+            if len(args) != len(value):
+                return False, value
+            values = []
+            for t_item, v_item in zip(args, value):
+                item_valid, item_value = _validate_type(t_item, v_item)
+                if not item_valid:
+                    return False, value
+                values.append(item_value)
+            return True, tuple(values)
+
+        if origin is set:
+            if not isinstance(value, set):
+                return False, value
+            if not hasattr(t, "__args__"):
+                return True, value
+            t_items = t.__args__[0]  # type: ignore
+            first_item_valid, _ = _validate_type(t_items, next(iter(value)))
+            if first_item_valid:
+                return True, value
+            return False, value
+
+    if isinstance(value, t):
+        return True, value
+
+    with contextlib.suppress(ValueError, TypeError):
+        if t is float and value is not None:
+            return True, float(value)
+        # TODO: dafuq, i had to add this not list check
+        # but it would also fail for objects and other complex values
+        if t is str and value and not isinstance(value, list):
+            return True, str(value)
+
+    return False, value
+
+
 class Base(_RegisteringBase):
-    id: Optional[str] = None
-    totalChildrenCount: Optional[int] = None
-    applicationId: Optional[str] = None
-    _units: Union[str, None] = None
+    id: Union[str, None] = None
+    totalChildrenCount: Union[int, None] = None
+    applicationId: Union[str, None] = None
+    _units: Union[None, str] = None
 
     def __init__(self, **kwargs) -> None:
         super().__init__()
@@ -217,11 +390,14 @@ class Base(_RegisteringBase):
     @classmethod
     def update_forward_refs(cls) -> None:
         """
-        Attempts to populate the internal defined types dict for type checking sometime after defining the class.
-        This is already done when defining the class, but can be called again if references to undefined types were
+        Attempts to populate the internal defined types dict for type checking
+        sometime after defining the class.
+        This is already done when defining the class, but can be called
+        again if references to undefined types were
         included.
 
-        See `objects.geometry` for an example of how this is used with the Brep class definitions
+        See `objects.geometry` for an example of how this is used with
+        the Brep class definitions.
         """
         try:
             cls._attr_types = get_type_hints(cls)
@@ -242,55 +418,27 @@ class Base(_RegisteringBase):
                 "Invalid Name: Base member names cannot contain characters '.' or '/'",
             )
 
-    def _type_check(self, name: str, value: Any):
+    def _type_check(self, name: str, value: Any) -> Any:
         """
         Lightweight type checking of values before setting them
 
-        NOTE: Does not check subscripted types within generics as the performance hit of checking
-        each item within a given collection isn't worth it. Eg if you have a type Dict[str, float],
+        NOTE: Does not check subscripted types within generics as the performance hit
+        of checking each item within a given collection isn't worth it.
+        Eg if you have a type Dict[str, float],
         we will only check if the value you're trying to set is a dict.
         """
         types = getattr(self, "_attr_types", {})
         t = types.get(name, None)
 
-        if t is None or t is Any:
-            return value
+        valid, checked_value = _validate_type(t, 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 = (
-                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."
-                )
-                return value
-        if isinstance(value, t):
-            return value
-
-        # to be friendly, we'll parse ints and strs into floats, but not the other way around
-        # (to avoid unexpected rounding)
-        if isinstance(t, tuple):
-            t = t[0]
-
-        with contextlib.suppress(ValueError):
-            if t is float:
-                return float(value)
-            if t is str and value:
-                return str(value)
+        if valid:
+            return checked_value
 
         raise SpeckleException(
-            f"Cannot set '{self.__class__.__name__}.{name}': it expects type '{t.__name__}', but received type '{type(value).__name__}'"
+            f"Cannot set '{self.__class__.__name__}.{name}':"
+            f"it expects type '{str(t)}',"
+            f"but received type '{type(value).__name__}'"
         )
 
     def add_chunkable_attrs(self, **kwargs: int) -> None:
@@ -298,7 +446,8 @@ class Base(_RegisteringBase):
         Mark defined attributes as chunkable for serialisation
 
         Arguments:
-            kwargs {int} -- the name of the attribute as the keyword and the chunk size as the arg
+            kwargs {int} -- the name of the attribute as the keyword
+            and the chunk size as the arg
         """
         chunkable = {k: v for k, v in kwargs.items() if isinstance(v, int)}
         self._chunkable = dict(self._chunkable, **chunkable)
@@ -308,19 +457,25 @@ class Base(_RegisteringBase):
         Mark defined attributes as detachable for serialisation
 
         Arguments:
-            names {Set[str]} -- the names of the attributes to detach as a set of strings
+            names {Set[str]} -- the names of the attributes to detach as a set of string
         """
         self._detachable = self._detachable.union(names)
 
     @property
-    def units(self):
+    def units(self) -> Union[str, None]:
         return self._units
 
     @units.setter
-    def units(self, value: str):
-        units = get_units_from_string(value)
-        if units:
-            self._units = units
+    def units(self, value: Union[str, Units, None]):
+        """While this property accepts any string value, geometry expects units to be specific strings (see Units enum)"""
+        if isinstance(value, str) or value is None:
+            self._units = value
+        elif isinstance(value, Units):
+            self._units = value.value
+        else:
+            raise SpeckleInvalidUnitException(
+                f"Unknown type {type(value)} received for units"
+            )
 
     def get_member_names(self) -> List[str]:
         """Get all of the property names on this object, dynamic or not"""
@@ -350,13 +505,17 @@ 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
+        Note: the hash of a decomposed object differs from that of a
+        non-decomposed object
 
         Arguments:
-            decompose {bool} -- if True, will decompose the object in the process of hashing it
+            decompose {bool} -- if True, will decompose the object in
+            the process of hashing it
 
         Returns:
             str -- the hash (id) of the fully serialized object

src/specklepy/objects/encoding.py

@@ -1,5 +1,5 @@
 from enum import Enum
-from typing import Any, Callable, List, Type, Dict
+from typing import Any, Callable, Dict, List, Optional, Type
 
 from specklepy.logging.exceptions import SpeckleException
 from specklepy.objects.base import Base
@@ -43,7 +43,7 @@ def curve_from_list(args: List[float]):
 
 
 class ObjectArray:
-    def __init__(self, data: list = None) -> None:
+    def __init__(self, data: Optional[list] = None) -> None:
         self.data = data or []
 
     @classmethod
@@ -68,7 +68,7 @@ class ObjectArray:
     def decode_data(
         data: List[Any], decoder: Callable[[List[Any]], Base], **kwargs: Dict[str, Any]
     ) -> List[Base]:
-        bases = []
+        bases: List[Base] = []
         if not data:
             return bases
         index = 0

src/specklepy/objects/fakemesh.py

@@ -1,5 +1,6 @@
 from enum import Enum
-from typing import List
+from typing import List, Optional
+
 from specklepy.objects.geometry import Point
 
 from .base import Base
@@ -16,8 +17,8 @@ DETACHABLE = {"detach_this", "origin", "detached_list"}
 
 
 class FakeGeo(Base, chunkable={"dots": 50}, detachable={"pointslist"}):
-    pointslist: List[Base] = None
-    dots: List[int] = None
+    pointslist: Optional[List[Base]] = None
+    dots: Optional[List[int]] = None
 
 
 class FakeDirection(Enum):
@@ -28,15 +29,15 @@ class FakeDirection(Enum):
 
 
 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
-    _origin: Point = None
+    vertices: Optional[List[float]] = None
+    faces: Optional[List[int]] = None
+    colors: Optional[List[int]] = None
+    textureCoordinates: Optional[List[float]] = None
+    cardinal_dir: Optional[FakeDirection] = None
+    test_bases: Optional[List[Base]] = None
+    detach_this: Optional[Base] = None
+    detached_list: Optional[List[Base]] = None
+    _origin: Optional[Point] = None
 
     # def __init__(self, **kwargs) -> None:
     #     super(FakeMesh, self).__init__(**kwargs)

src/specklepy/objects/geometry.py

@@ -1,39 +1,31 @@
 from enum import Enum
 from typing import Any, List, Optional
 
-from .base import Base
-from .encoding import CurveArray, CurveTypeEncoding, ObjectArray
-from .units import get_encoding_from_units, get_units_from_encoding
+from specklepy.objects.base import Base
+from specklepy.objects.encoding import CurveArray, CurveTypeEncoding, ObjectArray
+from specklepy.objects.primitive import Interval
+from specklepy.objects.units import get_encoding_from_units, get_units_from_encoding
 
 GEOMETRY = "Objects.Geometry."
 
 
-class Interval(Base, speckle_type="Objects.Primitive.Interval"):
-    start: float = 0.0
-    end: float = 0.0
-
-    def length(self):
-        return abs(self.start - self.end)
-
-    @classmethod
-    def from_list(cls, args: List[Any]) -> "Interval":
-        return cls(start=args[0], end=args[1])
-
-    def to_list(self) -> List[Any]:
-        return [self.start, self.end]
-
-
 class Point(Base, speckle_type=GEOMETRY + "Point"):
     x: float = 0.0
     y: float = 0.0
     z: float = 0.0
 
     def __repr__(self) -> str:
-        return f"{self.__class__.__name__}(x: {self.x}, y: {self.y}, z: {self.z}, id: {self.id}, speckle_type: {self.speckle_type})"
+        return (
+            f"{self.__class__.__name__}(x: {self.x}, y: {self.y}, z: {self.z}, id:"
+            f" {self.id}, speckle_type: {self.speckle_type})"
+        )
 
     @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"""
+        """
+        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]:
@@ -47,12 +39,50 @@ class Point(Base, speckle_type=GEOMETRY + "Point"):
         return pt
 
 
-class Vector(Point, speckle_type=GEOMETRY + "Vector"):
-    pass
+class Pointcloud(
+    Base,
+    speckle_type=GEOMETRY + "Pointcloud",
+    chunkable={"points": 31250, "colors": 62500, "sizes": 62500},
+):
+    points: Optional[List[float]] = None
+    colors: Optional[List[int]] = None
+    sizes: Optional[List[float]] = None
+    bbox: Optional["Box"] = None
+
+
+class Vector(Base, speckle_type=GEOMETRY + "Vector"):
+    x: float = 0.0
+    y: float = 0.0
+    z: float = 0.0
+    applicationId: Optional[str] = None
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__} "
+            "(x: {self.x}, y: {self.y}, z: {self.z}, id: {self.id}, "
+            "speckle_type: {self.speckle_type})"
+        )
+
+    @classmethod
+    def from_list(cls, args: List[float]) -> "Vector":
+        """
+        Create 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[float]:
+        return [self.x, self.y, self.z]
+
+    @classmethod
+    def from_coords(cls, x: float = 0.0, y: float = 0.0, z: float = 0.0) -> "Vector":
+        """Create a new Point from x, y, and z values"""
+        v = Vector()
+        v.x, v.y, v.z = x, y, z
+        return v
 
 
 class ControlPoint(Point, speckle_type=GEOMETRY + "ControlPoint"):
-    weight: float = None
+    weight: Optional[float] = None
 
 
 class Plane(Base, speckle_type=GEOMETRY + "Plane"):
@@ -77,25 +107,25 @@ class Plane(Base, speckle_type=GEOMETRY + "Plane"):
             *self.normal.to_list(),
             *self.xdir.to_list(),
             *self.ydir.to_list(),
-            get_encoding_from_units(self.units),
+            get_encoding_from_units(self._units),
         ]
 
 
 class Box(Base, speckle_type=GEOMETRY + "Box"):
     basePlane: Plane = Plane()
+    xSize: Interval = Interval()
     ySize: Interval = Interval()
     zSize: Interval = Interval()
-    xSize: Interval = Interval()
-    area: float = None
-    volume: float = None
+    area: Optional[float] = None
+    volume: Optional[float] = None
 
 
 class Line(Base, speckle_type=GEOMETRY + "Line"):
     start: Point = Point()
-    end: Point = None
-    domain: Interval = None
-    bbox: Box = None
-    length: float = None
+    end: Optional[Point] = None
+    domain: Optional[Interval] = None
+    bbox: Optional[Box] = None
+    length: Optional[float] = None
 
     @classmethod
     def from_list(cls, args: List[Any]) -> "Line":
@@ -113,23 +143,23 @@ class Line(Base, speckle_type=GEOMETRY + "Line"):
             *self.start.to_list(),
             *self.end.to_list(),
             *domain,
-            get_encoding_from_units(self.units),
+            get_encoding_from_units(self._units),
         ]
 
 
 class Arc(Base, speckle_type=GEOMETRY + "Arc"):
-    radius: float = None
-    startAngle: float = None
-    endAngle: float = None
-    angleRadians: float = None
-    plane: Plane = None
-    domain: Interval = None
-    startPoint: Point = None
-    midPoint: Point = None
-    endPoint: Point = None
-    bbox: Box = None
-    area: float = None
-    length: float = None
+    radius: Optional[float] = None
+    startAngle: Optional[float] = None
+    endAngle: Optional[float] = None
+    angleRadians: Optional[float] = None
+    plane: Optional[Plane] = None
+    domain: Optional[Interval] = None
+    startPoint: Optional[Point] = None
+    midPoint: Optional[Point] = None
+    endPoint: Optional[Point] = None
+    bbox: Optional[Box] = None
+    area: Optional[float] = None
+    length: Optional[float] = None
 
     @classmethod
     def from_list(cls, args: List[Any]) -> "Arc":
@@ -158,17 +188,17 @@ class Arc(Base, speckle_type=GEOMETRY + "Arc"):
             *self.startPoint.to_list(),
             *self.midPoint.to_list(),
             *self.endPoint.to_list(),
-            get_encoding_from_units(self.units),
+            get_encoding_from_units(self._units),
         ]
 
 
 class Circle(Base, speckle_type=GEOMETRY + "Circle"):
-    radius: float = None
-    plane: Plane = None
-    domain: Interval = None
-    bbox: Box = None
-    area: float = None
-    length: float = None
+    radius: Optional[float] = None
+    plane: Optional[Plane] = None
+    domain: Optional[Interval] = None
+    bbox: Optional[Box] = None
+    area: Optional[float] = None
+    length: Optional[float] = None
 
     @classmethod
     def from_list(cls, args: List[Any]) -> "Circle":
@@ -185,19 +215,19 @@ class Circle(Base, speckle_type=GEOMETRY + "Circle"):
             self.radius,
             *self.domain.to_list(),
             *self.plane.to_list(),
-            get_encoding_from_units(self.units),
+            get_encoding_from_units(self._units),
         ]
 
 
 class Ellipse(Base, speckle_type=GEOMETRY + "Ellipse"):
-    firstRadius: float = None
-    secondRadius: float = None
-    plane: Plane = None
-    domain: Interval = None
-    trimDomain: Interval = None
-    bbox: Box = None
-    area: float = None
-    length: float = None
+    firstRadius: Optional[float] = None
+    secondRadius: Optional[float] = None
+    plane: Optional[Plane] = None
+    domain: Optional[Interval] = None
+    trimDomain: Optional[Interval] = None
+    bbox: Optional[Box] = None
+    area: Optional[float] = None
+    length: Optional[float] = None
 
     @classmethod
     def from_list(cls, args: List[Any]) -> "Ellipse":
@@ -216,17 +246,17 @@ class Ellipse(Base, speckle_type=GEOMETRY + "Ellipse"):
             self.secondRadius,
             *self.domain.to_list(),
             *self.plane.to_list(),
-            get_encoding_from_units(self.units),
+            get_encoding_from_units(self._units),
         ]
 
 
 class Polyline(Base, speckle_type=GEOMETRY + "Polyline", chunkable={"value": 20000}):
-    value: List[float] = None
-    closed: bool = None
-    domain: Interval = None
-    bbox: Box = None
-    area: float = None
-    length: float = None
+    value: Optional[List[float]] = None
+    closed: Optional[bool] = None
+    domain: Optional[Interval] = None
+    bbox: Optional[Box] = None
+    area: Optional[float] = None
+    length: Optional[float] = None
 
     @classmethod
     def from_points(cls, points: List[Point]):
@@ -255,7 +285,7 @@ class Polyline(Base, speckle_type=GEOMETRY + "Polyline", chunkable={"value": 200
             *self.domain.to_list(),
             len(self.value),
             *self.value,
-            get_encoding_from_units(self.units),
+            get_encoding_from_units(self._units),
         ]
 
     def as_points(self) -> List[Point]:
@@ -272,23 +302,50 @@ class Polyline(Base, speckle_type=GEOMETRY + "Polyline", chunkable={"value": 200
         ]
 
 
+class SpiralType(Enum):
+    Biquadratic = (0,)
+    BiquadraticParabola = (1,)
+    Bloss = (2,)
+    Clothoid = (3,)
+    Cosine = (4,)
+    Cubic = (5,)
+    CubicParabola = (6,)
+    Radioid = (7,)
+    Sinusoid = (8,)
+    Unknown = 9
+
+
+class Spiral(Base, speckle_type=GEOMETRY + "Spiral", detachable={"displayValue"}):
+    startPoint: Optional[Point] = None
+    endPoint: Optional[Point]
+    plane: Optional[Plane]
+    turns: Optional[float]
+    pitchAxis: Optional[Vector] = Vector()
+    pitch: float = 0
+    spiralType: Optional[SpiralType] = None
+    displayValue: Optional[Polyline] = None
+    bbox: Optional[Box] = None
+    length: Optional[float] = None
+    domain: Optional[Interval] = None
+
+
 class Curve(
     Base,
     speckle_type=GEOMETRY + "Curve",
     chunkable={"points": 20000, "weights": 20000, "knots": 20000},
 ):
-    degree: int = None
-    periodic: bool = None
-    rational: bool = None
-    points: List[float] = None
-    weights: List[float] = None
-    knots: List[float] = None
-    domain: Interval = None
-    displayValue: Polyline = None
-    closed: bool = None
-    bbox: Box = None
-    area: float = None
-    length: float = None
+    degree: Optional[int] = None
+    periodic: Optional[bool] = None
+    rational: Optional[bool] = None
+    points: Optional[List[float]] = None
+    weights: Optional[List[float]] = None
+    knots: Optional[List[float]] = None
+    domain: Optional[Interval] = None
+    displayValue: Optional[Polyline] = None
+    closed: Optional[bool] = None
+    bbox: Optional[Box] = None
+    area: Optional[float] = None
+    length: Optional[float] = None
 
     def as_points(self) -> List[Point]:
         """Converts the `value` attribute to a list of Points"""
@@ -340,17 +397,17 @@ class Curve(
             *self.points,
             *self.weights,
             *self.knots,
-            get_encoding_from_units(self.units),
+            get_encoding_from_units(self._units),
         ]
 
 
 class Polycurve(Base, speckle_type=GEOMETRY + "Polycurve"):
-    segments: List[Base] = None
-    domain: Interval = None
-    closed: bool = None
-    bbox: Box = None
-    area: float = None
-    length: float = None
+    segments: Optional[List[Base]] = None
+    domain: Optional[Interval] = None
+    closed: Optional[bool] = None
+    bbox: Optional[Box] = None
+    area: Optional[float] = None
+    length: Optional[float] = None
 
     @classmethod
     def from_list(cls, args: List[Any]) -> "Polycurve":
@@ -370,22 +427,22 @@ class Polycurve(Base, speckle_type=GEOMETRY + "Polycurve"):
             *self.domain.to_list(),
             len(curve_array),
             *curve_array,
-            get_encoding_from_units(self.units),
+            get_encoding_from_units(self._units),
         ]
 
 
 class Extrusion(Base, speckle_type=GEOMETRY + "Extrusion"):
-    capped: bool = None
-    profile: Base = None
-    pathStart: Point = None
-    pathEnd: Point = None
-    pathCurve: Base = None
-    pathTangent: Base = None
-    profiles: List[Base] = None
-    length: float = None
-    area: float = None
-    volume: float = None
-    bbox: Box = None
+    capped: Optional[bool] = None
+    profile: Optional[Base] = None
+    pathStart: Optional[Point] = None
+    pathEnd: Optional[Point] = None
+    pathCurve: Optional[Base] = None
+    pathTangent: Optional[Base] = None
+    profiles: Optional[List[Base]] = None
+    length: Optional[float] = None
+    area: Optional[float] = None
+    volume: Optional[float] = None
+    bbox: Optional[Box] = None
 
 
 class Mesh(
@@ -398,21 +455,21 @@ class Mesh(
         "textureCoordinates": 2000,
     },
 ):
-    vertices: List[float] = None
-    faces: List[int] = None
-    colors: List[int] = None
-    textureCoordinates: List[float] = None
-    bbox: Box = None
-    area: float = None
-    volume: float = None
+    vertices: Optional[List[float]] = None
+    faces: Optional[List[int]] = None
+    colors: Optional[List[int]] = None
+    textureCoordinates: Optional[List[float]] = None
+    bbox: Optional[Box] = None
+    area: Optional[float] = None
+    volume: Optional[float] = None
 
     @classmethod
     def create(
         cls,
         vertices: List[float],
         faces: List[int],
-        colors: List[int] = None,
-        texture_coordinates: List[float] = None,
+        colors: Optional[List[int]] = None,
+        texture_coordinates: Optional[List[float]] = None,
     ) -> "Mesh":
         """
         Create a new Mesh from lists representing its vertices, faces,
@@ -430,20 +487,20 @@ class Mesh(
 
 
 class Surface(Base, speckle_type=GEOMETRY + "Surface"):
-    degreeU: int = None
-    degreeV: int = None
-    rational: bool = None
-    area: float = None
-    pointData: List[float] = None
-    countU: int = None
-    countV: int = None
-    bbox: Box = None
-    closedU: bool = None
-    closedV: bool = None
-    domainU: Interval = None
-    domainV: Interval = None
-    knotsU: List[float] = None
-    knotsV: List[float] = None
+    degreeU: Optional[int] = None
+    degreeV: Optional[int] = None
+    rational: Optional[bool] = None
+    area: Optional[float] = None
+    pointData: Optional[List[float]] = None
+    countU: Optional[int] = None
+    countV: Optional[int] = None
+    bbox: Optional[Box] = None
+    closedU: Optional[bool] = None
+    closedV: Optional[bool] = None
+    domainU: Optional[Interval] = None
+    domainV: Optional[Interval] = None
+    knotsU: Optional[List[float]] = None
+    knotsV: Optional[List[float]] = None
 
     @classmethod
     def from_list(cls, args: List[Any]) -> "Surface":
@@ -488,16 +545,16 @@ class Surface(Base, speckle_type=GEOMETRY + "Surface"):
             *self.pointData,
             *self.knotsU,
             *self.knotsV,
-            get_encoding_from_units(self.units),
+            get_encoding_from_units(self._units),
         ]
 
 
 class BrepFace(Base, speckle_type=GEOMETRY + "BrepFace"):
-    _Brep: "Brep" = None
-    SurfaceIndex: int = None
-    OuterLoopIndex: int = None
-    OrientationReversed: bool = None
-    LoopIndices: List[int] = None
+    _Brep: Optional["Brep"] = None
+    SurfaceIndex: Optional[int] = None
+    OuterLoopIndex: Optional[int] = None
+    OrientationReversed: Optional[bool] = None
+    LoopIndices: Optional[List[int]] = None
 
     @property
     def _outer_loop(self):
@@ -533,13 +590,13 @@ class BrepFace(Base, speckle_type=GEOMETRY + "BrepFace"):
 
 
 class BrepEdge(Base, speckle_type=GEOMETRY + "BrepEdge"):
-    _Brep: "Brep" = None
-    Curve3dIndex: int = None
-    TrimIndices: List[int] = None
-    StartIndex: int = None
-    EndIndex: int = None
-    ProxyCurveIsReversed: bool = None
-    Domain: Interval = None
+    _Brep: Optional["Brep"] = None
+    Curve3dIndex: Optional[int] = None
+    TrimIndices: Optional[List[int]] = None
+    StartIndex: Optional[int] = None
+    EndIndex: Optional[int] = None
+    ProxyCurveIsReversed: Optional[bool] = None
+    Domain: Optional[Interval] = None
 
     @property
     def _start_vertex(self):
@@ -590,7 +647,6 @@ class BrepEdge(Base, speckle_type=GEOMETRY + "BrepEdge"):
         ]
 
 
-
 class BrepLoopType(int, Enum):
     Unknown = 0
     Outer = 1
@@ -601,10 +657,10 @@ class BrepLoopType(int, Enum):
 
 
 class BrepLoop(Base, speckle_type=GEOMETRY + "BrepLoop"):
-    _Brep: "Brep" = None
-    FaceIndex: int = None
-    TrimIndices: List[int] = None
-    Type: BrepLoopType = None
+    _Brep: Optional["Brep"] = None
+    FaceIndex: Optional[Optional[int]] = None
+    TrimIndices: Optional[List[int]] = None
+    Type: Optional[BrepLoopType] = None
 
     @property
     def _face(self):
@@ -645,17 +701,17 @@ class BrepTrimType(int, Enum):
 
 
 class BrepTrim(Base, speckle_type=GEOMETRY + "BrepTrim"):
-    _Brep: "Brep" = None
-    EdgeIndex: int = None
-    StartIndex: int = None
-    EndIndex: int = None
-    FaceIndex: int = None
-    LoopIndex: int = None
-    CurveIndex: int = None
-    IsoStatus: int = None
-    TrimType: BrepTrimType = None
-    IsReversed: bool = None
-    Domain: Interval = None
+    _Brep: Optional["Brep"] = None
+    EdgeIndex: Optional[int] = None
+    StartIndex: Optional[int] = None
+    EndIndex: Optional[int] = None
+    FaceIndex: Optional[int] = None
+    LoopIndex: Optional[int] = None
+    CurveIndex: Optional[int] = None
+    IsoStatus: Optional[int] = None
+    TrimType: Optional[BrepTrimType] = None
+    IsReversed: Optional[bool] = None
+    Domain: Optional[Interval] = None
 
     @property
     def _face(self):
@@ -732,21 +788,21 @@ class Brep(
         "Faces",
     },
 ):
-    provenance: str = None
-    bbox: Box = None
-    area: float = None
-    volume: float = None
-    _displayValue: List[Mesh] = None
-    Surfaces: List[Surface] = None
-    Curve3D: List[Base] = None
-    Curve2D: List[Base] = None
-    Vertices: List[Point] = None
-    Edges: List[BrepEdge] = None
-    Loops: List[BrepLoop] = None
-    Faces: List[BrepFace] = None
-    Trims: List[BrepTrim] = None
-    IsClosed: bool = None
-    Orientation: int = None
+    provenance: Optional[str] = None
+    bbox: Optional[Box] = None
+    area: Optional[float] = None
+    volume: Optional[float] = None
+    _displayValue: Optional[List[Mesh]] = None
+    Surfaces: Optional[List[Surface]] = None
+    Curve3D: Optional[List[Base]] = None
+    Curve2D: Optional[List[Base]] = None
+    Vertices: Optional[List[Point]] = None
+    Edges: Optional[List[BrepEdge]] = None
+    Loops: Optional[List[BrepLoop]] = None
+    Faces: Optional[List[BrepFace]] = None
+    Trims: Optional[List[BrepTrim]] = None
+    IsClosed: Optional[bool] = None
+    Orientation: Optional[int] = None
 
     def _inject_self_into_children(self, children: Optional[List[Base]]) -> List[Base]:
         if children is None:
@@ -857,7 +913,7 @@ class Brep(
 
         for i in range(0, len(value), 3):
             vertex = Point.from_list(value[i : i + 3])
-            vertex._units = units
+            vertex.units = units
             vertices.append(vertex)
 
         self.Vertices = vertices

src/specklepy/objects/graph_traversal/commit_object_builder.py

@@ -0,0 +1,83 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Collection, Dict, Generic, Iterable, List, Optional, Tuple, TypeVar
+from attrs import define
+from specklepy.objects.base import Base
+
+ROOT: str = "__Root"
+
+T = TypeVar('T')
+PARENT_INFO = Tuple[Optional[str], str]
+
+@define(slots=True)
+class CommitObjectBuilder(ABC, Generic[T]):
+
+    converted: Dict[str, Base]
+    _parent_infos: Dict[str, Collection[PARENT_INFO]]
+
+    def __init__(self) -> None:
+        self.converted = {}
+        self._parent_infos = {}
+    
+    @abstractmethod
+    def include_object(self, conversion_result: Base, native_object: T) -> None:
+        pass
+
+    def build_commit_object(self, root_commit_object: Base) -> None:
+        self.apply_relationships(self.converted.values(), root_commit_object)
+
+    def set_relationship(self, app_id: Optional[str], *parent_info : PARENT_INFO) -> None:
+
+        if not app_id:
+            return
+        
+        self._parent_infos[app_id] = parent_info
+
+    def apply_relationships(self, to_add: Iterable[Base], root_commit_object: Base) -> None:
+        for c in to_add:
+            try:
+                self.apply_relationship(c, root_commit_object)
+            except Exception as ex:
+                print(f"Failed to add object {type(c)} to commit object: {ex}")
+
+    def apply_relationship(self, current: Base, root_commit_object: Base):
+        if not current.applicationId: raise Exception(f"Expected applicationId to have been set") 
+        
+        parents = self._parent_infos[current.applicationId]
+        
+        for (parent_id, prop_name) in parents:
+            if not parent_id: continue
+
+            parent: Optional[Base]
+            if parent_id == ROOT:
+                parent = root_commit_object
+            else:
+                parent = self.converted[parent_id] if parent_id in self.converted else None
+            
+            if not parent: continue
+
+            try:
+                elements = get_detached_prop(parent, prop_name)
+                if not isinstance(elements, list):
+                    elements = []
+                    set_detached_prop(parent, prop_name, elements)
+
+                elements.append(current)
+                return
+            except Exception as ex:
+                # A parent was found, but it was invalid (Likely because of a type mismatch on a `elements` property)
+                print(f"Failed to add object {type(current)} to a converted parent; {ex}")
+                
+            raise Exception(f"Could not find a valid parent for object of type {type(current)}. Checked {len(parents)} potential parent, and non were converted!")
+
+
+def get_detached_prop(speckle_object: Base, prop_name: str) -> Optional[Any]:
+    detached_prop_name = get_detached_prop_name(speckle_object, prop_name)
+    return getattr(speckle_object, detached_prop_name, None)
+
+def set_detached_prop(speckle_object: Base, prop_name: str, value: Optional[Any]) -> None:
+    detached_prop_name = get_detached_prop_name(speckle_object, prop_name)
+    setattr(speckle_object, detached_prop_name, value)
+
+def get_detached_prop_name(speckle_object: Base, prop_name: str) -> str:
+    return prop_name if hasattr(speckle_object, prop_name) else f"@{prop_name}"

src/specklepy/objects/graph_traversal/traversal.py

@@ -0,0 +1,123 @@
+from typing import Any, Callable, Collection, Iterable, Iterator, List, Optional, Set
+
+from attrs import define
+from typing_extensions import Protocol, final
+
+from specklepy.objects import Base
+
+
+class ITraversalRule(Protocol):
+    def get_members_to_traverse(self, o: Base) -> Set[str]:
+        """Get the members to traverse."""
+        pass
+
+    def does_rule_hold(self, o: Base) -> bool:
+        """Make sure the rule still holds."""
+        pass
+
+
+@final
+@define(slots=True, frozen=True)
+class DefaultRule:
+    def get_members_to_traverse(self, _) -> Set[str]:
+        return set()
+
+    def does_rule_hold(self, _) -> bool:
+        return True
+
+
+# we're creating a local protected "singleton"
+_default_rule = DefaultRule()
+
+
+@final
+@define(slots=True, frozen=True)
+class TraversalContext:
+    current: Base
+    member_name: Optional[str] = None
+    parent: Optional["TraversalContext"] = None
+
+
+@final
+@define(slots=True, frozen=True)
+class GraphTraversal:
+
+    _rules: List[ITraversalRule]
+
+    def traverse(self, root: Base) -> Iterator[TraversalContext]:
+        stack: List[TraversalContext] = []
+
+        stack.append(TraversalContext(root))
+
+        while len(stack) > 0:
+            head = stack.pop()
+            yield head
+
+            current = head.current
+            active_rule = self._get_active_rule_or_default_rule(current)
+            members_to_traverse = active_rule.get_members_to_traverse(current)
+            for child_prop in members_to_traverse:
+                try:
+                    if child_prop in {"speckle_type", "units", "applicationId"}: continue #debug: to avoid noisy exceptions, explicitly avoid checking ones we know will fail, this is not exhaustive
+                    if getattr(current, child_prop, None):
+                        value = current[child_prop]
+                        self._traverse_member_to_stack(
+                            stack, value, child_prop, head
+                        )
+                except KeyError as ex:
+                    # Unset application ids, and class variables like SpeckleType will throw when __getitem__ is called
+                    pass
+    @staticmethod
+    def _traverse_member_to_stack(
+        stack: List[TraversalContext],
+        value: Any,
+        member_name: Optional[str] = None,
+        parent: Optional[TraversalContext] = None,
+    ):
+        if isinstance(value, Base):
+            stack.append(TraversalContext(value, member_name, parent))
+        elif isinstance(value, list):
+            for obj in value:
+                GraphTraversal._traverse_member_to_stack(stack, obj, member_name, parent)
+        elif isinstance(value, dict):
+            for obj in value.values():
+                GraphTraversal._traverse_member_to_stack(stack, obj, member_name, parent)
+
+    @staticmethod
+    def traverse_member(value: Optional[Any]) -> Iterator[Base]:
+        if isinstance(value, Base):
+            yield value
+        elif isinstance(value, list):
+            for obj in value:
+                for o in GraphTraversal.traverse_member(obj):
+                    yield o
+        elif isinstance(value, dict):
+            for obj in value.values():
+                for o in GraphTraversal.traverse_member(obj):
+                    yield o
+
+
+    def _get_active_rule_or_default_rule(self, o: Base) -> ITraversalRule:
+        return self._get_active_rule(o) or _default_rule
+
+    def _get_active_rule(self, o: Base) -> Optional[ITraversalRule]:
+        for rule in self._rules:
+            if rule.does_rule_hold(o):
+                return rule
+        return None
+
+
+@final
+@define(slots=True, frozen=True)
+class TraversalRule:
+    _conditions: Collection[Callable[[Base], bool]]
+    _members_to_traverse: Callable[[Base], Iterable[str]]
+
+    def get_members_to_traverse(self, o: Base) -> Set[str]:
+        return set(self._members_to_traverse(o))
+
+    def does_rule_hold(self, o: Base) -> bool:
+        for condition in self._conditions:
+            if condition(o):
+                return True
+        return False

src/specklepy/objects/other.py

@@ -1,8 +1,12 @@
-from typing import Any, List
-from specklepy.objects.geometry import Point, Vector
+from typing import Any, List, Optional
+from deprecated import deprecated
+
+from specklepy.objects.geometry import Point, Vector, Plane, Polyline
+
 from .base import Base
 
 OTHER = "Objects.Other."
+OTHER_REVIT = OTHER + "Revit."
 
 IDENTITY_TRANSFORM = [
     1.0,
@@ -24,8 +28,23 @@ IDENTITY_TRANSFORM = [
 ]
 
 
+class Material(Base, speckle_type=OTHER + "Material"):
+    """Generic class for materials containing generic parameters."""
+
+    name: Optional[str] = None
+
+
+class RevitMaterial(Material, speckle_type="Objects.Other.Revit." + "RevitMaterial"):
+    materialCategory: Optional[str] = None
+    materialClass: Optional[str] = None
+    shininess: Optional[int] = None
+    smoothness: Optional[int] = None
+    transparency: Optional[int] = None
+    parameters: Optional[Base] = None
+
+
 class RenderMaterial(Base, speckle_type=OTHER + "RenderMaterial"):
-    name: str = None
+    name: Optional[str] = None
     opacity: float = 1
     metalness: float = 0
     roughness: float = 1
@@ -33,36 +52,79 @@ class RenderMaterial(Base, speckle_type=OTHER + "RenderMaterial"):
     emissive: int = -16777216  # black arbg
 
 
+class MaterialQuantity(Base, speckle_type=OTHER + "MaterialQuantity"):
+    material: Optional[Material] = None
+    volume: Optional[float] = None
+    area: Optional[float] = None
+
+
+class DisplayStyle(Base, speckle_type=OTHER + "DisplayStyle"):
+    """
+    Minimal display style class.
+    Developed primarily for display styles in Rhino and AutoCAD.
+    Rhino object attributes uses OpenNURBS definition for linetypes and lineweights.
+    """
+
+    name: Optional[str] = None
+    color: int = -2894893  # light gray arbg
+    linetype: Optional[str] = None
+    lineweight: float = 0
+
+
+class Text(Base, speckle_type=OTHER + "Text"):
+    """
+    Text object to render it on viewer.
+    """
+    plane: Plane
+    value: str
+    height: float
+    rotation: float
+    displayValue: Optional[List[Polyline]] = None
+    richText: Optional[str] = None
+
+
 class Transform(
     Base,
     speckle_type=OTHER + "Transform",
-    serialize_ignore={"translation", "scaling", "is_identity"},
+    serialize_ignore={"translation", "scaling", "is_identity", "value"},
 ):
     """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).
+    The 4th column defines translation,
+    where the last value is a divisor (usually equal to 1).
     """
 
-    _value: List[float] = None
+    _value: Optional[List[float]] = None
 
     @property
+    @deprecated(version="2.12", reason="Use matrix")
     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:
+        self.matrix = value
+
+    @property
+    def matrix(self) -> List[float]:
+        """The transform matrix represented as a flat list of 16 floats"""
+        return self._value
+
+    @matrix.setter
+    def matrix(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}"
+                "Could not create a Transform object with the requested value. Input"
+                f" 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"
+                "Could not create a Transform object: input list should be 16 floats"
+                f" long, but was {len(value)} long"
             )
 
         self._value = value
@@ -79,7 +141,7 @@ class Transform(
 
     @property
     def is_identity(self) -> bool:
-        return self.value == IDENTITY_TRANSFORM
+        return self._value == IDENTITY_TRANSFORM
 
     def apply_to_point(self, point: Point) -> Point:
         """Transform a single speckle Point
@@ -127,14 +189,16 @@ class Transform(
         """Transform a list of speckle Points
 
         Arguments:
-            points {List[float]} -- a flat list of floats representing points to transform
+            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"
+                "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):
@@ -171,11 +235,13 @@ class Transform(
         ][: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.
+    def from_list(cls, value: Optional[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)
+            value {List[float]} -- the matrix as a flat list of 16 numbers
+            (defaults to the identity transform)
 
         Returns:
             Transform -- a complete transform object
@@ -188,27 +254,57 @@ class Transform(
 class BlockDefinition(
     Base, speckle_type=OTHER + "BlockDefinition", detachable={"geometry"}
 ):
-    name: str = None
-    basePoint: Point = None
-    geometry: List[Base] = None
+    name: Optional[str] = None
+    basePoint: Optional[Point] = None
+    geometry: Optional[List[Base]] = None
+
+
+class Instance(
+    Base, speckle_type=OTHER + "Instance", detachable={"definition"}
+):
+    transform: Optional[Transform] = None
+    definition: Optional[Base] = None
 
 
 class BlockInstance(
-    Base, speckle_type=OTHER + "BlockInstance", detachable={"blockDefinition"}
+    Instance, speckle_type=OTHER + "BlockInstance", serialize_ignore={"blockDefinition"}
 ):
-    blockDefinition: BlockDefinition = None
-    transform: Transform = None
+    @property
+    @deprecated(version="2.13", reason="Use definition")
+    def blockDefinition(self) -> Optional[BlockDefinition]:
+        if isinstance(self.definition, BlockDefinition):
+            return self.definition
+        return None
 
+    @blockDefinition.setter
+    def blockDefinition(self, value: Optional[BlockDefinition]) -> None:
+        self.definition = value
+
+class RevitInstance(Instance, speckle_type=OTHER_REVIT + "RevitInstance"):
+    level: Optional[Base]  = None
+    facingFlipped: bool
+    handFlipped: bool
+    parameters: Optional[Base]  = None
+    elementId: Optional[str]
 
 # 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
+class RevitParameter(
+    Base, speckle_type="Objects.BuiltElements.Revit.Parameter"
+):
+    name: Optional[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
-    )
+    applicationUnitType: Optional[str] = None  # eg UnitType UT_Length
+    applicationUnit: Optional[str] = None  # DisplayUnitType eg DUT_MILLIMITERS
+    applicationInternalName: Optional[
+        str
+    ] = None  # BuiltInParameterName or GUID for shared parameter
     isShared: bool = False
     isReadOnly: bool = False
     isTypeParameter: bool = False
+
+class Collection(
+    Base, speckle_type="Speckle.Core.Models.Collection", detachable={"elements"}
+):
+    name: Optional[str] = None
+    collectionType: Optional[str] = None
+    elements: Optional[List[Base]] = None

src/specklepy/objects/primitive.py

@@ -0,0 +1,25 @@
+from typing import Any, List
+
+from specklepy.objects.base import Base
+
+NAMESPACE = "Objects.Primitive"
+
+
+class Interval(Base, speckle_type=f"{NAMESPACE}.Interval"):
+    start: float = 0.0
+    end: float = 0.0
+
+    def length(self):
+        return abs(self.start - self.end)
+
+    @classmethod
+    def from_list(cls, args: List[Any]) -> "Interval":
+        return cls(start=args[0], end=args[1])
+
+    def to_list(self) -> List[Any]:
+        return [self.start, self.end]
+
+
+class Interval2d(Base, speckle_type=f"{NAMESPACE}.Interval2d"):
+    u: Interval
+    v: Interval

src/specklepy/objects/structural/__init__.py

@@ -0,0 +1,145 @@
+"""Builtin Speckle object kit."""
+
+from specklepy.objects.structural.analysis import (
+    Model,
+    ModelInfo,
+    ModelSettings,
+    ModelUnits,
+)
+from specklepy.objects.structural.axis import (
+    AxisType,
+    Axis
+)
+from specklepy.objects.structural.geometry import (
+    Element1D,
+    Element2D,
+    Element3D,
+    ElementType1D,
+    ElementType2D,
+    ElementType3D,
+    Node,
+    Restraint,
+)
+from specklepy.objects.structural.loading import (
+    ActionType,
+    BeamLoadType,
+    CombinationType,
+    FaceLoadType,
+    Load,
+    LoadAxisType,
+    LoadBeam,
+    LoadCase,
+    LoadCombinations,
+    LoadDirection,
+    LoadDirection2D,
+    LoadFace,
+    LoadGravity,
+    LoadNode,
+    LoadType,
+)
+from specklepy.objects.structural.materials import (
+    Concrete,
+    MaterialType,
+    Steel,
+    StructuralMaterial,
+    Timber,
+)
+from specklepy.objects.structural.properties import (
+    BaseReferencePoint,
+    MemberType,
+    Property,
+    Property1D,
+    Property2D,
+    Property3D,
+    PropertyDamper,
+    PropertyMass,
+    PropertySpring,
+    PropertyType2D,
+    PropertyType3D,
+    PropertyTypeDamper,
+    PropertyTypeSpring,
+    ReferenceSurface,
+    ReferenceSurfaceEnum,
+    SectionProfile,
+    ShapeType,
+    shapeType,
+)
+from specklepy.objects.structural.results import (
+    Result,
+    Result1D,
+    Result2D,
+    Result3D,
+    ResultGlobal,
+    ResultNode,
+    ResultSet1D,
+    ResultSet2D,
+    ResultSet3D,
+    ResultSetAll,
+    ResultSetNode,
+)
+
+__all__ = [
+    "Element1D",
+    "Element2D",
+    "Element3D",
+    "ElementType1D",
+    "ElementType2D",
+    "ElementType3D",
+    "AxisType",
+    "Axis",
+    "Node",
+    "Restraint",
+    "Load",
+    "LoadType",
+    "ActionType",
+    "BeamLoadType",
+    "FaceLoadType",
+    "LoadDirection",
+    "LoadDirection2D",
+    "LoadAxisType",
+    "CombinationType",
+    "LoadBeam",
+    "LoadCase",
+    "LoadCombinations",
+    "LoadFace",
+    "LoadGravity",
+    "LoadNode",
+    "Model",
+    "ModelInfo",
+    "ModelSettings",
+    "ModelUnits",
+    "MaterialType",
+    "Concrete",
+    "StructuralMaterial",
+    "Steel",
+    "Timber",
+    "Property",
+    "Property1D",
+    "Property2D",
+    "Property3D",
+    "PropertyDamper",
+    "PropertyMass",
+    "PropertySpring",
+    "SectionProfile",
+    "MemberType",
+    "BaseReferencePoint",
+    "ReferenceSurface",
+    "PropertyType2D",
+    "PropertyType3D",
+    "ShapeType",
+    "PropertyTypeSpring",
+    "PropertyTypeDamper",
+    "ReferenceSurfaceEnum",
+    "shapeType",
+    "Result",
+    "Result1D",
+    "ResultSet1D",
+    "Result2D",
+    "ResultSet2D",
+    "Result3D",
+    "ResultSet3D",
+    "ResultGlobal",
+    "ResultSetNode",
+    "ResultNode",
+    "ResultSetAll",
+]

src/specklepy/objects/structural/analysis.py

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

src/specklepy/objects/structural/axis.py

@@ -0,0 +1,17 @@
+from typing import Optional
+from enum import Enum
+
+from specklepy.objects.base import Base
+from specklepy.objects.geometry import Plane
+
+
+class AxisType(int, Enum):
+    Cartesian = 0
+    Cylindrical = 1
+    Spherical = 2
+
+
+class Axis(Base, speckle_type="Objects.Structural.Geometry.Axis"):
+    name: Optional[str] = None
+    axisType: Optional[AxisType] = None
+    plane: Optional[Plane] = None

src/specklepy/objects/structural/geometry.py

@@ -0,0 +1,110 @@
+from enum import Enum
+from typing import List, Optional
+
+from specklepy.objects.base import Base
+from specklepy.objects.geometry import Line, Mesh, Plane, Point, Vector
+from specklepy.objects.structural.axis import Axis
+from specklepy.objects.structural.properties import (
+    Property1D,
+    Property2D,
+    Property3D,
+    PropertyDamper,
+    PropertyMass,
+    PropertySpring,
+)
+
+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: Optional[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
+
+
+class Node(Base, speckle_type=STRUCTURAL_GEOMETRY + ".Node"):
+    name: Optional[str] = None
+    basePoint: Optional[Point] = None
+    constraintAxis: Optional[Axis] = None
+    restraint: Optional[Restraint] = None
+    springProperty: Optional[PropertySpring] = None
+    massProperty: Optional[PropertyMass] = None
+    damperProperty: Optional[PropertyDamper] = None
+
+
+class Element1D(Base, speckle_type=STRUCTURAL_GEOMETRY + ".Element1D"):
+    name: Optional[str] = None
+    baseLine: Optional[Line] = None
+    property: Optional[Property1D] = None
+    type: Optional[ElementType1D] = None
+    end1Releases: Optional[Restraint] = None
+    end2Releases: Optional[Restraint] = None
+    end1Offset: Optional[Vector] = None
+    end2Offset: Optional[Vector] = None
+    orientationNode: Optional[Node] = None
+    orinetationAngle: float = 0.0
+    localAxis: Optional[Plane] = None
+    parent: Optional[Base] = None
+    end1Node: Optional[Node] = None
+    end2Node: Optional[Node] = None
+    topology: Optional[List] = None
+    displayMesh: Optional[Mesh] = None
+
+
+class Element2D(Base, speckle_type=STRUCTURAL_GEOMETRY + ".Element2D"):
+    name: Optional[str] = None
+    property: Optional[Property2D] = None
+    type: Optional[ElementType2D] = None
+    offset: float = 0.0
+    orientationAngle: float = 0.0
+    parent: Optional[Base] = None
+    topology: Optional[List] = None
+    displayMesh: Optional[Mesh] = None
+
+
+class Element3D(Base, speckle_type=STRUCTURAL_GEOMETRY + ".Element3D"):
+    name: Optional[str] = None
+    baseMesh: Optional[Mesh] = None
+    property: Optional[Property3D] = None
+    type: Optional[ElementType3D] = None
+    orientationAngle: float = 0.0
+    parent: Optional[Base] = None
+    topology: List
+
+
+# class Storey needs ependency on built elements first

src/specklepy/objects/structural/loading.py

@@ -1,14 +1,14 @@
 from enum import Enum
-from typing import List
+from typing import List, Optional
 
-from ..base import Base
-from .geometry import *
+from specklepy.objects.base import Base
+from specklepy.objects.geometry import Vector
+from specklepy.objects.structural.axis import Axis
 
 STRUCTURAL_LOADING = "Objects.Structural.Loading."
 
 
 class LoadType(int, Enum):
-
     none = 0
     Dead = 1
     SuperDead = 2
@@ -31,7 +31,6 @@ class LoadType(int, Enum):
 
 
 class ActionType(int, Enum):
-
     none = 0
     Permanent = 1
     Variable = 2
@@ -39,7 +38,6 @@ class ActionType(int, Enum):
 
 
 class BeamLoadType(int, Enum):
-
     Point = 0
     Uniform = 1
     Linear = 2
@@ -48,21 +46,18 @@ class BeamLoadType(int, Enum):
 
 
 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
@@ -80,7 +75,6 @@ class LoadAxisType(int, Enum):
 
 
 class CombinationType(int, Enum):
-
     LinearAdd = 0
     Envelope = 1
     AbsoluteAdd = 2
@@ -89,56 +83,55 @@ class CombinationType(int, Enum):
 
 
 class LoadCase(Base, speckle_type=STRUCTURAL_LOADING + "LoadCase"):
-    name: str = None
-    loadType: LoadType = None
-    group: str = None
-    actionType: ActionType = None
-    description: str = None
+    name: Optional[str] = None
+    loadType: Optional[LoadType] = None
+    group: Optional[str] = None
+    actionType: Optional[ActionType] = None
+    description: Optional[str] = None
 
 
 class Load(Base, speckle_type=STRUCTURAL_LOADING + "Load"):
-    name: str = None
-    units: str = None
-    loadCase: LoadCase = None
+    name: Optional[str] = None
+    loadCase: Optional[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
+    elements: Optional[List] = None
+    loadType: Optional[BeamLoadType] = None
+    direction: Optional[LoadDirection] = None
+    loadAxis: Optional[Axis] = None
+    loadAxisType: Optional[LoadAxisType] = None
+    isProjected: Optional[bool] = None
+    values: Optional[List] = None
+    positions: Optional[List] = None
 
 
 class LoadCombinations(Base, speckle_type=STRUCTURAL_LOADING + "LoadCombination"):
-    name: str = None
+    name: Optional[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
+    elements: Optional[List] = None
+    loadType: Optional[FaceLoadType] = None
+    direction: Optional[LoadDirection2D] = None
+    loadAxis: Optional[Axis] = None
+    loadAxisType: Optional[LoadAxisType] = None
+    isProjected: Optional[bool] = None
+    values: Optional[List] = None
+    positions: Optional[List] = None
 
 
 class LoadGravity(Load, speckle_type=STRUCTURAL_LOADING + "LoadGravity"):
-    elements: List = None
-    nodes: List = None
-    gravityFactors: Vector = None
+    elements: Optional[List] = None
+    nodes: Optional[List] = None
+    gravityFactors: Optional[Vector] = None
 
 
 class LoadNode(Load, speckle_type=STRUCTURAL_LOADING + "LoadNode"):
-    nodes: List = None
-    loadAxis: Axis = None
-    direction: LoadDirection = None
+    nodes: Optional[List] = None
+    loadAxis: Optional[Axis] = None
+    direction: Optional[LoadDirection] = None
     value: float = 0.0

src/specklepy/objects/structural/materials.py

@@ -1,7 +1,7 @@
 from enum import Enum
+from typing import Optional
 
-from ..base import Base
-
+from specklepy.objects.base import Base
 
 STRUCTURAL_MATERIALS = "Objects.Structural.Materials"
 
@@ -21,12 +21,14 @@ class MaterialType(int, Enum):
     Other = 11
 
 
-class Material(Base, speckle_type=STRUCTURAL_MATERIALS):
-    name: str = None
-    grade: str = None
-    materialType: MaterialType = None
-    designCode: str = None
-    codeYear: str = None
+class StructuralMaterial(
+    Base, speckle_type=STRUCTURAL_MATERIALS + ".StructuralMaterial"
+):
+    name: Optional[str] = None
+    grade: Optional[str] = None
+    materialType: Optional[MaterialType] = None
+    designCode: Optional[str] = None
+    codeYear: Optional[str] = None
     strength: float = 0.0
     elasticModulus: float = 0.0
     poissonsRatio: float = 0.0
@@ -38,22 +40,22 @@ class Material(Base, speckle_type=STRUCTURAL_MATERIALS):
     materialSafetyFactor: float = 0.0
 
 
-class Concrete(Material, speckle_type=STRUCTURAL_MATERIALS + ".Concrete"):
+class Concrete(StructuralMaterial):
     compressiveStrength: float = 0.0
     tensileStrength: float = 0.0
     flexuralStrength: float = 0.0
-    maxCompressiveStrength: float = 0.0
-    maxTensileStrength: float = 0.0
+    maxCompressiveStrain: float = 0.0
+    maxTensileStrain: float = 0.0
     maxAggregateSize: float = 0.0
-    lightweight: bool = None
+    lightweight: Optional[bool] = None
 
 
-class Steel(Material, speckle_type=STRUCTURAL_MATERIALS + ".Steel"):
+class Steel(StructuralMaterial, 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
+class Timber(StructuralMaterial, speckle_type=STRUCTURAL_MATERIALS + ".Timber"):
+    species: Optional[str] = None

src/specklepy/objects/structural/properties.py

@@ -1,12 +1,11 @@
 from enum import Enum
+from typing import Optional
 
-from ..base import Base
+from specklepy.objects.base import Base
+from specklepy.objects.structural.axis import Axis
+from specklepy.objects.structural.materials import StructuralMaterial
 
-from .material import *
-from .axis import Axis
-
-
-STRUCTURAL_PROPERTY = "Objectives.Structural.Properties"
+STRUCTURAL_PROPERTY = "Objects.Structural.Properties"
 
 
 class MemberType(int, Enum):
@@ -39,7 +38,6 @@ class ReferenceSurface(int, Enum):
 
 
 class PropertyType2D(int, Enum):
-
     Stress = 0
     Fabric = 1
     Plate = 2
@@ -59,7 +57,7 @@ class PropertyType3D(int, Enum):
 class ShapeType(int, Enum):
     Rectangular = 0
     Circular = 1
-    I = 2
+    I = 2  # noqa: E741
     Tee = 3
     Angle = 4
     Channel = 5
@@ -67,6 +65,7 @@ class ShapeType(int, Enum):
     Box = 7
     Catalogue = 8
     Explicit = 9
+    Undefined = 10
 
 
 class PropertyTypeSpring(int, Enum):
@@ -89,36 +88,37 @@ class PropertyTypeDamper(int, Enum):
 
 
 class Property(Base, speckle_type=STRUCTURAL_PROPERTY):
-    name: str = None
+    name: Optional[str] = None
 
 
-class SectionProfile(Base, speckle_type=STRUCTURAL_PROPERTY + ".SectionProfile"):
-    name: str = None
-    shapeType: ShapeType = None
+class SectionProfile(
+    Base, speckle_type=STRUCTURAL_PROPERTY + ".Profiles.SectionProfile"
+):
+    name: Optional[str] = None
+    shapeType: Optional[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
+    memberType: Optional[MemberType] = None
+    material: Optional[StructuralMaterial] = None
+    profile: Optional[SectionProfile] = None
+    referencePoint: Optional[BaseReferencePoint] = None
     offsetY: float = 0.0
     offsetZ: float = 0.0
 
 
 class Property2D(Property, speckle_type=STRUCTURAL_PROPERTY + ".Property2D"):
-    PropertyType2D: PropertyType2D = None
+    type: Optional[PropertyType2D] = None
     thickness: float = 0.0
-    Material: Material = None
-    axis: Axis = None
-    referenceSurface: ReferenceSurface = None
+    material: Optional[StructuralMaterial] = None
+    orientationAxis: Optional[Axis] = None
+    refSurface: Optional[ReferenceSurface] = None
     zOffset: float = 0.0
     modifierInPlane: float = 0.0
     modifierBending: float = 0.0
@@ -127,13 +127,13 @@ class Property2D(Property, speckle_type=STRUCTURAL_PROPERTY + ".Property2D"):
 
 
 class Property3D(Property, speckle_type=STRUCTURAL_PROPERTY + ".Property3D"):
-    PropertyType3D: PropertyType3D = None
-    Material: Material = None
-    axis: Axis = None
+    type: Optional[PropertyType3D] = None
+    material: Optional[StructuralMaterial] = None
+    orientationAxis: Optional[Axis] = None
 
 
 class PropertyDamper(Property, speckle_type=STRUCTURAL_PROPERTY + ".PropertyDamper"):
-    damperType: PropertyTypeDamper = None
+    damperType: Optional[PropertyTypeDamper] = None
     dampingX: float = 0.0
     dampingY: float = 0.0
     dampingZ: float = 0.0
@@ -150,14 +150,14 @@ class PropertyMass(Property, speckle_type=STRUCTURAL_PROPERTY + ".PropertyMass")
     inertiaXY: float = 0.0
     inertiaYZ: float = 0.0
     inertiaZX: float = 0.0
-    massModified: bool = None
+    massModified: Optional[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
+    springType: Optional[PropertyTypeSpring] = None
     springCurveX: float = 0.0
     stiffnessX: float = 0.0
     springCurveY: float = 0.0

src/specklepy/objects/structural/results.py

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

src/specklepy/objects/units.py

@@ -0,0 +1,122 @@
+from enum import Enum
+from typing import Union
+
+from specklepy.logging.exceptions import SpeckleException, SpeckleInvalidUnitException
+
+__all__ = [
+    "Units",
+    "get_encoding_from_units",
+    "get_units_from_encoding",
+    "get_units_from_string",
+]
+
+
+class Units(Enum):
+    mm = "mm"
+    cm = "cm"
+    m = "m"
+    km = "km"
+    inches = "in"
+    feet = "ft"
+    yards = "yd"
+    miles = "mi"
+    none = "none"
+
+
+UNITS_STRINGS = {
+    Units.mm: ["mm", "mil", "millimeters", "millimetres"],
+    Units.cm: ["cm", "centimetre", "centimeter", "centimetres", "centimeters"],
+    Units.m: ["m", "meter", "meters", "metre", "metres"],
+    Units.km: ["km", "kilometer", "kilometre", "kilometers", "kilometres"],
+    Units.inches: ["in", "inch", "inches"],
+    Units.feet: ["ft", "foot", "feet"],
+    Units.yards: ["yd", "yard", "yards"],
+    Units.miles: ["mi", "mile", "miles"],
+    Units.none: ["none", "null"],
+}
+
+
+UNITS_ENCODINGS = {
+    Units.none: 0,
+    None: 0,
+    Units.mm: 1,
+    Units.cm: 2,
+    Units.m: 3,
+    Units.km: 4,
+    Units.inches: 5,
+    Units.feet: 6,
+    Units.yards: 7,
+    Units.miles: 8,
+}
+
+
+UNIT_SCALE = {
+    Units.none: 1,
+    Units.mm: 0.001,
+    Units.cm: 0.01,
+    Units.m: 1.0,
+    Units.km: 1000.0,
+    Units.inches: 0.0254,
+    Units.feet: 0.3048,
+    Units.yards: 0.9144,
+    Units.miles: 1609.340,
+}
+"""Unit scaling factor to meters"""
+
+
+def get_units_from_string(unit: str) -> Units:
+    if not isinstance(unit, str):
+        raise SpeckleInvalidUnitException(unit)
+    unit = str.lower(unit)
+    for name, alternates in UNITS_STRINGS.items():
+        if unit in alternates:
+            return name
+    raise SpeckleInvalidUnitException(unit)
+
+
+def get_units_from_encoding(unit: int) -> Units:
+    for name, encoding in UNITS_ENCODINGS.items():
+        if unit == encoding:
+            return name or Units.none
+
+    raise SpeckleException(
+        message=(
+            f"Could not understand what unit {unit} is referring to."
+            f"Please enter a valid unit encoding (eg {UNITS_ENCODINGS})."
+        )
+    )
+
+
+def get_encoding_from_units(unit: Union[Units, str, None]):
+    maybe_sanitized_unit = unit
+    if isinstance(unit, str):
+        for unit_enum, aliases in UNITS_STRINGS.items():
+            if unit in aliases:
+                maybe_sanitized_unit = unit_enum
+    try:
+        return UNITS_ENCODINGS[maybe_sanitized_unit]
+    except KeyError as e:
+        raise SpeckleException(
+            message=(
+                f"No encoding exists for unit {maybe_sanitized_unit}."
+                f"Please enter a valid unit to encode (eg {UNITS_ENCODINGS})."
+            )
+        ) from e
+
+
+def get_scale_factor_from_string(fromUnits: str, toUnits: str) -> float:
+    """Returns a scalar to convert distance values from one unit system to another"""
+    return get_scale_factor(get_units_from_string(fromUnits), get_units_from_string(toUnits))
+
+
+def get_scale_factor(fromUnits: Units, toUnits: Units) -> float:
+    """Returns a scalar to convert distance values from one unit system to another"""
+    return get_scale_factor_to_meters(fromUnits) / get_scale_factor_to_meters(toUnits)
+
+
+def get_scale_factor_to_meters(fromUnits: Units) -> float:
+    """Returns a scalar to convert distance values from one unit system to meters"""
+    if fromUnits not in UNIT_SCALE:
+        raise ValueError(f"Invalid units provided: {fromUnits}")
+
+    return UNIT_SCALE[fromUnits]