Standalone Python API

Overview

The Standalone Python API can be used in Python for communicating with the HTTP API (documented in REST Overview). In order to use the HTTP API you must have the Web Service running on a machine whose address and port number you know. For a list of the API’s functions and how they are used go to the Deadline Downloads page and download the documentation. Essentially, our Standalone Python API is a Python wrapper API around our RESTful HTTP API.

Note, as all communication to Deadline travels through the machine running the Web Service and not the local host, there are consequences that should be considered carefully. Any file paths provided need to be valid on the Web Service machine, including any differences between operating systems if for example, your local host is running Windows but the Web Service machine is Linux. In the case of submitting a job, the job’s username will be the user account currently running the Web Service, NOT the submitting local user, unless a UserName is provided in the job info.

Set-up

In order to use the Standalone Python API you must have Python 2.7 or later installed. Copy the “Deadline” Folder containing the Standalone Python API from \your\repository\api\python to the “site-packages” folder of your Python installation and the API is ready to use.

Using the API

A DeadlineCon object must be created which is used to communicate with the web service to send and receive requests. First enter “import Deadline.DeadlineConnect as Connect”, then create your connection object “connectionObject = Deadline.DeadlineConnect.DeadlineCon(‘PulseName’, PulsePortNumber)”, where ‘PulseName’ is the DNS name or IP address of the machine currently running the web service and ‘PulsePortNumber’ is the web service port number as configured in the Web Service settings in the Repository Options. By default it is: 8080. The “connectionObject” variable can now be used to communicate requests to the web service.

Example: Getting group names and suspending a job

>>> from Deadline.DeadlineConnect import DeadlineCon as Connect
>>> con = Connect('PulseName', 8080)
>>> con.Groups.GetGroupNames()
[u'none', u'group1', u'group2', u'group3']
>>> jobId = validjobID
>>> con.Jobs.SuspendJob(jobId)
'Success'

Documentation for all the possible API functions can be found on at the Deadline Downloads page.

Authenticating

If your Web Service has authentication enabled then you must set up authentication for the Python API. This can be achieved through the “EnableAuthentication” and “SetAuthenticationCredentials” functions. Setting your authentication credentials allows the Python API to use them for as long as that instance of python is running.

>>> from Deadline.DeadlineConnect import DeadlineCon as Connect
>>> con = Connect('PulseName', 8080)
>>> con.Groups.GetGroupNames()
"Error: HTTP Status Code 401. Authentication with the Web Service failed.
Please ensure that the authentication credentials are set, are correct, and
that authentication mode is enabled."
>>> con.AuthenticationModeEnabled()
False
>>> con.EnabledAuthentication(True)
>>> con.AuthenticationModeEnabled()
True
>>> con.SetAuthenticationCredentials("username", "password")
>>> con.Groups.GetGroupNames()
[u'none', u'group1', u'group2', u'group3']

By default “SetAuthenticationCredentials” also enables authentication, so it is not actually necessary to explicitly call “EnableAuthentication” as well. If you want to store your credentials without enabling authentication you may do so as well using the optional third parameter.

>>> con.SetAuthenticationCredentials("username", "password", False)

API Functions

All of the Standalone Python API functions return a Python dictionary, a Python list, or a Python string. Lists often contain dictionaries.

Examples: Getting a list, a list containing dictionaries, a dictionary, and a string back.

>>> groupNames = con.Groups.GetGroupNames()
>>> groupNames[0]
group1
>>> jobs = con.Jobs.GetJobs()
>>> jobs[0]['FailedChunks']
12
>>> task = con.Tasks.GetJobTask(jobId, 0)
>>> task["Errs"]
8
>>> root = con.Repository.GetRootDirectory()
>>> root
'C:/DeadlineRepository'

Example: Getting a job, changing the pool and priority then saving it.

>>> job = con.Jobs.GetJob(jobId)
>>> str(job['Props']['Pool'])
none
>>> job['Props']['Pool'] = unicode('jobPool')
>>> str(job['Props']['Pool'])
jobPool
>>> print str(job['Props']['Pri'])
50
>>> job['Props']['Pri'] = 75
>>> str(job['Props']['Pri'])
75
>>> con.Jobs.SaveJob(job)
'Success'
>>> job = con.Jobs.GetJob(jobId)
>>> str(job['Props']['Pool']) + ' ' +str(job['Props']['Pri'])
jobPool 75

Example: Submitting a ‘reserve’ VraySpawner job using Python dictionaries.

import Deadline.DeadlineConnect as Connect

if __name__ == '__main__':

    Deadline = Connect.DeadlineCon('PulseName', 8080)

    JobInfo = {
        "Name": "Submitted via Python",
        "UserName": "UserName",
        "Frames": "0-1",
        "Plugin": "VraySpawner"
        }

    PluginInfo = {
        "Version": "Max2014"
        }

    try:
        newJob = Deadline.Jobs.SubmitJob(JobInfo, PluginInfo)
        print newJob
    except:
        print "Sorry, Web Service is currently down!"

The Manual Job Submission page documents all the Job Info options available, which can be used in the above example in the Python JobInfo dictionary. Please consult the specific Application Plugin for the required and optional Plugin Info KEY=VALUE pairs required for the PluginInfo dictionary. Note, when submitting a job, the JobInfo and PluginInfo dictionaries should contain ALL the minimum necessary KEY=VALUE pairs to successfully run this plugin job type in Deadline. As the KEY=VALUE pairs are internal and change depending on the application plugin, it is recommended you submit a job normally to Deadline and then inspect the job’s Submission Params to see what KEY=VALUE pairs should be submitted for this job type. You can also use the “Export” button to take a copy of the JobInfo and PluginInfo files to submit the job using these files instead of via Python dictionaries.