link.item

Item()

Bases: Data

Representation of a Bip item.

An Item is the highest data entity in a Bip project. It is usually used to represent shots and assets, but it can represent any type of entity needed for the project.

Items are defined by ItemModels, which define a set of rules and behaviours for the Item. For example the model controls the naming convention.

Info

This class inherits from Data, like Project, Document and Version, since they share similar behaviour. See bip.link.data.Data for inherited methods.

Attributes:

Name	Type	Description
uid	str	Bip unique identifier (uuid4). Edition is forbidden if this is an persistent (saved) entity.
slug	str	Human-readable unique identifier, namespaced in the parent model scope.
name	str	Name of the project.
folder_name	str	Folder name for path generation.
description	str	Short description of the item.
model	ItemModel	Bip item model object.

Source code in client/bip/link/item.py

def __init__(self):
    super(Item, self).__init__()
    self.uid: str = ""
    self.slug: str = ""
    self.name: str = ""
    self.folder_name: str = ""
    self.code: str = ""
    self.description: str = ""
    self.suffix: str = ""
    self.model = ItemModel
    self.sorting_weight = 0

    # Future
    self.self_contained: bool = False
    # An item can be its own content or can have a list of elements that compose it.
    # If self-contained, the item is basically itself, not a bunch of items
    # (like a shot or a layout scene would be) and adding elements is not allowed (or ignored)

    # Helpers
    self._project = None
    self._groups = []

children_count: int property

Number of Documents parented to the Item.

Returns:

Name	Type	Description
int	int	Documents count.

has_children: bool property

Does the Item have Documents.

Returns:

Name	Type	Description
bool	bool	True if the Item has Documents, False otherwise.

parent: Project property

Parent project.

Returns:

Name	Type	Description
Project	Project	parent of the item.

path: str property

Dynamic path of the item directory.

The path is dynamically generated by the running Bip client, based on the working directory.

Warning

The path may differ from a machine to another since the path uses the working_directory local setting, which might vary between machines, depending on the client config.

Returns:

Name	Type	Description
str	str	Path of the item directory.

delete(safe=True)

Deletes the Item.

By default, if the Item has Documents parented to it, the deletion won't be accepted, unless safe is set to True.

Deleting the Item deletes any downstream entity: Document, Version, Group (children only), Task and Attribute.

Parameters:

Name	Type	Description	Default
safe	bool	bool: Prevents the deletion if the Item has children (Documents) (Default value = True)	True

Raises:

Type	Description
ValueError	If safe is True and the Item has children.

Source code in client/bip/link/item.py

@permission("delete_item")
def delete(self, safe: bool = True):
    """Deletes the Item.

    By default, if the Item has Documents parented to it, the deletion won't be accepted,
    unless `safe` is set to True.

    Deleting the Item deletes any downstream entity: Document,
    Version, Group (children only), Task and Attribute.

    Args:
      safe: bool: Prevents the deletion if the Item has children (Documents) (Default value = True)

    Raises:
        ValueError: If safe is True and the Item has children.
    """
    if safe and self.has_children:
        raise ValueError(
            f"Impossible to safely delete {self}. The Item has children."
        )

    return sink.item.delete(self.to_dict())

generate(name, model=None, groups=(), auto_save=True, **kwargs) classmethod

Generates an Item object.

By default, the generated Item is saved straight after creation. In some cases, it can be useful to get the floating (not recorded on the database) object in order to perform further operation, and save after that. That can be achieved by setting auto_save to False.

Parameters:

Name	Type	Description	Default
name	str	str: Name of the new item.	required
model	Optional[ItemModel]	Optional[Union[ItemModel, str]]: Model of the new item. Can be left to None if the project has a default_item_model (see link.project), or can be the string of a ItemModel slug (Default value = None)	None
groups	Union[List, Tuple]	Union[List, Tuple]: If the ItemModel has required_memberships, list of the mandatory groups (Default value = ())	()
auto_save	bool	bool: If True, the returned object is saved. Otherwise it is floating. (Default value = True)	True
**kwargs		Any non-mandatory valid attribute of Item can be passed.	{}

Raises:

Type	Description
ValueError	Failed validation, if auto_save is True.
TypeError	Failed validation, if auto_save is True.

Returns:

Name	Type	Description
Item	Item	Generated Item.

Source code in client/bip/link/item.py

