Shotgun Utilities

ShotGrid Utilities Framework

A Collection of Qt objects and utilities to simplify app development and ShotGrid connectivity.
Latest Version: v5.8.0 (prod)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-framework-shotgunutils

Please Note: This document describes functionality only available if you have taken control over a Toolkit configuration. Please refer to the Shotgun Integrations User Guide for more details.

A collection of Shotgun related Helpers and utilities to make App development easier. Includes a Shotgun (MVC) Model which makes it easy to connect a Shotgun query with a standard QT View Widget such as a list view, tree view or spreadsheet. Includes a settings module which makes it easy to manage user preferences in apps and an asynchronous (background) Shotgun data retriever.


The API Reference documentation for this Framework can be found here:

Installation and Updates

Updating to the latest version

If you already have this item installed in a project and you want to get the latest version, you can run the update command. You can either navigate to the tank command that comes with that specific project, and run it there:

> cd /my_tank_configs/project_xyz
> ./tank updates

Alternatively, you can run your studio tank command and specify the project name to tell it which project to run the update check for:

> tank Project XYZ updates

Collaboration and Evolution

If you have access to the Shotgun Pipeline Toolkit, you also have access to the source code for all apps, engines and frameworks in Github where we store and manage them. Feel free to evolve these items; use them as a base for further independent development, make changes (and submit pull requests back to us!) or simply tinker with them to see how they have been built and how the toolkit works. You can access this code repository at

Special Requirements

  • You need Shotgun Pipeline Toolkit Core API version v0.19.18 or higher to use this.


No Configuration Needed!

This item does not have any options to configure!

Release Notes

Welcome to the release notes for this Framework. Below you will find an overview of all the changes we did for each release. We try to be as detailed as possible and include all bugs we have fixed, features we have added and things that may have changed. If you have questions about a particular release, don't hesitate to contact our support team!



Rebranded to ShotGrid



Fixes a bug to make "Open in Associated Application" work with SG Create



Switches from using the support email alias to pointing to the support site



Fixes an issue with actions caching in Shotgun Create.



Fixes an issue where VRED would freeze on exit.



Now suppresses imp import warnings and libpng warnings raised when using the external config loader.



Improve the config caching mechanism.



Fixes an issue where the external config loader couldn't run correctly in Python 3.



Fixes an issue where the background task manager couldn't sort thread priorities in Python 3.



Fixes a backwards compatibility issue when launching an action from Shotgun Create on a project that uses a core older than v0.19.0.



Adds Python 3 support.



ExternalCommand objects can now be updated or invalidated when the cached data becomes out of date.


A Toolkit application location and the Python interpreter can change over the scope of a project. It is now possible to update the Python interpreter to be invoked with a command or invalidate a command whose icon cannot be retrieved anymore.



QStandardItem fix for Qt 5.9.5



Adds the external configuration management API.


This module contains classes and methods for doing inspection of external environments. The typical scenario when this is helpful is if you are creating an environment with mixed contexts - for example a Shotgun ‘My Tasks’ tool which lists different items from different projects and presents a list of available commands, apps or similar for each one of them. Building this would require Toolkit to load up the different configurations for each task and introspect them.



Fixes issues with hard_refresh in ShotgunQueryModel.


During the hard refresh of a ShotgunQueryModel, the data handler's cache would be cleared out, and then the refresh process would request an update of the model's data. That call would fail, as it raised when no cache existed for the data handler. Instead, we now treat the missing cache kindly and just continue on with the update, which itself populates a fresh cache.



Fixes bug with task manager allocation for hierarchy widgets.



Fixes data_refreshed signal bug


Fixes an issue where the data_refreshed signal was always returning a True flag, thereby indicating that data had changed, effectively meaning we were generating many false positives.



Fixes high CPU usage under CentOS 7 when using PySide2.



Fixed a problem which could lead to crashes when deleting items from a Shotgun model.



Minor UI polish.


