Core¶

class pyshotgrid.core.SGEntity(sg, entity_id, entity_type=None)[source]¶

Bases: object

An instance of this class represents a single entity in ShotGrid.

Note

Try to avoid creating instances of this class in production code and use the pyshotgrid.new_entity method instead. This will make sure that you always get the correct entity class to work with.

DEFAULT_SG_ENTITY_TYPE: Optional[str] = None¶: The SG entity type that will be used when you do not specify it in the init arguments. For the base SGEntity this should always be None, but for sub classes this should be set to the SG entity type that the class should represent.

__init__(sg, entity_id, entity_type=None)[source]¶

Parameters:

sg (Shotgun) – A fully initialized instance of shotgun_api3.Shotgun.
entity_id (int) – The ID of the ShotGrid entity.
entity_type (Optional[str]) – The ShotGrid type of the entity.

property id: int¶

Returns:: The ID of the ShotGrid entity.

property type: str¶

Returns:: The type of the ShotGrid entity.

property sg: Shotgun¶

Returns:: The Shotgun instance that the entity belongs to.

property site: SGSite¶

Returns:: The pyshotgrid site for this entity.

property url: str¶

Returns:

The ShotGrid URL for this entity.

Note

This will only work on entities that have a detail view enabled in the system settings.

property name: Field¶

Returns:

The field that represents the name of the entity. Usually either the “code” or “name” field.

Raises:

RuntimeError:: When the current entity does not have a “name” or “code” field.

property thumbnail: Field¶

Returns:: Shortcut for the thumbnail field.

property filmstrip: Field¶

Returns:: Shortcut for the filmstrip thumbnail field.

fields(project_entity=None)[source]¶

Parameters:: project_entity (Union[dict[str, Any], SGEntity, None]) – A project entity to filter by.
Return type:: list[Field]
Returns:: All fields from this entity. If a project entity is given only fields that are visible to the project are returned.

all_field_values(project_entity=None, raw_values=False)[source]¶

Parameters:

project_entity (Union[dict[str, Any], SGEntity, None]) – A project entity to filter by.
raw_values (bool) – Whether to convert entities to pysg objects or not.

Return type:

dict[str, Any]

Returns:

All fields and values from this entity in a dict. If a project entity is given only fields that are visible to the project are returned.

to_dict()[source]¶

Creates a dict with just “type” and “id” (and does not call SG).

Example:

>>> sg_entity.to_dict()
{'type': 'CustomEntity01', 'id': 1}

Return type:: dict[str, Any]
Returns:: The entity as a dict which is ready to consume by the shotgun_api3 methods.

batch_update_dict(data)[source]¶

Parameters:: data (dict[str, Any]) – A dict with the fields and values to set.
Return type:: dict[str, Any]
Returns:: A dict that can be used in a shotgun.batch() call to update some fields. Useful when you want to collect field changes and set them in one go.

set(data, multi_entity_update_modes=None)[source]¶

Set many fields at once on this entity.

Parameters:

data (dict[str, Any]) – A dict with the fields and values to set.
multi_entity_update_modes (Optional[dict[str, Any]]) –
Optional dict indicating what update mode to use when updating a multi-entity link field. The keys in the dict are the fields to set the mode for, and the values from the dict are one of set, add, or remove. Defaults to set.
```
multi_entity_update_modes={"shots": "add", "assets": "remove"}
```

Return type:

None

get(fields, raw_values=False)[source]¶

Query many fields at once on this entity.

Parameters:

fields (list[str]) – A list of fields to query from this entity.
raw_values (bool) – Any entities will be converted to pyshotgrid instances. If you set this parameter to True you can turn this behaviour off.

Return type:

dict[str, Any]

Returns:

A dict with the fields and their corresponding values.

delete()[source]¶

Delete this entity.

Note

The python object that represents this entity does not make sense any more after you ran this method and will create errors if you keep calling functions on it.

Return type:: bool
Returns:: Whether the entity was successfully deleted.

property entity_display_name: str¶