@classmethod
@permission("create_item")
def generate(
    cls,
    name: str,
    model: Optional[ItemModel] = None,
    groups: Union[List, Tuple] = (),
    auto_save: bool = True,
    **kwargs,
) -> Item:
    """Generates an Item object.

    By default, the generated Item is saved straight after creation. In some cases, it can be useful to get the
    floating (not recorded on the database) object in order to perform further operation, and save after that.
    That can be achieved by setting `auto_save` to False.

    Args:
      name: str: Name of the new item.
      model: Optional[Union[ItemModel, str]]: Model of the new item. Can be left to None if the project
        has a `default_item_model` (see `link.project`),
        or can be the string of a ItemModel slug (Default value = None)
      groups: Union[List, Tuple]: If the ItemModel has required_memberships, list of the
        mandatory groups (Default value = ())
      auto_save: bool: If True, the returned object is saved. Otherwise it is floating. (Default value = True)
      **kwargs: Any non-mandatory valid attribute of Item can be passed.

    Raises:
        ValueError: Failed validation, if auto_save is True.
        TypeError: Failed validation, if auto_save is True.

    Returns:
        Item: Generated Item.
    """
    if not model:
        raise NotImplementedError("Default model is not supported yet.")

    item = cls()
    item._default()
    item.name = name
    item.model = model

    item._groups = groups
    item._project = model.project

    # Add optional attributes
    item._add_dynamic_attributes(**kwargs)

    if not item.folder_name:
        item.folder_name = string_cleaner(name, sep="_")

    if auto_save:
        item.save()

    return item

get(model, slug=None, uid=None, group=None) classmethod

Get a specific Item or all Items from an ItemModel.

It is possible to get a specific Item from its uid or its slug. When providing one, the other can be left to None. If none of these two parameters are specified, The getter becomes a global getter and returns a collection of Items.

If searching by slug and if the provided ItemModel has has_uniqueness_scope to True, a Group or its slug must be provided in order to defined the searching scope.

Examples:

project = link.project.get(slug="example")
asset = project.get_item_model(slug="asset")
shot = project.get_item_model(slug="shot")

# By slug
Item.get(model=asset, slug="john-doe")

# By uid
asset = project.get_item_model(slug="asset")
Item.get(model=asset, uid="46c12269-d5d9-40fb-8554-ed1dd9b46422")

# By slug with namespace group
Item.get(model=shot, slug="sh0100", group="seq10")

Parameters:

Name	Type	Description	Default
model	ItemModel	Union[ItemModel, str]: ItemModel object to search within. (Default value = None)	required
slug	Optional[str]	Optional[str]: Slug of an Item. If specified, uid can be left blank. (Default value = None)	None
uid	Optional[str]	Optional[str]: Uid of an Item. If specified, slug can be left blank. (Default value = None)	None
group	Optional[Union[Group, str]]	Optional[Union[Group, str]]: If the ItemModel has a uniqueness scope, Group object (or slug) in order to define the searching scope.	None

Raises:

Type	Description
TypeError	An argument has an unexpected type.
LookupError	No matching entity found.

Returns:

Type	Description
Union[Item, List[Item]]	list: Collection of Items, if no uid or slug specified.
Union[Item, List[Item]]	Item: Single Item if a uid or a slug has been specified.

Source code in client/bip/link/item.py

@classmethod
@permission("read_item")
def get(
    cls,
    model: ItemModel,
    slug: Optional[str] = None,
    uid: Optional[str] = None,
    group: Optional[Union[Group, str]] = None,
) -> Union[Item, List[Item]]:
    """Get a specific Item or all Items from an ItemModel.

    It is possible to get a specific Item from its `uid` or its `slug`.
    When providing one, the other can be left to None. If none of these two parameters are specified,
    The getter becomes a global getter and returns a collection of Items.

    If searching by slug and if the provided ItemModel has has_uniqueness_scope to True, a Group or its slug
    must be provided in order to defined the searching scope.

    Examples:
        ```python
        project = link.project.get(slug="example")
        asset = project.get_item_model(slug="asset")
        shot = project.get_item_model(slug="shot")

        # By slug
        Item.get(model=asset, slug="john-doe")

        # By uid
        asset = project.get_item_model(slug="asset")
        Item.get(model=asset, uid="46c12269-d5d9-40fb-8554-ed1dd9b46422")

        # By slug with namespace group
        Item.get(model=shot, slug="sh0100", group="seq10")
        ```

    Args:
        model: Union[ItemModel, str]: ItemModel object to search within. (Default value = None)
        slug: Optional[str]: Slug of an Item. If specified, `uid` can be left blank. (Default value = None)
        uid: Optional[str]: Uid of an Item. If specified, `slug` can be left blank. (Default value = None)
        group: Optional[Union[Group, str]]: If the ItemModel has a uniqueness scope, Group object (or slug)
            in order to define the searching scope.

    Raises:
        TypeError: An argument has an unexpected type.
        LookupError: No matching entity found.

    Returns:
        - list: Collection of Items, if no uid or slug specified.
        - Item: Single Item if a uid or a slug has been specified.
    """
    if uid or slug:
        if model.has_uniqueness_scope and not group:
            raise ValueError(
                f"The ItemModel {model} has a uniqueness scope. "
                "You must specify a group_slug"
            )
        if isinstance(group, Group):
            group = group.slug

        result = sink.item.get_item(
            model.to_dict(), slug, uid, group, scoped=model.has_uniqueness_scope
        )
        if result:
            item = cls.from_dict(result)
            item._project = model.project
            return item
    else:
        items = sink.item.get_items(model.to_dict())
        items = [cls.from_dict(i) for i in items]
        for item in items:
            item._project = model.project

        return items

get_from_project(project, uid=None) classmethod

