Welcome to `pyshotgrid`!¶

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

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.

Why does `pyshotgrid` not support Python 3.7? shotgun_api3 has support for it.¶

A couple of reasons:

Python 3.7 reached EOL and is no longer maintained.
Python 3.7 is soon off the VFX Reference Platform.
The hidden goal of this project is to create a python library that uses the latest innovations in the Python world. In a nutshell I want to create the simplest setup that gives you:
- automatic publishing to PyPI
- automatic testing with tox, pytest and coverage
- automatic Sphinx documentation
- mypy type hints
- ruff linting
- black code formatting (actually done by ruff format)
- pre-commit checks
- invoke setup for common tasks in the repository
- streamlined commit messages and changelog with commitizen
A good chunk of these tools do not support Python 3.7 anymore and I do not have the time to keep up the compatibility.

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!¶