Here you can see the full list of changes between each Python API release.
Add export_page method to Shotgun class.
Documentation has been updated to reflect this addition.
Removed the deprecated CACertsHTTPSConnection class, which was no longer needed after dropping Python 2 support.
Added basic type annotations throughout the package to improve IDE support and code completion. Note: Some typing improvements are still in progress and will be refined in future releases. Special thanks to @chadrik for this contribution!
Introduced a new environment variable SHOTGUN_ALLOW_OLD_PYTHON to temporarily bypass Python version warnings for users still on Python 3.7 or 3.8. While this provides flexibility during transition, we strongly recommend upgrading to Python 3.9 or newer for continued support and security updates.
Enhanced payload optimization for entity dictionaries, making it more flexible and preventing potential issues when working with special fields like type and url.
Updated attachment documentation with detailed information about the relative_path field and its usage.
Python versions older than 3.9 are now deprecated. A runtime warning will be displayed during initialization if you’re using Python 3.7 or 3.8. Please plan to upgrade to Python 3.9 or newer as these older versions will not be supported in future releases.
Removed Python 2 code.
Removed the six module. Note: if your code depends on the six library previously included in this package, you will need to update it, as it is no longer supported.
We don’t want to retry on general exceptions (e.g. timeout or remote disconnection) because we might send a resource modification request (create, batch create, etc) and we can end up duplicating things.
Replace utcfromtimestamp to prevent breaking changes in Python 3.12.
Add improvements to Mockgun.
Ensure string comparison are case insensitive.
Ignore duplicate entities when multi_entity_update_mode is added.
Support for None in mockgun when using ordering.
Thank you rlessardrodeofx, slingshotsys, and MHendricks for your contributions.
Minor fixes on unit tests and documentation.
Prevent flaky disconnection when uploading thumbnails on publish.
There’s a flaky disconnection when the publisher uploads the thumbnail to the server.
The most common errors were: Connection closed by peer and URLopen error EOF occurred in violation of protocol ssl.c:1006.
Upgrade certifi to 2024.12.14.
Apply black 25.1.0 formatting to the source code.
Update Software Credits
Extend the payload optimizations to the in and not_in filters and
the update method.
The payload optimization is now enabled by default.
It can be disabled with the SHOTGUN_API_DISABLE_ENTITY_OPTIMIZATION
environment variable.
Remove unnecessary data in the payload when combining related queries before sending it to the server. This would improve overall performance decreasing network latency and server processing. See documentation for more information.
Remove Ticket entity reference and prepare this to run in CI.
Condition auth for Jenkins environment.
Update certifi to 2024.7.4.
FIRST PHASE Python2 removing.
Adds multi_entity_update_modes support to mockgun update() and batch() methods.
Implements a retry strategy only when encountering an URLError or SSLEOFError.
Fixes the issue with deleting prefix and suffix for display_name variable at the moment of upload for a local install.
Clarifies the use of _build_opener in download_attachment().
Drop support for Python 2.7
certifi version changed to 2024.2.2
Documentation update
Documentation: Revert to Shotgun in the API Reference headers to keep consistency with the API methods
Mockgun: fix entity data type
Mockgun: add support for add_user_agent and set_session_uuid methods
Rebranding component for Flow Production Tracking
Add support for Python 3.11
Flaky Tests
Documentation: Fix issue regarding “in” filter prototype
Documentation: Travis badge image is no working anymore
Documentation: Add user_subscription_read and user_subscription_create methods
Update Python Certifi license block
Add methods for the user_subscriptions API end points
Retry ShotGrid request also on error 504
Retry S3 uploads on error 500
Comment typing annotation breaks Python 2 compatibility
Add field type entity_type to mockgun
Started support for Python 3.10 for CI.
Add documentation for PublishedFiles preset filters.
Upgrade httplib2 to 0.22.0.
Update licensing.
Updates Autodesk URLs.
Fix flaky tests.
Update docs for entity fields.
Fix typo.
Fix incorrect hint.
Reformat code examples to prevent text overflow.
Bump certifi from 2020.06.20 to 2022.12.7 in /shotgun_api3/lib.
Skip SG-MIM entities.
Replace shotgunsoftware references.
Deprecation of Python 2.
Security upgrade certifi to latest version 2023.07.22.
Add “Setting Up Your Environment with the Python API” to Python Docs (python-api docs).
[Python API Documentation] Update Python version requirements.
Rename Shotgun to Shotgrid in every about text like tk-multi-demo git repository.
Rename Shotgun servers to ShotGrid servers in the documentation.
Adds Retries on 503 Errors when uploading to S3.
Updates AMI Documentation to Support Python 3.
Adds Python 3.9 coverage in Azure Pipeline CI tests.
Fixes git protocol for the installation.
Replaces shotgunsoftware urls with Autodesk Knowledge Network and ShotGrid Developer Documentation pages.
Updates version of httplib2.
Implements retries with incremental backoff on 502 errors.
Updates documentation and error messages to mention ShotGrid.
Now includes certifi and defaults to using the certificates provided with that module.
Updates httplib2 to v0.18.0.
Fixes an import bug in httplib2 by using the forked repository.
Upgrades packaged six module to 1.13.0
Adds platform and normalize_platform to sgsix module to provide unified platform value across Python 2/3
Changes httplib import procedure to emulate direct import of the module
Adds test to ensure httplib2 is importable as expected
Returns a specific error from share_thumbnail when the source thumbnail is a ‘transient’ thumbnail.
Adds a new project_entity parameter to schema_field_update that allows to modify field visibility for a given project.
Adds an optional localized property on the Shotgun object which allows to retrieve localized display names on
methods schema_entity_read(), schema_field_read(), and schema_read().
Fixes a regression on Python 2.7.0-2.7.9 on Windows with the mimetypes module.
Adds support for Python 3.7
Adds an optional sleep between retries specified via the SHOTGUN_API_RETRY_INTERVAL environment variable, or by setting sg.config.rpc_attempt_interval.
Updates encoding method to use shutil when uploading, to avoid memory and overflow errors when reading large files. (contributed by @eestrada)
Ensures the certificates packaged with the API and those specified via the SHOTGUN_API_CACERTS environment variable are used when uploading a file.
Upgrades the version of httplib2 to 0.12.0, which fixes SNI issues. Note this
version contains a more recent list of certificate authorities. If you are running Shotgun locally and have
signed your https certificate with an outdated certificate authority, the Shotgun connection will be rejected.
Proper support added for unicode and utf-8 string paths given to upload methods, and a sane error is raised when an unusable string encoding is used.
Adds support for querying preferences from Shotgun via the new preferences_read method.
Under-the-hood changes to add support for direct to s3 uploads to Shotgun. This change should be transparent to users.
Fixes an error where connect=False during __init__ would still connect to Shotgun.
Adds support for SHOTGUN_API_CACERTS when uploading and downloading files.
Properly handles failed downloads due to malware scanning.
Add exception UserCredentialsNotAllowedForSSOAuthenticationFault. Triggered when attempting to initiate a connection with a username/password pair on an SSO-enabled Shotgun site.
Optimized pagination strategy for Shotgun 7.4+
Switched from a hard-coded value of 500 for “records_per_page” to a server-defined value. We will be experimenting with higher values with the goal of increasing performance for large result sets.
Raise an exception when uploading an empty file using upload(), upload_thumbnail()
or upload_filmstrip_thumbnail() before calling out to the server.
Multiple enhancements and bugfixes to Mockgun
Added nav_search_string() and nav_search_entity() methods as experimental, internal methods for querying SG hierarchy.
Introduces a following() query method, that accepts a user entity and optionally an entity type and/or project.
Optimized import speed of the API on Python 2.7.
Integrated the latest fixes to the mimetypes module.
Added nav_expand() method as an experimental, internal method for querying SG hierarchy.
Ported all documentation to sphinx. See http://developer.shotgridsoftware.com/python-api.
Moved Changelog to dedicated HISTORY file.
Add optional additional_filter_presets argument to find() and find_one()
Add option to use add/remove/set modes when updating multi-entity fields.
Add explicit file handler close to download_attachment.
Add basic find() ordering support to mockgun.
Allow for product specific authorization parameters.
Reverted the change to the default field names for image uploading.
Refactored nested classing of sgtimezone library to allow for serializable timestamps.
Make sure HTTP proxy authentication works with the @ character in a password.
Make sure sudo authentication test works with Shotgun versions after v6.3.10.
Smarter uploading of thumbnails and filmstrips with the upload() method.
Improve Travis build integration of the Python-API to run the full suite of API tests instead of just the unit and client tests.
Updating testing framework to use environment variables inconjunction with existing
example_config file so that commits and pull requests are automatically run on travis-ci.
Fix to prevent stripping out case-sensitivity of a URL if the user passes their credentials to
config.server as an authorization header.
Add handling for Python versions incompatible with SHA-2 (see this blog post).
Add SHOTGUN_FORCE_CERTIFICATE_VALIDATION environment variable to prevent disabling certficate
validation when SHA-2 validation is not available.
Add SSL info to user-agent header.
Not released.
Fix for python bug #23371 on Windows loading mimetypes module (thanks @patrickwolf).
Fix for tests on older versions of python.
Sanitize authentication values before raising error.
Added method text_search() which allows an API client to access the Shotgun global search
and auto completer.
Added method activity_stream_read() which allows an API client to access the activity
stream for a given Shotgun entity.
Added method note_thread_read() which allows an API client to download an entire Note
conversation, including Replies and Attachments, using a single API call.
Added an experimental mockgun module which can be used to emulate the Shotgun API, for
example inside unit test rigs.
[minor] Improved docstrings.
Update bundled httplib2 module to latest v0.9.1 - fixes some bugs
Add authentication support for Shotgun servers with two-factor authentication turned on.
Add ability to authenticate with Shotgun using session_token.
Add get_session_token() method for obtaining token to authenticate with.
Add new AuthenticationFault exception type to indicate when server communication has failed
due to authentication reasons.
Add support for SHOTGUN_API_CACERTS environment variable to provide location of external
SSL certificates file.
Fixes and updates to various tests.
Add ability to query the per-project visibility status for entities, fields and statuses. (requires Shotgun server >= v5.4.4)
Add ability to update last_accessed_by_current_user on Project.
Add workaround for bug #9291 in Python 2.7 affecting mimetypes library on Windows.
Add platform and Python version to user-agent (eg. shotgun-json (3.0.17); Python 2.7 (Mac))
Add flag to ignore entities from archived Projects.
Add support for differentiating between zero and None for number fields.
Add ability to act as a different user.
Fixed bug which allowed a value of None for password parameter in
authenticate_human_user()
Add follow(), unfollow() and followers() methods.
Add ability to login as HumanUser.
Ensure that webm/mp4 mime types are always available.
Updated link to video tour in README.
Fixes and updates to various tests.
added: additional tests for thumbnails.
added: support for downloading from s3 in download_attachment(). Accepts an Attachment
entity dict as a parameter (is still backwards compatible with passing in an Attachment id).
added: optional file_path parameter to download_attachment() to write data directly to
disk instead of loading into memory. (thanks to Adam Goforth @aag)
fixed: #20856 authenticate_human_user() login was sticky and would be used for permissions
and logging.
no tag
added: #18171 New ca_certs argument to the Shotgun constructor to specify the
certificates to use in SSL validation.
added: setup.py doesn’t compress the installed .egg file which makes the
cacerts.txt file accessible.
added: nested filter syntax (see Filter Syntax)
added: add_user_agent() and reset_user_agent() methods to allow client code to add
strings to track.
added: Changed default user-agent to include API version.
updated: advanced summarize filter support.
fixed: #19830 share_thumbnail() errors when source has no thumbnail.
added: share_thumbnail() method to share the same thumbnail record and media between
entities.
added: proxy handling to methods that transfer binary data (ie. upload(),
upload_thumbnail(), etc.).
updated: default logging level to WARN.
updated: documentation for summarize() method, previously released but without
documentation.
fixed: unicode strings not always being encoded correctly.
fixed: create() generates error when return_fields is None.
fixed: clearing thumbnail by setting image value to None not working as expected.
fixed: some html entities being returned sanitized via API.
improved: simplejson fallback now uses relative imports to match other bundled packages.
improved: various error messages are now clearer and more informative.
installation is now pip compatible.
use relative imports for included libraries when using Python v2.5 or later.
replace sideband request for image (thumbnail) field with native support (requires Shotgun
server >= v3.3.0. Request will still work on older versions but fallback to slow sideband
method).
allow setting image and filmstrip_thumbnail in data dict on create() and
update() (thanks @hughmacdonald).
fixed bug causing Attachment.tag_list to be set to "None" (str) for uploads.
added support for access to WorkDayRules (requires Shotgun server >= v3.2.0).
added support for filmstrip thumbnails (requires Shotgun server >= v3.1.0).
fixed download_attachment() pointing to incorrect url.
fixed some issues with module import paths.
now uses JSON as a transport rather than XML-RPC. This provides as much as a 40% speed boost.
added the summarize() method.
refactored single file into package.
tests added (Thanks to Aaron Morton @amorton).
return all strings as ascii for backwards compatibility, added ensure_ascii parameter to
enable returning unicode.
fix: update() method should return a dict object not a list.
optimization: don’t request paging_info unless required (and server support is available).
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.
add support for local files. Injects convenience info into returned hash for local file links.
add support for authentication through http proxy server.
add revive() method to revive deleted entities.
find(): default sorting to ascending, if not set (instead of requiring
ascending/descending).
upload() and upload_thumbnail(): pass auth info through.
fix python gotcha about using lists / dictionaries as defaults (see this page for more info).
add schema_read() method.
add additional retries for connection errors and a catch for broken pipe exceptions.
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).
fixed deprecation warnings to raise Exception class for python 2.5.
made upload() and upload_thumbnail() methods more backwards compatible.
changes to find_one(): now defaults to no filter_operator.
fixed upload() and upload_thumbnail() methods.
added download_attachment() 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.