Get a specific Item or all Items from a Project.

It is possible to get a specific Item from its uid. If no uid is provided, a collection of all the project Items is returned.

Info

This getter does not allow to search by slug since slugs are namespaced by ItemModel, therefore there can be identical slugs within the same project.

Parameters:

Name	Type	Description	Default
project	Project	Project: Project object to search within.	required
uid	Optional[str]	Optional[str]: Uid of an Item. (Default value = None)	None

Raises:

Type	Description
TypeError	An argument has an unexpected type.
LookupError	No matching entity found.

Returns:

Type	Description
	list: Collection of Items, if no uid specified.
	Item: Single Item if a uid has been specified.

Source code in client/bip/link/item.py

@classmethod
@permission("read_item")
def get_from_project(cls, project: Project, uid: Optional[str] = None):
    """Get a specific Item or all Items from a Project.

    It is possible to get a specific Item from its `uid`.
    If no uid is provided, a collection of all the project Items is returned.

    !!! info
        This getter does not allow to search by slug since slugs are namespaced by ItemModel,
        therefore there can be identical slugs within the same project.

    Args:
        project: Project: Project object to search within.
        uid: Optional[str]: Uid of an Item. (Default value = None)

    Raises:
        TypeError: An argument has an unexpected type.
        LookupError: No matching entity found.

    Returns:
        - list: Collection of Items, if no uid specified.
        - Item: Single Item if a uid has been specified.
    """
    if uid:
        item = sink.item.get_from_project(project.to_dict(), uid)
        item = cls.from_dict(item)

        # Add project to avoid an extra request
        item._project = project
        item.model._project = project

        return item
    else:
        items = sink.item.get_from_project(project.to_dict())
        items = [cls.from_dict(i) for i in items]

        # Add project to avoid an extra request
        for item in items:
            item._project = project
            item.model._project = project

        return items

get_task(model, slug=None, uid=None)

Convenient class implementation of: bip.link.task.get_task.

Warning

The signature of Item.get_task() and bip.link.task.get_task are different since Item.get_task() passes itself to the function as item=self.

Source code in client/bip/link/item.py

def get_task(
    self, model, slug: Optional[str] = None, uid: Optional[str] = None
) -> Task:
    """Convenient class implementation of: `bip.link.task.get_task`.

    !!! warning
        The signature of `Item.get_task()` and `bip.link.task.get_task`
        are different since `Item.get_task()` passes itself to the function as `item=self`.
    """
    return _task.get_task(item=self, model=model, slug=slug, uid=uid)

get_task_model(slug=None, uid=None)

Convenient class implementation of: bip.link.task.get_model.

Warning

The signature of Item.get_task_model() and bip.link.task.get_model are different since Item.get_task_model() passes itself to the function as item=self.

Source code in client/bip/link/item.py

def get_task_model(
    self, slug: Optional[str] = None, uid: Optional[str] = None
) -> TaskModel:
    """Convenient class implementation of: `bip.link.task.get_model`.

    !!! warning
        The signature of `Item.get_task_model()` and `bip.link.task.get_model`
        are different since `Item.get_task_model()` passes itself to the function as `item=self`.
    """
    return _task.get_model(item=self, slug=slug, uid=uid)

get_task_models()

Convenient class implementation of: bip.link.task.get_models.

Warning

The signature of Item.get_task_models() and bip.link.task.get_models are different since Item.get_task_models() passes itself to the function as item=self.

Source code in client/bip/link/item.py

def get_task_models(self) -> List[TaskModel]:
    """Convenient class implementation of: `bip.link.task.get_models`.

    !!! warning
        The signature of `Item.get_task_models()` and `bip.link.task.get_models`
        are different since `Item.get_task_models()` passes itself to the function as `item=self`.
    """
    return _task.get_models(item=self)

get_tasks(model=None, open_only=False)

Convenient class implementation of: bip.link.task.get_tasks.

Warning

The signature of Item.get_task() and bip.link.task.get_tasks are different since Item.get_tasks() passes itself to the function as item=self.

Source code in client/bip/link/item.py

def get_tasks(self, model=None, open_only: bool = False) -> List[Task]:
    """Convenient class implementation of: `bip.link.task.get_tasks`.

    !!! warning
        The signature of `Item.get_task()` and `bip.link.task.get_tasks`
        are different since `Item.get_tasks()` passes itself to the function as `item=self`.
    """
    return _task.get_tasks(item=self, model=model, open_only=open_only)

new_document(model, task=None, groups=(), element=None, auto_save=True, **kwargs)

Convenient class implementation of: bip.link.document.new.

Warning

The signature of Item.new_document() and bip.link.document.new are different since Item.new_document() passes itself to the function as item=self.

Source code in client/bip/link/item.py

def new_document(
    self,
    model: DocumentModel,
    task: Optional[Task] = None,
    groups: Union[List, Tuple] = (),
    element: Optional[str] = None,
    auto_save: bool = True,
    **kwargs,
) -> Document:
    """Convenient class implementation of: `bip.link.document.new`.

    !!! warning
        The signature of `Item.new_document()` and `bip.link.document.new`
        are different since `Item.new_document()` passes itself to the function as `item=self`.
    """
    return _document.new(model, self, task, groups, element, auto_save, **kwargs)

