Skip to content

SG-40841 Cleanup Python code examples in docs #421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 5 commits into
base: master
Choose a base branch
from
Draft

SG-40841 Cleanup Python code examples in docs #421

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e40bc0b
Auto update done by CoPilot
julien-lang Oct 27, 2025
4c7576a
test better
julien-lang Oct 27, 2025
f2fb0c7
More co pilot
julien-lang Oct 27, 2025
cc99aee
Update docs/reference.rst
julien-lang Oct 27, 2025
653c657
Update docs/cookbook/examples/ami_version_packager.rst
julien-lang Oct 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions docs/authentication.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,23 @@ User-based Authentication
*************************
When authenticating as a user, you provide your normal login and password when instantiating your :class:`shotgun_api3.Shotgun` object. The actions performed by this instance will be limited to your permission level just as they are in the web application. ::

sg = shotgun_api3.Shotgun("https://my-site.shotgrid.autodesk.com",
login="rhendriks",
password="c0mPre$Hi0n")
sg = shotgun_api3.Shotgun(
"https://my-site.shotgrid.autodesk.com",
login="rhendriks",
password="c0mPre$Hi0n",
)


***************************
Script-based Authentication
***************************
In order to authenticate as a script, your script must be :ref:`registered with Flow Production Tracking and have a valid API key <setting_up_shotgrid>`. When creating your :class:`shotgun_api3.Shotgun` object, provide the ``script_name`` and ``api_key``.::

sg = shotgun_api3.Shotgun("https://my-site.shotgrid.autodesk.com",
script_name="compress",
api_key="0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef")
sg = shotgun_api3.Shotgun(
"https://my-site.shotgrid.autodesk.com",
script_name="compress",
api_key="0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
)

.. note:: When using script-based authentication, we **strongly** recommend you register each script separately with Flow Production Tracking and have individual API keys for each. This allows you to track down each of your scripts and the actions they are performing much more accurately in the event logs.

Expand Down
204 changes: 112 additions & 92 deletions docs/cookbook/attachments.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,21 +100,25 @@ will vary.

::

{'content_type': 'image/jpeg',
'link_type': 'upload',
'name': 'western1FULL.jpg',
'url': 'https://my-site.shotgrid.autodesk.com/file_serve/attachment/538'}
{
"content_type": "image/jpeg",
"link_type": "upload",
"name": "western1FULL.jpg",
"url": "https://my-site.shotgrid.autodesk.com/file_serve/attachment/538",
}

- **Web links**
Designated by ``link_type: 'web'``, this is represents a url link. Examples include an
``http://`` link to another server or a custom protocol used to launch a local application
like ``rvlink://`` or ``cinesync://``
::

{'content_type': None,
'link_type': 'web',
'name': 'Join GUN12158',
'url': 'cinesync://session/GUN12158'}
{
"content_type": None,
"link_type": "web",
"name": "Join GUN12158",
"url": "cinesync://session/GUN12158",
}

- **Local Files**
Designated by ``link_type: 'local'``, this is represents a local file link. Additional keys
Expand All @@ -124,17 +128,21 @@ will vary.

::

{ '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'}
{
"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",
}


********************
Expand All @@ -146,14 +154,14 @@ Web Links
::

myurl = {
'url': 'http://apple.com/itunes',
'name': 'Apple: iTunes'
"url": "http://apple.com/itunes",
"name": "Apple: iTunes",
}
data = {
'this_file': myurl,
'project': {'type':'Project','id':64}
"this_file": myurl,
"project": {"type": "Project", "id": 64},
}
result = sg.create('Attachment', data)
result = sg.create("Attachment", data)


Uploads
Expand Down Expand Up @@ -245,24 +253,33 @@ Reading Local File Fields

::

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

Returns::

{'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'}
{
"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
Expand Down Expand Up @@ -308,36 +325,37 @@ Example 1: Using ``local_path``

::

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

Returns::

{
'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'
"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'
"url": "file:///Users/kp/Movies/testing/test_movie_002.mov",
},
'type': 'Version',
"type": "Version",
}

