shotgun.shotgun#

The module contains the classes and methods needed to provide linkage with ShotGrid.

In the simplest of cases (e.g. when a bookmark item is active and have already been linked with ShotGrid) we can initiate a connection using a ShotgunProperties instance:

 1import bookmarks.shotgun.shotgun as shotgun
 2
 3sg_properties = shotgun.ShotgunProperties(active=True)
 4sg_properties.init() # loads data from the bookmark database
 5
 6# Verify properties before connecting
 7if not sg_properties.verify(connection=True):
 8    raise ValueError('Bookmark not configured to use ShotGrid.')
 9
10with shotgun.connection(sg_properties) as sg:
11    schema = sg.schema_field_read('Shot')

The current implementation needs to authenticate using an API Script Name/Key. These values must be set in the bookmark database before initiating a connection.

https://developer.shotgunsoftware.com/python-api/reference.html

Classes:

EntityComboBox(items[, fixed_height, parent])

A ShotGrid specific combobox, intended to be used with the EntityFilterModel.

EntityFilterModel(model[, parent])

A filter model to wrap our EntityModel.

EntityModel(items[, parent])

Our custom model used to store ShotGrid entities.

ShotgunProperties(*args, **kwargs)

Returns all ShotGrid properties saved in the bookmark item database.

Functions:

connection(sg_properties)

Context manager used for connecting to ShotGrid using an API Script.

get_sg(domain, script, key)

Method for retrieving a thread specific ScriptConnection instance, backed by a cache.

sanitize_path(path, separator)

Utility method mirrors the ShotGrid sanitize path method.

Data:

ENTITY_URL

ShotGrid entity url pattern

SG_CONNECTIONS

ShotGrid connection instance cache

fields

A list of entity and field definitions used to assist entity data queries

class bookmarks.shotgun.shotgun.EntityComboBox(items, fixed_height=common.size(common.size_row_height), parent=None)[source]#

Bases: QComboBox

A ShotGrid specific combobox, intended to be used with the EntityFilterModel. Use self.set_model to set a new EntityModel.

Methods:

append_entity(entity)

Appends a new row to the end of the model.

set_model(model)

Sets a new EntityModel for the combobox.

append_entity(entity)[source]#

Appends a new row to the end of the model.

set_model(model)[source]#

Sets a new EntityModel for the combobox.

class bookmarks.shotgun.shotgun.EntityFilterModel(model, parent=None)[source]#

Bases: QSortFilterProxyModel

A filter model to wrap our EntityModel.

Use it to filter entities by type. self.set_entity_type sets the filter entity type.

Methods:

filterAcceptsColumn(self, source_column, ...)

filterAcceptsRow(self, source_row, source_parent)

filterAcceptsColumn(self, source_column: int, source_parent: PySide2.QtCore.QModelIndex) bool[source]#
filterAcceptsRow(self, source_row: int, source_parent: PySide2.QtCore.QModelIndex) bool[source]#
class bookmarks.shotgun.shotgun.EntityModel(items, parent=None)[source]#

Bases: QAbstractItemModel

Our custom model used to store ShotGrid entities.

The model itself does not load any data but instead uses a secondary worker thread to do the heavy lifting. The entityDataRequested and entityDataReceived signals are responsible for requesting and retrieving ShotGrid data.

Each instance has a unique uuid used to match data requests with retrieved data.

Methods:

columnCount(self[, parent])

data(self, index[, role])

flags(self, index)

index(self, row, column[, parent])

parent(-> PySide2.QtCore.QObject)

rowCount(self[, parent])

Attributes:

entityDataReceived(*args, **kwargs)

Signal used by the worker thread when data is ready, with the data's uuid, and list of entities.

entityDataRequested(*args, **kwargs)

Signal used to request data from ShotGrid.

columnCount(self, parent: PySide2.QtCore.QModelIndex = Invalid(PySide2.QtCore.QModelIndex)) int[source]#
data(self, index: PySide2.QtCore.QModelIndex, role: int = PySide2.QtCore.Qt.ItemDataRole.DisplayRole) Any[source]#
flags(self, index: PySide2.QtCore.QModelIndex) PySide2.QtCore.Qt.ItemFlags[source]#
index(self, row: int, column: int, parent: PySide2.QtCore.QModelIndex = Invalid(PySide2.QtCore.QModelIndex)) PySide2.QtCore.QModelIndex[source]#
parent(self) PySide2.QtCore.QObject[source]#
parent(self, child: PySide2.QtCore.QModelIndex) PySide2.QtCore.QModelIndex
rowCount(self, parent: PySide2.QtCore.QModelIndex = Invalid(PySide2.QtCore.QModelIndex)) int[source]#
entityDataReceived(*args, **kwargs)#