Step icons provided by Shotgun Models are now slightly transparent and don't have a black border anymore.



Fix for clean up of old cached data and old tk-core releases.


Fix a problem with tk-core releases older than v0.18.119 which would cause the clean up to fail.



Fix for clean up of old cached data.


This release fixes a deadlock problem which was introduced in v5.3.0 with the new data cleanup.



Fix for ShotgunModel only adding items for new Shotgun records.


Fix for a bug where, in some circumstances, only the new records added in Shotgun since the previous launch of an app using a ShotgunModel would be added to the model and appear in tree views. This fix improves performances as well by not automatically adding all new Shotgun data in the model when it is refreshed, but by doing it only for the expanded items in a tree view.



Clean up of old cached data.


The framework now performs a cached data clean up when it is loaded, only for the sg, sg_nav and thumbs cached folders. Files which have not been modified or accessed in the last 60 days are removed to prevent the cache to grow indefinitely.



Ability to cache thumbnails and Shotgun queries at the site level.


Thumbnails and Shotgun queries are now cached at the site level, instead of being cached per projet, pipeline configuration and plugin id, if the version of tk-core being used supports it.



Works around a thread safety bug in the datetime module.


The fix employed here comes from the Python bug report and appears to resolve the issue entirely. Linked in the code is the stackoverflow that provides more information and links back to the original Python bug ticket.



Provides a safe_delete_later utility function.


This function is used in place of QWidget.deleteLater, which behaves differently in Qt5 than it did in Qt4. Making use of this utility function helps reduce issues with garbage collection of C++ objects in PySide2/Qt5 environments.



Adds include_root option to hierarchy model for displaying root item



Hierarchy related additions and changes


  • Adds data retriever support for nav search methods. If used with an older core/shotgun API which does not have the nav search methods accessible, it degrades gracefully and returns an empty data set.
  • Adds async expansion/fetch_more methods to the hierarchy model via the async_item_from_entity and async_item_from_paths methods.
  • Upgrades to 0.18 logging and bumps minimum required core to 18.45.
  • The hierarchy model _load_data method has a breaking interface change. Previously, it would take a path argument, now it takes a root argument instead in order to avoid using path strings to drive the API.



Documentation updates



Downgraded log messages regarding extra cache files from 'warning' to 'debug' in ShotgunDataRetriever._get_thumbnail_path(). Removed old thumbnail cache path logic that was replaced in March 2015. If any of the old thumbnails still exist, they will now be recached into the new directory structure.



Properly retrieve the application palette for both Qt 4 and Qt 5 when initializing the Hierarchy model.



Added ShotgunDataRetriever methods to download entity thumbnail source files


  • Added ShotgunDataRetriever.download_thumbnail_source(entity_type, entity_id, bundle) and Shotgun DataRetriever.request_thumbnail_source(entity_type, entity_id) methods that retrieve the original file uploaded as an entity thumbnail.
  • If the source file has already been cached, a path to it will be returned instantly. Otherwise, it will be downloaded from Shotgun and placed in the standard cache location on disk.
  • The full path to the downloaded file is returned.

  • Updated all download calls to use the newly introduced use_url_extension parameter of sgtk.util.download_url() which derives the filetype extension for the cache file from the resolved url, instead of hard-coding it to ".jpeg". If the use_url_extension functionality is not available, the previous behavior of using ".jpeg" for all cache files will be envoked.



Optimization and deferred loading.

Note: This is a major revision bump to indicate a changed behavior.

As of v5, the ShotgunModel and HierarchyModel classes implement a new, optimized data backend to better handle large datasets. The models now load and save significantly faster and can handle orders of magnitude more data.

The trade-off in order to achieve this speed increase is that the data set is loaded into memory in a deferred fashion. If you visualise a tree of tasks, grouped by step, shot, sequence and project, the data will be loaded as you click the expand icon in the UI. Previously, the entire model was loaded at initialization.