The ``content_type`` was assigned a best-guess value based on the file extension. Flow Production Tracking selected
Expand All @@ -349,39 +367,40 @@ Example 2: Using ``relative_path``

::

result = sg.update(
'Version',
123,
{
'sg_uploaded_movie': {
'local_storage': {
'type': 'LocalStorage',
'name': 'Dailies Directories',
sg.update(
"Version", # entity_type
123, # entity_id
{ # data
"sg_uploaded_movie": {
"local_storage": {
"type": "LocalStorage",
"name": "Dailies Directories",
},
'relative_path': 'testing/test_movie_002.mov',
"relative_path": "testing/test_movie_002.mov",
}
)
},
)

Returns::

{
'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'
"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'
"url": "file:///Users/kp/Movies/testing/test_movie_002.mov",
},
'type': 'Version',
"type": "Version",
}


Expand All @@ -390,11 +409,12 @@ Un-setting local file field values

Removing a a local file field value is simple. Just set the value to ``None``::

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

Returns::

{'id':123,
'sg_uploaded_movie': None,
'type': 'Version'}]
{
"id": 123,
"sg_uploaded_movie": None,
"type": "Version",
}
60 changes: 30 additions & 30 deletions docs/cookbook/examples/ami_handler.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,30 +45,29 @@ via ``POST``. If you're using a custom protocol the data is sent via ``GET``.

In a more human-readable state that would translate to something like this:
{
'project_name': 'Demo Project',
'user_id': '24',
'title': 'All Versions',
'user_login': 'shotgun',
'sort_column': 'created_at',
'entity_type': 'Version',
'cols': 'created_at',
'ids': '5,2',
'selected_ids': '2,5',
'sort_direction': 'desc',
'project_id': '4',
'session_uuid': 'd8592bd6-fc41-11e1-b2c5-000c297a5f50',
'column_display_names':
[
'Version Name',
'Thumbnail',
'Link',
'Artist',
'Description',
'Status',
'Path to frames',
'QT',
'Date Created'
]
"project_name": "Demo Project",
"user_id": "24",
"title": "All Versions",
"user_login": "shotgun",
"sort_column": "created_at",
"entity_type": "Version",
"cols": "created_at",
"ids": "5,2",
"selected_ids": "2,5",
"sort_direction": "desc",
"project_id": "4",
"session_uuid": "d8592bd6-fc41-11e1-b2c5-000c297a5f50",
"column_display_names": [
"Version Name",
"Thumbnail",
"Link",
"Artist",
"Description",
"Status",
"Path to frames",
"QT",
"Date Created",
],
}

This simple class parses the url into easy to access types variables from the parameters,
Expand All @@ -83,18 +82,19 @@ via ``POST``. If you're using a custom protocol the data is sent via ``GET``.
The parameters variable will be returned as a dictionary of string key/value pairs. Here's
how to instantiate:

sa = ShotgunAction(sys.argv[1]) # sys.argv[1]
sa = ShotgunAction(sys.argv[1]) # sys.argv[1]

sa.params['user_login'] # returns 'miled'
sa.params['user_id'] # returns 123
sa.protocol # returns 'myCoolProtocol'
sa.params["user_login"] # returns "miled"
sa.params["user_id"] # returns 123
sa.protocol # returns "myCoolProtocol"
"""


# ---------------------------------------------------------------------------------------------
# Imports
# ---------------------------------------------------------------------------------------------
import sys, os
import sys
import os
import logging as logger

# ---------------------------------------------------------------------------------------------
Expand Down Expand Up @@ -213,7 +213,7 @@ via ``POST``. If you're using a custom protocol the data is sent via ``GET``.
logger.info("action: %s" % action)

# extract the parameters
# 'column_display_names' and 'cols' occurs once for each column displayed so we store it as a list
# "column_display_names" and "cols" occurs once for each column displayed so we store it as a list
params = params.split("&")
p = {"column_display_names": [], "cols": []}
for arg in params:
Expand Down
Loading
Loading