Merge remote-tracking branch 'template/main' into github-template-update

PR template was in a directory which allows selection using queries.  The PR template should be
provided by default so should be renamed and placed in the .github directory.

.circleci/config.yml

@@ -1,17 +1,79 @@
 version: 2.1
 
-# Define the jobs we want to run for this project
+orbs:
-jobs:
+  python: circleci/python@2.0.3
-  build:
+  codecov: codecov/codecov@3.2.2
-    docker:
+
-      - image: cimg/base:2023.03
+jobs:
-    steps:
+  test:
-      - run: echo "so long and thanks for all the fish"
+    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"
+    parameters:
+      tag:
+        default: "3.8"
+        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
+
+      - store_test_results:
+          path: reports
+
+      - store_artifacts:
+          path: reports
+
+      - codecov/upload
+
+  deploy:
+    docker:
+      - image: "cimg/python:3.8"
+    steps:
+      - checkout
+      - run: python patch_version.py $CIRCLE_TAG
+      - run: poetry build
+      - run: poetry publish -u specklesystems -p $PYPI_PASSWORD
 
-# Orchestrate our job run sequence
 workflows:
-  build_and_test:
+  main:
-    when:
-      false
     jobs:
-      - build
+      - test:
+          matrix:
+            parameters:
+              tag: ["3.7", "3.8", "3.9", "3.10"]
+          filters:
+            tags:
+              only: /.*/
+      - deploy:
+          requires:
+            - test
+          filters:
+            tags:
+              only: /[0-9]+(\.[0-9]+)*/
+            branches:
+              ignore: /.*/ # For testing only! /ci\/.*/

.devcontainer/Dockerfile

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

.devcontainer/devcontainer.json

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

.devcontainer/docker-compose.yaml

@@ -0,0 +1,44 @@
+version: "3.3"  # optional since v1.27.0
+services:
+  postgres:
+    image: cimg/postgres:14.2
+    environment:
+      POSTGRES_DB: speckle2_test
+      POSTGRES_PASSWORD: speckle
+      POSTGRES_USER: speckle
+    network_mode: host
+  redis:
+    image: cimg/redis:6.2
+    network_mode: host
+  speckle-server:
+    image: speckle/speckle-server:latest
+    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"
+    network_mode: host
+
+  specklepy:
+    build:
+      dockerfile: Dockerfile
+      context: .
+      args:
+        VARIANT: 3.9
+        NODE_VERSION: lts/*
+    volumes:
+      # Mounts the project folder to '/workspace'. While this file is in .devcontainer,
+      # mounts are relative to the first file in the list, which is a level up.
+      - ..:/workspaces/specklepy:cached
+    # Overrides default command so things don't shut down after the process ends.
+    command: /bin/sh -c "while sleep 1000; do :; done"
+    network_mode: host
+# networks:
+#     default:

.gitattributes

@@ -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

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

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

.github/workflows/pr.yml

@@ -1,98 +0,0 @@
-name: "Specklepy test"
-on:
-  workflow_call:
-    secrets:
-      CODECOV_TOKEN:
-        required: true
-  pull_request:
-    branches:
-      - "main"
-
-jobs:
-  test-internal: # Run integration tests against the internal server image
-    name: Test (internal)
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version:
-          - "3.10"
-          - "3.11"
-          - "3.12"
-          - "3.13"
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv and set the python version
-        uses: astral-sh/setup-uv@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-          enable-cache: true
-          cache-dependency-glob: "uv.lock"
-
-      - name: Install the project
-        run: uv sync --all-extras --dev
-
-      - name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: "ghcr.io"
-          username: ${{ github.actor }}
-          password: ${{ github.token }}
-
-      - name: Run Speckle Server
-        run: docker compose --file docker-compose-internal.yml up --detach --wait
-
-      - name: Run tests
-        run: uv run pytest --cov --cov-report xml:reports/coverage.xml --junitxml=reports/test-results.xml
-
-      - uses: codecov/codecov-action@v5
-        if: matrix.python-version == 3.12
-        with:
-          fail_ci_if_error: true # optional (default = false)
-          files: ./reports/test-results.xml # optional
-          token: ${{ secrets.CODECOV_TOKEN }}
-
-      - name: Minimize uv cache
-        run: uv cache prune --ci
-
-  test-public: # Run integration tests against the public server image
-    name: Test (public)
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version:
-          - "3.10"
-          - "3.11"
-          - "3.12"
-          - "3.13"
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv and set the python version
-        uses: astral-sh/setup-uv@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-          enable-cache: true
-          cache-dependency-glob: "uv.lock"
-
-      - name: Install the project
-        run: uv sync --all-extras --dev
-
-      - uses: actions/cache@v3
-        with:
-          path: ~/.cache/pre-commit/
-          key: ${{ hashFiles('.pre-commit-config.yaml') }}
-
-      - name: Run pre-commit
-        run: uv run pre-commit run --all-files
-
-      - name: Run Speckle Server
-        run: docker compose --file docker-compose.yml up --detach --wait
-
-      - name: Run tests
-        run: uv run pytest --cov --cov-report xml:reports/coverage.xml --junitxml=reports/test-results.xml
-
-      - name: Minimize uv cache
-        run: uv cache prune --ci

.github/workflows/publish.yml

@@ -1,55 +0,0 @@
-name: "Publish Python Package"
-on:
-  push:
-    branches:
-      - "main"
-    tags:
-      - "3.*.*"
-
-jobs:
-  test:
-    uses: "./.github/workflows/pr.yml"
-    secrets:
-      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-
-  publish-package:
-    name: "Build and Publish Python Package"
-    runs-on: ubuntu-latest
-    needs: test
-
-    # set the environment based on what triggered the workflow
-    environment:
-      name: ${{ github.ref_type == 'tag' && 'pypi' || 'testpypi' }}
-
-    permissions:
-      id-token: write
-
-    steps:
-      - name: "Install uv"
-        uses: astral-sh/setup-uv@v5
-
-      - name: "Checkout code"
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: "Build package artifacts"
-        run: uv build
-
-      # Logic for TestPyPI (on main branch push)
-      - name: "Publish to TestPyPI"
-        if: ${{ github.ref_type == 'branch' }}
-        run: uv publish --index test
-
-      - name: "Verify TestPyPI package installation"
-        if: ${{ github.ref_type == 'branch' }}
-        run: uv run --index test --with specklepy --no-project -- python -c "import specklepy"
-
-      # Logic for PyPI (on v3* tag creation)
-      - name: "Publish to PyPI"
-        if: ${{ github.ref_type == 'tag' }}
-        run: uv publish
-
-      - name: "Verify PyPI package installation"
-        if: ${{ github.ref_type == 'tag' }}
-        run: uv run --with specklepy --no-project -- python -c "import specklepy"

.gitignore

@@ -2,8 +2,6 @@
 .envrc
 reports/
 
-.volumes/
-
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -114,4 +112,4 @@ venv.bak/
 
 # other
 scratch.py
-settings.json
+settings.json

.pre-commit-config.yaml

@@ -1,31 +0,0 @@
-repos:
-  - repo: local
-    hooks:
-      # Run the linter.
-      - id: ruff
-        name: ruff lint
-        entry: uv run ruff check --force-exclude
-        language: system
-        types_or: [python, pyi]
-      # Run the formatter.
-      - id: ruff-format
-        name: ruff format
-        entry: uv run ruff format --force-exclude
-        language: system
-        types_or: [python, pyi]
-
-
-  - repo: https://github.com/commitizen-tools/commitizen
-    hooks:
-      - id: commitizen
-      - id: commitizen-branch
-        stages:
-          - pre-push
-    rev: v3.13.0
-
-
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
-    hooks:
-      - id: end-of-file-fixer
-      - id: trailing-whitespace

.vscode/extensions.json

@@ -1,6 +0,0 @@
-{
-    "recommendations": [
-        "ms-python.python",
-        "charliermarsh.ruff"
-    ]
-}

.vscode/launch.json

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

README.md

@@ -2,26 +2,52 @@
   <img src="https://user-images.githubusercontent.com/2679513/131189167-18ea5fe1-c578-47f6-9785-3748178e4312.png" width="150px"/><br/>
   Speckle | specklepy 🐍
 </h1>
-
-<p align="center"><a href="https://twitter.com/SpeckleSystems"><img src="https://img.shields.io/twitter/follow/SpeckleSystems?style=social" alt="Twitter Follow"></a> <a href="https://speckle.community"><img src="https://img.shields.io/discourse/users?server=https%3A%2F%2Fspeckle.community&amp;style=flat-square&amp;logo=discourse&amp;logoColor=white" alt="Community forum users"></a> <a href="https://speckle.systems"><img src="https://img.shields.io/badge/https://-speckle.systems-royalblue?style=flat-square" alt="website"></a> <a href="https://speckle.guide/dev/"><img src="https://img.shields.io/badge/docs-speckle.guide-orange?style=flat-square&amp;logo=read-the-docs&amp;logoColor=white" alt="docs"></a></p>
-
-> Speckle is the first AEC data hub that connects with your favorite AEC tools. Speckle exists to overcome the challenges of working in a fragmented industry where communication, creative workflows, and the exchange of data are often hindered by siloed software and processes. It is here to make the industry better.
-
 <h3 align="center">
     The Python SDK
 </h3>
+<p align="center"><b>Speckle</b> is the data infrastructure for the AEC industry.</p><br/>
+
+<p align="center"><a href="https://twitter.com/SpeckleSystems"><img src="https://img.shields.io/twitter/follow/SpeckleSystems?style=social" alt="Twitter Follow"></a> <a href="https://speckle.community"><img src="https://img.shields.io/discourse/users?server=https%3A%2F%2Fspeckle.community&amp;style=flat-square&amp;logo=discourse&amp;logoColor=white" alt="Community forum users"></a> <a href="https://speckle.systems"><img src="https://img.shields.io/badge/https://-speckle.systems-royalblue?style=flat-square" alt="website"></a> <a href="https://speckle.guide/dev/"><img src="https://img.shields.io/badge/docs-speckle.guide-orange?style=flat-square&amp;logo=read-the-docs&amp;logoColor=white" alt="docs"></a></p>
+<p align="center"><a href="https://github.com/specklesystems/specklepy/"><img src="https://circleci.com/gh/specklesystems/specklepy.svg?style=svg&amp;circle-token=76eabd350ea243575cbb258b746ed3f471f7ac29" alt="Speckle-Next"></a><a href="https://codecov.io/gh/specklesystems/specklepy">
+  <img src="https://codecov.io/gh/specklesystems/specklepy/branch/main/graph/badge.svg?token=8KQFL5N0YF"/>
+</a> </p>
+
+# About Speckle
+
+What is Speckle? Check our ![YouTube Video Views](https://img.shields.io/youtube/views/B9humiSpHzM?label=Speckle%20in%201%20minute%20video&style=social)
+
+### Features
+
+- **Object-based:** say goodbye to files! Speckle is the first object based platform for the AEC industry
+- **Version control:** Speckle is the Git & Hub for geometry and BIM data
+- **Collaboration:** share your designs collaborate with others
+- **3D Viewer:** see your CAD and BIM models online, share and embed them anywhere
+- **Interoperability:** get your CAD and BIM models into other software without exporting or importing
+- **Real time:** get real time updates and notifications and changes
+- **GraphQL API:** get what you need anywhere you want it
+- **Webhooks:** the base for a automation and next-gen pipelines
+- **Built for developers:** we are building Speckle with developers in mind and got tools for every stack
+- **Built for the AEC industry:** Speckle connectors are plugins for the most common software used in the industry such as Revit, Rhino, Grasshopper, AutoCAD, Civil 3D, Excel, Unreal Engine, Unity, QGIS, Blender and more!
+
+### Try Speckle now!
+
+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 
+
+### Resources
+
+- [![Community forum users](https://img.shields.io/badge/community-forum-green?style=for-the-badge&logo=discourse&logoColor=white)](https://speckle.community) for help, feature requests or just to hang with other speckle enthusiasts, check out our community forum!
+- [![website](https://img.shields.io/badge/tutorials-speckle.systems-royalblue?style=for-the-badge&logo=youtube)](https://speckle.systems) our tutorials portal is full of resources to get you started using Speckle
+- [![docs](https://img.shields.io/badge/docs-speckle.guide-orange?style=for-the-badge&logo=read-the-docs&logoColor=white)](https://speckle.guide/dev/) reference on almost any end-user and developer functionality
 
-<p align="center">
-  <a href="https://pypi.org/project/specklepy/"><img alt="PyPI - Version" src="https://img.shields.io/pypi/v/specklepy"></a>
-  <a href="https://codecov.io/gh/specklesystems/specklepy"><img src="https://codecov.io/gh/specklesystems/specklepy/branch/main/graph/badge.svg?token=8KQFL5N0YF" alt="Codecov"></a>
-  <a href="https://github.com/specklesystems/specklepy/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/specklesystems/specklepy"></a>
-</p>
 
 # Repo structure
 
 ## 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.
 
@@ -29,25 +55,19 @@ Head to the [**📚 specklepy docs**](https://speckle.guide/dev/python.html) for
 
 ### Installation
 
-This project uses uv for dependency management, make sure you follow the official [docs](https://docs.astral.sh/uv/) to get it.
+This project uses python-poetry for dependency management, make sure you follow the official [docs](https://python-poetry.org/docs/#installation) to get poetry.
 
-To create a new virtual environment with uv run `$ uv venv` and follow the instructions on the screen to activate the virtual environment.
+To bootstrap the project environment run `$ poetry install`. This will create a new virtual-env for the project and install both the package and dev dependencies.
-To bootstrap the project environment run `$ uv sync`. This will install both the package and dev dependencies.
 
-To execute any python script run `$ uv run python my_script.py`
+If this is your first time using poetry and you're used to creating your venvs within the project directory, run `poetry config virtualenvs.in-project true` to configure poetry to do the same.
 
-> Alternatively you may roll your own virtual-env with either venv, virtualenv, pyenv-virtualenv etc. Uv will play along an recognize if it is invoked from inside a virtual environment.
+To execute any python script run `$ poetry run python my_script.py`
 
-### Style guide
+> 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.
-
-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:
-
 - Windows: `APPDATA` or `<USER>\AppData\Roaming\Speckle`
 - Linux: `$XDG_DATA_HOME` or by default `~/.local/share/Speckle`
 - Mac: `~/.config/Speckle`
@@ -62,7 +82,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-internal.yml

@@ -1,118 +0,0 @@
-name: "speckle-server"
-
-services:
-  ####
-  # Speckle Server dependencies
-  #######
-  postgres:
-    image: "postgres:16.4-alpine3.20@sha256:d898b0b78a2627cb4ee63464a14efc9d296884f1b28c841b0ab7d7c42f1fffdf"
-    restart: always
-    environment:
-      POSTGRES_DB: speckle
-      POSTGRES_USER: speckle
-      POSTGRES_PASSWORD: speckle
-    volumes:
-      - ./.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: "valkey/valkey:8.1-alpine@sha256:0d27f0bca0249f61d060029a6aaf2e16b2c417d68d02a508e1dfb763fa2948b4"
-    restart: always
-    volumes:
-      - ./.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:
-      - ./.volumes/minio-data:/data
-    ports:
-      - '127.0.0.1:9000:9000'
-      - '127.0.0.1:9001:9001'
-    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:
-    image: ghcr.io/specklesystems/speckle-server:latest
-    restart: always
-    healthcheck:
-      test:
-        - CMD
-        - /nodejs/bin/node
-        - -e
-        - "try { require('node:http').request({headers: {'Content-Type': 'application/json'}, port:3000, hostname:'127.0.0.1', path:'/readiness', method: 'GET', timeout: 2000 }, (res) => { body = ''; res.on('data', (chunk) => {body += chunk;}); res.on('end', () => {process.exit(Number(res.statusCode != 200 || body.toLowerCase().includes('error')));}); }).end(); } catch { process.exit(1); }"
-      interval: 10s
-      timeout: 10s
-      retries: 3
-      start_period: 90s
-    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"
-      FRONTEND_ORIGIN: "http://127.0.0.1:8081"
-
-      # TODO: Change thvolumes:
-      REDIS_URL: "redis://redis"
-
-      S3_ENDPOINT: "http://minio:9000"
-      S3_PUBLIC_ENDPOINT: "http://127.0.0.1:9000"
-      S3_ACCESS_KEY: "minioadmin"
-      S3_SECRET_KEY: "minioadmin"
-      S3_BUCKET: "speckle-server"
-      S3_CREATE_BUCKET: "true"
-
-      FILE_SIZE_LIMIT_MB: 100
-      MAX_PROJECT_MODELS_PER_PAGE: 500
-
-      # TODO: Change this to a unique secret for this server
-      SESSION_SECRET: "TODO:ReplaceWithLongString"
-
-      STRATEGY_LOCAL: "true"
-
-      POSTGRES_URL: "postgres"
-      POSTGRES_USER: "speckle"
-      POSTGRES_PASSWORD: "speckle"
-      POSTGRES_DB: "speckle"
-      ENABLE_MP: "false"
-
-      LOG_PRETTY: "true"
-
-      FF_NEXT_GEN_FILE_IMPORTER_ENABLED: "true"
-      FF_LARGE_FILE_IMPORTS_ENABLED: "true"
-
-networks:
-  default:
-    name: speckle-server
-
-volumes:
-  postgres-data:
-  redis-data:
-  minio-data:

docker-compose.yml

@@ -1,118 +0,0 @@
-name: "speckle-server"
-
-services:
-  ####
-  # Speckle Server dependencies
-  #######
-  postgres:
-    image: "postgres:16.4-alpine3.20@sha256:d898b0b78a2627cb4ee63464a14efc9d296884f1b28c841b0ab7d7c42f1fffdf"
-    restart: always
-    environment:
-      POSTGRES_DB: speckle
-      POSTGRES_USER: speckle
-      POSTGRES_PASSWORD: speckle
-    volumes:
-      - ./.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: "valkey/valkey:8.1-alpine@sha256:0d27f0bca0249f61d060029a6aaf2e16b2c417d68d02a508e1dfb763fa2948b4"
-    restart: always
-    volumes:
-      - ./.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:
-      - ./.volumes/minio-data:/data
-    ports:
-      - '127.0.0.1:9000:9000'
-      - '127.0.0.1:9001:9001'
-    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:
-    image: speckle/speckle-server:latest
-    restart: always
-    healthcheck:
-      test:
-        - CMD
-        - /nodejs/bin/node
-        - -e
-        - "try { require('node:http').request({headers: {'Content-Type': 'application/json'}, port:3000, hostname:'127.0.0.1', path:'/readiness', method: 'GET', timeout: 2000 }, (res) => { body = ''; res.on('data', (chunk) => {body += chunk;}); res.on('end', () => {process.exit(Number(res.statusCode != 200 || body.toLowerCase().includes('error')));}); }).end(); } catch { process.exit(1); }"
-      interval: 10s
-      timeout: 10s
-      retries: 3
-      start_period: 90s
-    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"
-      FRONTEND_ORIGIN: "http://127.0.0.1:8081"
-
-      # TODO: Change thvolumes:
-      REDIS_URL: "redis://redis"
-
-      S3_ENDPOINT: "http://minio:9000"
-      S3_PUBLIC_ENDPOINT: "http://127.0.0.1:9000"
-      S3_ACCESS_KEY: "minioadmin"
-      S3_SECRET_KEY: "minioadmin"
-      S3_BUCKET: "speckle-server"
-      S3_CREATE_BUCKET: "true"
-
-      FILE_SIZE_LIMIT_MB: 100
-      MAX_PROJECT_MODELS_PER_PAGE: 500
-
-      # TODO: Change this to a unique secret for this server
-      SESSION_SECRET: "TODO:ReplaceWithLongString"
-
-      STRATEGY_LOCAL: "true"
-
-      POSTGRES_URL: "postgres"
-      POSTGRES_USER: "speckle"
-      POSTGRES_PASSWORD: "speckle"
-      POSTGRES_DB: "speckle"
-      ENABLE_MP: "false"
-
-      LOG_PRETTY: "true"
-
-      FF_NEXT_GEN_FILE_IMPORTER_ENABLED: "true"
-      FF_LARGE_FILE_IMPORTS_ENABLED: "true"
-
-networks:
-  default:
-    name: speckle-server
-
-volumes:
-  postgres-data:
-  redis-data:
-  minio-data:

example/many_children.py

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

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

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

@@ -1,36 +0,0 @@
-from devtools import debug
-
-from specklepy.api import operations
-from specklepy.objects_v2.geometry import Base
-from specklepy.objects_v2.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,9 @@
 """This is an example showcasing the usage of speckle `Base` class."""
 
 # the speckle.objects module exposes all speckle provided classes
-from devtools import debug
-
-from specklepy.api import operations
 from specklepy.objects import Base
+from specklepy.api import operations
+from devtools import debug
 
 
 class ExampleSub(Base):

mise.toml

@@ -1,6 +0,0 @@
-[tools]
-python = "3.13.7"
-
-[settings]
-experimental = true
-python.uv_venv_auto = true

patch_version.py

@@ -0,0 +1,31 @@
+import re
+import sys
+
+
+def patch(tag):
+    print(f"Patching version: {tag}")
+
+    with open("pyproject.toml", "r") as f:
+        lines = f.readlines()
+
+        if "version" not in lines[2]:
+            raise Exception(f"Invalid pyproject.toml. Could not patch version.")
+
+        lines[2] = f'version = "{tag}"\n'
+        with open("pyproject.toml", "w") as file:
+            file.writelines(lines)
+
+
+def main():
+    if len(sys.argv) < 2:
+        return
+
+    tag = sys.argv[1]
+    if not re.match(r"[0-9]+(\.[0-9]+)*$", tag):
+        raise ValueError(f"Invalid tag provided: {tag}")
+
+    patch(tag)
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -1,100 +1,53 @@
-[project]
+[tool.poetry]
-dynamic = ["version"]
-# version = "3.0.0a1"
 name = "specklepy"
-description = "The Python SDK for Speckle"
+version = "2.4.0"
+description = "The Python SDK for Speckle 2.0"
 readme = "README.md"
-authors = [{ name = "Speckle Systems", email = "devops@speckle.systems" }]
+authors = ["Speckle Systems <devops@speckle.systems>"]
-license = { text = "Apache-2.0" }
+license = "Apache-2.0"
-requires-python = ">=3.10.0, <4.0"
+repository = "https://github.com/specklesystems/speckle-py"
-dependencies = [
-    "appdirs>=1.4.4",
-    "attrs>=24.3.0",
-    "deprecated>=1.2.15",
-    "gql[requests,websockets]>=3.5.0,<4.0.0",
-    "httpx>=0.28.1",
-    "mkdocs>=1.6.1",
-    "mkdocs-material>=9.6.5",
-    "mkdocstrings>=0.28.1",
-    "mkdocstrings-python>=1.15.0",
-    "pydantic>=2.10.5",
-    "pydantic-settings>=2.7.1",
-    "ujson>=5.10.0",
-]
-
-[project.optional-dependencies]
-speckleifc = ["ifcopenshell>=0.8.3.post2"]
-
-[dependency-groups]
-dev = [
-    "commitizen>=4.1.0",
-    "devtools>=0.12.2",
-    "hatch>=1.14.0",
-    "hatch-vcs>=0.4.0",
-    "pre-commit>=4.0.1",
-    "pytest>=8.3.4",
-    "pytest-asyncio>=0.25.2",
-    "pytest-cov>=6.0.0",
-    "pytest-ordering>=0.6",
-    "ruff>=0.9.2",
-    "types-deprecated>=1.2.15.20241117",
-    "types-requests>=2.32.0.20241016",
-    "types-ujson>=5.10.0.20240515",
-]
-
-[project.urls]
-repository = "https://github.com/specklesystems/specklepy"
 documentation = "https://speckle.guide/dev/py-examples.html"
 homepage = "https://speckle.systems/"
 
+
+[tool.poetry.dependencies]
+python = ">=3.7.2, <4.0"
+pydantic = "^1.8.2"
+appdirs = "^1.4.4"
+gql = {extras = ["requests", "websockets"], version = "^3.3.0"}
+ujson = "^5.3.0"
+Deprecated = "^1.2.13"
+
+[tool.poetry.dev-dependencies]
+black = "^20.8b1"
+isort = "^5.7.0"
+pytest = "^6.2.2"
+pytest-ordering = "^0.6"
+pytest-cov = "^3.0.0"
+devtools = "^0.8.0"
+pylint = "^2.14.4"
+
+
+[tool.black]
+exclude = '''
+/(
+    \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | _build
+  | buck-out
+  | build
+  | dist
+)/
+'''
+include = '\.pyi?$'
+line-length = 88
+target-version = ["py37", "py38", "py39", "py310"]
+
+
 [build-system]
-requires = ["hatchling", "hatch-vcs"]
+requires = ["poetry-core>=1.0.0"]
-build-backend = "hatchling.build"
+build-backend = "poetry.core.masonry.api"
-
-[tool.hatch.version]
-source = "vcs"
-
-[tool.hatch.build.targets.wheel]
-only-include = ["src", "licenses"]
-sources = ["src"]
-
-[tool.hatch.build.targets.sdist]
-include = ["src", "licenses"]
-
-[tool.hatch.version.raw-options]
-local_scheme = "no-local-version"
-
-[tool.commitizen]
-name = "cz_conventional_commits"
-version = "2.9.2"
-tag_format = "$version"
-
-[tool.ruff]
-exclude = [".venv", "**/*.yml"]
-
-[tool.ruff.lint]
-select = [
-    # pycodestyle
-    "E",
-    # Pyflakes
-    "F",
-    # pyupgrade
-    "UP",
-    # flake8-bugbear
-    "B",
-    # flake8-simplify
-    "SIM",
-    # isort
-    "I",
-]
-ignore = ["UP006", "UP007", "UP035"]
-
-[[tool.uv.index]]
-name = "pypi"
-url = "https://pypi.org/simple/"
-publish-url = "https://upload.pypi.org/legacy/"
-
-[[tool.uv.index]]
-name = "test"
-url = "https://test.pypi.org/simple/"
-publish-url = "https://test.pypi.org/legacy/"

