Perforce Framework

Common Perforce functionality used by various apps & hooks
By: Shotgun Software
Latest Version: v0.1.15 (alpha)
For our version numbers, we follow the Semantic Versioning standard.
System Name: tk-framework-perforce


This framework provides common Perforce actions and utility functions that can be used by other apps and hooks to integrate with Perforce. It also includes the default set of app hooks that the Games configuration uses for this integration.

Experimental Framework!

Please note that the latest release of this framework is v0.1.15, meaning that its interfaces are still experimental. While we try hard not to break backwards compatibility between updates, this still occasionally happens when the version number starts with a zero. Once the framework reaches 1.0, interfaces do not to break between major version number changes. For more information about these conventions, see the Semantic Versioning standard guidelines.

Overview Video

The following video gives a quick overview of features and functionality.



We're currently working on the docs for this framework but in the mean time, for a more high-level overview of how we've integrated Perforce into Shotgun Pipeline Toolkit, please see this page:

What's included in the Framework?

Rather than just wrap the Perforce API, the Perforce framework incorporates P4Python and then a set of utility functions that provide common functionality such as opening a connection through a dialog, checking out the latest version, etc. A connected P4Python instance can always be obtained for more direct access to Perforce commands.


The Toolkit Perforce integration uses the standard P4Python modules provided by Perforce. This framework includes versions of P4Python for the various operating systems & applications that Toolkit works with. However, in case the version you need isn't included then it will just load it from your Python path if it can.


(coming soon...)


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.14.61 or higher to use this.


Below is a summary of all the configuration settings used. These settings need to be defined in the environment file where you want to enable this App or Engine.


Type: hook

Default Value: get_perforce_user

Description: Specify a hook that will return the Perforce user name for a specified Shotgun user name


Type: hook

Default Value: store_publish_data



Type: str

Description: Name of the host computer to impersonate when connecting to Perforce. This is usually left empty!


Type: str

Description: Perforce server to connect to. Should be of the form: 'protocol:server:port'. e.g. 'tcp:perforce:1666'


Type: hook

Default Value: get_shotgun_user

Description: Specify a hook that will return the Shotgun user name for a specified Perforce user name


Type: hook

Default Value: store_review_data



Type: list

Description: A list of aliases for the Perforce server - if the Perforce server is moved or given a new protocol, name or port, adding the original to this list will allow Toolkit to continue using publishes that were published to the old server. The current server should always be specified in the 'server' setting.


Type: hook

Default Value: load_publish_data



Type: hook

Default Value: load_review_data



Release Notes

Welcome to the release notes for this App. 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!



Added debugging and fixed a few bugs.


  • The tool now prints out more debugging information.
  • If a user has a workspace without a host, it will be shown in the workspace dialog.
  • Various error reporting bugs were fixed.



Added user activity metrics for particular actions


Connecting to Perforce is now exclusive across multiple threads.


  • When connecting to Perforce from multiple threads, the user is now only presented with a single connection dialog/password entry at a time and once they have successfully connected they will no longer be prompted from other threads.
  • This requires a fix in core v0.16.18 to work correctly


Added support for Perforce SSL connections


  • Added SSL support to all versions of P4Python distributed with the framework
  • Added call to 'p4 trust' as part of connecting to Perforce to ensure the SSL fingerprint is trusted. If it isn't then the user will be prompted to confirm the changed fingerprint.
  • Added README to the /resources folder detailing the build process for P4Python.


Updated P4Python to include SSL support for Windows VS2012 x64 version


Added Windows x64 VS2012 P4Python module for Maya 2015


  • This adds PyPython support for Maya 2015 and other applications on Windows running a Python version compiled against 64-bit Visual Studio 2012.


General bug fixes


  • Fixed issue where the filter_publishes hook would fail if for some reason the path for a publish was invalid (None)
  • util.open_file_for_edit() now works correctly when the file being opened had previously been deleted from Perforce (headRev is delete or move/delete)


Adds .PSB support in Photoshop.


Requires tk-photoshop v0.3.0.


Update to support 3dsmaxplus.


Adds all the necessary hooks to support 3dsmaxplus engine.


Fixed P4Python import issue in 3ds Max 2014


  • Previously, P4Python wouldn't load into 3ds Max 2014 as it was trying to load the wrong version.


Added 3ds Max support


Addition of hook for experimental support for tk-shotgun-launchpublish


Various minor improvements

Details: - Load/Store hooks now take an optional P4 connection instance - Workspace can now be set to '' in connect() method to allow connection without a Workspace - Improved validation of Perforce user obtained from Shotgun user via hook - Updated to require core v0.14.47 - Settings now work correctly with PyQt


Updated documentation


Fixed order of operations for the scene operation hooks when opening files


Various improvements and fixes:

Details: - Default get-perforce/shotgun hooks no longer assume custom sg field. - Updated hook for loader to be compatible with latest version - Moved hooks from games config into framework - Added utility method to get change details - Connecting without a workspace is now supported correctly


General improvements and fixes

Details: - Opening a file for edit now handles the file being opened by another user - Store/load of review data is now fully implemented


General improvements and restructuring


Various fixes and improvements

Details: - Addition of hooks for storing and loading review (version) data - Default store/load publish hooks now use a combination of perforce attributes and Shotgun attachments - Improvements to file utils to be a lot more robust - Added functions to construct/deconstruct Perforce url's from depot paths - Lots of other changes!


Added missing P4Python build for OSX plus other minor tweaks


Minor fixes and improvements


Added hooks to manage storing/loading of publish data


Fixed fstat utils to better handle Windows file paths


Initial version of the framework