Articles, Blog

Developer Training – Shotgun: Basics of the Shotgun API


Developers interact with Shotgun through the Shotgun Python API. It’s important to have easy access to that API in a Python console, so you can test commands while you are learning or building tools for Shotgun. In this video I will demonstrate several ways to gain access to a Shotgun Python API console. Here’s a quick example of something you can do with the API. Say I want a list of all Shots that belong to a Project called Animation with Cuts. I can use a find_one api call to search for a Project whose name contains the text “Cuts”. I’ll return the name field to make sure I’ve got the right Project and store the result in a variable called project. Let’s take a quick look at our Project in Shotgun, and its attached Shots before running our next query. Here we see the Shot records we’re interested in pulling down, this time we’ll use a find api call to return all the shots whose project field is linked to our project. We’re interested in the code field, which contains the name of the shot, and the sg_status_list field, we can loop over our result and display the shots list, but before we can run any api commands we need to get the api. So how do we do that? Probably the easiest way to get the API, is to go to the Shotgun GitHub site, search for python-api, go to the releases tab, and find the most recent tagged release, download the zip file. Once you’ve downloaded the file, unzip it and put it anywhere you want on your file system. In this case we’ll put it in my Documents folder. Then jump into the Terminal, locate the API in your Documents folder, or wherever you’ve put it, start up a Python console and import shotgun_api3. You’re then ready to grab a Shotgun handle and authenticate against your Shotgun Site. Pass in the URL address of your shotgun Site, your login, and password. Note that the API has the same permissions rule set as your user in Shotgun. At this point we can run the familiar find_one command to return our Project record. If you’re familiar with GitHub and want the latest version of the api, feel free to clone the master branch instead of downloading a zip file. Use git commands to pull down updates, investigate changes in the log, etc. After the API exists on disk the workflow is the same. Import the API and then authenticate. Note that this version of the API may not represent the most recent tagged release and should be considered experimental. If you’d like to install the Shotgun API as a python library, we recommend that you use pip and virtualenv. This way your system python doesn’t become cluttered with libraries, and the python environment you test the API in is clean. Visit the Shotgun Python API docs to find a variety of pip-related installation options. In this case, I want to install a specific tagged release and will use this command as reference. First I’ll create a virtual environment and activate it. Next, I can install the API with the command I copied from the docs. Remember to set the version number to match the tag or release you want to install. Once the API is installed, it can be imported from anywhere you start Python, so long as your virtual environment is active. Remember to deactivate your virtual environment when you’re done. If you’ve installed Shotgun Desktop, you have easy access to a Python console. Log into your Shotgun Site, choose a Project, and then open tk-multi-python console from the pull-down menu in the upper-right hand corner. Since you already signed in with Shotgun Desktop, an authenticated shotgun handle is available and ready to use. Additionally, the tk-desktop engine can provide access to a context object, which stores useful information, like the current project record. We can use that record to get the list of Shots attached to the current Project. If you launch a DCC from Shotgun Desktop, an API handle is available via sgtk. I’ll demonstrate how to access it from Maya, as an example. Once Maya has loaded its plugins, open a Python tab in the Script Editor and import sgtk. Then get the current engine from sgtk’s platform object. An authenticated Shotgun handle is available under the engine, as well as our familiar context object. Here is the same code being run from the Python Script Editor in Nuke. If your Project uses an advanced Toolkit configuration, you can use the tank shell command to access the API. Go to the Pipeline Configurations Page in Shotgun and display the path field. I’m on a mac, so I’m interested in the mac_path. Copy the path from the active configuration and navigate to that location in the Terminal. The tank command-line utility is linked to your Project and can be used to run a variety of commands. One of them is the shell command. If you’re already logged into Shotgun Desktop, an authenticated shotgun handle is available and ready to use, as well as our familiar engine object. In this video I’ve demonstrated several ways to access the Shotgun Python API, but there are more. Visit the Python API Docs for exhaustive and up-to-date information about API installation, usage, and examples.

Leave a Reply

Your email address will not be published. Required fields are marked *