Signal used by the worker thread when data is ready, with the data’s uuid, and list of entities.

entityDataRequested(*args, **kwargs)#

Signal used to request data from ShotGrid. Takes uuid, server, job, root, asset, entity_type, filters and fields arguments.

class bookmarks.shotgun.shotgun.ShotgunProperties(*args, **kwargs)[source]#

Bases: object

Returns all ShotGrid properties saved in the bookmark item database.

These properties define the linkage between ShotGrid entities and local assets and are required to make ShotGrid connections.

The instance is uninitialized by default, use self.init() to load the values from the bookmark database.

Parameters
  • server (str) – server path segment.

  • job (str) – job path segment.

  • root (str) – root path segment.

  • asset (str) – asset path segment.

  • active (bool) – Use the active paths when True. False by default.

Methods:

init([db])

Load all current shotgun values from the bookmark item database.

urls()

Returns a list of available urls based on the sg_properties provided.

verify([connection, bookmark, asset])

Checks the validity of the current configuration.

Attributes:

asset

Asset path segment.

job

Job path segment.

root

Root path segment.

server

Server path segment.

init(db=None)[source]#

Load all current shotgun values from the bookmark item database.

urls()[source]#

Returns a list of available urls based on the sg_properties provided.

Returns

A list of urls.

Return type

list

verify(connection=False, bookmark=False, asset=False)[source]#

Checks the validity of the current configuration.

Parameters
  • connection (bool, optional) – Verifies the connection information if True.

  • bookmark (bool, optional) – Checks only the bookmark item’s configuration if True.

  • asset (bool, optional) – Checks only the asset item’s configuration if True.

Returns

True if the configuration is valid, False otherwise.

Return type

bools

property asset#

Asset path segment.

property job#

Job path segment.

property root#

Root path segment.

property server#

Server path segment.

bookmarks.shotgun.shotgun.connection(sg_properties)[source]#

Context manager used for connecting to ShotGrid using an API Script.

The context manager will connect to shotgun on entering and close the connection when exiting.

Parameters

sg_properties (dict) – The shotgun properties saved in the bookmark database.

Yields

ScriptConnection – A connected shotgun connection instance

bookmarks.shotgun.shotgun.get_sg(domain, script, key)[source]#

Method for retrieving a thread specific ScriptConnection instance, backed by a cache.

Warning

User authentication is not implemented currently!

Parameters
  • domain (str) – The base url or domain where the shotgun server is located.

  • script (str) – A valid ShotGrid API Script’s name.

  • key (str) – A valid ShotGrid Script’s API Key.

bookmarks.shotgun.shotgun.sanitize_path(path, separator)[source]#

Utility method mirrors the ShotGrid sanitize path method.

bookmarks.shotgun.shotgun.ENTITY_URL = '{domain}/detail/{entity_type}/{entity_id}'#

ShotGrid entity url pattern

bookmarks.shotgun.shotgun.SG_CONNECTIONS = {}#

ShotGrid connection instance cache

bookmarks.shotgun.shotgun.fields = {'Asset': ['type', 'id', 'code', 'project', 'description', 'notes'], 'HumanUser': ['type', 'id', 'name', 'firstname', 'lastname', 'projects'], 'LocalStorage': ['type', 'id', 'code', 'description', 'mac_path', 'windows_path', 'linux_path'], 'Project': ['type', 'id', 'name', 'is_template', 'is_demo', 'is_template_project', 'archived'], 'PublishedFile': ['type', 'id', 'code', 'name', 'description', 'entity', 'version', 'version_number', 'project'], 'PublishedFileType': ['type', 'id', 'code', 'description', 'short_name'], 'Sequence': ['type', 'id', 'code', 'project', 'description', 'notes'], 'Shot': ['type', 'id', 'code', 'project', 'description', 'notes', 'cut_in', 'cut_out', 'cut_duration', 'sg_cut_in', 'sg_cut_out', 'sg_cut_duration'], 'Status': ['id', 'name', 'type', 'code', 'bg_color'], 'Task': ['type', 'id', 'content', 'sg_description', 'project', 'entity', 'step', 'notes', 'color', 'task_assignees', 'start_date', 'due_date'], 'Version': ['type', 'id', 'code', 'description', 'sg_task', 'sg_path_to_frames', 'sg_path_to_movie', 'sg_path_to_geometry', 'sg_status_list', 'project', 'entity', 'tasks', 'user']}#

A list of entity and field definitions used to assist entity data queries