Welcome to `pyshotgrid`!¶

pyshotgrid is a python package that gives you a pythonic and object-oriented way to talk to Autodesk Flow Production Tracking (formerly known as ShotGrid or Shotgun).

Quickstart¶

Install pyshotgrid via pip:

pip install pyshotgrid

You are now ready to use it in your project (For other installation methods see the Installation section in the documentation)! Here is a quick example to list the “code” (aka. “name”) of all shots from all projects:

import pyshotgrid as pysg

site = pysg.new_site(base_url='https://example.shotgunstudio.com',
                     script_name='Some User',
                     api_key='$ome_password')

for project in site.projects():
    print(project["name"].get())
    for shot in project.shots():
        print(shot["code"].get())

Features¶

In pyshotgrid you are working with SGEntity instances which each represent exactly one entity in ShotGrid. Any operation on it is reflected to ShotGrid. So for example you can :

Get entity fields in ShotGrid

# Get the value of a field ...
print(sg_project["name"].get())  # "foobar"
# ... or get multiple fields at once.
print(sg_project.get(["name", "tank_name"]))  # {"name": "foobar", "tank_name": "fb"}

Update entity fields in ShotGrid

# Set the value of a field ...
sg_project["name"].set("foobar")
# ... or set multiple fields at once.
sg_project.set({"name": "foobar", "tank_name": "fb"})

Values are automatically converted to pyshotgrid objects which makes it possible to chain queries together.
```
# Name of the first Version in a Playlist.
print(sg_playlist["versions"].get()[0]["code"].get())
```

Get information about a field

print(sg_project["name"].data_type)     # "text"
print(sg_project["name"].description)   # "The name of the project."
print(sg_project["name"].display_name)  # "Project Name"

Upload/Download to/from a field

sg_version['sg_uploaded_movie'].upload('/path/to/movie.mov')
sg_version['sg_uploaded_movie'].download('/path/to/download/to/')

Get the URL of the entity

print(sg_project.url)  # https://example.shotgunstudio.com/detail/Project/1

Convert it to a regular dict, to use it in Autodesk shotgun_api3.
```
sg_project.to_dict()  # {"type": "Project", "id": 1}
```

Iterate over all fields

# Iterate over the fields directly to get some information about them...
for field, value in sg_project.fields().items():
     print(field.display_name)
# ... or iterate over the fields and values at the same time.
for field_name, value in sg_project.all_field_values().items():
     print(field_name, value)

Do you keep forgetting which field is the “name” of an entity? (was it “code” or “name”?) Just use the “SGEntity.name” property:

sg_project.name  # returns the "name" field.    Same as:  sg_project["name"]
sg_shot.name     # returns the "code" field.    Same as:  sg_shot["code"]
sg_task.name     # returns the "content" field. Same as:  sg_task["content"]

It is possible to inherit from SGEntity and create implementations for specific entity types. pyshotgrid ships with a few common entities by default. For example the implementation for the Project entity (SGProject) gives you additional functions to query shots, assets or publishes:
```
sg_project.shots()
sg_project.assets()
sg_project.publishes()
```
Checkout the overview of all the default entities and the API documentation for all the extra functionality! As an additional bonus: You can customize and extend all these classes to your hearts content. Have a look at How to add custom entities in the docs.

FAQ¶

Is it faster than shotgun_api3?¶

No, and since it is build on top of shotgun_api3, it never will be. pyshotgrid is syntactic sugar that hopefully enables you to develop better and faster. :)

Is `pyshotgrid` replacing shotgun_api3?¶

No, quite the opposite. It is meant to be used in conjunction with shotgun_api3 and improve handling and writing code with it. Its main goal is to make it easier to write code for common scenarios and leave the special cases for shotgun_api3. That said, it is totally possible to write pyshotgrid code without using shotgun_api3.

I have some custom entity setup in ShotGrid. Can this be reflected in `pyshotgrid`?¶

Yes, it can! By default pyshotgrid returns any entity as SGEntity to provide a minimum of functionality in all cases. However, you can write your own class that inherits from SGEntity and register that to pyshotgrid. After that, pyshotgrid will use your custom entity whenever you ask for it. With this method you can even overwrite default classes that ship with pyshotgrid.

Is this an official project from Autodesk?¶

No, just a brainchild from me, Fabian Geisler. I am a Pipeline Developer based in Berlin. Feel free to follow me on GitHub. :)

How will the rebranding from “ShotGrid” to “Flow Production Tracking” affect this project?¶

There will be no code-breaking name changes and pyshotgrid will not be rebranded. Only docs and docstrings will use the new name.

Credits¶

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template (but was heavily modified in the meantime).

Welcome to pyshotgrid!¶