new_task(model, name=None, status=None, auto_save=True, **kwargs)

Convenient class implementation of: bip.link.task.new.

Warning

The signature of Item.new_task() and bip.link.task.new are different since Item.new_task() passes itself to the function as item=self.

Source code in client/bip/link/item.py

def new_task(
    self,
    model: Union[TaskModel, str],
    name: Optional[str] = None,
    status: Optional[Union[Status, str]] = None,
    auto_save: bool = True,
    **kwargs,
) -> Task:
    """Convenient class implementation of: `bip.link.task.new`.

    !!! warning
        The signature of `Item.new_task()` and `bip.link.task.new`
        are different since `Item.new_task()` passes itself to the function as `item=self`.
    """
    return _task.new(name, model, self, status, auto_save, **kwargs)

save()

Saves the Item to the database.

If the Item is floating, saving makes it persistent.

Attributes changes are not applied to the database at modification. Saving the Item does.

Raises:

Type	Description
ValueError	Failed validation.
TypeError	Failed validation.

Source code in client/bip/link/item.py

@permission("edit_item")
def save(self):
    """Saves the Item to the database.

    If the Item is floating, saving makes it persistent.

    Attributes changes are not applied to the database at modification.
    Saving the Item does.

    Raises:
        ValueError: Failed validation.
        TypeError: Failed validation.

    """
    if not self._is_modified and self.uid:
        return

    if not self.uid:
        self._generate_uid()

    self._validate()

    sink.item.save(self.to_dict())

    was_floating = self.is_floating

    self._sink()

    if self._groups and was_floating:
        for group in self._groups:
            try:
                self.add_to(group)
            except Exception as e:
                self.delete(safe=False)
                raise e

    if was_floating:
        try:
            self.generate_directories()
        except Exception as e:
            self.delete(safe=False)
            raise e

        try:
            execute_routine("item", CREATE, item=self)
        except Exception as e:
            self.delete(safe=False)
            raise e

ItemModel()

Bases: BipObject

Representation of a Bip item model.

The ItemModel is a template, which sets some rules that any Item modelged with this model must follow.

Attributes:

Name	Type	Description
uid	str	Bip unique identifier (uuid4). Edition is forbidden if this is an persistent (saved) entity.
slug	str	Human-readable unique identifier.
name	str	Name of the model.
plural	int	Plural of the name.
path_pattern	str	Path pattern for Items path generation.
use_suffix	bool	If True, the items must have a suffix.
suffix_format	str	If use_suffix, "alpha" (wink.SUFFIX_ALPHA) or "num" (wink.SUFFIX_NUM).
suffix_length	int	If use_suffix, length of the suffix.
suffix_name_separator	str	If use_suffix, separation string between the name and the suffix.
suffix_folder_name_separator	str	If use_suffix, separation string between the folder name and the suffix.
default_suffix	str	If use_suffix, default suffix.
folder_name_case_hint	str	Case hint (see wink.constants.case for accepted values.)
name_case_hint	str	Case hint (see wink.constants.case for accepted values.)
name_pattern	str	Regular expression used to validate the name when saving an item.
name_hint	str	Example of a valid name (used for UI).
force_name_pattern	bool	If True, the name pattern must be matched in order to create or save the item.
folder_name_pattern	str	Regular expression used to validate the name when saving an item.
folder_name_hint	str	Example of a valid folder name (used for UI).
force_folder_name_pattern	bool	If True, the folder name pattern must be matched in order to create or save the item.

Source code in client/bip/link/item.py

def __init__(self):
    super(ItemModel, self).__init__()
    self.uid: str = ""
    self.slug: str = ""

    self.name: str = ""
    self.plural: str = ""
    self.folder_name: str = ""
    self.code: str = ""
    self.path_pattern: str = ""
    self.root: str = ""
    self.directories: list = []

    self.use_suffix: bool = False
    self.suffix_format: str = SUFFIX_NUM
    self.suffix_length: int = 0
    self.suffix_name_separator: str = ""
    self.suffix_folder_name_separator: str = ""
    self.default_suffix: str = ""

    self.folder_name_case_hint: str = ""
    self.name_case_hint: str = ""

    self.name_pattern: str = ""
    self.name_hint: str = ""
    self.force_name_pattern: bool = False

    self.folder_name_pattern: str = ""
    self.folder_name_hint: str = ""
    self.force_folder_name_pattern: bool = False

    self.element_number_padding: int = 3

    # Helpers
    self._project = None
    self._has_uniqueness_scope = False
    self._has_required_memberships = False
    self._has_optional_memberships = False

children_count: int property

Number of Items linked to the ItemModel.

Returns:

Name	Type	Description
int	int	Item count.

has_children: bool property

Does the ItemModel have Items.

Returns:

Name	Type	Description
bool	bool	True if the ItemModel has Items, False otherwise.

