Working With Local Files

Working With Local Files

Introduction

We added support for linking to local files in the UI in v2.1. This doc covers how to work with these local file links using the API.

Requirements

• Python API v3.0.3+
• Shotgun v2.1.10+

Structure of local file values

There is a new key in the dictionary that represents file/link fields called link_type which can be one of ['local', 'upload', 'web']. This is to help determine what type of link value of the field is. For local files this value is always local and there are additional keys that are available:

• content_type: the mime-type of the associated local file. This is assigned automatically using a best-guess based on the file extension. You can override this by setting this explicitly.
• link_type: 'local'
• name: the display name of the local file. This is set to the filename by default but can be overridden by setting this explicitly.
• local_path: the full path to the file on the current platform. The Python API tries to determine the platform it is currently running on and then copies the value from the corresponding key above to this field for convenience.
• local_path_linux: full path to file on a Mac as defined by the LocalStorage (or None if no Linux path is set)
• local_path_mac: full path to file on a Mac as defined by the LocalStorage (or None if no Mac path is set)
• local_path_windows: full path to file on a Mac as defined by the LocalStorage (or None if no Windows path is set)
• local_storage: a dictionary representing which LocalStorage entity is applied for this local file link
• url: a file:// link provided for convenience pointing to the value in the local_path

Reading local file field values

fields = ['sg_uploaded_movie']
result = sg.find('Version', [['id', 'is', 123]], fields)

result is:

{'id':123,
 'sg_uploaded_movie': { 'content_type': None,
                        'link_type': 'local', 
                        'name': 'my_test_movie.mov', 
                        'local_path': '/Users/kp/Movies/testing/test_movie_001_.mov' 
                        'local_path_linux': '/home/users/macusers/kp/Movies/testing/test_movie_001_.mov'
                        'local_path_mac': '/Users/kp/Movies/testing/test_movie_001_.mov'
                        'local_path_windows': 'M:\\macusers\kp\Movies\testing\test_movie_001_.mov'
                        'local_storage': {'id': 1,
                                          'name': 'Dailies Directories',
                                          'type': 'LocalStorage'},
                        'url': 'file:///Users/kp/Movies/testing/test_movie_001_.mov'}, 
 'type': 'Version'}

Note: When viewing results that include file/link fields with local file link values, all of the keys will be returned regardless of whether there are values in them. So in the above example, if there was no windows path set for the local storage, local_path_windows would be None.

Modifying local file field values

When setting a file/link field value to a local file, only the local_path is mandatory. Shotgun will automatically select the appropriate matching local storage for your file based on the path. You can optionally specify the name and content_type fields if you wish to override their defaults. Any other keys that are provided will be ignored.

• content_type: string (optional) the mime-type of the associated local file. This is assigned automatically using a best-guess based on the file extension.
• name: string (optional) the display name of the local file. This is set to the filename by default.
• local_path: string the full path to the file. Shotgun will find the LocalStorage that has the most specific match to this path and automatically assign that LocalStorage to the file.

data = {'sg_uploaded_movie': {'local_path': '/Users/kp/Movies/testing/test_movie_002.mov',
                              'name': 'Better Movie'}
result = sg.update('Version', 123, data)

result is:

{'id':123,
 'sg_uploaded_movie': { 'content_type': 'video/quicktime',
                        'link_type': 'local', 
                        'name': 'my_test_movie.mov', 
                        'local_path': '/Users/kp/Movies/testing/test_movie_002.mov' 
                        'local_path_linux': '/home/users/macusers/kp/Movies/testing/test_movie_002.mov'
                        'local_path_mac': '/Users/kp/Movies/testing/test_movie_002.mov'
                        'local_path_windows': 'M:\\macusers\kp\Movies\testing\test_movie_002.mov'
                        'local_storage': {'id': 1,
                                          'name': 'Dailies Directories',
                                          'type': 'LocalStorage'},
                        'url': 'file:///Users/kp/Movies/testing/test_movie_002.mov'}, 
 'type': 'Version'}]

The content_type was assigned a best-guess value based on the file extension. Shotgun selected the most appropriate specific LocalStorage match and assigned it to local_storage automatically.

Removing local file field values

Removing a a local file field value is simple. Just set it to None

data = {'sg_uploaded_movie': None}
result = sg.update('Version', 123, data)

result is:

{'id':123,
 'sg_uploaded_movie': None, 
 'type': 'Version'}]