This is a change in behaviour and means that certain operations will not work the same way in v5 as they did in v4 of the Shotgun Model. One example is filtering using the QSortFilterProxyModel, which assumes a model where everything is loaded. In order to achieve the same behavior with ShotgunModel v5, the entire model needs to be loaded prior to filtering. This can be achieved via the helper method ShotgunModel.ensure_data_is_loaded

In addition, the model has been updated to correctly retain state when data is updated or deleted. Previously, these operations would force a model reset. Now, when new shotgun data arrives, the model correctly handles all update cases, so if an item has been updated or deleted, the model is no longer cleared but instead updated. Any selection that exists in associated views will be retained.



All schema cache methods that accept entity type and field now handle bubble field notation



API Documentation updates only, no code changes.



Including hierarchy model docs.



Updated to fallback gracefully with older core



Adds additional fallback for python-api without hierarchy support



Adds sg to timestamp data cleanup back into sg models



Bug fix for checking cached schma



Allows for graceful failure when Hierarchy API is not available



Shotgun Hierarchy Model



Added missing entity dark icons



Ensures that cached schema and status data is loaded from disk when requesting that data from a project that isn't the active context.



Reduces noise from the background task manager debug messages and resolves a schema_cache bug related to per-project lookup of type schemas.



Updates field editable/visible to use project id based schema caches



Allow the editor widgets to be used with the shotgunmodel



Fixed variable reference issue in shotgun globals, causing warnings to be printed in some cases.



Adds the ability to download attachments via the ShotgunDataRetriever.


In the same way that the data retriever can be used to asynchronously download thumbnail images, it can now be used to download data associated with Attachment entities in Shotgun.



Changes a log_warning into a log_debug to cut down on noisy output.



The schema and status caches are now stored in memory on a per-project basis.


Schema and status information can be queried for a given project, even if it is outside of the current context. By default the behavior remains as it always has and the current project is queried. If a project id is provided and the version of tk-core being used does not support looking up cache paths on a per-project basis, the current project will be used instead as a means of remaining backwards compatible with older core releases.



Fixes a bug with tooltip generation in the Shotgun Model


The Shotgun Model can now generate a tooltip for model items that reference a field with more than two period in their name, e.g. entity.Shot.sg_sequence.Sequence.sg_status_list.



Optimization - settings module no longer requires an initialized shotgun API handle at initialization.



Adds utility methods to cached schema api



Adds support for an "additional_filter_presets" optional argument for ShotgunModel when loading data. Also adds support for detecting and handling bubbled fields when getting field data types.



Introduces an alternate event dispatching scheme for events from the background manager's to avoid a deadlock bug between the GIL and PySide.


Signalling between two different threads in PySide is broken in several versions of PySide. There are very subtle race conditions that arise when there is a lot of signalling between two threads. Some of these things have been fixed in later versions of PySide, but most hosts integrate PySide 1.2.2 and lower, which are victim of this race condition.

The background task manager and its workers does a lot on inter-threads communications and therefore can easily fall pray to these deadlocks that exist within PySide.

Therefore, the worker threads now use a different event dispatching mechanism based on QMetaObject::invokeMethod.



Adds support for columns in the Shotgun data model.


In addition to column support, bug fixes related to Toolkit operating in a "site" context plus better handling of null thumbnails on entities are included.



ShotgunStandardItem now displays the entity's type in its tooltip instead of on its label.



Added data retriever support for find_one



Optimized tree rebuilding speed in the ShotgunModel.


  • Rewrote the tree building algorithm of the ShotgunModel which provides speed boosts from 2.5x to 6.5x depending on the number of nodes in the tree.
  • The ShotgunModel now advertises that is going to be reset before clearing the tree..



Fixed incorrect python imports



Bumped major version to 4. Deprecated ShotgunOverlayModel in favour of new view adapter object.



Improved cache handling for advanced use cases.


This improves how cache files are partitioned when using the seed query parameter and the schema_generation parameters are being used. The documentation around these parameters have also been improved. Cache files containing thumbnails and the ones without are also separated in order to allow non-thumbnail caches to be loaded in multi-threaded scenarios without getting QT pixmap warnings.



