Back to top image

Python SDK

The Smartling SDK for Python simplifies the use of Smartling’s APIs from Python application code by providing a Python library for accessing the underlying REST APIs.

The SDK is distributed as a standard Python package via the PyPI repository.

Sample code that uses the SDK can be found in the Smartling Samples GitHub repository.

Source code for the SDK itself can be found in the Python SDK GitHub repository.

Setup

To use the SDK, you need the following:

  • Python installed
  • API token (user identifier and secret) for a Smartling project

Once Python is installed, you can install the SDK by entering the command:

python3 -m pip install SmartlingApiSDK

Using the SDK

Creating API clients

In order to use a particular API, such as the Jobs API or Files API, you must first create a client for that API passing the authentication credentials and any other required arguments. For example:

jobs_api = JobsApi(USER_IDENTIFIER, USER_SECRET, PROJECT_ID)
files_api = FilesApi(USER_IDENTIFIER, USER_SECRET, PROJECT_ID)

The API client takes care of calling the authentication API and refreshing the authentication access tokens automatically.

Custom client configuration

The following shows how to configure the client to use a proxy, and to include a custom header:

proxySettings = ProxySettings("login", "password", "proxy_host", "proxy_port or None")
custom_headers = {“CUSTOM_HEADER_NAME”: “CUSTOM_HEADER_VALUE”}
files_api = FilesApi(USER_IDENTIFIER, USER_SECRET, PROJECT_ID, proxySettings, custom_headers)

Making API requests

Each REST API endpoint has a corresponding method on the API client object in the SDK. Calling a method on the API client object results in an HTTP request being sent to the corresponding REST endpoint. Any parameters that are required by the REST endpoint are also required when calling the corresponding SDK client method; optional parameters can be passed as named arguments when needed.

resp, status = jobs_api.addJob(job_name, description=”description of the job”)

Method and parameter names are the same as those used in the corresponding API documentation. For example, the documentation for the ‘create job’ action is found at:

https://api-reference.smartling.com/#operation/addJob

and thus the method is named ‘addJob’ as shown in the example above. Similarly, the job description is set using the named parameter ‘description’ as shown in the request body schema documentation for that endpoint.

The following complete example lists the first 50 jobs sorted ascending by job name:

from smartlingApiSdk.Credentials import Credentials
from smartlingApiSdk.api.JobsApi import JobsApi
 
# Credentials expects the following environment variables to be defined:
# SL_USER_IDENTIFIER, SL_USER_SECRET, SL_PROJECT_ID
creds = Credentials() 
jobs_api = JobsApi(creds.MY_USER_IDENTIFIER, creds.MY_USER_SECRET, creds.MY_PROJECT_ID)
 
resp, status = jobs_api.getJobsByProject(sortBy='jobName', sortDirection='ASC', offset=0, limit=50)
for item in resp.data.items:
    print(item['jobName'])

The following call creates a job with values for additional optional parameters:

 resp, status = jobs_api.addJob(job_name,
                                targetLocaleIds=['fr-FR', 'de-DE'],
                                description='description of the job',
                                dueDate='2022-11-21T01:51:17Z',
                                referenceNumber='Ref num 1234',
                                callbackUrl='https://www.example.com/smartling/job',
                                callbackMethod='GET')

Handling responses

Most API methods in the SDK return two values: the response and the HTTP status code. The status code is simply the integer value of the status code. The response is an object representing the contents of the HTTP response from the API call. Top-level contents of the REST response (code, data and errors) are accessible as attributes of the returned response object, and top-level contents of the data node are also accessible as attributes. For example:

resp, status = jobs_api.addJob(job_name)
job_uid = resp.data.translationJobUid
resp, status = jobs_api.getJobProgress(translationJobUid=job_uid)
percent_complete = resp.data.progress['percentComplete']

Thread safety

API clients are not thread safe and therefore separate instances of the clients should be created for each thread.

Table of Contents