• Stars
    star
    293
  • Rank 141,748 (Top 3 %)
  • Language
    Python
  • License
    Other
  • Created over 14 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A Python-based API for accessing ShotGrid.

VFX Platform Python 2.7 3.7 Reference Documentation Build Status Coverage Status

ShotGrid Python API

ShotGrid provides a simple Python-based API for accessing ShotGrid and integrating with other tools. This is the official API that is maintained by ShotGrid Software (https://knowledge.autodesk.com/contact-support)

The latest version can always be found at http://github.com/shotgunsoftware/python-api

Minimum Requirements

  • Python v3.7

Documentation

Tutorials and detailed documentation about the Python API are available at http://developer.shotgridsoftware.com/python-api).

Some useful direct links:

Changelog

You can see the full history of the Python API on the documentation site.

Updating HTTPLib2

The API comes with a copy of the httplib2 inside the shotgun_api3/lib folder. To update the copy to a more recent version of the API, you can run the update_httplib2.py script at the root of this repository like this:

python update_httplib2.py vX.Y.Z

where vX.Y.Z is a release found on httplib2's release page.

Maintaining Python 2 and 3 compatibility

python-api should remain compatible with both Python 2, and 3. To make this easier, we use six. When adding code that works with types that have changed between Python 2 and 3, notably strings and files, it's advisable to use the six types for casting and comparisons. Be sure to follow Python 2 and 3 compatible conventions in code, especially when raising or capturing exceptions and printing. While we don't use future, this page contains a fairly comprehensive list of Python 2/3 compatibility sticking points to look out for.

Additionally, the python-modernize tool can be helpful when updating Python 2 code for Python 3 compatibility.

Examples:

Comparisons against changed types:

Python 2:

if isinstance(my_variable, str):

Python 2/3:

if isinstance(my_variable, six.string_types):

Catching exceptions

Python 2:

except SomeExceptionType, e:
    print "I like to swallow exceptions!"

Python 2/3:

from __future__ import print_function
except SomeExceptionType as e:
    print("I like to swallow exceptions!")

Print statements

Python 2:

print "My spoon is too big!"

Python 2/3:

from __future__ import print_function
print("My spoon is too big!")

Additionally, when testing locally, tests should be run for both python 2 and python 3 to ensure changes won't break cross-compatibility.

Tests

Integration and unit tests are provided.

  • All tests require:
  • A tests/config file (you can copy an example from tests/example_config).
  • Tests can be run individually like this: nosetests --config="nose.cfg" tests/test_client.py
    • Make sure to not forget the --config="nose.cfg" option. This option tells nose to use our config file. This will exclude python 2- and 3-specific files in the /lib directory, preventing a failure from being reported by nose for compilation due to incompatible syntax in those files.
  • test_client and tests_unit use mock server interaction and do not require a ShotGrid instance to be available (no modifications to tests/config are necessary).
  • test_api and test_api_long do require a ShotGrid instance, with a script key available for the tests. The server and script user values must be supplied in the tests/config file. The tests will add test data to your server based on information in your config. This data will be manipulated by the tests, and should not be used for other purposes.
  • To run all of the tests, use the shell script run-tests.

Release process

Packaging up new release

  1. Update the Changelog in the HISTORY.rst file
    • Add bullet points for any changes that have happened since the previous release. This may include changes you did not make so look at the commit history and make sure we don't miss anything. If you notice something was done that wasn't added to the changelog, hunt down that engineer and make them feel guilty for not doing so. This is a required step in making changes to the API.
    • Try and match the language of previous change log messages. We want to keep a consistent voice.
    • Make sure the date of the release matches today. We try and keep this TBD until we're ready to do a release so it's easy to catch that it needs to be updated.
    • Make sure the version number is filled out and correct. We follow semantic versioning.
  2. Ensure any changes or additions to public methods are documented
    • Ensure that doc strings are updated in the code itself to work with Sphinx and are correctly formatted.
    • Examples are always good especially if this a new feature or method.
    • Think about a new user to the API trying to figure out how to use the features you're documenting.
  3. Update the version value in python-api/setup.py to match the version you are packaging. This controls what version users will get when installing via pip.
  4. Update the __version__ value in shotgun_api3/shotgun.py to the version you're releasing. This identified the current version within the API itself.
  5. Commit these changes in master with a commit message like packaging for the vx.x.x release.
  6. Create a tag based off of the master branch called vx.x.x to match the version number you're releasing.
  7. Push master and your tag to Github.
  8. Update the Releases page with your new release.
    • The release should already be there from your tag but if not, create a new one.
    • Add more detailed information regarding the changes in this release. This is a great place to add examples, and reasons for the change!

Letting the world know

Post a message in the Pipeline Community channel.

Prepare for the Next Dev Cycle

  1. Update the __version__ value in shotgun_api3/shotgun.py to the next version number with .dev appended to it. For example, v3.0.24.dev
  2. Add a new section to the Changelog in the HISTORY.rst file with the next version number and a TBD date
    **v3.0.24 - TBD**
       + TBD
  1. Commit the changes to master with a commit message like Bump version to v3.0.24.dev
  2. Push master to Github

More Repositories

1

tk-core

The Flow Production Tracking Pipeline Toolkit Core API
Python
89
star
2

tk-maya

A Flow Production Tracking Pipeline Toolkit Engine for Maya
Python
49
star
3

tk-config-default2

The second generation default configuration for Flow Production Tracking Toolkit.
Python
42
star
4

tk-framework-qtwidgets

A collection of Toolkit related QT Widgets
Python
37
star
5

tk-houdini

A Flow Production Tracking Pipeline Toolkit Engine for Houdini
Python
27
star
6

sg-jira-bridge

Flow Production Tracking / Jira Synchronization
Python
23
star
7

tk-multi-starterapp

ShotGrid Pipeline Toolkit App Template
Python
22
star
8

tk-desktop

A Flow Production Tracking Pipeline Toolkit engine for desktop applications and operating system integration.
Python
22
star
9

tk-multi-workfiles2

Flow Production Tracking Toolkit File Manager helps you safely manage your Work Files
Python
20
star
10

tk-nuke

A Flow Production Tracking Pipeline Toolkit Engine for Nuke
Python
20
star
11

tk-multi-publish2

Toolkit Publishing
Python
18
star
12

rv-integration-package

The Shotgun + RV integration makes it super easy to find and play media in RV right from Shotgun. And once you are in RV, you now have access to a new toolset that lets you modify the playback based on information in Shotgun, or deep link right into Shotgun to take Notes or view more information. A "Shotgun-aware" URL from RV let's you send around links that will launch people right into RV to view the work.
17
star
13

developer.shotgunsoftware.com

Content for the *legacy* ShotGrid Developer site.
14
star
14

sg-siggraph-2019

Shotgun Sessions at SIGGRAPH 2019 - Documentation and Resources
Python
14
star
15

file_uploader

A simple Python script that uploads files or thumbnails and links them to the appropriate entities based on a simple regex pattern.
Python
14
star
16

tk-shotgun

A Flow Production Tracking Pipeline Toolkit Engine for the Flow Production Tracking Web App
Python
13
star
17

sg-devday-2018

Shotgun Ecosystem Developer Day 2018 - Documentation and Resources
Python
13
star
18

tk-nuke-writenode

A Flow Production Tracking Pipeline Toolkit App that implements a custom write node for Nuke
Python
12
star
19

tk-flame

A Flow Production Tracking Pipeline Toolkit engine for Flame
Python
10
star
20

cplusplus-api

C++ implementation of the Shotgun API
C++
10
star
21

s3-proxy-example

An nginx S3 proxy Docker image example
Dockerfile
10
star
22

tk-aftereffects

Flow Production Tracking After Effects integration.
Python
10
star
23

tk-framework-adobe

Foundation Tech for all Adobe Integrations
JavaScript
10
star
24

tk-3dsmaxplus

A Flow Production Tracking Pipeline Toolkit Engine for 3dsMax with builtin Python support
Python
9
star
25

shotgun-nodejs

NodeJS client library for Flow Production Tracking.
JavaScript
9
star
26

shotgun-toolbox

This repository contains various tools that can be useful for Hosted Flow Production Tracking Administrators
Python
9
star
27

tk-multi-workfiles

A File Manager App for the Flow Production Tracking Pipeline Toolkit
Python
9
star
28

java-api

Shotgun Java API
Java
9
star
29

tk-hiero-export

A Flow Production Tracking Pipeline Toolkit App that implements a custom exporter in Hiero
Python
9
star
30

tk-multi-launchapp

A Flow Production Tracking Pipeline Toolkit app that launches Host Applications.
Python
8
star
31

tk-toolchain

A suite of tools for Toolkit development
Python
8
star
32

tk-multi-loader2

Toolkit Generation 2 Content Import and Load
Python
8
star
33

tk-config-default

The old default Toolkit project configuration - now replaced by tk-config-default2.
Python
8
star
34

tk-photoshopcc

A Flow Production Tracking Pipeline Toolkit Engine for Photoshop
Python
8
star
35

tk-framework-remotestorageexample

An example framework for uploading and downloading files from a remote storage.
Python
8
star
36

tk-framework-shotgunutils

Flow Production Tracking Related Utilities
Python
8
star
37

tk-multi-demo

Provides demonstrations of Flow Production Tracking's native developer platform components including the Flow Production Tracking Utilities framework, the Qt Widgets frameworks and Toolkit core.
Python
8
star
38

shotgrid_api_ruby

A gem to interact with the Flow Production Tracking REST api
Ruby
7
star
39

enterprise-toolbox

This repository contains various tools that can be useful for Flow Production Tracking Enterprise System Administrators
Python
7
star
40

tk-config-publish_api_webinar

Configuration used by the Publish API webinar. It branches off [email protected]
Python
7
star
41

tk-rv-shotgunreview

Python
6
star
42

tk-multi-shotgunpanel

Access Flow Production Tracking data inside the artist app.
Python
6
star
43

tk-multi-publish

A Flow Production Tracking Pipeline Toolkit App that handles publishing and version control.
Python
6
star
44

shotgun-docker-example

Example configuration of Flow Production Tracking container with docker-compose
Dockerfile
6
star
45

tk-framework-perforce

Common Perforce functionality
Python
6
star
46

tk-motionbuilder

A Flow Production Tracking Pipeline Toolkit Engine for Motionbuilder
Python
6
star
47

tk-multi-pythonconsole

A Python console for Toolkit
Python
6
star
48

tk-flame-export

A Flow Production Tracking Pipeline Toolkit App to export data into Flow Production Tracking.
Python
6
star
49

tk-nuke-quickdailies

A ShotGrid Pipeline Toolkit App that implements a custom quickdailies node in Nuke
Python
6
star
50

tk-config-basic

The configuration driving the Flow Production Tracking Integrations.
Python
6
star
51

tk-framework-desktopstartup

Startup logic for the desktop
Python
5
star
52

tk-config-flame

The toolkit default configuration with Flame integration added on top.
Python
5
star
53

shotgunsoftware.github.io

The html content for the *legacy* Flow Production Tracking Developer Site
HTML
5
star
54

tk-multi-reviewsubmission

A Flow Production Tracking Pipeline Toolkit App to make quicktimes with slates
Python
5
star
55

tk-ci-tools

Tools for CI using Azure Pipelines
Python
5
star
56

gists

A collection of short code examples for reference.
Python
5
star
57

tk-shell

A Flow Production Tracking Pipeline Toolkit Engine for the Terminal
Python
5
star
58

tk-shotgun-launchfolder

A Flow Production Tracking Pipeline Toolkit App to Launch an explorer/finder style window
Python
4
star
59

tk-mari

A Flow Production Tracking Pipeline Toolkit engine for Mari
Python
4
star
60

shotgrid-nodejs-cli

NodeJS CLI for Flow Production Tracking.
JavaScript
4
star
61

tk-rv

Tweak implementation of a toolkit engine for RV.
Python
4
star
62

tk-shotgun-folders

A Flow Production Tracking Pipeline Toolkit App to Create folders on disk
Python
4
star
63

tk-doc-generator

ShotGrid Developer Documentation Generation
Python
4
star
64

tk-multi-breakdown2

A Flow Production Tracking Pipeline Toolkit app that helps you see what is out of date in your scene across multiple projects.
Python
4
star
65

tk-flame-review

Send content to review from Flame.
Python
4
star
66

openrv-pub

Legacy third partiy packaging for https://github.com/AcademySoftwareFoundation/OpenRV
C
4
star
67

tk-config-flameplugin

Flame Plugin Configuration
Python
4
star
68

tk-3dsmax

A Flow Production Tracking Pipeline Toolkit Engine for 3DS Max
Python
4
star
69

tk-multi-screeningroom

A Flow Production Tracking Pipeline Toolkit App that lets you Launch Screening Room directly from an application
Python
3
star
70

tk-houdini-alembicnode

Alembic Output node App for use with Toolkit's Houdini engine.
Python
3
star
71

tk-framework-desktopserver

A framework that provides a server to run local commands.
Python
3
star
72

tk-multi-snapshot

Snapshot functionality for multiple engines
Python
3
star
73

tk-framework-widget

QT Widget Framework for Tank Apps
Python
3
star
74

tk-multi-setframerange

A Flow Production Tracking Pipeline Toolkit App that lets you synchronize the application frame range with the one in Flow Production Tracking
Python
3
star
75

tk-shotgun-launchpublish

A Flow Production Tracking Pipeline Toolkit App to Lanch Published Files
Python
3
star
76

tk-multi-data-validation

A Flow Production Tracking Pipeline Toolkit app to validate the data in your scene.
Python
3
star
77

enterprise-unified-logging

Elasticsearch stack for Flow Production Tracking Enterprise logging
Shell
3
star
78

tk-houdini-mantranode

Mantra Output node App for use with Toolkit's Houdini engine.
Python
3
star
79

tk-config-rv

Embedded Toolkit in RV
Python
2
star
80

tk-framework-desktopclient

Provides the client used to send requests to a Desktop Server
Python
2
star
81

tk-framework-adminui

A framework that provides GUIs for administrative commands.
Python
2
star
82

tk-mari-projectmanager

Project management for the Mari toolkit engine
Python
2
star
83

sghubot

Our Hubot
CoffeeScript
2
star
84

tk-desktop2

Toolkit Engine for Flow Production Tracking Create
Python
2
star
85

tk-alias

Toolkit Engine for Alias
Python
2
star
86

tk-vred

Toolkit Engine for VRED
Python
2
star
87

tk-multi-about

A Flow Production Tracking Pipeline Toolkit App that shows info about the current setup.
Python
2
star
88

tk-framework-aliastranslations

Framework to handle translations for Alias and other 3D file formats.
Python
2
star
89

tk-framework-softimageqt

PySide & Qt distributions for the Toolkit Softimage engine
C++
1
star
90

tk-shotgun-launchvredreview

Use VRED Presenter with Flow Production Tracking Panel for reviewing data
Python
1
star
91

tk-multi-scenebuilder

Automate the build of your scene by helping retrieving and loading published files
Python
1
star
92

tk-config-testing

Repository used for Toolkit unit tests in tk-core
Python
1
star
93

sg-automation

Repository for automation related work, for ShotGrid Web, Studio and Toolkit
Python
1
star
94

tk-multi-bg-publish

A Flow Production Tracking Pipeline Toolkit app to perform publishes in a background process
Python
1
star
95

tk-hiero-openinshotgun

A Flow Production Tracking Pipeline Toolkit App that lets you jump from Hiero to Flow Production Tracking
Python
1
star
96

tk-multi-testing

App used for testing our release scripts
Python
1
star
97

tk-multi-breakdown

A Flow Production Tracking Pipeline Toolkit app that helps you see what is out of date in your scene.
Python
1
star
98

x_send_file

Clone of https://github.com/simmerz/x_send_file
Ruby
1
star
99

tk-shotgun-setupproject

Project setup wizard for use from the Flow Production Tracking web application.
Python
1
star
100

tk-nuke-quickreview

Nuke node that uploads a video to Flow Production Tracking for review.
Python
1
star