has_memberships: bool property

Does the ItemModel has memberships.

Lightweight method avoiding querying the database.

Returns:

Name	Type	Description
bool	bool	True if the ItemModel has memberships, False otherwise.

has_optional_memberships: bool property

Does the ItemModel has optional memberships.

This utility method does not query the database, and is a helper for checking if it is necessary to get the optional memberships.

Returns:

Name	Type	Description
bool	bool	True if the ItemModel has optional memberships, False otherwise.

has_required_memberships: bool property

Does the ItemModel requires memberships.

This utility method does not query the database, and is a helper for checking if it is necessary to get the required memberships.

Returns:

Name	Type	Description
bool	bool	True if the ItemModel requires memberships, False otherwise.

has_uniqueness_scope: bool property

Does the ItemModel has a uniqueness scope.

This utility method does not query the database, and is a helper for checking if it is necessary to get the uniqueness scope.

Returns:

Name	Type	Description
bool	bool	True if the ItemModel has a uniqueness scope, False otherwise.

path: str property

Dynamic path of the item model.

The path is dynamically generated by the running Bip client, based on the working directory.

Warning

The path may differ from a machine to another since the path uses the working_directory local setting, which might vary between machines, depending on the client config.

Returns:

Name	Type	Description
str	str	Path of the item model directory.

project: Project property

Parent project.

Returns:

Name	Type	Description
Project	Project	parent of the ItemModel.

add_membership(group_model, required=True)

Adds a required or optional membership.

Tip

Required or optional memberships are GroupModel that any new Project created with the current ProjectModel must or can be member of in order to be saved.

Parameters:

Name	Type	Description	Default
group_model	GroupModel	GroupModel: GroupModel.	required
required		bool	True

Raises:

Type	Description
ValueError	Failed validation.
TypeError	Failed validation.

Source code in client/bip/link/item.py

def add_membership(self, group_model: GroupModel, required=True):
    """Adds a required or optional membership.

    !!! tip
        Required or optional memberships are GroupModel that any new Project created with the current ProjectModel
        must or can be member of in order to be saved.

    Args:
      group_model: GroupModel: GroupModel.
      required: bool

    Raises:
        ValueError: Failed validation.
        TypeError: Failed validation.
    """
    if self.has_children:
        raise ValueError(
            "This ItemModel already has instances. You cannot modify its required memberships."
        )

    if not isinstance(group_model, _group.GroupModel):
        raise TypeError("group_model must be a GroupModel object.")

    if group_model.is_floating:
        raise ValueError("group_model must be saved first.")

    if self.has_optional_memberships:
        optional_memberships = self.get_optional_memberships()
        if group_model in optional_memberships:
            raise ValueError(f"{group_model} is already an optional membership.")

    if self.has_required_memberships:
        required_memberships = self.get_required_memberships()
        if group_model in required_memberships:
            raise ValueError(f"{group_model} is already a required membership.")

    _group.add_membership(self, group_model, required)

    if required:
        self._has_required_memberships = True
    else:
        self._has_optional_memberships = True

    self.save()

delete(safe=True)

Deletes the ItemModel.

By default, if the ItemModel has Items parented to it, the deletion won't be accepted, unless safe is set to True.

Deleting the ItemModel deletes any downstream entity: Item, Document,Version, Group (local only), Task and Attribute.

Warning

If the project has a locked model, the operation is not allowed.

Parameters:

Name	Type	Description	Default
safe	bool	bool: Prevents the deletion if the ItemModel has children (Items) (Default value = True)	True

Raises:

Type	Description
ValueError	If safe is True and the ItemModel has children.

Source code in client/bip/link/item.py

@meta_model_locked
def delete(self, safe: bool = True):
    """Deletes the ItemModel.

    By default, if the ItemModel has Items parented to it, the deletion won't be accepted,
    unless `safe` is set to True.

    Deleting the ItemModel deletes any downstream entity: Item, Document,Version,
    Group (local only), Task and Attribute.

    !!! warning
        If the project has a locked model, the operation is not allowed.

    Args:
      safe: bool: Prevents the deletion if the ItemModel has children (Items) (Default value = True)

    Raises:
        ValueError: If safe is True and the ItemModel has children.
    """
    if safe and self.has_children:
        raise ValueError(
            f"Impossible to safely delete {self}. The ItemModel has children."
        )

    if self.has_children:
        for item in self.get_items():
            item.delete(safe=False)

    sink.item.delete_model(self.to_dict())

generate(name, project, auto_save=True, **kwargs) classmethod

Generates an ItemModel object.

By default, the generated ItemModel is saved straight after creation. In some cases, it can be useful to get the floating (not recorded on the database) object in order to perform further operation, and save after that. That can be achieved by setting auto_save to False.

Parameters:

Name	Type	Description	Default
name	str	str: Name of the new model.	required
project	Project	str: Parent Project of the new model.	required
auto_save	bool	bool: If True, the returned object is saved. Otherwise it is floating. (Default value = True)	True
**kwargs		Any non-mandatory valid attribute of ItemModel can be passed.	{}