Returns:: The display name of the current entity type.

schema()[source]¶

Return type:: dict[str, dict[str, Any]]
Returns:: The schema for the current entity.

field_schemas()[source]¶

Return type:: dict[str, FieldSchema]
Returns:: The schemas of all the entity fields.

class pyshotgrid.core.SGSite(sg)[source]¶

Bases: object

An instance of this class represents a ShotGrid site as a whole.

Note

Try to avoid creating instances of this class in production code and use the pyshotgrid.new_site method instead. This gives you more ways to initialize the this class and ensures that the plugin system is correctly used.

__init__(sg)[source]¶

Parameters:: sg (Shotgun) – A fully initialized instance of shotgun_api3.Shotgun.

property sg: Shotgun¶

Returns:: The Shotgun instance that the entity belongs to.

create(entity_type, data)[source]¶

The same function as Shotgun.create, but it accepts and returns a pyshotgrid object.

Parameters:

entity_type (str) – The type of the entity to create.
data (dict[str, Any]) – dict of fields and values to set on creation. The values can contain pysg objects.

Return type:

SGEntity

Returns:

The new created entity.

find(entity_type, filters, order=None, filter_operator=None, limit=0, retired_only=False, page=0, include_archived_projects=True, additional_filter_presets=None)[source]¶

The same function as Shotgun.find, but it accepts and returns pyshotgrid objects.

Parameters:

entity_type (str)
filters (list[list[Any]])
order (Optional[dict[str, str]])
filter_operator (Optional[str])
limit (int)
retired_only (bool)
page (int)
include_archived_projects (bool)
additional_filter_presets (Optional[str])

Return type:

list[SGEntity]

Returns:

find_one(entity_type, filters, order=None, filter_operator=None, limit=0, retired_only=False, page=0, include_archived_projects=True, additional_filter_presets=None)[source]¶

The same function as Shotgun.find_one , but it accepts and returns pyshotgrid objects.

Return type:: Optional[SGEntity]

entity_field_schemas()[source]¶

Return type:: dict[str, dict[str, FieldSchema]]
Returns:: The field schemas for all entities of the current ShotGrid Site.

project(name_or_id)[source]¶

Parameters:: name_or_id (Union[str, int]) – The name or id of the project to return. The name can either match the “tank_name” (recommended) or the “name” field.
Return type:: Optional[SGEntity]
Returns:: The found SG project or None.

projects(names_or_ids=None, include_archived=False, template_projects=False)[source]¶

Parameters:

names_or_ids (Optional[list[Union[str, int]]]) – list of names or ids of the projects to return. The names can either match the “tank_name” (recommended) or the “name” field.
include_archived (bool) – Whether to include archived projects or not.
template_projects (bool) – Whether to return template projects or not.

Return type:

list[SGEntity]

Returns:

A list of SG projects.

pipeline_configuration(name_or_id=None, project=None)[source]¶

Parameters:

name_or_id (Union[str, int, None]) – Name or ID of the PipelineConfiguration.
project (Union[dict[str, Any], SGEntity, None]) – The project that the PipelineConfiguration is attached to.

Return type:

Optional[SGEntity]

Returns:

A PipelineConfiguration or None.

people(only_active=True)[source]¶

Parameters:: only_active (bool) – Whether to list only active people or all the people.
Return type:: list[SGEntity]
Returns:: All HumanUsers of this ShotGrid site.

class pyshotgrid.core.FieldSchema(sg, entity_type, name)[source]¶

Bases: object

This class represents the schema of a field.

__init__(sg, entity_type, name)[source]¶

Parameters:

sg (Shotgun) – The current Shotgun instance this instance uses.
entity_type (str) – The type of the SG entity.
name (str) – The name of the Field.

property sg: Shotgun¶

Returns:: The Shotgun instance that the field belongs to.

property name: str¶

Returns:: The name of the field.

property entity_type: str¶

Returns:: The type of the SG entity that this Field belongs to.

property data_type: str¶

Returns:: The data type of the field.

property description: str¶