specklepy/api/client.py

@@ -0,0 +1,207 @@
+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 specklepy.api import resources
+from specklepy.api.resources import (
+    branch,
+    commit,
+    stream,
+    object,
+    server,
+    user,
+    subscriptions,
+)
+from specklepy.api.models import ServerInfo
+from gql import Client
+from gql.transport.requests import RequestsHTTPTransport
+from gql.transport.websockets import WebsocketsTransport
+
+
+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`.
+
+    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:
+        metrics.track(metrics.CLIENT, custom_props={"name": "create"})
+        ws_protocol = "ws"
+        http_protocol = "http"
+
+        if use_ssl:
+            ws_protocol = "wss"
+            http_protocol = "https"
+
+        # sanitise host input by removing protocol and trailing slash
+        host = re.sub(r"((^\w+:|^)\/\/)|(\/$)", "", host)
+
+        self.url = f"{http_protocol}://{host}"
+        self.graphql = f"{self.url}/graphql"
+        self.ws_url = f"{ws_protocol}://{host}/graphql"
+        self.account = Account()
+
+        self.httpclient = Client(
+            transport=RequestsHTTPTransport(url=self.graphql, verify=True, retries=3)
+        )
+        self.wsclient = None
+
+        self._init_resources()
+
+        # ? Check compatibility with the server - i think we can skip this at this point? save a request
+        # try:
+        #     server_info = self.server.get()
+        #     if isinstance(server_info, Exception):
+        #         raise server_info
+        #     if not isinstance(server_info, ServerInfo):
+        #         raise Exception("Couldn't get ServerInfo")
+        # except Exception as ex:
+        #     raise SpeckleException(
+        #         f"{self.url} is not a compatible Speckle Server", ex
+        #     ) from ex
+
+    def __repr__(self):
+        return f"SpeckleClient( server: {self.url}, authenticated: {self.account.token is not None} )"
+
+    @deprecated(
+        version="2.6.0",
+        reason="Renamed: please use `authenticate_with_account` or `authenticate_with_token` instead.",
+    )
+    def authenticate(self, token: str) -> None:
+        """Authenticate the client using a personal access token
+        The token is saved in the client object and a synchronous GraphQL entrypoint is created
+
+        Arguments:
+            token {str} -- an api token
+        """
+        self.authenticate_with_token(token)
+        self._set_up_client()
+
+    def authenticate_with_token(self, token: str) -> None:
+        """Authenticate the client using a personal access token
+        The token is saved in the client object and a synchronous GraphQL entrypoint is created
+
+        Arguments:
+            token {str} -- an api token
+        """
+        self.account = get_account_from_token(token, self.url)
+        metrics.track(metrics.CLIENT, self.account, {"name": "authenticate with token"})
+        self._set_up_client()
+
+    def authenticate_with_account(self, account: Account) -> None:
+        """Authenticate the client using an Account object
+        The account is saved in the client object and a synchronous GraphQL entrypoint is created
+
+        Arguments:
+            account {Account} -- the account object which can be found with `get_default_account` or `get_local_accounts`
+        """
+        metrics.track(metrics.CLIENT, account, {"name": "authenticate with account"})
+        self.account = account
+        self._set_up_client()
+
+    def _set_up_client(self) -> None:
+        metrics.track(metrics.CLIENT, self.account, {"name": "set up client"})
+        headers = {
+            "Authorization": f"Bearer {self.account.token}",
+            "Content-Type": "application/json",
+        }
+        httptransport = RequestsHTTPTransport(
+            url=self.graphql, headers=headers, verify=True, retries=3
+        )
+        wstransport = WebsocketsTransport(
+            url=self.ws_url,
+            init_payload={"Authorization": f"Bearer {self.account.token}"},
+        )
+        self.httpclient = Client(transport=httptransport)
+        self.wsclient = Client(transport=wstransport)
+
+        self._init_resources()
+
+        if self.user.get() is None:
+            warn(
+                SpeckleWarning(
+                    f"Possibly invalid token - could not authenticate Speckle Client for server {self.url}"
+                )
+            )
+
+    def execute_query(self, query: str) -> Dict:
+        return self.httpclient.execute(query)
+
+    def _init_resources(self) -> None:
+        self.server = server.Resource(
+            account=self.account, basepath=self.url, client=self.httpclient
+        )
+        server_version = None
+        try:
+            server_version = self.server.version()
+        except:
+            pass
+        self.user = 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,
+        )
+
+    def __getattr__(self, name):
+        try:
+            attr = getattr(resources, name)
+            return attr.Resource(
+                account=self.account, basepath=self.url, client=self.httpclient
+            )
+        except:
+            raise SpeckleException(
+                f"Method {name} is not supported by the SpeckleClient class"
+            )

specklepy/api/credentials.py

@@ -0,0 +1,135 @@
+import os
+from pydantic import BaseModel, Field  # pylint: disable=no-name-in-module
+from typing import List, Optional
+from specklepy.logging import metrics
+from specklepy.api.models import ServerInfo
+from specklepy.transports.sqlite import SQLiteTransport
+from specklepy.logging.exceptions import SpeckleException
+
+
+class UserInfo(BaseModel):
+    name: Optional[str]
+    email: Optional[str]
+    company: Optional[str]
+    id: Optional[str]
+
+
+class Account(BaseModel):
+    isDefault: bool = False
+    token: Optional[str] = None
+    refreshToken: Optional[str] = None
+    serverInfo: ServerInfo = Field(default_factory=ServerInfo)
+    userInfo: UserInfo = Field(default_factory=UserInfo)
+    id: Optional[str] = None
+
+    def __repr__(self) -> str:
+        return f"Account(email: {self.userInfo.email}, server: {self.serverInfo.url}, isDefault: {self.isDefault})"
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    @classmethod
+    def from_token(cls, token: str, server_url: str = None):
+        acct = cls(token=token)
+        acct.serverInfo.url = server_url
+        return acct
+
+
+def get_local_accounts(base_path: str = None) -> List[Account]:
+    """Gets all the accounts present in this environment
+
+    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
+    """
+    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()
+
+    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))
+                for json_file in json_acct_files
+            )
+        except Exception as ex:
+            raise SpeckleException(
+                "Invalid json accounts could not be read. Please fix or remove them.",
+                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.
+    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 = 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
+    """
+    accounts = get_local_accounts()
+    if not accounts:
+        return Account.from_token(token, server_url)
+
+    acct = next((acc for acc in accounts if acc.token == token), None)
+    if acct:
+        return acct
+
+    if server_url:
+        url = server_url.lower()
+        acct = next(
+            (acc for acc in accounts if url in acc.serverInfo.url.lower()), None
+        )
+        if acct:
+            return acct
+
+    return Account.from_token(token, server_url)
+
+
+class StreamWrapper:
+    def __init__(self, url: str = None) -> None:
+        raise SpeckleException(
+            message="The StreamWrapper has moved as of v2.6.0! Please import from specklepy.api.wrapper",
+            exception=DeprecationWarning,
+        )

specklepy/api/models.py

@@ -0,0 +1,170 @@
+# 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/operations.py

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

specklepy/api/resource.py

@@ -1,24 +1,18 @@
-from threading import Lock
+from graphql import DocumentNode
-from typing import Any, Dict, List, Optional, Tuple, Type, TypeVar, Union
+from specklepy.api.credentials import Account
-
+from specklepy.transports.sqlite import SQLiteTransport
+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 pydantic import BaseModel
-
-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
-
-T = TypeVar("T", bound=BaseModel)
 
 
-class ResourceBase:
+class ResourceBase(object):
     def __init__(
         self,
         account: Account,
@@ -33,7 +27,6 @@ class ResourceBase:
         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,35 +39,6 @@ class ResourceBase:
                 response = response[key]
             return response
 
-    def make_request_and_parse_response(
-        self,
-        schema: Type[T],
-        query: DocumentNode,
-        variables: Optional[Dict[str, Any]] = None,
-    ) -> T:
-        try:
-            with self.__lock:
-                response = self.client.execute(query, variable_values=variables)
-        except TransportQueryError as ex:
-            raise GraphQLException(
-                message=(
-                    f"Failed to execute the GraphQL {self.name} request. Errors:"
-                    f" {ex.errors}"
-                ),
-                errors=ex.errors,
-                data=ex.data,
-            ) from ex
-        except Exception as ex:
-            raise SpeckleException(
-                message=(
-                    f"Failed to execute the GraphQL {self.name} request. Inner"
-                    f" exception: {ex}"
-                ),
-                exception=ex,
-            ) from ex
-
-        return schema.model_validate(response)
-
     def _parse_response(self, response: Union[dict, list, None], schema=None):
         """Try to create a class instance from the response"""
         if response is None:
@@ -82,11 +46,11 @@ class ResourceBase:
         if isinstance(response, list):
             return [self._parse_response(response=r, schema=schema) for r in response]
         if schema:
-            return schema.model_validate(response)
+            return schema.parse_obj(response)
         elif self.schema:
             try:
-                return self.schema.model_validate(response)
+                return self.schema.parse_obj(response)
-            except Exception:
+            except:
                 s = BaseObjectSerializer(read_transport=SQLiteTransport())
                 return s.recompose_base(response)
         else:
@@ -95,34 +59,24 @@ class ResourceBase:
     def make_request(
         self,
         query: DocumentNode,
-        params: Optional[Dict] = None,
+        params: Dict = None,
         return_type: Union[str, List, None] = None,
         schema=None,
         parse_response: bool = True,
     ) -> Any:
         """Executes the GraphQL query"""
-        # This method has quite complex and ambiguous typing,
-        # and counter-intuitive error handling
-        # We are going to phase it out in favour of `make_request_and_parse_response`
         try:
-            with self.__lock:
+            response = self.client.execute(query, variable_values=params)
-                response = self.client.execute(query, variable_values=params)
         except Exception as ex:
             if isinstance(ex, TransportQueryError):
                 return GraphQLException(
-                    message=(
+                    message=f"Failed to execute the GraphQL {self.name} request. Errors: {ex.errors}",
-                        f"Failed to execute the GraphQL {self.name} request. Errors:"
-                        f" {ex.errors}"
-                    ),
                     errors=ex.errors,
                     data=ex.data,
                 )
             else:
                 return SpeckleException(
-                    message=(
+                    message=f"Failed to execute the GraphQL {self.name} request. Inner exception: {ex}",
-                        f"Failed to execute the GraphQL {self.name} request. Inner"
-                        f" exception: {ex}"
-                    ),
                     exception=ex,
                 )
 
@@ -134,23 +88,16 @@ class ResourceBase:
             return response
 
     def _check_server_version_at_least(
-        self, target_version: Tuple[Any, ...], unsupported_message: Optional[str] = None
+        self, target_version: Tuple[Any, ...], unsupported_message: str = None
     ):
         """Use this check to guard against making unsupported requests on older servers.
 
         Arguments:
-            target_version {tuple}
+            target_version {tuple} -- the minimum server version in the format (major, minor, patch, (tag, build))
-            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
-            eg (2, 6, 3) for a stable build and (2, 6, 4, 'alpha', 4711) for alpha
         """
         if not unsupported_message:
-            unsupported_message = (
+            unsupported_message = f"The client method used is not supported on Speckle Server versios prior to v{'.'.join(target_version)}"
-                "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)
 
@@ -160,7 +107,8 @@ class ResourceBase:
         """
         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"
+                "Stream invites are only supported as of Speckle Server v2.6.4. "
-            " `grant_permission` flow instead.",
+                "Please update your Speckle Server to use this method or use the `grant_permission` flow instead."
+            ),
         )

specklepy/api/resources/__init__.py

@@ -0,0 +1,12 @@
+from pathlib import Path
+import sys
+import pkgutil
+from importlib import import_module
+
+
+for (_, name, _) in pkgutil.iter_modules(__path__):
+
+    imported_module = import_module("." + name, package=__name__)
+
+    if hasattr(imported_module, "Resource"):
+        setattr(sys.modules[__name__], name, imported_module)

specklepy/api/resources/branch.py

@@ -0,0 +1,214 @@
+from gql import gql
+from specklepy.api.resource import ResourceBase
+from specklepy.api.models import Branch
+from specklepy.logging import metrics
+
+NAME = "branch"
+
+
+class Resource(ResourceBase):
+    """API Access class for branches"""
+
+    def __init__(self, account, basepath, client) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+            name=NAME,
+        )
+        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.BRANCH, self.account, {"name": "create"})
+        query = gql(
+            """
+            mutation BranchCreate($branch: BranchCreateInput!) {
+              branchCreate(branch: $branch)
+            }
+          """
+        )
+        params = {
+            "branch": {
+                "streamId": stream_id,
+                "name": name,
+                "description": description,
+            }
+        }
+
+        return self.make_request(
+            query=query, params=params, return_type="branchCreate", parse_response=False
+        )
+
+    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.BRANCH, self.account, {"name": "get"})
+        query = gql(
+            """
+            query BranchGet($stream_id: String!, $name: String!, $commits_limit: Int!) {
+                stream(id: $stream_id) {
+                        branch(name: $name) {
+                          id,
+                          name,
+                          description,
+                          commits (limit: $commits_limit) {
+                            totalCount,
+                            cursor,
+                            items {
+                              id,
+                              referencedObject,
+                              sourceApplication,
+                              totalChildrenCount,
+                              message,
+                              authorName,
+                              authorId,
+                              branchName,
+                              parents,
+                              createdAt
+                            }
+                        }
+                    }                      
+                }
+            }
+            """
+        )
+
+        params = {"stream_id": stream_id, "name": name, "commits_limit": commits_limit}
+
+        return self.make_request(
+            query=query, params=params, return_type=["stream", "branch"]
+        )
+
+    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.BRANCH, self.account, {"name": "get"})
+        query = gql(
+            """
+            query BranchesGet($stream_id: String!, $branches_limit: Int!, $commits_limit: Int!) {
+                stream(id: $stream_id) {
+                    branches(limit: $branches_limit) {
+                        items {
+                            id
+                            name
+                            description
+                            commits(limit: $commits_limit) {
+                                totalCount
+                                items{
+                                    id
+                                    message
+                                    referencedObject
+                                    sourceApplication
+                                    parents
+                                    authorId
+                                    authorName
+                                    branchName
+                                    createdAt
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            """
+        )
+
+        params = {
+            "stream_id": stream_id,
+            "branches_limit": branches_limit,
+            "commits_limit": commits_limit,
+        }
+
+        return self.make_request(
+            query=query, params=params, return_type=["stream", "branches", "items"]
+        )
+
+    def update(
+        self, stream_id: str, branch_id: str, name: str = None, description: 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.BRANCH, self.account, {"name": "update"})
+        query = gql(
+            """
+            mutation  BranchUpdate($branch: BranchUpdateInput!) {
+                branchUpdate(branch: $branch)
+                }
+            """
+        )
+        params = {
+            "branch": {
+                "streamId": stream_id,
+                "id": branch_id,
+            }
+        }
+
+        if name:
+            params["branch"]["name"] = name
+        if description:
+            params["branch"]["description"] = description
+
+        return self.make_request(
+            query=query, params=params, return_type="branchUpdate", parse_response=False
+        )
+
+    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.BRANCH, self.account, {"name": "delete"})
+        query = gql(
+            """
+            mutation BranchDelete($branch: BranchDeleteInput!) {
+                branchDelete(branch: $branch)
+            }
+            """
+        )
+
+        params = {"branch": {"streamId": stream_id, "id": branch_id}}
+
+        return self.make_request(
+            query=query, params=params, return_type="branchDelete", parse_response=False
+        )

specklepy/api/resources/commit.py

@@ -0,0 +1,233 @@
+from typing import Optional, List
+from gql import gql
+from specklepy.api.resource import ResourceBase
+from specklepy.api.models import Commit
+from specklepy.logging import metrics
+
+
+NAME = "commit"
+
+
+class Resource(ResourceBase):
+    """API Access class for commits"""
+
+    def __init__(self, account, basepath, client) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+            name=NAME,
+        )
+        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
+        """
+        query = gql(
+            """
+            query Commit($stream_id: String!, $commit_id: String!) {
+                stream(id: $stream_id) {
+                    commit(id: $commit_id) {
+                        id
+                        message
+                        referencedObject
+                        authorId
+                        authorName
+                        authorAvatar
+                        branchName
+                        createdAt
+                        sourceApplication
+                        totalChildrenCount
+                        parents
+                    }
+                }
+            }
+            """
+        )
+        params = {"stream_id": stream_id, "commit_id": commit_id}
+
+        return self.make_request(
+            query=query, params=params, return_type=["stream", "commit"]
+        )
+
+    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.COMMIT, self.account, {"name": "get"})
+        query = gql(
+            """
+            query Commits($stream_id: String!, $limit: Int!) {
+                stream(id: $stream_id) {
+                    commits(limit: $limit) {
+                        items {
+                            id
+                            message
+                            referencedObject
+                            authorName
+                            authorId
+                            authorName
+                            authorAvatar
+                            branchName
+                            createdAt
+                            sourceApplication
+                            totalChildrenCount
+                            parents
+                        }
+                    }
+                }
+            }
+            """
+        )
+        params = {"stream_id": stream_id, "limit": limit}
+
+        return self.make_request(
+            query=query, params=params, return_type=["stream", "commits", "items"]
+        )
+
+    def create(
+        self,
+        stream_id: str,
+        object_id: str,
+        branch_name: str = "main",
+        message: str = "",
+        source_application: str = "python",
+        parents: List[str] = None,
+    ) -> str:
+        """
+        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.COMMIT, self.account, {"name": "create"})
+        query = gql(
+            """
+            mutation CommitCreate ($commit: CommitCreateInput!){ commitCreate(commit: $commit)}
+            """
+        )
+        params = {
+            "commit": {
+                "streamId": stream_id,
+                "branchName": branch_name,
+                "objectId": object_id,
+                "message": message,
+                "sourceApplication": source_application,
+            }
+        }
+        if parents:
+            params["commit"]["parents"] = parents
+
+        return self.make_request(
+            query=query, params=params, return_type="commitCreate", parse_response=False
+        )
+
+    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.COMMIT, self.account, {"name": "update"})
+        query = gql(
+            """
+            mutation CommitUpdate($commit: CommitUpdateInput!){ commitUpdate(commit: $commit)}
+            """
+        )
+        params = {
+            "commit": {"streamId": stream_id, "id": commit_id, "message": message}
+        }
+
+        return self.make_request(
+            query=query, params=params, return_type="commitUpdate", parse_response=False
+        )
+
+    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.COMMIT, self.account, {"name": "delete"})
+        query = gql(
+            """
+            mutation CommitDelete($commit: CommitDeleteInput!){ commitDelete(commit: $commit)}
+            """
+        )
+        params = {"commit": {"streamId": stream_id, "id": commit_id}}
+
+        return self.make_request(
+            query=query, params=params, return_type="commitDelete", parse_response=False
+        )
+
+    def received(
+        self,
+        stream_id: str,
+        commit_id: str,
+        source_application: str = "python",
+        message: Optional[str] = None,
+    ) -> bool:
+        """
+        Mark a commit object a received by the source application.
+        """
+        metrics.track(metrics.COMMIT, self.account, {"name": "received"})
+        query = gql(
+            """
+            mutation CommitReceive($receivedInput:CommitReceivedInput!){
+                commitReceive(input:$receivedInput)
+            }
+            """
+        )
+        params = {
+            "receivedInput": {
+                "sourceApplication": source_application,
+                "streamId": stream_id,
+                "commitId": commit_id,
+                "message": "message",
+            }
+        }
+
+        try:
+            return self.make_request(
+                query=query,
+                params=params,
+                return_type="commitReceive",
+                parse_response=False,
+            )
+        except Exception as ex:
+            print(ex.with_traceback)
+            return False

specklepy/api/resources/object.py

@@ -0,0 +1,83 @@
+from typing import Dict, List
+from gql import gql
+from specklepy.api.resource import ResourceBase
+from specklepy.objects.base import Base
+
+NAME = "object"
+
+
+class Resource(ResourceBase):
+    """API Access class for objects"""
+
+    def __init__(self, account, basepath, client) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+            name=NAME,
+        )
+        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
+        """
+        query = gql(
+            """
+            query Object($stream_id: String!, $object_id: String!) {
+              stream(id: $stream_id) {
+                id
+                name
+                object(id: $object_id) {
+                  id
+                  speckleType
+                  applicationId
+                  createdAt
+                  totalChildrenCount
+                  data
+                }
+              }
+            }
+          """
+        )
+        params = {"stream_id": stream_id, "object_id": object_id}
+
+        return self.make_request(
+            query=query,
+            params=params,
+            return_type=["stream", "object", "data"],
+        )
+
+    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
+        """
+        query = gql(
+            """
+          mutation ObjectCreate($object_input: ObjectCreateInput!) { objectCreate(objectInput: $object_input) }
+          """
+        )
+        params = {"object_input": {"streamId": stream_id, "objects": objects}}
+
+        return self.make_request(
+            query=query, params=params, return_type="objectCreate", parse_response=False
+        )

specklepy/api/resources/server.py

@@ -1,16 +1,16 @@
 import re
 from typing import Any, Dict, List, Tuple
-
 from gql import gql
-
+from specklepy.api.models import ServerInfo
-from specklepy.core.api.models import ServerInfo
+from specklepy.api.resource import ResourceBase
-from specklepy.core.api.resource import ResourceBase
+from specklepy.logging import metrics
 from specklepy.logging.exceptions import GraphQLException
 
+
 NAME = "server"
 
 
-class ServerResource(ResourceBase):
+class Resource(ResourceBase):
     """API Access class for the server"""
 
     def __init__(self, account, basepath, client) -> None:
@@ -27,6 +27,7 @@ class ServerResource(ResourceBase):
         Returns:
             dict -- the server info in dictionary form
         """
+        metrics.track(metrics.SERVER, self.account, {"name": "get"})
         query = gql(
             """
             query Server {
@@ -37,6 +38,11 @@ class ServerResource(ResourceBase):
                     adminContact
                     canonicalUrl
                     version
+                    roles {
+                        name
+                        description
+                        resourceTarget
+                    }
                     scopes {
                         name
                         description
@@ -46,29 +52,23 @@ class ServerResource(ResourceBase):
                         name
                         icon
                     }
-                    workspaces {
-                      workspacesEnabled
-                    }
                 }
             }
             """
         )
 
-        server_info = self.make_request(
+        return self.make_request(
             query=query, return_type="serverInfo", schema=ServerInfo
         )
 
-        return server_info
-
     def version(self) -> Tuple[Any, ...]:
         """Get the server version
 
         Returns:
-            the server version in the format (major, minor, patch, (tag, build))
+            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
+                     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
+        # not tracking as it will be called along with other mutations / queries as a check
-        # as a check
         query = gql(
             """
             query Server {
@@ -100,6 +100,7 @@ class ServerResource(ResourceBase):
         Returns:
             dict -- a dictionary of apps registered on the server
         """
+        metrics.track(metrics.SERVER, self.account, {"name": "apps"})
         query = gql(
             """
             query Apps {
@@ -133,6 +134,7 @@ class ServerResource(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!) {
@@ -158,6 +160,7 @@ class ServerResource(ResourceBase):
         Returns:
             bool -- True if the token was successfully deleted
         """
+        metrics.track(metrics.SERVER, self.account, {"name": "revoke_token"})
         query = gql(
             """
             mutation TokenRevoke($token: String!) {

specklepy/api/resources/stream.py

@@ -0,0 +1,769 @@
+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
+
+
+NAME = "stream"
+
+
+class Resource(ResourceBase):
+    """API Access class for streams"""
+
+    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 = 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.STREAM, self.account, {"name": "get"})
+        query = gql(
+            """
+            query Stream($id: String!, $branch_limit: Int!, $commit_limit: Int!) {
+                stream(id: $id) {
+                    id
+                    name
+                    role
+                    description
+                    isPublic
+                    createdAt
+                    updatedAt
+                    commentCount
+                    favoritesCount
+                    collaborators {
+                        id
+                        name
+                        role
+                        avatar
+                    }
+                    branches(limit: $branch_limit) {
+                        totalCount
+                        cursor
+                        items {
+                            id
+                            name
+                            description
+                            commits(limit: $commit_limit) {
+                                totalCount
+                                cursor
+                                items {
+                                    id
+                                    message
+                                    authorId
+                                    createdAt
+                                    authorName
+                                    referencedObject
+                                    sourceApplication
+                                }
+                              }
+                          }
+                      }
+                }
+            }
+          """
+        )
+
+        params = {"id": id, "branch_limit": branch_limit, "commit_limit": commit_limit}
+
+        return self.make_request(query=query, params=params, return_type="stream")
+
+    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.STREAM, self.account, {"name": "get"})
+        query = gql(
+            """
+            query User($stream_limit: Int!) {
+                user {
+                    id
+                    bio
+                    name
+                    email
+                    avatar
+                    company
+                    verified
+                    profiles
+                    role
+                    streams(limit: $stream_limit) {
+                        totalCount
+                        cursor
+                        items {
+                            id
+                            name
+                            role
+                            isPublic
+                            createdAt
+                            updatedAt
+                            description
+                            commentCount
+                            favoritesCount
+                            collaborators {
+                                id
+                                name
+                                role
+                            }
+                          }
+                      }
+                  }
+            }
+          """
+        )
+
+        params = {"stream_limit": stream_limit}
+
+        return self.make_request(
+            query=query, params=params, return_type=["user", "streams", "items"]
+        )
+
+    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.STREAM, self.account, {"name": "create"})
+        query = gql(
+            """
+            mutation StreamCreate($stream: StreamCreateInput!) {
+              streamCreate(stream: $stream)
+            }
+        """
+        )
+
+        params = {
+            "stream": {"name": name, "description": description, "isPublic": is_public}
+        }
+
+        return self.make_request(
+            query=query, params=params, return_type="streamCreate", parse_response=False
+        )
+
+    def update(
+        self, id: str, name: str = None, description: str = None, is_public: 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.STREAM, self.account, {"name": "update"})
+        query = gql(
+            """
+            mutation StreamUpdate($stream: StreamUpdateInput!) {
+                streamUpdate(stream: $stream)
+            }
+        """
+        )
+
+        params = {
+            "id": id,
+            "name": name,
+            "description": description,
+            "isPublic": is_public,
+        }
+        # remove None values so graphql doesn't cry
+        params = {"stream": {k: v for k, v in params.items() if v is not None}}
+
+        return self.make_request(
+            query=query, params=params, return_type="streamUpdate", parse_response=False
+        )
+
+    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.STREAM, self.account, {"name": "delete"})
+        query = gql(
+            """
+            mutation StreamDelete($id: String!) {
+                streamDelete(id: $id)
+            }
+            """
+        )
+
+        params = {"id": id}
+
+        return self.make_request(
+            query=query, params=params, return_type="streamDelete", parse_response=False
+        )
+
+    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.STREAM, self.account, {"name": "search"})
+        query = gql(
+            """
+            query StreamSearch($search_query: String!,$limit: Int!, $branch_limit:Int!, $commit_limit:Int!) {
+                streams(query: $search_query, limit: $limit) {
+                    items {
+                        id
+                        name
+                        role
+                        description
+                        isPublic
+                        createdAt
+                        updatedAt
+                        collaborators {
+                            id
+                            name
+                            role
+                            avatar
+                        }
+                        branches(limit: $branch_limit) {
+                            totalCount
+                            cursor
+                            items {
+                                id
+                                name
+                                description
+                                commits(limit: $commit_limit) {
+                                    totalCount
+                                    cursor
+                                    items {
+                                        id
+                                        referencedObject
+                                        message
+                                        authorName
+                                        authorId
+                                        createdAt
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+          """
+        )
+
+        params = {
+            "search_query": search_query,
+            "limit": limit,
+            "branch_limit": branch_limit,
+            "commit_limit": commit_limit,
+        }
+
+        return self.make_request(
+            query=query, params=params, return_type=["streams", "items"]
+        )
+
+    def favorite(self, stream_id: str, favorited: bool = True):
+        """Favorite or unfavorite the given stream.
+
+        Arguments:
+            stream_id {str} -- the id of the stream to favorite / unfavorite
+            favorited {bool} -- whether to favorite (True) or unfavorite (False) the stream
+
+        Returns:
+            Stream -- the stream with its `id`, `name`, and `favoritedDate`
+        """
+        metrics.track(metrics.STREAM, self.account, {"name": "favorite"})
+        query = gql(
+            """
+            mutation StreamFavorite($stream_id: String!, $favorited: Boolean!) {
+                streamFavorite(streamId: $stream_id, favorited: $favorited) {
+                    id
+                    name
+                    favoritedDate
+                    favoritesCount
+                }
+            }
+            """
+        )
+
+        params = {
+            "stream_id": stream_id,
+            "favorited": favorited,
+        }
+
+        return self.make_request(
+            query=query, params=params, return_type=["streamFavorite"]
+        )
+
+    @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]:
+        """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.INVITE, self.account, {"name": "get"})
+        self._check_invites_supported()
+
+        query = gql(
+            """
+            query StreamInvites($streamId: String!) {
+                stream(id: $streamId){
+                    pendingCollaborators {
+                        id
+                        token
+                        inviteId
+                        streamId
+                        streamName
+                        title
+                        role
+                        invitedBy{
+                            id
+                            name
+                            company
+                            avatar
+                        }
+                        user {
+                            id
+                            name
+                            company
+                            avatar
+                        }
+                    }
+                }
+            }
+            """
+        )
+        params = {"streamId": stream_id}
+
+        return self.make_request(
+            query=query,
+            params=params,
+            return_type=["stream", "pendingCollaborators"],
+            schema=PendingStreamCollaborator,
+        )
+
+    def invite(
+        self,
+        stream_id: str,
+        email: str = None,
+        user_id: str = None,
+        role: str = "stream:contributor",  # should default be reviewer?
+        message: 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 assing 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"
+            )
+
+        query = gql(
+            """
+            mutation StreamInviteCreate($input: StreamInviteCreateInput!) {
+                streamInviteCreate(input: $input)
+            }
+            """
+        )
+
+        params = {
+            "email": email,
+            "userId": user_id,
+            "streamId": stream_id,
+            "message": message,
+            "role": role,
+        }
+        params = {"input": {k: v for k, v in params.items() if v is not None}}
+
+        return self.make_request(
+            query=query,
+            params=params,
+            return_type="streamInviteCreate",
+            parse_response=False,
+        )
+
+    def invite_batch(
+        self,
+        stream_id: str,
+        emails: List[str] = None,
+        user_ids: List[None] = None,
+        message: 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.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"
+            )
+
+        query = gql(
+            """
+            mutation StreamInviteBatchCreate($input: [StreamInviteCreateInput!]!) {
+                streamInviteBatchCreate(input: $input)
+            }
+            """
+        )
+
+        email_invites = [
+            {"streamId": stream_id, "message": message, "email": email}
+            for email in emails
+            if emails 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
+        ]
+
+        params = {"input": [*email_invites, *user_invites]}
+
+        return self.make_request(
+            query=query,
+            params=params,
+            return_type="streamInviteBatchCreate",
+            parse_response=False,
+        )
+
+    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.INVITE, self.account, {"name": "cancel"})
+        self._check_invites_supported()
+
+        query = gql(
+            """
+            mutation StreamInviteCancel($streamId: String!, $inviteId: String!) {
+                streamInviteCancel(streamId: $streamId, inviteId: $inviteId)
+            }
+            """
+        )
+
+        params = {"streamId": stream_id, "inviteId": invite_id}
+
+        return self.make_request(
+            query=query,
+            params=params,
+            return_type="streamInviteCancel",
+            parse_response=False,
+        )
+
+    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.INVITE, self.account, {"name": "use"})
+        self._check_invites_supported()
+
+        query = gql(
+            """
+            mutation StreamInviteUse($accept: Boolean!, $streamId: String!, $token: String!) {
+                streamInviteUse(accept: $accept, streamId: $streamId, token: $token)
+            }
+            """
+        )
+
+        params = {"streamId": stream_id, "token": token, "accept": accept}
+
+        return self.make_request(
+            query=query,
+            params=params,
+            return_type="streamInviteUse",
+            parse_response=False,
+        )
+
+    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.PERMISSION, self.account, {"name": "update", "role": role}
+        )
+        if self.server_version 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."
+                )
+            )
+        query = gql(
+            """
+            mutation StreamUpdatePermission($permission_params: StreamUpdatePermissionInput !) {
+                streamUpdatePermission(permissionParams: $permission_params)
+            }
+            """
+        )
+
+        params = {
+            "permission_params": {
+                "streamId": stream_id,
+                "userId": user_id,
+                "role": role,
+            }
+        }
+
+        return self.make_request(
+            query=query,
+            params=params,
+            return_type="streamUpdatePermission",
+            parse_response=False,
+        )
+
+    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.PERMISSION, self.account, {"name": "revoke"})
+        query = gql(
+            """
+            mutation StreamRevokePermission($permission_params: StreamRevokePermissionInput !) {
+                streamRevokePermission(permissionParams: $permission_params)
+            }
+            """
+        )
+
+        params = {"permission_params": {"streamId": stream_id, "userId": user_id}}
+
+        return self.make_request(
+            query=query,
+            params=params,
+            return_type="streamRevokePermission",
+            parse_response=False,
+        )
+
+    def activity(
+        self,
+        stream_id: str,
+        action_type: str = None,
+        limit: int = 20,
+        before: datetime = None,
+        after: datetime = None,
+        cursor: datetime = None,
+    ):
+        """
+        Get the activity from a given stream in an Activity collection. Step into the activity `items` for the list of activity.
+
+        Note: all timestamps arguments should be `datetime` of any tz as they will be converted to UTC ISO format strings
+
+        stream_id {str} -- the id of the stream to get activity from
+        action_type {str} -- filter results to a single action type (eg: `commit_create` or `commit_receive`)
+        limit {int} -- max number of Activity items to return
+        before {datetime} -- latest cutoff for activity (ie: return all activity _before_ this time)
+        after {datetime} -- oldest cutoff for activity (ie: return all activity _after_ this time)
+        cursor {datetime} -- timestamp cursor for pagination
+        """
+        query = gql(
+            """
+            query StreamActivity($stream_id: String!, $action_type: String, $before:DateTime, $after: DateTime, $cursor: DateTime, $limit: Int){
+                stream(id: $stream_id) {
+                    activity(actionType: $action_type, before: $before, after: $after, cursor: $cursor, limit: $limit) {
+                        totalCount
+                        cursor
+                        items {
+                            actionType
+                            info
+                            userId
+                            streamId
+                            resourceId
+                            resourceType
+                            message
+                            time
+                        }
+                    }
+                }
+            }
+            """
+        )
+        try:
+            params = {
+                "stream_id": stream_id,
+                "limit": limit,
+                "action_type": action_type,
+                "before": before.astimezone(timezone.utc).isoformat()
+                if before
+                else before,
+                "after": after.astimezone(timezone.utc).isoformat() if after else after,
+                "cursor": cursor.astimezone(timezone.utc).isoformat()
+                if cursor
+                else cursor,
+            }
+        except AttributeError as e:
+            raise SpeckleException(
+                "Could not get stream activity - `before`, `after`, and `cursor` must be in `datetime` format if provided",
+                ValueError,
+            ) from e
+
+        return self.make_request(
+            query=query,
+            params=params,
+            return_type=["stream", "activity"],
+            schema=ActivityCollection,
+        )

specklepy/api/resources/subscriptions.py

@@ -0,0 +1,124 @@
+from typing import Callable, Dict, List, Union
+from functools import wraps
+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
+
+NAME = "subscribe"
+
+
+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(ResourceBase):
+    """API Access class for subscriptions"""
+
+    def __init__(self, account, basepath, client) -> None:
+        super().__init__(
+            account=account,
+            basepath=basepath,
+            client=client,
+            name=NAME,
+        )
+
+    @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.
+
+        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
+        """
+        query = gql(
+            """
+            subscription { userStreamAdded }
+            """
+        )
+        return await self.subscribe(
+            query=query, callback=callback, return_type="userStreamAdded", schema=Stream
+        )
+
+    @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.
+
+        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
+        """
+        query = gql(
+            """
+            subscription Update($id: String!) { streamUpdated(streamId: $id) }
+            """
+        )
+        params = {"id": id}
+
+        return await self.subscribe(
+            query=query,
+            params=params,
+            callback=callback,
+            return_type="streamUpdated",
+            schema=Stream,
+        )
+
+    @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.
+
+        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'
+        """
+        query = gql(
+            """
+            subscription { userStreamRemoved }
+            """
+        )
+
+        return await self.subscribe(
+            query=query,
+            callback=callback,
+            return_type="userStreamRemoved",
+            parse_response=False,
+        )
+
+    @check_wsclient
+    async def subscribe(
+        self,
+        query: DocumentNode,
+        params: Dict = None,
+        callback: Callable = None,
+        return_type: 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

specklepy/api/resources/user.py

@@ -0,0 +1,280 @@
+from typing import List, Optional, Union
+from datetime import datetime, timezone
+from gql import gql
+from specklepy.logging import metrics
+from specklepy.logging.exceptions import SpeckleException
+from specklepy.api.resource import ResourceBase
+from specklepy.api.models import ActivityCollection, PendingStreamCollaborator, User
+
+NAME = "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, 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).
+
+        Arguments:
+            id {str} -- the user id
+
+        Returns:
+            User -- the retrieved user
+        """
+        metrics.track(metrics.USER, self.account, {"name": "get"})
+        query = gql(
+            """
+            query User($id: String) {
+                user(id: $id) {
+                    id
+                    email
+                    name
+                    bio
+                    company
+                    avatar
+                    verified
+                    profiles
+                    role
+                }
+            }
+          """
+        )
+
+        params = {"id": id}
+
+        return self.make_request(query=query, params=params, return_type="user")
+
+    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
+        """
+        if len(search_query) < 3:
+            return SpeckleException(
+                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!) {
+                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 update(
+        self, name: str = None, company: str = None, bio: str = None, avatar: 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"})
+        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,
+        user_id: str = None,
+        limit: int = 20,
+        action_type: str = None,
+        before: datetime = None,
+        after: datetime = None,
+        cursor: datetime = None,
+    ):
+        """
+        Get the activity from a given stream in an Activity collection. Step into the activity `items` for the list of activity.
+        If no id argument is provided, will return the current authenticated user's activity (as extracted from the authorization header).
+
+        Note: all timestamps arguments should be `datetime` of any tz as they will be converted to UTC ISO format strings
+
+        user_id {str} -- the id of the user to get the activity from
+        action_type {str} -- filter results to a single action type (eg: `commit_create` or `commit_receive`)
+        limit {int} -- max number of Activity items to return
+        before {datetime} -- latest cutoff for activity (ie: return all activity _before_ this time)
+        after {datetime} -- oldest cutoff for activity (ie: return all activity _after_ this time)
+        cursor {datetime} -- timestamp cursor for pagination
+        """
+
+        query = gql(
+            """
+            query UserActivity($user_id: String, $action_type: String, $before:DateTime, $after: DateTime, $cursor: DateTime, $limit: Int){
+                user(id: $user_id) {
+                    activity(actionType: $action_type, before: $before, after: $after, cursor: $cursor, limit: $limit) {
+                        totalCount
+                        cursor
+                        items {
+                            actionType
+                            info
+                            userId
+                            streamId
+                            resourceId
+                            resourceType
+                            message
+                            time
+                        }
+                    }
+                }
+            }
+            """
+        )
+
+        params = {
+            "user_id": user_id,
+            "limit": limit,
+            "action_type": action_type,
+            "before": before.astimezone(timezone.utc).isoformat() if before else before,
+            "after": after.astimezone(timezone.utc).isoformat() if after else after,
+            "cursor": cursor.astimezone(timezone.utc).isoformat() if cursor else cursor,
+        }
+
+        return self.make_request(
+            query=query,
+            params=params,
+            return_type=["user", "activity"],
+            schema=ActivityCollection,
+        )
+
+    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"})
+        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: 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"})
+        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,
+        )

specklepy/api/speckle2schema.graphql

@@ -0,0 +1,640 @@
+
+      
+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/api/wrapper.py

@@ -0,0 +1,166 @@
+from warnings import warn
+from urllib.parse import urlparse, unquote
+from specklepy.api.credentials import (
+    Account,
+    get_account_from_token,
+    get_local_accounts,
+)
+from specklepy.logging import metrics
+from specklepy.api.client import SpeckleClient
+from specklepy.transports.server.server import ServerTransport
+from specklepy.logging.exceptions import SpeckleException, SpeckleWarning
+
+
+class StreamWrapper:
+    """
+    The `StreamWrapper` gives you some handy helpers to deal with urls and get authenticated clients and transports.
+
+    Construct a `StreamWrapper` with a stream, branch, commit, or object URL. The corresponding ids will be stored
+    in the wrapper. If you have local accounts on the machine, you can use the `get_account` and `get_client` methods
+    to get a local account for the server. You can also pass a token into `get_client` if you don't have a corresponding
+    local account for the server.
+
+    ```py
+    from specklepy.api.wrapper import StreamWrapper
+
+    # provide any stream, branch, commit, object, or globals url
+    wrapper = StreamWrapper("https://speckle.xyz/streams/3073b96e86/commits/604bea8cc6")
+
+    # get an authenticated SpeckleClient if you have a local account for the server
+    client = wrapper.get_client()
+
+    # get an authenticated ServerTransport if you have a local account for the server
+    transport = wrapper.get_transport()
+    ```
+    """
+
+    stream_url: str = None
+    use_ssl: bool = True
+    host: str = None
+    stream_id: str = None
+    commit_id: str = None
+    object_id: str = None
+    branch_name: str = None
+    _client: SpeckleClient = None
+    _account: Account = None
+
+    def __repr__(self):
+        return f"StreamWrapper( server: {self.host}, stream_id: {self.stream_id}, type: {self.type} )"
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    @property
+    def type(self) -> str:
+        if self.object_id:
+            return "object"
+        elif self.commit_id:
+            return "commit"
+        elif self.branch_name:
+            return "branch"
+        else:
+            return "stream" if self.stream_id else "invalid"
+
+    def __init__(self, url: str) -> None:
+        self.stream_url = url
+        parsed = urlparse(url)
+        self.host = parsed.netloc
+        self.use_ssl = parsed.scheme == "https"
+        segments = parsed.path.strip("/").split("/", 3)
+        metrics.track(metrics.STREAM_WRAPPER, self.get_account())
+
+        if not segments or len(segments) < 2:
+            raise SpeckleException(
+                f"Cannot parse {url} into a stream wrapper class - invalid URL provided."
+            )
+
+        while segments:
+            segment = segments.pop(0)
+            if segments and segment.lower() == "streams":
+                self.stream_id = segments.pop(0)
+            elif segments and segment.lower() == "commits":
+                self.commit_id = segments.pop(0)
+            elif segments and segment.lower() == "branches":
+                self.branch_name = unquote(segments.pop(0))
+            elif segments and segment.lower() == "objects":
+                self.object_id = segments.pop(0)
+            elif segment.lower() == "globals":
+                self.branch_name = "globals"
+                if segments:
+                    self.commit_id = segments.pop(0)
+            else:
+                raise SpeckleException(
+                    f"Cannot parse {url} into a stream wrapper class - invalid URL provided."
+                )
+
+        if not self.stream_id:
+            raise SpeckleException(
+                f"Cannot parse {url} into a stream wrapper class - no stream id found."
+            )
+
+    @property
+    def server_url(self):
+        return f"{'https' if self.use_ssl else 'http'}://{self.host}"
+
+    def get_account(self, token: str = None) -> Account:
+        """
+        Gets an account object for this server from the local accounts db (added via Speckle Manager or a json file)
+        """
+        if self._account and self._account.token:
+            return self._account
+
+        self._account = next(
+            (a for a in get_local_accounts() if self.host in a.serverInfo.url),
+            None,
+        )
+
+        if not self._account:
+            self._account = get_account_from_token(token, self.server_url)
+
+        if self._client:
+            self._client.authenticate_with_account(self._account)
+
+        return self._account
+
+    def get_client(self, token: str = None) -> SpeckleClient:
+        """
+        Gets an authenticated client for this server. You may provide a token if there aren't any local accounts on this
+        machine. If no account is found and no token is provided, an unauthenticated client is returned.
+
+        Arguments:
+            token {str} -- optional token if no local account is available (defaults to None)
+
+        Returns:
+            SpeckleClient -- authenticated with a corresponding local account or the provided token
+        """
+        if self._client and token is None:
+            return self._client
+
+        if not self._account or not self._account.token:
+            self.get_account(token)
+
+        if not self._client:
+            self._client = SpeckleClient(host=self.host, use_ssl=self.use_ssl)
+
+        if self._account.token is None and token is None:
+            warn(f"No local account found for server {self.host}", SpeckleWarning)
+            return self._client
+
+        if self._account.token:
+            self._client.authenticate_with_account(self._account)
+        else:
+            self._client.authenticate_with_token(token)
+
+        return self._client
+
+    def get_transport(self, token: str = None) -> ServerTransport:
+        """
+        Gets a server transport for this stream using an authenticated client. If there is no local account for this
+        server and the client was not authenticated with a token, this will throw an exception.
+
+        Returns:
+            ServerTransport -- constructed for this stream with a pre-authenticated client
+        """
+        if not self._account or not self._account.token:
+            self.get_account(token)
+        return ServerTransport(self.stream_id, account=self._account)

specklepy/logging/exceptions.py

@@ -11,17 +11,6 @@ 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)
@@ -29,10 +18,7 @@ class SerializationException(SpeckleException):
         self.unhandled_type = type(obj)
 
     def __str__(self) -> str:
-        return (
+        return f"SpeckleException: Could not serialize object of type {self.unhandled_type}"
-            "SpeckleException: Could not serialize object of type"
-            f" {self.unhandled_type}"
-        )
 
 
 class GraphQLException(SpeckleException):
@@ -58,8 +44,3 @@ class UnsupportedException(SpeckleException):
 class SpeckleWarning(Warning):
     def __init__(self, *args: object) -> None:
         super().__init__(*args)
-
-
-class WorkspacePermissionException(SpeckleException):
-    def __init__(self, message: str) -> None:
-        super().__init__(message=message)

specklepy/logging/metrics.py

@@ -0,0 +1,148 @@
+import sys
+import queue
+import hashlib
+import getpass
+import logging
+import requests
+import threading
+import platform
+import contextlib
+
+
+"""
+Anonymous telemetry to help us understand how to make a better Speckle.
+This really helps us to deliver a better open source project and product!
+"""
+TRACK = True
+HOST_APP = "python"
+HOST_APP_VERSION = f"python {'.'.join(map(str, sys.version_info[:2]))}"
+PLATFORMS = {"win32": "Windows", "cygwin": "Windows", "darwin": "Mac OS X"}
+
+LOG = logging.getLogger(__name__)
+METRICS_TRACKER = None
+
+# actions
+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"
+
+ACCOUNTS = "Get Local Accounts"
+
+SERIALIZE = "serialization/serialize"
+DESERIALIZE = "serialization/deserialize"
+
+
+def disable():
+    global TRACK
+    TRACK = False
+
+
+def enable():
+    global TRACK
+    TRACK = True
+
+
+def set_host_app(host_app: str, host_app_version: str = None):
+    global HOST_APP, HOST_APP_VERSION
+    HOST_APP = host_app
+    HOST_APP_VERSION = host_app_version or HOST_APP_VERSION
+
+
+def track(action: str, account: "Account" = None, custom_props: dict = None):
+    if not TRACK:
+        return
+    try:
+        initialise_tracker(account)
+        event_params = {
+            "event": action,
+            "properties": {
+                "distinct_id": METRICS_TRACKER.last_user,
+                "server_id": METRICS_TRACKER.last_server,
+                "token": METRICS_TRACKER.analytics_token,
+                "hostApp": HOST_APP,
+                "hostAppVersion": HOST_APP_VERSION,
+                "$os": METRICS_TRACKER.platform,
+                "type": "action",
+            },
+        }
+        if custom_props:
+            event_params["properties"].update(custom_props)
+
+        METRICS_TRACKER.queue.put_nowait(event_params)
+    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)}")
+
+
+def initialise_tracker(account: "Account" = None):
+    global METRICS_TRACKER
+    if not METRICS_TRACKER:
+        METRICS_TRACKER = MetricsTracker()
+
+    if account and account.userInfo.email:
+        METRICS_TRACKER.set_last_user(account.userInfo.email)
+    if account and account.serverInfo.url:
+        METRICS_TRACKER.set_last_server(account.userInfo.email)
+
+
+class Singleton(type):
+    _instances = {}
+
+    def __call__(cls, *args, **kwargs):
+        if cls not in cls._instances:
+            cls._instances[cls] = super(Singleton, cls).__call__(*args, **kwargs)
+        return cls._instances[cls]
+
+
+class MetricsTracker(metaclass=Singleton):
+    analytics_url = "https://analytics.speckle.systems/track?ip=1"
+    analytics_token = "acd87c5a50b56df91a795e999812a3a4"
+    last_user = ""
+    last_server = None
+    platform = None
+    sending_thread = None
+    queue = queue.Queue(1000)
+
+    def __init__(self) -> None:
+        self.sending_thread = threading.Thread(
+            target=self._send_tracking_requests, daemon=True
+        )
+        self.platform = PLATFORMS.get(sys.platform, "linux")
+        self.sending_thread.start()
+        with contextlib.suppress(Exception):
+            node, user = platform.node(), getpass.getuser()
+            if node and user:
+                self.last_user = f"@{self.hash(f'{node}-{user}')}"
+
+    def set_last_user(self, email: str):
+        if not email:
+            return
+        self.last_user = f"@{self.hash(email)}"
+
+    def set_last_server(self, server: str):
+        if not server:
+            return
+        self.last_server = self.hash(server)
+
+    def hash(self, value: str):
+        return hashlib.md5(value.lower().encode("utf-8")).hexdigest().upper()
+
+    def _send_tracking_requests(self):
+        session = requests.Session()
+        while True:
+            event_params = [self.queue.get()]
+
+            try:
+                session.post(self.analytics_url, json=event_params)
+            except Exception as ex:
+                LOG.error(f"Error sending metrics request: {str(ex)}")
+
+            self.queue.task_done()

specklepy/objects/__init__.py

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

specklepy/objects/base.py

@@ -0,0 +1,416 @@
+from typing import (
+    Any,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Union,
+    Set,
+    Type,
+    get_type_hints,
+)
+
+import contextlib
+from enum import EnumMeta
+from warnings import warn
+
+from specklepy.logging.exceptions import SpeckleException
+from specklepy.objects.units import get_units_from_string
+from specklepy.transports.memory import MemoryTransport
+
+PRIMITIVES = (int, float, str, bool)
+
+# to remove from dir() when calling get_member_names()
+REMOVE_FROM_DIR = {
+    "Config",
+    "_Base__dict_helper",
+    "__annotations__",
+    "__class__",
+    "__delattr__",
+    "__dict__",
+    "__dir__",
+    "__doc__",
+    "__eq__",
+    "__format__",
+    "__ge__",
+    "__getattribute__",
+    "__getitem__",
+    "__gt__",
+    "__hash__",
+    "__init__",
+    "__init_subclass__",
+    "__le__",
+    "__lt__",
+    "__module__",
+    "__ne__",
+    "__new__",
+    "__reduce__",
+    "__reduce_ex__",
+    "__repr__",
+    "__setattr__",
+    "__setitem__",
+    "__sizeof__",
+    "__str__",
+    "__subclasshook__",
+    "__weakref__",
+    "_chunk_size_default",
+    "_chunkable",
+    "_count_descendants",
+    "_attr_types",
+    "_detachable",
+    "_handle_object_count",
+    "_type_check",
+    "_type_registry",
+    "_units",
+    "add_chunkable_attrs",
+    "add_detachable_attrs",
+    "get_children_count",
+    "get_dynamic_member_names",
+    "get_id",
+    "get_member_names",
+    "get_registered_type",
+    "get_typed_member_names",
+    "to_dict",
+    "update_forward_refs",
+    "validate_prop_name",
+    "from_list",
+    "to_list",
+}
+
+
+class _RegisteringBase:
+    """
+    Private Base model for Speckle types.
+
+    This is an implementation detail, please do not use this outside this module.
+
+    This class provides automatic registration of `speckle_type` into a global,
+    (class level) registry for each subclassing type.
+    The type registry is a base for accurate type based (de)serialization.
+    """
+
+    speckle_type: ClassVar[str]
+    _type_registry: ClassVar[Dict[str, "Base"]] = {}
+    _attr_types: ClassVar[Dict[str, Type]] = {}
+    # dict of chunkable props and their max chunk size
+    _chunkable: Dict[str, int] = {}
+    _chunk_size_default: int = 1000
+    _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
+    ) -> 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 __init_subclass__(
+        cls,
+        speckle_type: str = None,
+        chunkable: Dict[str, int] = None,
+        detachable: Set[str] = None,
+        serialize_ignore: Set[str] = None,
+        **kwargs: Dict[str, Any],
+    ):
+        """
+        Hook into subclass type creation.
+
+        This is provides a mechanism to hook into the event of the subclass type object
+        initialization. This is reused to register each subclassing type into a class
+        level dictionary.
+        """
+        if speckle_type 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."
+            )
+        cls.speckle_type = speckle_type or cls.__name__
+        cls._type_registry[cls.speckle_type] = cls  # type: ignore
+        try:
+            cls._attr_types = get_type_hints(cls)
+        except Exception:
+            cls._attr_types = getattr(cls, "__annotations__", {})
+        if chunkable:
+            chunkable = {k: v for k, v in chunkable.items() if isinstance(v, int)}
+            cls._chunkable = dict(cls._chunkable, **chunkable)
+        if detachable:
+            cls._detachable = cls._detachable.union(detachable)
+        if serialize_ignore:
+            cls._serialize_ignore = cls._serialize_ignore.union(serialize_ignore)
+        super().__init_subclass__(**kwargs)
+
+
+class Base(_RegisteringBase):
+    id: Optional[str] = None
+    totalChildrenCount: Optional[int] = None
+    applicationId: Optional[str] = None
+    _units: Union[str, None] = None
+
+    def __init__(self, **kwargs) -> None:
+        super().__init__()
+        for k, v in kwargs.items():
+            self.__setattr__(k, v)
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}(id: {self.id}, "
+            f"speckle_type: {self.speckle_type}, "
+            f"totalChildrenCount: {self.totalChildrenCount})"
+        )
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    @classmethod
+    def of_type(cls, speckle_type: str, **kwargs) -> "Base":
+        """
+        Get a plain Base object with a specified speckle_type.
+
+        The speckle_type is protected and cannot be overwritten on a class instance.
+        This is to prevent problems with receiving in other platforms or connectors.
+        However, if you really need a base with a different type, here is a helper
+        to do that for you.
+
+        This is used in the deserialisation of unknown types so their speckle_type
+        can be preserved.
+        """
+        b = cls(**kwargs)
+        b.__dict__.update(speckle_type=speckle_type)
+        return b
+
+    def __setitem__(self, name: str, value: Any) -> None:
+        self.validate_prop_name(name)
+        self.__dict__[name] = value
+
+    def __getitem__(self, name: str) -> Any:
+        return self.__dict__[name]
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """
+        Type checking, guard attribute, and property set mechanism.
+
+        The `speckle_type` is a protected class attribute it must not be overridden.
+
+        This also performs a type check if the attribute is type hinted.
+        """
+        if name == "speckle_type":
+            # not sure if we should raise an exception here??
+            # raise SpeckleException(
+            #     "Cannot override the `speckle_type`. This is set manually by the class or on deserialisation"
+            # )
+            return
+        # if value is not None:
+        value = self._type_check(name, value)
+        attr = getattr(self.__class__, name, None)
+        if isinstance(attr, property):
+            try:
+                attr.__set__(self, value)
+            except AttributeError:
+                return  # the prop probably doesn't have a setter
+        super().__setattr__(name, value)
+
+    @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
+        included.
+
+        See `objects.geometry` for an example of how this is used with the Brep class definitions
+        """
+        try:
+            cls._attr_types = get_type_hints(cls)
+        except Exception as e:
+            warn(f"Could not update forward refs for class {cls.__name__}: {e}")
+
+    @classmethod
+    def validate_prop_name(cls, name: str) -> None:
+        """Validator for dynamic attribute names."""
+        if name in {"", "@"}:
+            raise ValueError("Invalid Name: Base member names cannot be empty strings")
+        if name.startswith("@@"):
+            raise ValueError(
+                "Invalid Name: Base member names cannot start with more than one '@'",
+            )
+        if "." in name or "/" in name:
+            raise ValueError(
+                "Invalid Name: Base member names cannot contain characters '.' or '/'",
+            )
+
+    def _type_check(self, name: str, value: 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],
+        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
+
+        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)
+
+        raise SpeckleException(
+            f"Cannot set '{self.__class__.__name__}.{name}': it expects type '{t.__name__}', but received type '{type(value).__name__}'"
+        )
+
+    def add_chunkable_attrs(self, **kwargs: int) -> None:
+        """
+        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
+        """
+        chunkable = {k: v for k, v in kwargs.items() if isinstance(v, int)}
+        self._chunkable = dict(self._chunkable, **chunkable)
+
+    def add_detachable_attrs(self, names: Set[str]) -> None:
+        """
+        Mark defined attributes as detachable for serialisation
+
+        Arguments:
+            names {Set[str]} -- the names of the attributes to detach as a set of strings
+        """
+        self._detachable = self._detachable.union(names)
+
+    @property
+    def units(self):
+        return self._units
+
+    @units.setter
+    def units(self, value: str):
+        units = get_units_from_string(value)
+        if units:
+            self._units = units
+
+    def get_member_names(self) -> List[str]:
+        """Get all of the property names on this object, dynamic or not"""
+        attr_dir = list(set(dir(self)) - REMOVE_FROM_DIR)
+        return [
+            name
+            for name in attr_dir
+            if not name.startswith("_") and not callable(getattr(self, name))
+        ]
+
+    def get_serializable_attributes(self) -> List[str]:
+        """Get the attributes that should be serialized"""
+        return sorted(list(set(self.get_member_names()) - self._serialize_ignore))
+
+    def get_typed_member_names(self) -> List[str]:
+        """Get all of the names of the defined (typed) properties of this object"""
+        return list(self._attr_types.keys())
+
+    def get_dynamic_member_names(self) -> List[str]:
+        """Get all of the names of the dynamic properties of this object"""
+        return list(set(self.__dict__.keys()) - set(self._attr_types.keys()))
+
+    def get_children_count(self) -> int:
+        """Get the total count of children Base objects"""
+        parsed = []
+        return 1 + self._count_descendants(self, parsed)
+
+    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!
+
+        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
+
+        Returns:
+            str -- the hash (id) of the fully serialized object
+        """
+        from specklepy.serialization.base_object_serializer import BaseObjectSerializer
+
+        serializer = BaseObjectSerializer()
+        if decompose:
+            serializer.write_transports = [MemoryTransport()]
+        return serializer.traverse_base(self)[0]
+
+    def _count_descendants(self, base: "Base", parsed: List) -> int:
+        if base in parsed:
+            return 0
+        parsed.append(base)
+
+        return sum(
+            self._handle_object_count(value, parsed)
+            for name, value in base.get_member_names()
+            if not name.startswith("@")
+        )
+
+    def _handle_object_count(self, obj: Any, parsed: List) -> int:
+        # pylint: disable=isinstance-second-argument-not-valid-type
+        count = 0
+        if obj is None:
+            return count
+        if isinstance(obj, "Base"):
+            count += 1
+            count += self._count_descendants(obj, parsed)
+            return count
+        elif isinstance(obj, list):
+            for item in obj:
+                if isinstance(item, "Base"):
+                    count += 1
+                    count += self._count_descendants(item, parsed)
+                else:
+                    count += self._handle_object_count(item, parsed)
+        elif isinstance(obj, dict):
+            for _, value in obj.items():
+                if isinstance(value, "Base"):
+                    count += 1
+                    count += self._count_descendants(value, parsed)
+                else:
+                    count += self._handle_object_count(value, parsed)
+        return count
+
+
+Base.update_forward_refs()
+
+
+class DataChunk(Base, speckle_type="Speckle.Core.Models.DataChunk"):
+    data: Union[List[Any], None] = None
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.data = []

specklepy/objects/encoding.py

@@ -0,0 +1,131 @@
+from enum import Enum
+from typing import Any, Callable, List, Type, Dict
+
+from specklepy.logging.exceptions import SpeckleException
+from specklepy.objects.base import Base
+
+
+class CurveTypeEncoding(int, Enum):
+    Arc = 0
+    Circle = 1
+    Curve = 2
+    Ellipse = 3
+    Line = 4
+    Polyline = 5
+    Polycurve = 6
+
+    @property
+    def object_class(self) -> Type:
+        from . import geometry
+
+        if self == self.Arc:
+            return geometry.Arc
+        elif self == self.Circle:
+            return geometry.Circle
+        elif self == self.Curve:
+            return geometry.Curve
+        elif self == self.Ellipse:
+            return geometry.Ellipse
+        elif self == self.Line:
+            return geometry.Line
+        elif self == self.Polyline:
+            return geometry.Polyline
+        elif self == self.Polycurve:
+            return geometry.Polycurve
+        raise SpeckleException(
+            f"No corresponding object class for CurveTypeEncoding: {self}"
+        )
+
+
+def curve_from_list(args: List[float]):
+    curve_type = CurveTypeEncoding(args[0])
+    return curve_type.object_class.from_list(args)
+
+
+class ObjectArray:
+    def __init__(self, data: list = None) -> None:
+        self.data = data or []
+
+    @classmethod
+    def from_objects(cls, objects: List[Base]) -> "ObjectArray":
+        data_list = cls()
+        if not objects:
+            return data_list
+
+        speckle_type = objects[0].speckle_type
+
+        for obj in objects:
+            if speckle_type != obj.speckle_type:
+                raise SpeckleException(
+                    "All objects in chunk should have the same speckle_type. "
+                    f"Found {speckle_type} and {obj.speckle_type}"
+                )
+            data_list.encode_object(obj=obj)
+
+        return data_list
+
+    @staticmethod
+    def decode_data(
+        data: List[Any], decoder: Callable[[List[Any]], Base], **kwargs: Dict[str, Any]
+    ) -> List[Base]:
+        bases = []
+        if not data:
+            return bases
+        index = 0
+        while index < len(data):
+            item_length = int(data[index])
+            item_start = index + 1
+            item_end = item_start + item_length
+            item_data = data[item_start:item_end]
+            index = item_end
+            decoded_data = decoder(item_data, **kwargs)
+            bases.append(decoded_data)
+
+        return bases
+
+    def decode(self, decoder: Callable[[List[Any]], Any], **kwargs: Dict[str, Any]):
+        return self.decode_data(data=self.data, decoder=decoder, **kwargs)
+
+    def encode_object(self, obj: Base):
+        encoded = obj.to_list()
+        encoded.insert(0, len(encoded))
+        self.data.extend(encoded)
+
+
+class CurveArray(ObjectArray):
+    @classmethod
+    def from_curve(cls, curve: Base) -> "CurveArray":
+        crv_array = cls()
+        crv_array.data = curve.to_list()
+        return crv_array
+
+    @classmethod
+    def from_curves(cls, curves: List[Base]) -> "CurveArray":
+        data = []
+        for curve in curves:
+            curve_list = curve.to_list()
+            curve_list.insert(0, len(curve_list))
+            data.extend(curve_list)
+        crv_array = cls()
+        crv_array.data = data
+        return crv_array
+
+    @staticmethod
+    def curve_from_list(args: List[float]) -> Base:
+        curve_type = CurveTypeEncoding(args[0])
+        return curve_type.object_class.from_list(args)
+
+    @property
+    def type(self) -> CurveTypeEncoding:
+        return CurveTypeEncoding(self.data[0])
+
+    def to_curve(self) -> Base:
+        return self.type.object_class.from_list(self.data)
+
+    @classmethod
+    def _curve_decoder(cls, data: List[float]) -> Base:
+        crv_array = cls(data)
+        return crv_array.to_curve()
+
+    def to_curves(self) -> List[Base]:
+        return self.decode(decoder=self._curve_decoder)

specklepy/objects/fakemesh.py

@@ -0,0 +1,52 @@
+from enum import Enum
+from typing import List
+from specklepy.objects.geometry import Point
+
+from .base import Base
+
+CHUNKABLE_PROPS = {
+    "vertices": 100,
+    "faces": 100,
+    "colors": 100,
+    "textureCoordinates": 100,
+    "test_bases": 10,
+}
+
+DETACHABLE = {"detach_this", "origin", "detached_list"}
+
+
+class FakeGeo(Base, chunkable={"dots": 50}, detachable={"pointslist"}):
+    pointslist: List[Base] = None
+    dots: List[int] = None
+
+
+class FakeDirection(Enum):
+    NORTH = 1
+    EAST = 2
+    SOUTH = 3
+    WEST = 4
+
+
+class FakeMesh(FakeGeo, chunkable=CHUNKABLE_PROPS, detachable=DETACHABLE):
+    vertices: List[float] = None
+    faces: List[int] = None
+    colors: List[int] = None
+    textureCoordinates: List[float] = None
+    cardinal_dir: FakeDirection = None
+    test_bases: List[Base] = None
+    detach_this: Base = None
+    detached_list: List[Base] = None
+    _origin: Point = None
+
+    # def __init__(self, **kwargs) -> None:
+    #     super(FakeMesh, self).__init__(**kwargs)
+    #     self.add_chunkable_attrs(**CHUNKABLE_PROPS)
+    #     self.add_detachable_attrs(DETACHABLE)
+
+    @property
+    def origin(self):
+        return self._origin
+
+    @origin.setter
+    def origin(self, value: Point):
+        self._origin = value

specklepy/objects/geometry.py

@@ -0,0 +1,890 @@
+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
+
+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})"
+
+    @classmethod
+    def from_list(cls, args: List[float]) -> "Point":
+        """Create a new Point from a list of three floats representing the x, y, and z coordinates"""
+        return cls(x=args[0], y=args[1], z=args[2])
+
+    def to_list(self) -> List[Any]:
+        return [self.x, self.y, self.z]
+
+    @classmethod
+    def from_coords(cls, x: float = 0.0, y: float = 0.0, z: float = 0.0):
+        """Create a new Point from x, y, and z values"""
+        pt = Point()
+        pt.x, pt.y, pt.z = x, y, z
+        return pt
+
+
+class Vector(Point, speckle_type=GEOMETRY + "Vector"):
+    pass
+
+
+class ControlPoint(Point, speckle_type=GEOMETRY + "ControlPoint"):
+    weight: float = None
+
+
+class Plane(Base, speckle_type=GEOMETRY + "Plane"):
+    origin: Point = Point()
+    normal: Vector = Vector()
+    xdir: Vector = Vector()
+    ydir: Vector = Vector()
+
+    @classmethod
+    def from_list(cls, args: List[Any]) -> "Plane":
+        return cls(
+            origin=Point.from_list(args[:3]),
+            normal=Vector.from_list(args[3:6]),
+            xdir=Vector.from_list(args[6:9]),
+            ydir=Vector.from_list(args[9:12]),
+            units=get_units_from_encoding(args[-1]),
+        )
+
+    def to_list(self) -> List[Any]:
+        return [
+            *self.origin.to_list(),
+            *self.normal.to_list(),
+            *self.xdir.to_list(),
+            *self.ydir.to_list(),
+            get_encoding_from_units(self.units),
+        ]
+
+
+class Box(Base, speckle_type=GEOMETRY + "Box"):
+    basePlane: Plane = Plane()
+    ySize: Interval = Interval()
+    zSize: Interval = Interval()
+    xSize: Interval = Interval()
+    area: float = None
+    volume: float = None
+
+
+class Line(Base, speckle_type=GEOMETRY + "Line"):
+    start: Point = Point()
+    end: Point = None
+    domain: Interval = None
+    bbox: Box = None
+    length: float = None
+
+    @classmethod
+    def from_list(cls, args: List[Any]) -> "Line":
+        return cls(
+            start=Point.from_list(args[1:4]),
+            end=Point.from_list(args[4:7]),
+            domain=Interval.from_list(args[7:10]),
+            units=get_units_from_encoding(args[-1]),
+        )
+
+    def to_list(self) -> List[Any]:
+        domain = self.domain.to_list() if self.domain else [0, 1]
+        return [
+            CurveTypeEncoding.Line.value,
+            *self.start.to_list(),
+            *self.end.to_list(),
+            *domain,
+            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
+
+    @classmethod
+    def from_list(cls, args: List[Any]) -> "Arc":
+        return cls(
+            radius=args[1],
+            startAngle=args[2],
+            endAngle=args[3],
+            angleRadians=args[4],
+            domain=Interval.from_list(args[5:7]),
+            plane=Plane.from_list(args[7:20]),
+            startPoint=Point.from_list(args[20:23]),
+            midPoint=Point.from_list(args[23:26]),
+            endPoint=Point.from_list(args[26:29]),
+            units=get_units_from_encoding(args[-1]),
+        )
+
+    def to_list(self) -> List[Any]:
+        return [
+            CurveTypeEncoding.Arc.value,
+            self.radius,
+            self.startAngle,
+            self.endAngle,
+            self.angleRadians,
+            *self.domain.to_list(),
+            *self.plane.to_list(),
+            *self.startPoint.to_list(),
+            *self.midPoint.to_list(),
+            *self.endPoint.to_list(),
+            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
+
+    @classmethod
+    def from_list(cls, args: List[Any]) -> "Circle":
+        return cls(
+            radius=args[1],
+            domain=Interval.from_list(args[2:4]),
+            plane=Plane.from_list(args[4:17]),
+            units=get_units_from_encoding(args[-1]),
+        )
+
+    def to_list(self) -> List[Any]:
+        return [
+            CurveTypeEncoding.Circle.value,
+            self.radius,
+            *self.domain.to_list(),
+            *self.plane.to_list(),
+            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
+
+    @classmethod
+    def from_list(cls, args: List[Any]) -> "Ellipse":
+        return cls(
+            firstRadius=args[1],
+            secondRadius=args[2],
+            domain=Interval.from_list(args[3:5]),
+            plane=Plane.from_list(args[5:18]),
+            units=get_units_from_encoding(args[-1]),
+        )
+
+    def to_list(self) -> List[Any]:
+        return [
+            CurveTypeEncoding.Ellipse.value,
+            self.firstRadius,
+            self.secondRadius,
+            *self.domain.to_list(),
+            *self.plane.to_list(),
+            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
+
+    @classmethod
+    def from_points(cls, points: List[Point]):
+        """Create a new Polyline from a list of Points"""
+        polyline = cls()
+        polyline.units = points[0].units
+        polyline.value = []
+        for point in points:
+            polyline.value.extend([point.x, point.y, point.z])
+        return polyline
+
+    @classmethod
+    def from_list(cls, args: List[Any]) -> "Polyline":
+        point_count = args[4]
+        return cls(
+            closed=bool(args[1]),
+            domain=Interval.from_list(args[2:4]),
+            value=args[5 : 5 + point_count],
+            units=get_units_from_encoding(args[-1]),
+        )
+
+    def to_list(self) -> List[Any]:
+        return [
+            CurveTypeEncoding.Polyline.value,
+            int(self.closed),
+            *self.domain.to_list(),
+            len(self.value),
+            *self.value,
+            get_encoding_from_units(self.units),
+        ]
+
+    def as_points(self) -> List[Point]:
+        """Converts the `value` attribute to a list of Points"""
+        if not self.value:
+            return
+
+        if len(self.value) % 3:
+            raise ValueError("Points array malformed: length%3 != 0.")
+
+        values = iter(self.value)
+        return [
+            Point(x=v, y=next(values), z=next(values), units=self.units) for v in values
+        ]
+
+
+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
+
+    def as_points(self) -> List[Point]:
+        """Converts the `value` attribute to a list of Points"""
+        if not self.points:
+            return
+
+        if len(self.points) % 3:
+            raise ValueError("Points array malformed: length%3 != 0.")
+
+        values = iter(self.points)
+        return [
+            Point(x=v, y=next(values), z=next(values), units=self.units) for v in values
+        ]
+
+    @classmethod
+    def from_list(cls, args: List[Any]) -> "Curve":
+        point_count = int(args[7])
+        weights_count = int(args[8])
+        knots_count = int(args[9])
+
+        points_start = 10
+        weights_start = 10 + point_count
+        knots_start = weights_start + weights_count
+        knots_end = knots_start + knots_count
+
+        return cls(
+            degree=int(args[1]),
+            periodic=bool(args[2]),
+            rational=bool(args[3]),
+            closed=bool(args[4]),
+            domain=Interval.from_list(args[5:7]),
+            points=args[points_start:weights_start],
+            weights=args[weights_start:knots_start],
+            knots=args[knots_start:knots_end],
+            units=get_units_from_encoding(args[-1]),
+        )
+
+    def to_list(self) -> List[Any]:
+        return [
+            CurveTypeEncoding.Curve.value,
+            self.degree,
+            int(self.periodic),
+            int(self.rational),
+            int(self.closed),
+            *self.domain.to_list(),
+            len(self.points),
+            len(self.weights),
+            len(self.knots),
+            *self.points,
+            *self.weights,
+            *self.knots,
+            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
+
+    @classmethod
+    def from_list(cls, args: List[Any]) -> "Polycurve":
+        curve_arrays = CurveArray(args[5:-1])
+        return cls(
+            closed=bool(args[1]),
+            domain=Interval.from_list(args[2:4]),
+            segments=curve_arrays.to_curves(),
+            units=get_units_from_encoding(args[-1]),
+        )
+
+    def to_list(self) -> List[Any]:
+        curve_array = CurveArray.from_curves(self.segments).data
+        return [
+            CurveTypeEncoding.Polycurve.value,
+            int(self.closed),
+            *self.domain.to_list(),
+            len(curve_array),
+            *curve_array,
+            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
+
+
+class Mesh(
+    Base,
+    speckle_type=GEOMETRY + "Mesh",
+    chunkable={
+        "vertices": 2000,
+        "faces": 2000,
+        "colors": 2000,
+        "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
+
+    @classmethod
+    def create(
+        cls,
+        vertices: List[float],
+        faces: List[int],
+        colors: List[int] = None,
+        texture_coordinates: List[float] = None,
+    ) -> "Mesh":
+        """
+        Create a new Mesh from lists representing its vertices, faces,
+        colors (optional), and texture coordinates (optional).
+
+        This will initialise empty lists for colors and texture coordinates
+        if you do not provide any.
+        """
+        return cls(
+            vertices=vertices,
+            faces=faces,
+            colors=colors or [],
+            textureCoordinates=texture_coordinates or [],
+        )
+
+
+class Surface(Base, speckle_type=GEOMETRY + "Surface"):
+    degreeU: int = None
+    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
+
+    @classmethod
+    def from_list(cls, args: List[Any]) -> "Surface":
+        point_count = int(args[11])
+        knots_u_count = int(args[12])
+        knots_v_count = int(args[13])
+
+        start_point_data = 14
+        start_knots_u = start_point_data + point_count
+        start_knots_v = start_knots_u + knots_u_count
+
+        return cls(
+            degreeU=int(args[0]),
+            degreeV=int(args[1]),
+            countU=int(args[2]),
+            countV=int(args[3]),
+            rational=bool(args[4]),
+            closedU=bool(args[5]),
+            closedV=bool(args[6]),
+            domainU=Interval(start=args[7], end=args[8]),
+            domainV=Interval(start=args[9], end=args[10]),
+            pointData=args[start_point_data:start_knots_u],
+            knotsU=args[start_knots_u:start_knots_v],
+            knotsV=args[start_knots_v : start_knots_v + knots_v_count],
+            units=get_units_from_encoding(args[-1]),
+        )
+
+    def to_list(self) -> List[Any]:
+        return [
+            self.degreeU,
+            self.degreeV,
+            self.countU,
+            self.countV,
+            int(self.rational),
+            int(self.closedU),
+            int(self.closedV),
+            *self.domainU.to_list(),
+            *self.domainV.to_list(),
+            len(self.pointData),
+            len(self.knotsU),
+            len(self.knotsV),
+            *self.pointData,
+            *self.knotsU,
+            *self.knotsV,
+            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
+
+    @property
+    def _outer_loop(self):
+        return self._Brep.Loops[self.OuterLoopIndex]  # pylint: disable=no-member
+
+    @property
+    def _surface(self):
+        return self._Brep.Surfaces[self.SurfaceIndex]  # pylint: disable=no-member
+
+    @property
+    def _loops(self):
+        if self.LoopIndices:
+            # pylint: disable=not-an-iterable, no-member
+            return [self._Brep.Loops[i] for i in self.LoopIndices]
+
+    @classmethod
+    def from_list(cls, args: List[Any], brep: "Brep" = None) -> "BrepFace":
+        return cls(
+            _Brep=brep,
+            SurfaceIndex=args[0],
+            OuterLoopIndex=args[1],
+            OrientationReversed=bool(args[2]),
+            LoopIndices=args[3:],
+        )
+
+    def to_list(self) -> List[Any]:
+        return [
+            self.SurfaceIndex,
+            self.OuterLoopIndex,
+            int(self.OrientationReversed),
+            *self.LoopIndices,
+        ]
+
+
+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
+
+    @property
+    def _start_vertex(self):
+        return self._Brep.Vertices[self.StartIndex]
+
+    @property
+    def _end_vertex(self):
+        return self._Brep.Vertices[self.EndIndex]
+
+    @property
+    def _trims(self):
+        if self.TrimIndices:
+            # pylint: disable=not-an-iterable
+            return [self._Brep.Trims[i] for i in self.TrimIndices]
+
+    @property
+    def _curve(self):
+        return self._Brep.Curve3D[self.Curve3dIndex]
+
+    @classmethod
+    def from_list(cls, args: List[Any], brep: "Brep" = None) -> "BrepEdge":
+        domain_start = args[4]
+        domain_end = args[5]
+        domain = (
+            Interval(start=domain_start, end=domain_end)
+            if None not in (domain_start, domain_end)
+            else None
+        )
+        return cls(
+            _Brep=brep,
+            Curve3dIndex=int(args[0]),
+            TrimIndices=[int(t) for t in args[6:]],
+            StartIndex=int(args[1]),
+            EndIndex=int(args[2]),
+            ProxyCurveIsReversed=bool(args[3]),
+            Domain=domain,
+        )
+
+    def to_list(self) -> List[Any]:
+        return [
+            self.Curve3dIndex,
+            self.StartIndex,
+            self.EndIndex,
+            int(self.ProxyCurveIsReversed),
+            self.Domain.start,
+            self.Domain.end,
+            *self.TrimIndices,
+        ]
+
+
+
+class BrepLoopType(int, Enum):
+    Unknown = 0
+    Outer = 1
+    Inner = 2
+    Slit = 3
+    CurveOnSurface = 4
+    PointOnSurface = 5
+
+
+class BrepLoop(Base, speckle_type=GEOMETRY + "BrepLoop"):
+    _Brep: "Brep" = None
+    FaceIndex: int = None
+    TrimIndices: List[int] = None
+    Type: BrepLoopType = None
+
+    @property
+    def _face(self):
+        return self._Brep.Faces[self.FaceIndex]
+
+    @property
+    def _trims(self):
+        if self.TrimIndices:
+            # pylint: disable=not-an-iterable
+            return [self._Brep.Trims[i] for i in self.TrimIndices]
+
+    @classmethod
+    def from_list(cls, args: List[any], brep: "Brep" = None):
+        return cls(
+            _Brep=brep,
+            FaceIndex=args[0],
+            Type=BrepLoopType(args[1]),
+            TrimIndices=args[2:],
+        )
+
+    def to_list(self) -> List[int]:
+        return [
+            self.FaceIndex,
+            self.Type.value,
+            *self.TrimIndices,
+        ]
+
+
+class BrepTrimType(int, Enum):
+    Unknown = 0
+    Boundary = 1
+    Mated = 2
+    Seam = 3
+    Singular = 4
+    CurveOnSurface = 5
+    PointOnSurface = 6
+    Slit = 7
+
+
+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
+
+    @property
+    def _face(self):
+        if self._Brep:
+            return self._Brep.Faces[self.FaceIndex]  # pylint: disable=no-member
+
+    @property
+    def _loop(self):
+        if self._Brep:
+            return self._Brep.Loops[self.LoopIndex]  # pylint: disable=no-member
+
+    @property
+    def _edge(self):
+        if self._Brep:
+            # pylint: disable=no-member
+            return self._Brep.Edges[self.EdgeIndex] if self.EdgeIndex != -1 else None
+
+    @property
+    def _curve_2d(self):
+        if self._Brep:
+            return self._Brep.Curve2D[self.CurveIndex]  # pylint: disable=no-member
+
+    @classmethod
+    def from_list(cls, args: List[Any], brep: "Brep" = None) -> "BrepTrim":
+        return cls(
+            _Brep=brep,
+            EdgeIndex=args[0],
+            StartIndex=args[1],
+            EndIndex=args[2],
+            FaceIndex=args[3],
+            LoopIndex=args[4],
+            CurveIndex=args[5],
+            IsoStatus=args[6],
+            TrimType=BrepTrimType(args[7]),
+            IsReversed=bool(args[8]),
+        )
+
+    def to_list(self) -> List[Any]:
+        return [
+            self.EdgeIndex,
+            self.StartIndex,
+            self.EndIndex,
+            self.FaceIndex,
+            self.LoopIndex,
+            self.CurveIndex,
+            self.IsoStatus,
+            self.TrimType.value,
+            int(self.IsReversed),
+        ]
+
+
+class Brep(
+    Base,
+    speckle_type=GEOMETRY + "Brep",
+    chunkable={
+        "SurfacesValue": 31250,
+        "Curve3DValues": 31250,
+        "Curve2DValues": 31250,
+        "VerticesValue": 31250,
+        "EdgesValue": 62500,
+        "LoopsValue": 62500,
+        "FacesValue": 62500,
+        "TrimsValue": 62500,
+    },
+    detachable={"displayValue"},
+    serialize_ignore={
+        "Surfaces",
+        "Curve3D",
+        "Curve2D",
+        "Vertices",
+        "Trims",
+        "Edges",
+        "Loops",
+        "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
+
+    def _inject_self_into_children(self, children: Optional[List[Base]]) -> List[Base]:
+        if children is None:
+            return children
+
+        for child in children:
+            child._Brep = self  # pylint: disable=protected-access
+        return children
+
+    # set as prop for now for backwards compatibility
+    @property
+    def displayValue(self) -> List[Mesh]:
+        return self._displayValue
+
+    @displayValue.setter
+    def displayValue(self, value):
+        if isinstance(value, Mesh):
+            self._displayValue = [value]
+        elif isinstance(value, list):
+            self._displayValue = value
+
+    @property
+    def EdgesValue(self) -> List[BrepEdge]:
+        return None if self.Edges is None else ObjectArray.from_objects(self.Edges).data
+
+    @EdgesValue.setter
+    def EdgesValue(self, value: List[float]):
+        if not value:
+            return
+
+        self.Edges = ObjectArray.decode_data(value, BrepEdge.from_list, brep=self)
+
+    @property
+    def LoopsValue(self) -> List[BrepLoop]:
+        return None if self.Loops is None else ObjectArray.from_objects(self.Loops).data
+
+    @LoopsValue.setter
+    def LoopsValue(self, value: List[int]):
+        if not value:
+            return
+
+        self.Loops = ObjectArray.decode_data(value, BrepLoop.from_list, brep=self)
+
+    @property
+    def FacesValue(self) -> List[int]:
+        return None if self.Faces is None else ObjectArray.from_objects(self.Faces).data
+
+    @FacesValue.setter
+    def FacesValue(self, value: List[int]):
+        if not value:
+            return
+
+        self.Faces = ObjectArray.decode_data(value, BrepFace.from_list, brep=self)
+
+    @property
+    def SurfacesValue(self) -> List[float]:
+        return (
+            None
+            if self.Surfaces is None
+            else ObjectArray.from_objects(self.Surfaces).data
+        )
+
+    @SurfacesValue.setter
+    def SurfacesValue(self, value: List[float]):
+        if not value:
+            return
+
+        self.Surfaces = ObjectArray.decode_data(value, Surface.from_list)
+
+    @property
+    def Curve3DValues(self) -> List[float]:
+        return (
+            None if self.Curve3D is None else CurveArray.from_curves(self.Curve3D).data
+        )
+
+    @Curve3DValues.setter
+    def Curve3DValues(self, value: List[float]):
+        crv_array = CurveArray(value)
+        self.Curve3D = crv_array.to_curves()
+
+    @property
+    def Curve2DValues(self) -> List[Base]:
+        return (
+            None if self.Curve2D is None else CurveArray.from_curves(self.Curve2D).data
+        )
+
+    @Curve2DValues.setter
+    def Curve2DValues(self, value: List[float]):
+        crv_array = CurveArray(value)
+        self.Curve2D = crv_array.to_curves()
+
+    @property
+    def VerticesValue(self) -> List[Point]:
+        if self.Vertices is None:
+            return None
+        encoded_unit = get_encoding_from_units(self.Vertices[0].units)
+        values = [encoded_unit]
+        for vertex in self.Vertices:
+            values.extend(vertex.to_list())
+        return values
+
+    @VerticesValue.setter
+    def VerticesValue(self, value: List[float]):
+        value = value.copy()
+        units = get_units_from_encoding(value.pop(0))
+
+        vertices = []
+
+        for i in range(0, len(value), 3):
+            vertex = Point.from_list(value[i : i + 3])
+            vertex._units = units
+            vertices.append(vertex)
+
+        self.Vertices = vertices
+
+    # TODO: can this be consistent with loops, edges, faces, curves, etc and prepend with the chunk list? needs to happen in sharp first
+    @property
+    def TrimsValue(self) -> List[float]:
+        # return None if self.Trims is None else ObjectArray.from_objects(self.Trims).data
+        if not self.Trims:
+            return
+        value = []
+        for trim in self.Trims:
+            value.extend(trim.to_list())
+        return value
+
+    @TrimsValue.setter
+    def TrimsValue(self, value: List[float]):
+        if not value:
+            return
+
+        # self.Trims = ObjectArray.decode_data(value, BrepTrim.from_list, brep=self)
+        self.Trims = [
+            BrepTrim.from_list(value[i : i + 9], self) for i in range(0, len(value), 9)
+        ]
+
+
+BrepEdge.update_forward_refs()
+BrepLoop.update_forward_refs()
+BrepTrim.update_forward_refs()
+BrepFace.update_forward_refs()

specklepy/objects/other.py

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

specklepy/objects/structural/__init__.py

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

specklepy/objects/structural/analysis.py

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

specklepy/objects/structural/axis.py

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

specklepy/objects/structural/geometry.py

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

specklepy/objects/structural/loading.py

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

specklepy/objects/structural/material.py

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

specklepy/objects/structural/properties.py

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

specklepy/objects/structural/results.py

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

specklepy/objects/units.py

@@ -0,0 +1,63 @@
+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/serialization/base_object_serializer.py

@@ -1,17 +1,21 @@
-import hashlib
 import re
-import warnings
-from enum import Enum
-from typing import Any, Dict, List, Optional, Tuple
-from uuid import uuid4
-from warnings import warn
-
 import ujson
+import hashlib
+import warnings
+from uuid import uuid4
+from enum import Enum
+from warnings import warn
+from typing import Any, Dict, List, Tuple
+from specklepy.objects.base import Base, DataChunk
+from specklepy.logging.exceptions import (
+    SpeckleException,
+    SpeckleWarning,
+)
+from specklepy.transports.abstract_transport import AbstractTransport
 
 # import for serialization
-from specklepy.logging.exceptions import SpeckleException, SpeckleWarning
+import specklepy.objects.geometry
-from specklepy.objects.base import Base, DataChunk
+import specklepy.objects.other
-from specklepy.transports.abstract_transport import AbstractTransport
 
 PRIMITIVES = (int, float, str, bool)
 
@@ -27,10 +31,8 @@ def safe_json_loads(obj: str, obj_id=None) -> Any:
         import json
 
         warn(
-            f"Failed to deserialise object (id: {obj_id}). This is likely a ujson big"
+            f"Failed to deserialise object (id: {obj_id}). This is likely a ujson big int error - falling back to json. \nError: {err}",
-            f" int error - falling back to json. \nError: {err}",
             SpeckleWarning,
-            stacklevel=2,
         )
         return json.loads(obj)
 
@@ -42,15 +44,9 @@ class BaseObjectSerializer:
     lineage: List[str]  # keeps track of hash chain through the object tree
     family_tree: Dict[str, Dict[str, int]]
     closure_table: Dict[str, Dict[str, int]]
-    deserialized: Dict[
+    deserialized: Dict[str, Base]   # holds deserialized objects so objects with same id return the same instance
-        str, Base
-    ]  # holds deserialized objects so objects with same id return the same instance
 
-    def __init__(
+    def __init__(self, write_transports: List[AbstractTransport] = None, read_transport=None) -> None:
-        self,
-        write_transports: Optional[List[AbstractTransport]] = None,
-        read_transport: Optional[AbstractTransport] = None,
-    ) -> None:
         self.write_transports = write_transports or []
         self.read_transport = read_transport
         self.detach_lineage = []
@@ -65,23 +61,21 @@ class BaseObjectSerializer:
             base {Base} -- the base object to be decomposed and serialized
 
         Returns:
-            (str, str) -- a tuple containing the object id of the base object and
+            (str, str) -- a tuple containing the object id of the base object and the serialized object string
-            the serialized object string
         """
 
         obj_id, obj = self.traverse_base(base)
 
         return obj_id, ujson.dumps(obj)
 
-    def traverse_base(self, base: Base) -> Tuple[str, Dict[str, Any]]:
+    def traverse_base(self, base: Base) -> Tuple[str, Dict]:
         """Decomposes the given base object and builds a serializable dictionary
 
         Arguments:
             base {Base} -- the base object to be decomposed and serialized
 
         Returns:
-            (str, dict) -- a tuple containing the object id of the base object and
+            (str, dict) -- a tuple containing the object id of the base object and the constructed serializable dictionary
-            the constructed serializable dictionary
         """
         self.__reset_writer()
 
@@ -141,8 +135,7 @@ class BaseObjectSerializer:
                 object_builder[prop] = value
                 continue
 
-            # NOTE: for dynamic props, this won't be re-serialised
+            # NOTE: for dynamic props, this won't be re-serialised as an enum but as an int
-            # as an enum but as an int
             if isinstance(value, Enum):
                 object_builder[prop] = value.value
                 continue
@@ -199,9 +192,8 @@ class BaseObjectSerializer:
 
         # write detached or root objects to transports
         if detached and self.write_transports:
-            serialized_data = ujson.dumps(object_builder)
             for t in self.write_transports:
-                t.save_object(id=obj_id, serialized_object=serialized_data)
+                t.save_object(id=obj_id, serialized_object=ujson.dumps(object_builder))
 
         del self.lineage[-1]
 
@@ -216,8 +208,6 @@ class BaseObjectSerializer:
         Returns:
             Any -- a serializable version of the given object
         """
-        if obj is None:
-            return None
         if isinstance(obj, PRIMITIVES):
             return obj
 
@@ -225,7 +215,7 @@ class BaseObjectSerializer:
         if isinstance(obj, Enum):
             return obj.value
 
-        elif isinstance(obj, list | tuple | set):
+        elif isinstance(obj, (list, tuple, set)):
             if not detach:
                 return [self.traverse_value(o) for o in obj]
 
@@ -255,20 +245,16 @@ class BaseObjectSerializer:
         else:
             try:
                 return obj.dict()
-            except Exception:
+            except:
                 warn(
-                    f"Failed to handle {type(obj)} in"
+                    f"Failed to handle {type(obj)} in `BaseObjectSerializer.traverse_value`",
-                    " `BaseObjectSerializer.traverse_value`",
                     SpeckleWarning,
-                    stacklevel=2,
                 )
 
                 return str(obj)
 
     def detach_helper(self, ref_id: str) -> Dict[str, str]:
-        """
+        """Helper to keep track of detached objects and their depth in the family tree and create reference objects to place in the parent object
-        Helper to keep track of detached objects and their depth in the family tree
-        and create reference objects to place in the parent object
 
         Arguments:
             ref_id {str} -- the id of the fully traversed object
@@ -291,10 +277,7 @@ class BaseObjectSerializer:
         }
 
     def __reset_writer(self) -> None:
-        """
+        """Reinitializes the lineage, and other variables that get used during the json writing process"""
-        Reinitializes the lineage, and other variables that get used during the json
-        writing process
-        """
         self.detach_lineage = [True]
         self.lineage = []
         self.family_tree = {}
@@ -311,7 +294,7 @@ class BaseObjectSerializer:
         """
         if not obj_string:
             return None
-
+        
         self.deserialized = {}
         obj = safe_json_loads(obj_string)
         return self.recompose_base(obj=obj)
@@ -346,11 +329,7 @@ class BaseObjectSerializer:
         object_type = Base.get_registered_type(speckle_type)
 
         # initialise the base object using `speckle_type` fall back to base if needed
-        base = (
+        base = object_type() if object_type else Base.of_type(speckle_type=speckle_type)
-            object_type.__new__(object_type)
-            if object_type
-            else Base.of_type(speckle_type=speckle_type)
-        )
         # get total children count
         if "__closure" in obj:
             if not self.read_transport:
@@ -375,10 +354,8 @@ class BaseObjectSerializer:
                     base.__setattr__(prop, self.recompose_base(obj=ref_obj))
                 else:
                     warnings.warn(
-                        f"Could not find the referenced child object of id `{ref_id}`"
+                        f"Could not find the referenced child object of id `{ref_id}` in the given read transport: {self.read_transport.name}",
-                        f" in the given read transport: {self.read_transport.name}",
                         SpeckleWarning,
-                        stacklevel=2,
                     )
                     base.__setattr__(prop, self.handle_value(value))
 
@@ -392,8 +369,7 @@ class BaseObjectSerializer:
         return base
 
     def handle_value(self, obj: Any):
-        """Helper for recomposing a base object by handling the dictionary
+        """Helper for recomposing a base object by handling the dictionary representation's values
-        representation's values
 
         Arguments:
             obj {Any} -- a value from the base object dictionary
@@ -439,10 +415,8 @@ class BaseObjectSerializer:
         ref_obj_str = self.read_transport.get_object(id=ref_id)
         if not ref_obj_str:
             warnings.warn(
-                f"Could not find the referenced child object of id `{ref_id}` in the"
+                f"Could not find the referenced child object of id `{ref_id}` in the given read transport: {self.read_transport.name}",
-                f" given read transport: {self.read_transport.name}",
                 SpeckleWarning,
-                stacklevel=2,
             )
             return obj
 

specklepy/transports/abstract_transport.py

@@ -1,12 +1,24 @@
 from abc import ABC, abstractmethod
-from typing import Dict, List, Optional
+from typing import Optional, List, Dict
+from pydantic import BaseModel
+from pydantic.main import Extra
+
+#  __________________
+# |                  |
+# |  this is v wip   |
+# |  pls be careful  |
+# |__________________|
+# (\__/) ||
+# (•ㅅ•)  ||
+# / 　 づ
 
 
-class AbstractTransport(ABC):
+class AbstractTransport(ABC, BaseModel):
+    _name: str = "Abstract"
+
     @property
-    @abstractmethod
     def name(self):
-        pass
+        return type(self)._name
 
     @abstractmethod
     def begin_write(self) -> None:
@@ -15,9 +27,7 @@ class AbstractTransport(ABC):
 
     @abstractmethod
     def end_write(self) -> None:
-        """
+        """Optional: signals to the transport that no more items will need to be written."""
-        Optional: signals to the transport that no more items will need to be written.
-        """
         pass
 
     @abstractmethod
@@ -38,8 +48,7 @@ class AbstractTransport(ABC):
 
         Arguments:
             id {str} -- the hash of the object
-            source_transport {AbstractTransport)
+            source_transport {AbstractTransport) -- the transport through which the object can be found
-            -- the transport through which the object can be found
         """
         pass
 
@@ -51,8 +60,7 @@ class AbstractTransport(ABC):
             id {str} -- the hash of the object
 
         Returns:
-            str -- the full string representation
+            str -- the full string representation of the object (or null if no object is found)
-            of the object (or null if no object is found)
         """
         pass
 
@@ -64,8 +72,7 @@ class AbstractTransport(ABC):
             id_list -- List of object id to be checked
 
         Returns:
-            Dict[str, bool] -- keys: input ids, values:
+            Dict[str, bool] -- keys: input ids, values: whether the transport has that object
-                whether the transport has that object
         """
         pass
 
@@ -77,9 +84,12 @@ class AbstractTransport(ABC):
 
         Arguments:
             id {str} -- the id of the object you want to copy
-            target_transport {AbstractTransport}
+            target_transport {AbstractTransport} -- the transport you want to copy the object to
-                -- the transport you want to copy the object to
         Returns:
             str -- the string representation of the root object
         """
         pass
+
+    class Config:
+        extra = Extra.allow
+        arbitrary_types_allowed = True

specklepy/transports/memory.py

@@ -1,18 +1,16 @@
-from typing import Dict, List
+from typing import Any, List, Dict
-
 from specklepy.transports.abstract_transport import AbstractTransport
 
 
 class MemoryTransport(AbstractTransport):
-    def __init__(self, name="Memory") -> None:
+    _name: str = "Memory"
-        super().__init__()
+    objects: dict = {}
-        self._name = name
+    saved_object_count: int = 0
-        self.objects = {}
-        self.saved_object_count = 0
 
-    @property
+    def __init__(self, name=None, **data: Any) -> None:
-    def name(self) -> str:
+        super().__init__(**data)
-        return self._name
+        if name:
+            self._name = name
 
     def __repr__(self) -> str:
         return f"MemoryTransport(objects: {len(self.objects)})"
@@ -27,8 +25,8 @@ class MemoryTransport(AbstractTransport):
     ) -> None:
         raise NotImplementedError
 
-    def get_object(self, id: str) -> str | None:
+    def get_object(self, id: str) -> str or None:
-        return self.objects.get(id, None)
+        return self.objects[id] if id in self.objects else None
 
     def has_objects(self, id_list: List[str]) -> Dict[str, bool]:
         return {id: (id in self.objects) for id in id_list}

specklepy/transports/server/__init__.py

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

specklepy/transports/server/batch_sender.py

@@ -1,25 +1,22 @@
-import gzip
 import json
 import logging
-import queue
 import threading
+import queue
+import gzip
 
 import requests
-
 from specklepy.logging.exceptions import SpeckleException
-from specklepy.transports.server.retry_policy import setup_session
 
 LOG = logging.getLogger(__name__)
 
 
-class BatchSender:
+class BatchSender(object):
     def __init__(
         self,
         server_url,
         stream_id,
         token,
         max_batch_size_mb=1,
-        max_batch_length=20000,
         batch_buffer_length=10,
         thread_count=4,
     ):
@@ -28,7 +25,6 @@ class BatchSender:
         self._token = token
 
         self.max_size = int(max_batch_size_mb * 1000 * 1000)
-        self.max_batch_length = int(max_batch_length)
         self._batches = queue.Queue(batch_buffer_length)
         self._crt_batch = []
         self._crt_batch_size = 0
@@ -42,11 +38,7 @@ class BatchSender:
             self._create_threads()
 
         crt_obj_size = len(obj)
-        crt_batch_length = len(self._crt_batch)
+        if not self._crt_batch or self._crt_batch_size + crt_obj_size < self.max_size:
-        if not self._crt_batch or (
-            self._crt_batch_size + crt_obj_size < self.max_size
-            and crt_batch_length < self.max_batch_length
-        ):
             self._crt_batch.append((id, obj))
             self._crt_batch_size += crt_obj_size
             return
@@ -73,7 +65,10 @@ class BatchSender:
 
     def _sending_thread_main(self):
         try:
-            session = setup_session(self._token)
+            session = requests.Session()
+            session.headers.update(
+                {"Authorization": f"Bearer {self._token}", "Accept": "text/plain"}
+            )
 
             while True:
                 batch = self._batches.get()
@@ -94,18 +89,17 @@ class BatchSender:
             self._exception = self._exception or ex
             LOG.error("ServerTransport sending thread error: " + str(ex))
 
-    def _bg_send_batch(self, session: requests.Session, batch):
+    def _bg_send_batch(self, session, batch):
         object_ids = [obj[0] for obj in batch]
-        response = session.post(
+        try:
-            url=f"{self.server_url}/api/diff/{self.stream_id}",
+            server_has_object = session.post(
-            data={"objects": json.dumps(object_ids)},
+                url=f"{self.server_url}/api/diff/{self.stream_id}",
-        )
+                data={"objects": json.dumps(object_ids)},
-        if response.status_code == 403:
+            ).json()
+        except Exception as ex:
             raise SpeckleException(
                 f"Invalid credentials - cannot send objects to server {self.server_url}"
-            )
+            ) from ex
-        response.raise_for_status()
-        server_has_object = response.json()
 
         new_object_ids = [x for x in object_ids if not server_has_object[x]]
         new_object_ids = set(new_object_ids)
@@ -113,22 +107,15 @@ class BatchSender:
 
         if not new_objects:
             LOG.info(
-                f"Uploading batch of {len(batch)} objects: all objects are already in"
+                f"Uploading batch of {len(batch)} objects: all objects are already in the server"
-                " the server"
             )
             return
 
         upload_data = "[" + ",".join(new_objects) + "]"
         upload_data_gzip = gzip.compress(upload_data.encode())
         LOG.info(
-            "Uploading batch of {batch_size} objects {new_object_count}: "
+            "Uploading batch of %s objects (%s new): (size: %s, compressed size: %s)"
-            + "(size: {upload_size}, compressed size: {upload_data_size})",
+            % (len(batch), len(new_objects), len(upload_data), len(upload_data_gzip))
-            {
-                "batch_size": len(batch),
-                "new_object_count": len(new_objects),
-                "upload_size": len(upload_data),
-                "upload_data_size": len(upload_data_gzip),
-            },
         )
 
         try:
@@ -139,16 +126,11 @@ class BatchSender:
             if r.status_code != 201:
                 LOG.warning("Upload server response: %s", r.text)
                 raise SpeckleException(
-                    message=(
+                    message=f"Could not save the object to the server - status code {r.status_code}"
-                        "Could not save the object to the server - status code"
-                        f" {r.status_code} ({r.text[:1000]})"
-                    )
                 )
         except json.JSONDecodeError as error:
             return SpeckleException(
-                f"Failed to send objects to {self.server_url}. Please ensure this"
+                f"Failed to send objects to {self.server_url}. Please ensure this stream ({self.stream_id}) exists on this server and that you have permission to send to it.",
-                f" stream ({self.stream_id}) exists on this server and that you have"
-                " permission to send to it.",
                 error,
             )
 

specklepy/transports/server/server.py

@@ -1,75 +1,71 @@
 import json
-from typing import Dict, List, Optional
+import requests
 from warnings import warn
 
-from specklepy.core.api.client import SpeckleClient
+from typing import Any, Dict, List
-from specklepy.core.api.credentials import Account, get_account_from_token
+
+from specklepy.api.client import SpeckleClient
+from specklepy.api.credentials import Account, get_account_from_token
 from specklepy.logging.exceptions import SpeckleException, SpeckleWarning
 from specklepy.transports.abstract_transport import AbstractTransport
-from specklepy.transports.server.retry_policy import setup_session
 
 from .batch_sender import BatchSender
 
 
 class ServerTransport(AbstractTransport):
     """
-    The `ServerTransport` is the vehicle through which you transport objects to and
+    The `ServerTransport` is the vehicle through which you transport objects to and from a Speckle Server. Provide it to
-    from a Speckle Server. Provide it to `operations.send()` or `operations.receive()`.
+    `operations.send()` or `operations.receive()`.
 
-    The `ServerTransport` can be authenticated two different ways:
+    The `ServerTransport` can be authenticted two different ways:
         1. by providing a `SpeckleClient`
         2. by providing an `Account`
         3. by providing a `token` and `url`
 
     ```py
     from specklepy.api import operations