Raises:

Type	Description
ValueError	Failed validation, if auto_save is True.
TypeError	Failed validation, if auto_save is True.

Returns:

Name	Type	Description
ItemModel	ItemModel	Generated ItemModel.

Source code in client/bip/link/item.py

@classmethod
def generate(
    cls, name: str, project: Project, auto_save: bool = True, **kwargs
) -> ItemModel:
    """Generates an ItemModel object.

    By default, the generated ItemModel is saved straight after creation.
    In some cases, it can be useful to get the floating (not recorded on the database)
    object in order to perform further operation, and save after that.
    That can be achieved by setting `auto_save` to False.

    Args:
      name: str: Name of the new model.
      project: str: Parent Project of the new model.
      auto_save: bool: If True, the returned object is saved. Otherwise it is floating. (Default value = True)
      **kwargs: Any non-mandatory valid attribute of ItemModel can be passed.

    Raises:
        ValueError: Failed validation, if auto_save is True.
        TypeError: Failed validation, if auto_save is True.

    Returns:
        ItemModel: Generated ItemModel.
    """
    model = cls()
    model.name = name
    model._project = project

    # Add optional attributes
    model._add_dynamic_attributes(**kwargs)

    if auto_save:
        model.save()

    return model

get(project, slug=None, uid=None) classmethod

Get a specific ItemModel or all ProjectModels.

It is possible to get a specific ItemModel from its uid or its slug. When providing one, the other can be left to None. If none of these two parameters are filled, The getter becomes a global getter and returns a collection.

Parameters:

Name	Type	Description	Default
project		str: Parent Project.	required
slug	Optional[str]	Optional[str]: Slug of a ItemModel. If specified, uid can be left blank. (Default value = None)	None
uid	Optional[str]	Optional[str]: Uid of a ItemModel. If specified, slug can be left blank. (Default value = None)	None

Raises:

Type	Description
LookupError	No matching ItemModel found.

Returns:

Type	Description
Union[ItemModel, List[ItemModel], None]	list: Collection of ItemModels, if no uid or slug specified.
Union[ItemModel, List[ItemModel], None]	ItemModel: Single ItemModel if a uid or a slug has been specified.

Source code in client/bip/link/item.py

@classmethod
def get(
    cls, project, slug: Optional[str] = None, uid: Optional[str] = None
) -> Union[ItemModel, List[ItemModel], None]:
    """Get a specific ItemModel or all ProjectModels.

    It is possible to get a specific ItemModel from its `uid` or its `slug`.
    When providing one, the other can be left to None. If none of these two parameters are filled,
    The getter becomes a global getter and returns a collection.

    Args:
        project: str: Parent Project.
        slug: Optional[str]: Slug of a ItemModel. If specified, `uid` can be left blank. (Default value = None)
        uid: Optional[str]: Uid of a ItemModel. If specified, `slug` can be left blank. (Default value = None)

    Raises:
        LookupError: No matching ItemModel found.

    Returns:
        - list: Collection of ItemModels, if no uid or slug specified.
        - ItemModel: Single ItemModel if a uid or a slug has been specified.
    """
    if uid or slug:
        result = sink.item.get_model(slug, uid, project.to_dict())
        if not result:
            return
        model = cls.from_dict(result)
        model._project = project
        return model
    else:
        models = sink.item.get_models(project.to_dict())
        models = [cls.from_dict(t) for t in models]

        # Add project to avoid an extra request
        for model in models:
            model._project = project

        return models

get_item(slug=None, uid=None, group=None)

Convenient class implementation of: bip.link.item.get_item.

Warning

The signature of ItemModel.get_item() and bip.link.item.get_item() are different since ItemModel.get_item() passes itself to the function as model=self.

Source code in client/bip/link/item.py

def get_item(
    self, slug: Optional[str] = None, uid: Optional[str] = None, group=None
) -> Item:
    """Convenient class implementation of: `bip.link.item.get_item`.

    !!! warning
        The signature of `ItemModel.get_item()` and `bip.link.item.get_item()`
        are different since `ItemModel.get_item()` passes itself to the function as `model=self`.
    """
    return get_item(self, slug, uid, group)

get_items()

Convenient class implementation of: bip.link.item.get_items.

Warning

The signature of ItemModel.get_items() and bip.link.item.get_items() are different since ItemModel.get_items() passes itself to the function as model=self.

Source code in client/bip/link/item.py

def get_items(self) -> List[Item]:
    """Convenient class implementation of: `bip.link.item.get_items`.

    !!! warning
        The signature of `ItemModel.get_items()` and `bip.link.item.get_items()`
        are different since `ItemModel.get_items()` passes itself to the function as `model=self`.
    """
    return get_items(self)

get_task_models()

Convenient class implementation of: bip.link.task.get_models_from_item_model.

Warning

The signature of ItemModel.get_task_models() and bip.link.task.get_models_from_item_model() are different since ItemModel.get_task_models() passes itself to the function as model=self.

Source code in client/bip/link/item.py