Converted documentation to use sphinx. Added a shotgun_globals module with access to shotgun schema and other site-global data.



Adjusted code imports to avoid dependency cycles.


Pre-release v3.x for testing with File Manager v2


  • Code tidy up and code-review fixes
  • Fully merged changes from master 2.x.x branch



Added support for capped queries via a limit parameter.


You can now define a model which holds a maximum of X entries by passing a limit parameter to the data load command. This is then passed to the Shotgun API find() call to limit the results returned from the server. In conjunction with ordering your shotgun resultset, this can be used to effectively cap the data set that the model is handling, allowing a user to for example show the twenty most recent notes or similar.


Pre-release v3.x for testing with File Manager v2


  • PyQt fixes


Moved some data sanitation methods into the utilities part of the Shotgun Model module.


This makes it easy for other model code outside of the shotgun utils framework to take advantage of these methods.


Optimizations and bug fixes.


  • Adds a new bg_load_thumbs flag to the ShotgunModel constructor. This is false by default. Setting the flag to True will request that the sgdata async fetcher not only downloads the thumbnail but also loads it up into a QImage object. This means that most I/O will happen in the worker thread rather than in the main UI thread. It seems to lead to much better behaviour, especially when you have lots of images.
  • When bg_load_thumbs is set to True, the method _populate_thumbnail_image() is called from the base class instead of the normal _populate_thumbnail() method. Code subclassing the Shotgun model needs to implement this _populate_thumbnail_image() method if they want to take advantage of the new behaviour.
  • Thumbnails are downloaded faster from S3. Instead of doing a find prior to every S3 download, this is only done on failure. Thumbs queued up several times (not an uncommon situation) are only dowloaded once.
  • Improved debugging output to aid troubleshooting.
  • Fixed issue with S3 logic inside attachment entities, causing queries pulling down attachment fields with uploads to always invalidate and refresh.
  • Fixed an issue with callbacks firing when thumbnails are removed on the server and not returned Shotgun connections are now created JIT - for optimal performance of initial thumbnail download tasks.


Added additional methods for async data access and retrieval


  • Schema method now combines both schema_read and schema_entity_read
  • execute_find() call in sg data fetcher now supports arbitrary arguments that are being dispatched to sg.find()
  • Added delete, update and create methods to async data fetcher
  • Added method which allows for the execution of an arbitrary method in the async data fetcher
  • Fixed an issue where the wrong request_type was being returned for thumbnails.


Added methods for better overlay access and schema retrieval.


  • The shotgun asynchronous data fetcher now supports Shotgun schema retrieval via a new get_schema() method.
  • The overlay model now exposes spinner access via a _show_overlay_spinner() method.


Fixed a race condition in SgDataRetriever.


Fixed a race condition in SgDataRetriever. This happens if you try to set the Shotgun connection after starting the thread.


Various changes and tweaks to the ShotgunModel class.


  • Signals are now blocked during ShotgunModel destruction to avoid instability
  • Changed a couple of members/methods to be protected rather than private
  • Added an method to easily get a QModelIndex from an entity
  • Exposed an property that returns the list of entity ids in the model


Initial pre-release v3.x for testing with File Manager v2


Memory related bug fixes and improved cache path structure.


Improved workarounds for a known pyside/qt issue where clearing and resetting of models will result in dangling pointers on the PySide side. This change implements close() and reset() for the Shotgun Model in the interest of stability - anyone trying to call reset() will now get an exception raised instead of a (highly likely) scenario with stability issues or crashes. close() is reimplemented in order to avoid the default C++ implementation and instead use the hand crafted recursion based clearing that ensures that all objects both on the C++ and Python side are removed.

