QuickStart

Playing with a new library or API client can be daunting. We feel you! This is why we have compiled a bunch of example usage scenarios to walk you through how to use the python speckle client.

In the following set of examples we assume you don’t have your own Speckle server up and running so you can test all of the steps below by connecting to the hestia speckle server.

First we must instantiate the SpeckleApiClient. You can name it whatever you want, we will use client for simplicity. As we are connecting to the hestia test server we will input the full domain name as an argument: hestia.speckle.works

from speckle import SpeckleApiClient

client = SpeckleApiClient('hestia.speckle.works')

Registering and Logging in

Before you can do anything with Speckle you need to register yourself to the server you are going to be using. If you have already registered then you can skip the first code section below and look at the one right after where we explain how to login.

Note

When you register using a PySpeckle client this client is also authenticated and you can start using it to make API calls immediately without needing to login.

client.register(
    email='test@test.com',
    password='Speckle<3Python',
    company='SnakeySnakes',
    name='Snakey',
    surname='Snake'
)

If you are already registered then you can simply login your client as follows:

client.login(
    email='test@test.com',
    password='Speckle<3Python'
)

If your server uses an alternate login mechanism (e.g. ActiveDirectory integration), you can use the login_with_token method, using the API token that you find in your user profile on the Speckle server web interface:

client.login_with_token(
    token='JWT xwy334xdkfksldf....'
)

Sending and Retrieving Things

At the moment the api client takes dictionary payloads as data inputs (a Speckle Object for example) and returns data classes in most cases (essentially a class instance). If a data class is not returned then the object return is a dictionary.

Warning

Whether the client returns a data class or a dictionary is not yet very well segmented. To be sure you are getting back what you expect from the python client we reccomend reading through the API referemce

Attention

PySpeckle doesn’t yet support any of the websockets data transfer methods that the SpeckleServer offers. We’re working on it. Feel free to contribute if you’ve got an idea on how to implement it.

Common Methods

Speckle mostly follows a bog standard REST API setup where a user can POST, GET, PUT and DELETE different resources. As such the following verbs can be used to make standard REST calls to Speckle.

Warning

For most resources that support a get, update, delete call the id value to use to retrieve them is the object.id or Mongo ObjectId. The exception to this rule is the Stream resource which can only be retrieved by using the StreamId property of that stream.

Create

Equivalent of POST / -d '{"key1":"value1", "key2":"value2"}'

project = {
    'name': 'test project',
    'description': 'a project made for testing purposes',
    'tags': [],
    'streams': [],
}

project = client.projects.create(data=project)

print(project.id)

List

Equivalent of GET /

projects = client.projects.list()

for project in projects:
  print(project.dict())

Get

Equivalent of GET /{id}

project_id = '507f1f77bcf86cd799439011'

project = client.projects.get(project_id)

print(project.dict())

Update

Equivalent of PUT /{id} -d '{"key1":"value1", "key2":"value2"}'

Note

The update method returns a payload response dictionary rather than a resource data class. The response payload should look something like this

{
  "success": True,
  "message": "Patched ['description'] for 507f1f77bcf86cd799439011"
}

Warning

The update method will replace all the values in the input dictionary payload even if they are None. Be careful if you are trying to run upsert commands with dictionaries that contain None values

project_id = '507f1f77bcf86cd799439011'
project_update = {
    'description': 'a project updated for testing purposes',
}

response = client.projects.update(id=project_id, data=project_update)

assert response['success'], response['message']

Delete

Equivalent of DELETE /{id}

Note

The delete method returns a payload response dictionary rather than a resource data class. The response payload should look something like this

{
  "success": True,
  "message": "Project was deleted."
}
project_id = '507f1f77bcf86cd799439011'

response = client.projects.delete(id=project_id)

assert response['success'], response['message']

API Objects

If you’ve made it this far down you’re probably thinking to yourself:

Great I can login and mess with a project… anything else I can do?

—Some Ambitious User

Glad you asked! There are a bunch of different types of Speckle objects or resources you can mess with using this python client. Here is a list of them with links to their specific documentation:

Note

Each resource supports some or all of the common methods described above. Additionally each resource might support some extra methods which are specific to that resource. A good example is the stream resource which supports the clone method

streamId = 'GBexG1'

clone_stream, parent_stream = client.streams.clone(streamId)

Parting Notes

Hope you’ve found this quickstart guide useful. Please do contribute any proposed changes/improvements on the main projects github repo.