def get_task_models(self) -> List[GroupModel]:
    """Convenient class implementation of: `bip.link.task.get_models_from_item_model`.

    !!! warning
        The signature of `ItemModel.get_task_models()` and `bip.link.task.get_models_from_item_model()`
        are different since `ItemModel.get_task_models()` passes itself to the function as `model=self`.
    """
    return _task.get_models_from_item_model(item_model=self)

get_uniqueness_scope()

Convenient class implementation of: bip.link.group.get_uniqueness_scope.

Warning

The signature of ItemModel.get_uniqueness_scope() and bip.link.item.get_uniqueness_scope() are different since ItemModel.get_uniqueness_scope() passes itself to the function as entity=self.

Source code in client/bip/link/item.py

def get_uniqueness_scope(self) -> Group:
    """Convenient class implementation of: `bip.link.group.get_uniqueness_scope`.

    !!! warning
        The signature of `ItemModel.get_uniqueness_scope()` and `bip.link.item.get_uniqueness_scope()`
        are different since `ItemModel.get_uniqueness_scope()` passes itself to the function as `entity=self`.
    """
    return _group.get_uniqueness_scope(self)

new(name, groups=(), auto_save=True, **kwargs)

Convenient class implementation of: bip.link.item.new_item.

Warning

The signature of ItemModel.new_item() and bip.link.item.new_item() are different since ItemModel.new_item() passes itself to the function as model=self.

Source code in client/bip/link/item.py

def new(
    self,
    name: str,
    groups: Union[List, Tuple] = (),
    auto_save: bool = True,
    **kwargs,
) -> Item:
    """Convenient class implementation of: `bip.link.item.new_item`.

    !!! warning
        The signature of `ItemModel.new_item()` and `bip.link.item.new_item()`
        are different since `ItemModel.new_item()` passes itself to the function as `model=self`.
    """
    return new_item(name, self, groups, auto_save, **kwargs)

new_item(name, groups=(), auto_save=True, **kwargs)

Convenient class implementation of: bip.link.item.new_item.

Warning

The signature of ItemModel.new_item() and bip.link.item.new_item() are different since ItemModel.new_item() passes itself to the function as model=self.

Source code in client/bip/link/item.py

def new_item(
    self,
    name: str,
    groups: Union[List, Tuple] = (),
    auto_save: bool = True,
    **kwargs,
) -> Item:
    """Convenient class implementation of: `bip.link.item.new_item`.

    !!! warning
        The signature of `ItemModel.new_item()` and `bip.link.item.new_item()`
        are different since `ItemModel.new_item()` passes itself to the function as `model=self`.
    """
    return new_item(name, self, groups, auto_save, **kwargs)

save()

Saves the ItemModel to the database.

If the ItemModel is floating, saving makes it persistent.

Attributes changes are not applied to the database at modification. Saving the ItemModel does.

Warning

If the project has a locked model, the operation is not allowed.

Raises:

Type	Description
ValueError	Failed validation.
TypeError	Failed validation.
PermissionError	The Project doesn't allow post-creation changes of its data model.

Source code in client/bip/link/item.py

@meta_model_locked
def save(self):
    """Saves the ItemModel to the database.

    If the ItemModel is floating, saving makes it persistent.

    Attributes changes are not applied to the database at modification. Saving the ItemModel does.

    !!! warning
        If the project has a locked model, the operation is not allowed.

    Raises:
        ValueError: Failed validation.
        TypeError: Failed validation.
        PermissionError: The Project doesn't allow post-creation changes of its data model.
    """
    if not self._is_modified and self.uid:
        return

    if not self.uid:
        self._generate_uid()

    self._validate()

    sink.item.save_model(self.to_dict())

    if self.is_floating:
        sink.item.connect_model(self.to_dict(), self.project.to_dict())

    self._sink()

    return self

set_uniqueness_scope(group_model)

Sets a uniqueness scope.

Warning

If the project has a locked model, the operation is not allowed.

Tip

A uniqueness scope is a GroupModel (that must also be a required membership) that will determine the uniqueness scope for the slug and the folder name. For example. If an ItemModel "asset" has a GroupModel "category" as required membership and uniqueness scope, two assets in two different members of category, like characters and props can both be called "AssetA".

Parameters:

Name	Type	Description	Default
group_model	GroupModel	GroupModel: Required GroupModel.	required

Raises:

Type	Description
ValueError	Failed validation.
TypeError	Failed validation.

Source code in client/bip/link/item.py

@meta_model_locked
def set_uniqueness_scope(self, group_model: GroupModel):
    """Sets a uniqueness scope.

    !!! warning
        If the project has a locked model, the operation is not allowed.

    !!! tip
        A uniqueness scope is a GroupModel (that must also be a required membership) that will determine
        the uniqueness scope for the slug and the folder name. For example. If an ItemModel "asset" has a GroupModel
        "category" as required membership and uniqueness scope, two _assets_ in two different members of _category_,
        like _characters_ and _props_ can both be called "AssetA".

    Args:
      group_model: GroupModel: Required GroupModel.

    Raises:
        ValueError: Failed validation.
        TypeError: Failed validation.
    """
    if self.has_children:
        raise ValueError(
            "You cannot set the uniqueness scope once the model has children."
        )

    _group.set_uniqueness_scope(self, group_model)
    self._has_uniqueness_scope = True
    self.save()