Returns:: The description of the field.

property display_name: str¶

Returns:: The display name of the field.

property custom_metadata: str¶

Returns:: Custom metadata attached to this field.

property properties: dict[str, dict[str, Any]]¶

Returns:: The properties of the field. This strongly depends on the data type of the field. This can for example give you all the possible values of a status field.

property valid_types: list[str]¶

Returns:: The valid SG entity types for entity- and multi-entity-fields.

class pyshotgrid.core.Field(name, entity)[source]¶

Bases: FieldSchema

This class represents a field on a ShotGrid entity. It provides an interface to manage various aspects of a field.

__init__(name, entity)[source]¶

Parameters:

name (str) – The name of the field.
entity (SGEntity) – The entity that this field is attached to.

property entity: SGEntity¶

Returns:: The entity that this field is attached to.

get(raw_values=False)[source]¶

Parameters:

raw_values (bool) – Whether to return the raw dict values or the values converted to pyshotgrid objects.

Return type:

Any

Returns:

The value of the field. Any entities will be automatically converted to pyshotgrid objects. Fields with type “url” will return their values as follows:

Uploaded Files:
Will return the dict that describes the uploaded file attachment, so you can pass it on to Shotgun.download_attachment().
Link to local files:
Will return the platform dependent absolute path to the linked file.
Link to a URL:
Will return the URL.

set(value)[source]¶

Set the field to the given value in ShotGrid.

Parameters:: value (Any) – The value to set the field to.
Return type:: None

add(values)[source]¶

Add some values to this field

Parameters:: values (list[Any]) – The value to add to this field.
Return type:: None

remove(values)[source]¶

Remove some values from this field.

Parameters:: values (list[Any]) – The values to remove from this field.
Return type:: None

upload(path, display_name=None)[source]¶

Upload a file to this field.

Parameters:

path (str) – The path to the file to upload.
display_name (Optional[str]) – The display name of the file in ShotGrid.

Return type:

SGEntity

Returns:

The Attachment entity that was created for the uploaded file.

download(path, create_folders=True)[source]¶

Download a file from a field.

Parameters:

path (str) – The path to download to. If you only provide a folder a file name will be auto-generated.
create_folders (bool) – Create any folders from “path” that do not exist.

Raises:

RuntimeError:: When the field is not a “url” or “image” field.
RuntimeError:: When nothing was uploaded to this field.

Return type:

str

Returns:

The full path of the downloaded file.

property schema: FieldSchema¶

Returns:: The schema of this field.

batch_update_dict(value)[source]¶

Parameters:: value (Any) – The value to set.
Return type:: dict[str, Any]
Returns:: A dict that can be used in a shotgun.batch() call to update this field. Useful when you want to collect field changes and set them in one go.

pyshotgrid.core.new_entity(sg, *args, **kwargs)[source]¶

Create a new instance of a pyshotgrid class that represents a ShotGrid entity. This function is meant to be used as the main way to create new pyshotgrid instances and will always return the correct entity instance that you should work with.

Note

This does NOT create an entity in Shotgrid. It just gives you a python object that represents an entity.

The function can be used in 3 ways which all do the same thing:

>>> import pyshotgrid as pysg
>>> sg_entity_a = pysg.new_entity(sg, {"id": 1, "type": "Project"})
>>> sg_entity_b = pysg.new_entity(sg, 1, "Project")
>>> sg_entity_c = pysg.new_entity(sg, entity_id=1, entity_type="Project")
>>> assert sg_entity_a == sg_entity_b == sg_entity_c

Parameters:

sg (Shotgun) – A fully initialized Shotgun instance.

Return type:

SGEntity

Returns:

The pyshotgrid object or None if it could not be converted.

Raises:

ValueError:: If entity type and ID could not be extracted from the given values.

pyshotgrid.core.new_site(*args, **kwargs)[source]¶

This function will create a new pyshotgrid.SGSite instance that represents a ShotGrid site. You can pass in either a shotgun_api3.Shotgun instance or the parameters of shotgun_api3.Shotgun itself. So this is equivalent:

>>> sg = shotgun_api3.Shotgun(base_url='https://example.shotgunstudio.com',
...                           script_name='Some User',
...                           api_key='$ome_password')
>>> sg_site = new_site(sg)

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

Return type:: SGSite
Returns:: A new instance of the pyshotgrid site.

pyshotgrid.core.register_pysg_class(pysg_class, shotgrid_type=None)[source]¶

Register a class for a ShotGrid type to pyshotgrid. This is best illustrated as by an example: Suppose you have a custom entity setup where you have an Episode in each project that collects some sequences of shots. It would be nice to have some additional functionality on the ShotGridEntity for episode objects (like a “sequences” function that returns all the sequences belonging to that episode). What you would do is to create a class SGEpisode that inherits from SGEntity and add all the functionality you like to it. After that you call:

register_plugin(SGEpisode)

or if you like it more explicitly:

register_plugin(pysg_class=SGEpisode,
                shotgrid_type="CustomProjectEntity01")

This will register the class to pyshotgrid and the new_entity function will automatically create an “SGEpisode” instance as soon as it encounters an Episode entity. This is also true for all queries that happen from a SGEntity. So sg_project[‘sg_episodes’] would return “SGEpisode” instances as well.

Note

Registering a class for an existing entity will overwrite the existing entity class. This way you can add/overwrite functionality for the classes that are shipped by default.

Parameters:

pysg_class (Type[SGEntity]) – The class to use for this entity type.
shotgrid_type (Optional[str]) – The ShotGrid entity type to register for. If this is None it will be taken from the _DEFAULT_SG_ENTITY_TYPE variable from the given pysg_class.

Return type:

None

pyshotgrid.core.register_sg_site_class(sg_site_class)[source]¶

Note

This defaults to the SGSite class, but you can use it to overwrite this behaviour.

Parameters:: sg_site_class (Type[SGSite]) – The class to use as a fallback.
Return type:: None

pyshotgrid.core.convert_fields_to_pysg(sg, fields)[source]¶

Convert all the values from a fields dict to pysg objects where possible.

Parameters:

sg (Shotgun) – A fully initialized Shotgun instance.
fields (dict[str, Any]) – A fields dict as returned from a shotgun_api3.Shotgun.find() call for example.

Return type:

dict[str, Any]

Returns:

The same dict with all values converted to pysg objects where possible.

pyshotgrid.core.convert_fields_to_dicts(fields)[source]¶

Convert all the values from a fields dict to simple dictionaries. The counterpart function to func:_convert_fields_to_pysg.

Parameters:: fields (dict[str, Any]) – A fields dict as returned from a shotgun_api3.Shotgun.find() call for example.
Return type:: dict[str, Any]
Returns:: The same dict with all pysg objects converted to dictionaries.

pyshotgrid.core.convert_value_to_dict(value)[source]¶

Convert any pysg objects form the given value to simple dictionaries.

Parameters:: value (Any) – A field value
Return type:: Union[dict[str, Any], list[dict[str, Any]]]
Returns:: The value with all pysg objects converted to dictionaries.

pyshotgrid.core.convert_filters_to_dict(filters)[source]¶

Convert any pysg objects form the given shotgun_api3 filter to simple dictionaries.

Example:

>>> person = SGEntity(shotgun_api3.Shotgun('...'), entity_type='HumanUser', entity_id=5)
>>> convert_filters_to_dict([['user', 'is', person]])
[['user', 'is', {'type': 'HumanUser', 'id': 5}]]

Parameters:: filters (list[list[Any]]) – The filters to convert
Return type:: list[list[Any]]
Returns:: The filter with all pysg objects converted to dictionaries.

pyshotgrid.core.convert_value_to_pysg(sg, value)[source]¶

Convert the value from a field to pysg object(s) where possible.

Parameters:

sg (Shotgun) – A fully initialized Shotgun instance.
value (Any) – A field value

Return type:

Any

Returns:

The value converted to pysg object(s) where possible.