This is a beta release of a new version of the Python API that uses JSON as a transport instead of XML-RPC. The intent is for this to be drop-in compatible with the previous version. If you find any incompatibilities, please contact us through support or on the dev list.
Shotgun 2.4 or greater.
For Python 2.4 and 2.5, install simplejson 2.0.9: http://pypi.python.org/pypi/simplejson/2.0.9
For Python 2.6 and higher, we will use the built-in json module... but installing the latest simplejson will give the best performance. Currently, that's version 2.1.6: http://pypi.python.org/pypi/simplejson/2.1.6
-
- In Shotgun 2.4.12 and lower there are bugs getting/setting float fields
Shotgun provides a simple Python-based API for accessing Shotgun and integrating with other tools. This is the official API that is maintained by Shotgun Software (support@shotgunsoftware.com)
GitHub is the new official location for the latest Shotgun Python API. We will no longer be including it in our code tree that is deployed to your servers or posting it for download from our support site. So update your bookmarks!
SEE NEW REQUIREMENTS ABOVE
- Shotgun server v1.8.0 or higher. Note that some API features are only available in later Shotgun server versions.
- Python v2.4 - v2.7. (We do have plans to eventually support Python 3)
To use Shotgun's Python API module, you need to place the package shotgun_api3 in one of the directories specified by the environment variable PYTHONPATH. For more information on PYTHONPATH and using modules in Python, see http://docs.python.org/tutorial/modules.html
Tutorials and detailed documentation about the Python API are available on the Shotgun Support website. Some useful direct links within this section are below:
Integration and unit tests are provided.
- test_client and tests_unit mock server interaction and do not require a shotgun instance to be available.
- test_api and test_api_long do require a shotgun instance, with a script key available for the tests. These tests rely on a tests/config file, which can be created by renaming example_config and supplying the server and script user values. The tests will set up test data on the server based on the data set forth in the 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. This script require nose to be installed.
(Note that many of these items may be specific to the XML-RPC version of the API and may not apply to the Python JSON API)
v3.0.8 Beta - 2011 August 4
- summarize available in json api
- refactored single file into package
- tests added (Thanks to Aaron Morton https://github.com/amorton)
- return all strings as ascii for backwards compatibility, added ensure_ascii parameter to enable returning unicode
v3.0.6 - 2010 Jan 25
- optimization: don't request paging_info unless required (and server support is available)
v3.0.5 - 2010 Dec 20
- officially remove support for old api3_preview controller
- find(): allow requesting a specific page of results instead of returning them all at once
- add support for "session_uuid" parameter for communicating with a web browser session.
v3.0.4 - 2010 Nov 22
- fix for issue where create() method was returning list type instead of dictionary
- support new style classes (thanks to Alex Schworer https://github.com/schworer)
v3.0.3 - 2010 Nov 12
- add support for local files. Injects convenience info into returned hash for local file links
- add support for authentication through http proxy server
v3.0.2 - 2010 Aug 27
- add revive() method to revive deleted entities
v3.0.1 - 2010 May 10
- find(): default sorting to ascending, if not set (instead of requiring ascending/descending)
- upload() and upload_thumbnail(): pass auth info through
v3.0 - 2010 May 5
- non-beta!
- add batch() method to do multiple create, update, and delete requests in one request to the server (requires Shotgun server to be v1.13.0 or higher)
v3.0b8 - 2010 February 19
- fix python gotcha about using lists / dictionaries as defaults. See: http://www.ferg.org/projects/python_gotchas.html#contents_item_6
- add schema_read method
v3.0b7 - 2009 November 30
- add additional retries for connection errors and a catch for broken pipe exceptions
v3.0b6 - 2009 October 20
- add support for HTTP/1.1 keepalive, which greatly improves performance for multiple requests
- add more helpful error if server entered is not http or https
- add support assigning tags to file uploads (for Shotgun version >= 1.10.6)
v3.0b5 - 2009 Sept 29
- fixed deprecation warnings to raise Exception class for python 2.5
v3.0b4 - 2009 July 3
- made upload() and upload_thumbnail() methods more backwards compatible
- changes to find_one():
- now defaults to no filter_operator
v3.0b3 - 2009 June 24
- fixed upload() and upload_thumbnail() methods
- added download_attchment() method
- added schema_* methods for accessing entities and fields
- added support for http proxy servers
- added version string
- removed RECORDS_PER_PAGE global (can just set records_per_page on the Shotgun object after initializing it)
- removed api_ver from the constructor, as this class is only designed to work with api v3