get(model, slug=None, uid=None, group=None)

Convenient shortcut to Item.get for getting a specific Item or all Items.

Source code in client/bip/link/item.py

def get(
    model: ItemModel,
    slug: Optional[str] = None,
    uid: Optional[str] = None,
    group: Optional[Union[Group, str]] = None,
) -> Union[Item, List[Item]]:
    """Convenient shortcut to `Item.get` for getting a specific Item or all Items."""
    return Item.get(model, slug, uid, group)

get_folder_names(project)

Get all Projects folder names.

Utility function for path building.

Returns:

Name	Type	Description
dict	Dict[str, str]	Pair or uid and folder names.

Source code in client/bip/link/item.py

def get_folder_names(project: Project) -> Dict[str, str]:
    """Get all Projects folder names.

    Utility function for path building.

    Returns:
        dict: Pair or uid and folder names.
    """
    return sink.item.get_folder_names(project.to_dict())

get_from_project(project, uid=None)

Convenient shortcut to Item.get_from_project for getting a specific Item or all Items from a Project.

Source code in client/bip/link/item.py

def get_from_project(
    project: Project, uid: Optional[str] = None
) -> Union[Item, List[Item]]:
    """Convenient shortcut to `Item.get_from_project` for getting a specific Item or all Items from a Project."""
    return Item.get_from_project(project, uid)

get_item(model, slug=None, uid=None, group=None)

Convenient shortcut to Item.get for getting a specific Item.

Raises:

Type	Description
ValueError	No slug and no uid provided.

Source code in client/bip/link/item.py

def get_item(
    model: ItemModel,
    slug: Optional[str] = None,
    uid: Optional[str] = None,
    group: Optional[Union[Group, str]] = None,
) -> Union[Item, List[Item]]:
    """Convenient shortcut to `Item.get` for getting a specific Item.

    Raises:
        ValueError: No slug and no uid provided.
    """
    if not uid and not slug:
        raise ValueError("A uid or a slug must be provided.")
    return Item.get(model, slug, uid, group)

get_items(model)

Convenient shortcut to Item.get for getting all Items.

Source code in client/bip/link/item.py

def get_items(model: ItemModel) -> List[Item]:
    """Convenient shortcut to `Item.get` for getting all Items."""
    return Item.get(model)

get_items_by_groups(model, groups)

Convenient shortcut to Item.get for getting all Items.

Source code in client/bip/link/item.py

def get_items_by_groups(model: ItemModel, groups: List[Group]) -> List[Item]:
    """Convenient shortcut to `Item.get` for getting all Items."""
    return Item.get_by_groups(model, groups)

get_model(project, slug=None, uid=None)

Convenient shortcut to ItemModel.get for specific ItemModel.

Raises:

Type	Description
ValueError	No slug and no uid provided.

Source code in client/bip/link/item.py

def get_model(
    project: Project, slug: Optional[str] = None, uid: Optional[str] = None
) -> ItemModel:
    """Convenient shortcut to `ItemModel.get` for specific ItemModel.

    Raises:
        ValueError: No slug and no uid provided.
    """
    if not uid and not slug:
        raise ValueError("A uid or a slug must be provided.")
    return ItemModel.get(project, slug, uid)

get_models(project)

Convenient shortcut to ItemModel.get for all ItemModel.

Source code in client/bip/link/item.py

def get_models(project: Project) -> List[ItemModel]:
    """Convenient shortcut to `ItemModel.get` for all ItemModel."""
    return ItemModel.get(project)

new(name, model=None, groups=(), auto_save=True, **kwargs)

Convenient shortcut to Item.generate.

Source code in client/bip/link/item.py

def new(
    name: str,
    model: Optional[ItemModel] = None,
    groups: Union[List, Tuple] = (),
    auto_save: bool = True,
    **kwargs,
) -> Item:
    """Convenient shortcut to `Item.generate`."""
    return Item.generate(name, model, groups, auto_save, **kwargs)

new_item(name, model=None, groups=(), auto_save=True, **kwargs)

Convenient shortcut to Item.generate.

Source code in client/bip/link/item.py

def new_item(
    name: str,
    model: Optional[ItemModel] = None,
    groups: Union[List, Tuple] = (),
    auto_save: bool = True,
    **kwargs,
) -> Item:
    """Convenient shortcut to `Item.generate`."""
    return Item.generate(name, model, groups, auto_save, **kwargs)

new_model(name, project, auto_save=True, **kwargs)

Convenient shortcut to ItemModel.generate.

Source code in client/bip/link/item.py

def new_model(
    name: str,
    project: Project,
    auto_save: bool = True,
    **kwargs,
) -> ItemModel:
    """Convenient shortcut to `ItemModel.generate`."""
    return ItemModel.generate(name, project, auto_save, **kwargs)