-    from specklepy.api.client import SpeckleClient
-    from specklepy.core.api.inputs.version_inputs import CreateVersionInput
     from specklepy.transports.server import ServerTransport
 
     # here's the data you want to send
     block = Block(length=2, height=4)
 
-    # here's the project and model you want to send to
+    # next create the server transport - this is the vehicle through which you will send and receive
-    project_id = "abcdefghi"
+    transport = ServerTransport(stream_id=new_stream_id, client=client)
-    model_id = "ihgfedcba"
-
-    # next, create the server transport - this is the vehicle through which
-    # you will send and receive
-    transport = ServerTransport(stream_id=project_id, client=client)
 
     # this serialises the block and sends it to the transport
     hash = operations.send(base=block, transports=[transport])
 
-    # you can now create tag this version of the model with this object
+    # you can now create a commit on your stream with this object
-    input = CreateVersionInput(
+    commid_id = client.commit.create(
-        objectId = hash,
+        stream_id=new_stream_id,
-        modelId = model_id,
+        obj_id=hash,
-        projectId = project_id,
+        message="this is a block I made in speckle-py",
     )
-    version = client.version.create(input)
     ```
     """
 
+    _name = "RemoteTransport"
+    url: str = None
+    stream_id: str = None
+    account: Account = None
+    saved_obj_count: int = 0
+    session: requests.Session = None
+
     def __init__(
         self,
         stream_id: str,
-        client: Optional[SpeckleClient] = None,
+        client: SpeckleClient = None,
-        account: Optional[Account] = None,
+        account: Account = None,
-        token: Optional[str] = None,
+        token: str = None,
-        url: Optional[str] = None,
+        url: str = None,
-        name: str = "RemoteTransport",
+        **data: Any,
     ) -> None:
-        super().__init__()
+        super().__init__(**data)
         if client is None and account is None and token is None and url is None:
             raise SpeckleException(
-                "You must provide either a client or a token and url to construct a"
+                "You must provide either a client or a token and url to construct a ServerTransport."
-                " ServerTransport."
             )
 
-        self._name = name
-        self.account = None
-        self.saved_obj_count = 0
         if account:
             self.account = account
             url = account.serverInfo.url
@@ -78,10 +74,8 @@ class ServerTransport(AbstractTransport):
             if not client.account.token:
                 warn(
                     SpeckleWarning(
-                        "Unauthenticated Speckle Client provided to Server Transport"
+                        f"Unauthenticated Speckle Client provided to Server Transport for {self.url}. Receiving from private streams will fail."
-                        f" for {url}. Receiving from private streams will fail."
+                    )
-                    ),
-                    stacklevel=2,
                 )
             else:
                 self.account = client.account
@@ -91,17 +85,14 @@ class ServerTransport(AbstractTransport):
         self.stream_id = stream_id
         self.url = url
 
-        if self.account is not None:
+        self._batch_sender = BatchSender(
-            self._batch_sender = BatchSender(
+            self.url, self.stream_id, self.account.token, max_batch_size_mb=1
-                self.url, self.stream_id, self.account.token, max_batch_size_mb=1
-            )
-        self.session = setup_session(
-            self.account.token if self.account is not None else None
         )
 
-    @property
+        self.session = requests.Session()
-    def name(self) -> str:
+        self.session.headers.update(
-        return self._name
+            {"Authorization": f"Bearer {self.account.token}", "Accept": "text/plain"}
+        )
 
     def begin_write(self) -> None:
         self.saved_obj_count = 0
@@ -127,9 +118,8 @@ class ServerTransport(AbstractTransport):
         # return obj
 
         raise SpeckleException(
-            "Getting a single object using `ServerTransport.get_object()` is not"
+            "Getting a single object using `ServerTransport.get_object()` is not implemented. To get an object from the server, please use the `SpeckleClient.object.get()` route",
-            " implemented.",
+            NotImplementedError,
-            NotImplementedError(),
         )
 
     def has_objects(self, id_list: List[str]) -> Dict[str, bool]:
@@ -144,8 +134,7 @@ class ServerTransport(AbstractTransport):
 
         if r.status_code != 200:
             raise SpeckleException(
-                f"Can't get object {self.stream_id}/{id}: HTTP error"
+                f"Can't get object {self.stream_id}/{id}: HTTP error {r.status_code} ({r.text[:1000]})"
-                f" {r.status_code} ({r.text[:1000]})"
             )
         root_obj_serialized = r.text
         root_obj = json.loads(root_obj_serialized)

specklepy/transports/sqlite.py

@@ -1,30 +1,41 @@
 import os
+import sys
+import time
+import sched
 import sqlite3
+from typing import Any, List, Dict, Tuple
+from appdirs import user_data_dir
 from contextlib import closing
-from typing import Dict, List, Optional, Tuple
-
-from specklepy.core.helpers import speckle_path_provider
-from specklepy.logging.exceptions import SpeckleException
 from specklepy.transports.abstract_transport import AbstractTransport
+from specklepy.logging.exceptions import SpeckleException
 
 
 class SQLiteTransport(AbstractTransport):
+    _name = "SQLite"
+    _base_path: str = None
+    _root_path: str = None
+    __connection: sqlite3.Connection = None
+    app_name: str = ""
+    scope: str = ""
+    saved_obj_count: int = 0
+    max_size: int = None
+    _current_batch: List[Tuple[str, str]] = None
+    _current_batch_size: int = None
+
     def __init__(
         self,
-        base_path: Optional[str] = None,
+        base_path: str = None,
-        app_name: Optional[str] = None,
+        app_name: str = None,
-        scope: Optional[str] = None,
+        scope: str = None,
         max_batch_size_mb: float = 10.0,
-        name: str = "SQLite",
+        **data: Any,
     ) -> None:
-        super().__init__()
+        super().__init__(**data)
-        self._name = name
         self.app_name = app_name or "Speckle"
         self.scope = scope or "Objects"
         self._base_path = base_path or self.get_base_path(self.app_name)
         self.max_size = int(max_batch_size_mb * 1000 * 1000)
-        self.saved_obj_count = 0
+        self._current_batch = []
-        self._current_batch: List[Tuple[str, str]] = []
         self._current_batch_size = 0
 
         try:
@@ -36,23 +47,30 @@ class SQLiteTransport(AbstractTransport):
             self.__initialise()
         except Exception as ex:
             raise SpeckleException(
-                f"SQLiteTransport could not initialise {self.scope}.db at"
+                f"SQLiteTransport could not initialise {self.scope}.db at {self._base_path}. Either provide a different `base_path` or use an alternative transport.",
-                f" {self._base_path}. Either provide a different `base_path` or use an"
+                ex,
-                " alternative transport.",
+            )
-            ) from ex
 
     def __repr__(self) -> str:
         return f"SQLiteTransport(app: '{self.app_name}', scope: '{self.scope}')"
 
-    @property
-    def name(self) -> str:
-        return self._name
-
     @staticmethod
     def get_base_path(app_name):
-        return str(
+        # from appdirs https://github.com/ActiveState/appdirs/blob/master/appdirs.py
-            speckle_path_provider.user_application_data_path().joinpath(app_name)
+        # default mac path is not the one we use (we use unix path), so using special case for this
-        )
+        system = sys.platform
+        if system.startswith("java"):
+            import platform
+
+            os_name = platform.java_ver()[3][0]
+            if os_name.startswith("Mac"):
+                system = "darwin"
+
+        if system != "darwin":
+            return user_data_dir(appname=app_name, appauthor=False, roaming=True)
+
+        path = os.path.expanduser("~/.config/")
+        return os.path.join(path, app_name)
 
     def save_object_from_transport(
         self, id: str, source_transport: AbstractTransport
@@ -61,16 +79,14 @@ class SQLiteTransport(AbstractTransport):
 
         Arguments:
             id {str} -- the object id
-            source_transport {AbstractTransport)
+            source_transport {AbstractTransport) -- the transport through which the object can be found
-            -- the transport through which the object can be found
         """
         serialized_object = source_transport.get_object(id)
         self.save_object(id, serialized_object)
 
     def save_object(self, id: str, serialized_object: str) -> None:
         """
-        Adds an object to the current batch to be written to the db.
+        Adds an object to the current batch to be written to the db. If the current batch is full,
-        If the current batch is full,
         the batch is written to the db and the current batch is reset.
 
         Arguments:
@@ -102,11 +118,11 @@ class SQLiteTransport(AbstractTransport):
                 self.__connection.commit()
         except Exception as ex:
             raise SpeckleException(
-                "Could not save the batch of objects to the local db. Inner exception:"
+                f"Could not save the batch of objects to the local db. Inner exception: {ex}",
-                f" {ex}",
+                ex,
-            ) from ex
+            )
 
-    def get_object(self, id: str) -> str | None:
+    def get_object(self, id: str) -> str or None:
         self.__check_connection()
         with closing(self.__connection.cursor()) as c:
             row = c.execute(
@@ -141,10 +157,7 @@ class SQLiteTransport(AbstractTransport):
         raise NotImplementedError
 
     def get_all_objects(self):
-        """
+        """Returns all the objects in the store. NOTE: do not use for large collections!"""
-        Returns all the objects in the store.
-        NOTE: do not use for large collections!
-        """
         self.__check_connection()
         with closing(self.__connection.cursor()) as c:
             rows = c.execute("SELECT * FROM objects").fetchall()

src/docs/Specklepy_SDK/api/client.md

@@ -1 +0,0 @@
-::: specklepy.api.client.SpeckleClient

src/docs/Specklepy_SDK/objects/Data_Objects/DataObject.md

@@ -1 +0,0 @@
-::: specklepy.objects.data_objects.DataObject

src/docs/Specklepy_SDK/objects/Data_Objects/QgisObject.md

@@ -1 +0,0 @@
-::: specklepy.objects.data_objects.QgisObject

src/docs/Specklepy_SDK/objects/Interfaces/IBlenderObject.md

@@ -1 +0,0 @@
-::: specklepy.objects.interfaces.IBlenderObject

src/docs/Specklepy_SDK/objects/Interfaces/ICurve.md

@@ -1 +0,0 @@
-::: specklepy.objects.interfaces.ICurve

src/docs/Specklepy_SDK/objects/Interfaces/IDataObject.md

@@ -1 +0,0 @@
-::: specklepy.objects.interfaces.IDataObject

src/docs/Specklepy_SDK/objects/Interfaces/IDisplayValue.md

@@ -1 +0,0 @@
-::: specklepy.objects.interfaces.IDisplayValue

src/docs/Specklepy_SDK/objects/Interfaces/IGisObject.md

@@ -1 +0,0 @@
-::: specklepy.objects.interfaces.IBlenderObject

src/docs/Specklepy_SDK/objects/Interfaces/IHasArea.md

@@ -1 +0,0 @@
-::: specklepy.objects.interfaces.IHasArea

src/docs/Specklepy_SDK/objects/Interfaces/IHasUnits.md

@@ -1 +0,0 @@
-::: specklepy.objects.interfaces.IHasUnits

src/docs/Specklepy_SDK/objects/Interfaces/IHasVolume.md

@@ -1 +0,0 @@
-::: specklepy.objects.interfaces.IHasVolume

src/docs/Specklepy_SDK/objects/Interfaces/IProperties.md

@@ -1 +0,0 @@
-::: specklepy.objects.interfaces.IProperties

src/docs/Specklepy_SDK/objects/Other/RenderMaterial.md

@@ -1 +0,0 @@
-::: specklepy.objects.other.RenderMaterial

src/docs/Specklepy_SDK/objects/Primitve/Interval.md

@@ -1 +0,0 @@
-::: specklepy.objects.primitive.Interval

src/docs/Specklepy_SDK/objects/Proxies/ColorProxy.md

@@ -1 +0,0 @@
-::: specklepy.objects.proxies.ColorProxy

src/docs/Specklepy_SDK/objects/Proxies/GroupProxy.md

@@ -1 +0,0 @@
-::: specklepy.objects.proxies.GroupProxy

src/docs/Specklepy_SDK/objects/Proxies/InstanceDefinitionProxy.md

@@ -1 +0,0 @@
-::: specklepy.objects.proxies.InstanceDefinitionProxy

src/docs/Specklepy_SDK/objects/Proxies/InstanceProxy.md

@@ -1 +0,0 @@
-::: specklepy.objects.proxies.InstanceProxy

src/docs/Specklepy_SDK/objects/Proxies/RenderMaterialProxy.md

@@ -1 +0,0 @@
-::: specklepy.objects.proxies.RenderMaterialProxy

src/docs/Specklepy_SDK/objects/base.md

@@ -1 +0,0 @@
-::: specklepy.objects.base.Base

src/docs/Specklepy_SDK/objects/geometry/Arc.md

@@ -1 +0,0 @@
-::: specklepy.objects.geometry.arc.Arc

src/docs/Specklepy_SDK/objects/geometry/Box.md

@@ -1 +0,0 @@
-::: specklepy.objects.geometry.box.Box

src/docs/Specklepy_SDK/objects/geometry/Circle.md

@@ -1 +0,0 @@
-::: specklepy.objects.geometry.circle.Circle

src/docs/Specklepy_SDK/objects/geometry/ControlPoint.md

@@ -1 +0,0 @@
-::: specklepy.objects.geometry.control_point.ControlPoint

src/docs/Specklepy_SDK/objects/geometry/Ellipse.md

@@ -1 +0,0 @@
-::: specklepy.objects.geometry.ellipse.Ellipse

src/docs/Specklepy_SDK/objects/geometry/Line.md

@@ -1 +0,0 @@
-::: specklepy.objects.geometry.line.Line

src/docs/Specklepy_SDK/objects/geometry/Mesh.md

@@ -1 +0,0 @@
-::: specklepy.objects.geometry.mesh.Mesh

src/docs/Specklepy_SDK/objects/geometry/Plane.md

@@ -1 +0,0 @@
-::: specklepy.objects.geometry.plane.Plane

src/docs/Specklepy_SDK/objects/geometry/Point.md

@@ -1 +0,0 @@
-::: specklepy.objects.geometry.point.Point

src/docs/Specklepy_SDK/objects/geometry/Point_Cloud.md

@@ -1 +0,0 @@
-::: specklepy.objects.geometry.point_cloud.PointCloud

src/docs/Specklepy_SDK/objects/geometry/Polycurve.md

@@ -1 +0,0 @@
-::: specklepy.objects.geometry.polycurve.Polycurve