Skip to content

Client

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 app.speckle.systems.

To authenticate the client, you'll need to have downloaded the Speckle Manager and added your account.

from specklepy.api.client import SpeckleClient
from specklepy.api.inputs.project_inputs import ProjectCreateInput
from specklepy.api.credentials import get_default_account

# initialise the client
client = SpeckleClient(host="app.speckle.systems") # 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 project
input = ProjectCreateInput(name="a shiny new project")
project = self.project.create(input)

# or, use a project id to get an existing project from the server
new_stream = client.project.get("abcdefghij")
Source code in src/specklepy/api/client.py 
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def __init__(
    self,
    host: str = DEFAULT_HOST,
    use_ssl: bool = USE_SSL,
    verify_certificate: bool = True,
    connection_retries: int = 3,
    connection_timeout: int = 10,
) -> None:
    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.verify_certificate = verify_certificate
    self.connection_retries = connection_retries
    self.connection_timeout = connection_timeout

    self.httpclient = Client(
        transport=RequestsHTTPTransport(
            url=self.graphql,
            verify=self.verify_certificate,
            retries=self.connection_retries,
            timeout=self.connection_timeout,
        )
    )
    self.wsclient = None

    self._init_resources()

DEFAULT_HOST class-attribute instance-attribute 

DEFAULT_HOST = 'app.speckle.systems'

USE_SSL class-attribute instance-attribute 

USE_SSL = True

url instance-attribute 

url = f'{http_protocol}://{host}'

graphql instance-attribute 

graphql = f'{url}/graphql'

ws_url instance-attribute 

ws_url = f'{ws_protocol}://{host}/graphql'

account instance-attribute 

account = Account()

verify_certificate instance-attribute 

verify_certificate = verify_certificate

connection_retries instance-attribute 

connection_retries = connection_retries

connection_timeout instance-attribute 

connection_timeout = connection_timeout

httpclient instance-attribute 

httpclient = Client(
    transport=RequestsHTTPTransport(
        url=graphql,
        verify=verify_certificate,
        retries=connection_retries,
        timeout=connection_timeout,
    )
)

wsclient instance-attribute 

wsclient = None

authenticate_with_token 

authenticate_with_token(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

Source code in src/specklepy/api/client.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
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 = Account.from_token(token, self.url)
    self._set_up_client()

    userData = self.active_user.get()

    # None if the token lacked the profile:read scope or if it was None
    if userData:
        self.account.userInfo.id = userData.id
        self.account.userInfo.email = userData.email
        self.account.userInfo.name = userData.name
        self.account.userInfo.company = userData.company
        self.account.userInfo.avatar = userData.avatar

    self.account.serverInfo = self.server.get()
    self.account.serverInfo.url = self.url

authenticate_with_account 

authenticate_with_account(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

Source code in src/specklepy/api/client.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
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`
    """
    self.account = account
    self._set_up_client()

    try:
        _ = self.active_user.get()
    except SpeckleException as ex:
        if isinstance(ex.exception, TransportServerError):
            if ex.exception.code == 403:
                warn(
                    SpeckleWarning(
                        "Possibly invalid token - could not authenticate "
                        f"Speckle Client for server {self.url}"
                    ),
                    stacklevel=2,
                )
            else:
                raise ex

execute_query 

execute_query(query: str) -> Dict
Source code in src/specklepy/api/client.py 
194
195
def execute_query(self, query: str) -> Dict:
    return self.httpclient.execute(query)