Python

This API allows developers to write Python scripts that talk directly with an ftrack server. The scripts can perform operations against that server depending on granted permissions.

With any API it is important to find the right balance between flexibility and usefulness. If an API is too low level then everyone ends up writing boilerplate code for common problems and usually in an non-uniform way making it harder to share scripts with others. It's also harder to get started with such an API. Conversely, an API that attempts to be too smart can often become restrictive when trying to do more advanced functionality or optimise for performance.

With this API we have tried to strike the right balance between these two, providing an API that should be simple to use out-of-the-box, but also expose more flexibility and power when needed.

Nothing is perfect though, so please do provide feedback on ways that we can continue to improve this API for your specific needs.

Overview

📄️ Installing

Installation is simple with pip:

📄️ Tutorial

This tutorial provides a quick dive into using the API and the broad stroke concepts involved.

📄️ Understanding sessions

All communication with an ftrack server takes place through a Session. This allows more opportunity for configuring the connection, plugins etc. and also makes it possible to connect to multiple ftrack servers from within the same Python process.

📄️ Working with entities

Entity instances are Python dict-like objects whose keys correspond to attributes for that type in the system. They may also provide helper methods to perform common operations such as replying to a note:

📄️ Querying

A complete walkthrough of the query language can be found here.

📄️ Handling events

Events are generated in ftrack when things happen such as a task being updated or a new version being published. Each ~ftrack_api.session.Session can optionally connect to the event server and can be used to subscribe to specific events and perform an action as a result. That action could be updating another related entity based on a status change or generating folders when a new shot is created for example.