Thumbnail and cached query paths are restructured to better handle long path name as we were running into issues with MAX_PATH on windows. We had to deal with taking an S3 guid and shard that into the file system (which wasn't done nicely before) so now all thumbnail paths that shotgun generate are first hashed and then sharded on disk. This should result in an even distribution of thumbnails on disk.

Paths logic for shotgun caches have been updated as well in order to avoid MAX_PATH on windows (260 char limitation). Warnings are emitted if the paths are getting close.

The code attempts to move thumbnail files from the old to the new path cache structure if possible in the interest of saving disk space and bandwidth.


Improved storage logic for cache files.


While this update will work with pre-015 cores (where cache files will be stored in the pipeline configuration cache directory), it is really intended as a 0.15 followup, attempting to resolve some things related to the cache storage:

  • sg data caches are now stored in the official bundle cache location, allowing clients to customize the location of cache data. In addition, it also creates a more clear, standardized structure and resolves potential buildup of cache files in temp storage, which sometimes is highly limited by design.

  • we have seen potential evidence of md5 cache collisions with the current implementation, where a large number of parameters are squeezed into a single string that is md5 hashed. This change breaks out the structure further and hopefully no collisions should appear.

  • improved I/O handling around cache writes.


Fixed a bug causing some thumbnail comparisons to fail.


Minor administrative adjustment: This framework now requires core v0.14.58 or greater to correctly handle installation in certain setups.


Fixed a bug which was preventing some I/O warning messages from being emitted.


Fixed a bug relating to unicode conversion.

Details: The recursive unicode conversion method was designed in such a way that it only worked on shotgun multi-entity list data structures, not normal lists of simple data items. This could cause it to fail for any field which returns a list of things (or a customization which relies on this).


Minor bug fixes and adjustments.

Details: - Cache now correctly responds whena thumbnail is updated. Previously thumbnail updates were ignored. - Added improved trapping of use case where cache comparisons fail due to strange values in cache. This attempts to resolve of at least work around a long standing issue where NULL errors would appear infrequently when the loader was retrieving its content. - Multi entity values are now formatted as a comma separated list. Previously these were printed out in their "raw" form, as a list of link dictionaries. - Items with their name field set to None are now displayed as "Unnamed Asset" rather than just "Unnamed". - Cache writer now explicitly closes its cache file handle.


Moved UI related modules into a separate widgets framework.

Details: Please note that this is a breaking change - hence the major version number increase! This release has removed the shotgun_view, overlay_widget and help_screen modules. These are now located in tk-framework-qtwidgets instead for better separation. In addition to this, the following smaller changes were carried out: - A shotgun_data module was added. This was previously a private part of the shotgun model, but has now become a first class citizen of the framework. This module makes it easy to do asynchronous shotgun queries and also manages caching and retrieval of shotgun thumbnails. - Changed the framework icon - Improved some documentation relating to time zone management.


Data refreshing signal and bug fix for simpleshotgunmodel.

Details: New data_refreshing signal emitted when data starts refreshing (thanks Tony!) Bug fix for how simpleshotgunmodel passes on hierarchy.


Bug fixes for PyQt4 and fixed an interface typo.

Details: Fixed an issue in the widget delegates framework where the QWidget.render() method would work correctly on some pyqt distros but not all. Fixed a spelling error in the set_shotgun_connection() method name in the public interface.


Improved exception handling in the settings module.


Improved documentation.


Updated framework icon.


Fixed a bug causing the help screen transitions not to show on Linux.


Bug fixes and tweaks.

Details: - Help screen module now hides arrow buttons on the first and last page. - Fixed issues with help screen object parenting, causing problems on earlier versions of PySide/Shiboken. - Fixed an issue with object deallocation which was causing crashes on earlier versions of PySide/Shiboken (Nuke 6.3).


Changed initialization order so that all data population happens prior to adding objects to the model.

Details: This ensures that by the time signals are emitted by the model, the item data is fully initialized.


Fixed a bug causing models to behave erratically when items where nested in a hierarchy.

Details: For more information, see


Minor tweaks to default values formatting.


First version of public interface.