Item()

class Item(parent=None)

This class describes an Item object child of Aquarium class.

append(type='', data={}, edge_type='Child', edge_data={}, apply_template=None, template_key=None, path=None)

Create and append a new item to the current one

Tip

The type of the item is case sensitive ! By convention, all items’ type start with a capital letter

Parameters:

• type (string) – The new item type

• data (dictionary) – The new item data, optional

• apply_template (boolean, optional) – Do apply template ?

• template_key (string, optional) – The template key to apply. If no template key, automatic context’s template will be used.

• path (string, optional) – File path you want to upload on the appended item

Returns:

Dictionary composed by an item and its edge.

Return type:

dict {item: Item or subclass : Asset | Project | Shot | Task | Template | User | Usergroup | Organisation, edge: Edge}

apply_template(template_key='')

Apply a template on the item

Parameters:

template_key (string) – The key of the template

Returns:

Item object

Return type:

Item or subclass : Asset | Project | Shot | Task | Template | User | Usergroup

compare(key='')

Compare the item with a given item

Parameters:

key (string) – The key of the item to compare with

Returns:

The comparison result

Return type:

dictionary

convert_to_template(parent_key='')

Convert an item and its hierarchy to a template into a parent

Parameters:

parent_key (string) – The key of the parent

Returns:

template object

Return type:

Template

copy(parent_key='')

Copie the item into the parent

Parameters:

parent_key (string) – The key of the parent

Returns:

List of new items object

Return type:

List of Item or subclass : Asset | Project | Shot | Task | Template | User | Usergroup

create(type='', data={}, path=None)

Create an item

Warning

We advice you to use append() instead of create(). This function will create an item, without inserting it to an existing hiearchy. Once the item is created, you should use Edge create() function to connect it to an other existing item.

Tip

The type of the item is case sensitive ! By convention, all items’ type start with a capital letter

Parameters:

• type (string) – The newitem type

• data (dictionary, optional) – The newitem data

• path (string, optional) – File path you want to upload on the appended item

Returns:

Item object

Return type:

Item or subclass : Asset | Project | Shot | Task | Template | User | Usergroup

create_permission(participant_key, permissions, propagate=True)

Create a new permission on an item. It’s like sharing an item to an existing user, usergroup or organisation.

Parameters:

• participant_key (string) – The _key of the user, usergroup or organisation to invite.

• permissions (string) – The permissions you want to grant to the participant.

• propagate (boolean, optional) – Propagate or not this new permission.

Tip

Available permissions :

• Can read is r

• Can write is w

• Can add content is a

• Can trash content is t

• Can link (assign, favorite..) is l

• Can unlink is u

• Can share is s

• Can delete is d

• Can change permissions is g

Examples:

• Read only is permissions=’r’

• Write is permissions=’rwa’

• Write & connect is permissions=’rwalu’

• Write, connect & trash is permissions=’rwatlu’

• Write, connect, trash & share is permissions=’rwatslu’

• Admin is permissions=’rwsadtlug’

The special permission *, is to avoid permissions inheritage when append content.

Returns:

A dict with the {user: participant, edge: the created permission edge}

Return type:

dict

delete()

Delete the item.

Danger

The item will be completely deleted. You can use trash() instead

Returns:

Deleted item object from API

Return type:

dictionary

download_file(path, versionKey=None)

Download the item’s file to the path

Parameters:

• path (string) – The path used to store the download. If directory is provided, the file name from original file is used

• versionKey (string, optional) – The versionKey used to download the file

export_json()

Export item hierarchy to json

Returns:

Exported items and edges

Return type:

dictionary

get(populate=False, history=False)

Get item object with its _key

Parameters:

• populate (boolean) – Populate item.createdBy and item.updatedBy with User object

• history (boolean, optional) – Get previous item’s data history

Returns:

Item object

Return type:

Item or subclass : Asset | Project | Shot | Task | Template | User | Usergroup

get_children(show_hidden=False, types=None, names=None, limit=50, offset=0)

Gets the children of the item

Parameters:

• show_hidden (boolean, optional) – Show hidden items

• types (string or list, optional) – One string or list of string items type you want to filter

• names (string or list, optional) – One string or list of string items name you want to filter

• limit (integer, optional) – Maximum limit of returned items

• offset (integer, optional) – Number of skipped items. Used for pagination

Returns:

List of item and edge object

Return type:

list of {item: Item, edge: Edge}

get_history(populate=False)

Get the previous item’s data history

Parameters:

populate (boolean, optional) – Populate item.createdBy and item.updatedBy with User object

Returns:

The versions values

Return type:

list

get_parents(limit=50, offset=0)

Gets the parents of the item

Parameters:

• limit (integer, optional) – Maximum limit of returned items

• offset (integer, optional) – Number of skipped items. Used for pagination

Returns:

List of item and edge object

Return type:

list of {item: Item, edge: Edge}

get_permissions(sort=None, populate=False, offset=0, limit=50, depth=1, includeMembers=False)

Gets the permissions of the item

Parameters:

• sort (boolean, optional) – Sort participants with a meshQL expression. Example: ‘item.data.name ASC’

• populate (boolean, optional) – Populate with User object

• offset (integer, optional) – Number of skipped items. Used for pagination

• limit (integer, optional) – Maximum limit of returned items

• includeMembers (boolean, optional) – Include members of the current item

Returns:

List of edge and user

Return type:

list

get_shortest_path(key='')

Get the shortest path between the current item and the item _key

Parameters:

key (string) – The destination key

Returns:

List of item Object

Return type:

list of Item or subclass : Asset | Project | Shot | Task | Template | User | Usergroup

get_trash(meshql='# -($Child)> *')

Gets the trashed items

Parameters:

meshql (string, optional) – The meshql string. Default is : # -($Child)> *

Returns:

List of trashed item and edge object

Return type:

list of {item: Item, edge: Edge}

get_versions(populate=False)

Alias of get_history()

import_json(content={})

Import item hierarchy from json content

Parameters:

content (dictionary) – The json content

Returns:

Dictionary of imported items and edges

Return type:

dictionary

link(to_key, type='Child', data={})

Create an edge from this item to the item in to_key param

Tip

The type of the edge is case sensitive ! By convention, all edges’ type start with a capital letter

Parameters:

• type (string) – The edge type

• to_key (string) – The destination key

• data (dictionary, optional) – The edge data

Returns:

Edge object

Return type:

Edge

move(old_parent_key=None, new_parent_key=None)

Move item from old parent to new parent

Parameters:

• old_parent_key (string) – The key of the old parent

• new_parent_key (string) – The key of the new parent

Returns:

New item parent and new child edge

Return type:

dictionary {item: Item,edge: Edge}

reapply_template(template_key=None)

Re-apply the specific template

Parameters:

template_key (string) – The key of the template to re-apply

Returns:

Item object

Return type:

Item or subclass : Asset | Project | Shot | Task | Template | User | Usergroup

remove_permission(participant_key)

Remove an existing permission from an item. It’s like unsharing an item to an existing user, usergroup or organisation.

Parameters:

participant_key (string) – The _key of the user, usergroup or organisation to invite.

Returns:

A dict with the {user: participant, edge: the removed permission edge}

Return type:

dict

replace_data(data={})

Replace the item data with new ones

Danger

This is replacing all existing item data. Meaning that you can loose data.

Parameters:

data (dictionary) – The new item data

Returns:

Item object

Return type:

Item

restore()

Restore an item from trash

Returns:

Restored item

Return type:

Item

to_dict()

Convert the item to a dictionary

Returns:

The item as a dictionary

Return type:

dictionary

trash()

Move item to the trash

Returns:

Trashed item

Return type:

dictionary

traverse(meshql='', aliases={})

Execute a traverse from the current item

Parameters:

• meshql (string) – The meshql string

• aliases (dictionary, optional) – The aliases used in the meshql query

Returns:

List of item and/or edge or VIEW used in the meshql query

Return type:

list

traverse_trashed(meshql='', aliases={})

Execute a traverse from the current item on trashed_items

Parameters:

• meshql (string) – The meshql string

• aliases (dictionary, optional) – The aliases used in the meshql query

Returns:

List of item and/or edge or VIEW used in the meshql query

Return type:

list

update_data(data={}, deep_merge=True)

Update the item data by merging the existing ones with the new ones

Parameters:

• data (dictionary) – The new item data

• deep_merge (boolean, optional) – Merge nested objects

Returns:

Item object

Return type:

Item

update_permission(participant_key, permissions, propagate=True)

Update an existing permission on an item.

Parameters:

• participant_key (string) – The _key of the user, usergroup or organisation to invite.

• permissions (string) – The permissions you want to grant to the participant.

• propagate (boolean, optional) – Propagate or not this new permission.

Tip

Available permissions are the same than create_permission()

Returns:

A dict with the {user: participant, edge: the updated permission edge}

Return type:

dict

upload_file(path='', data={}, message=None)

Upload a file on the item

Warning

This function will replace the data on the item. It’s here to replace the existing file’s data by creating a new history entry. We advice you to use append() if you want to upload the file as a new item.

Parameters:

• path (string) – The path of the file to upload

• data (dict) – The data you want to upload with the file, optional

• message (string) – The message associated with the upload, optional

Returns:

Item object

Return type:

Item