link.document

Document()

Bases: Data

Representation of a Bip document.

A Document is a part of an Item. It can be seen as the representation of a group of files. For example, in a CG production, the modelling scenes of an asset can be represented as a Document. A Document has versions, which are represented by the smallest entity of Bip, the Version object.

Documents are defined by DocumentModels, which define a set of rules and behaviours for the Document. For example the model controls the naming convention.

Info

This class inherits from Data, like Project, Item 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.
description	str	Short description of the item.
model	DocumentModel	Bip item model object.

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

def __init__(self):
    super(Document, self).__init__()
    self.uid: str = ""
    self.slug: str = ""
    self.element: str = ""
    self.model = DocumentModel
    self.thumbnail_path: str = ""

    # Helpers
    self._task = None
    self._parent = None
    self._groups = []

children_count: int property

Number of Versions parented to the Document.

Returns:

Name	Type	Description
int	int	Versions count.

has_children: bool property

Does the Document have Versions.

Returns:

Name	Type	Description
bool	bool	True if the Document has Versions, False otherwise.

latest_version_number: int property

Version number of the latest (highest) Version of the Document.

Returns:

Name	Type	Description
int	int	version number.

new_version_number: int property

Next version number.

Returns:

Name	Type	Description
int	int	next version number.

parent: Item property

Parent item.

Returns:

Name	Type	Description
Item	Item	parent of the document.

path: str property

Dynamic path of the document 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 document directory.

task: Union[Task, None] property

Task associated to the Document.

Returns:

Type	Description
Union[Task, None]	Union[Task, None]: Task if found, None otherwise.

add_version(files, number=None, author=None, published=False, auto_save=True, **kwargs)

Convenient class implementation of: bip.link.version.new_version.

Warning

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

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

def add_version(
    self,
    files: Union[str, List[str]],
    number: Optional[int] = None,
    author: Optional[User] = None,
    published: Optional[bool] = False,
    auto_save: bool = True,
    **kwargs,
) -> Version:
    """Convenient class implementation of: `bip.link.version.new_version`.

    !!! warning
        The signature of `Item.new_version()` and `bip.link.version.new_version`
        are different since `Item.new_version()` passes itself to the function as `document=self`.
    """
    return _version.new_version(
        self, files, number, author, published, auto_save, **kwargs
    )

delete(safe=True)

Deletes the Document.

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

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

Parameters:

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

Raises:

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

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

def delete(self, safe: bool = True):
    """Deletes the Document.

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

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

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

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

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

generate(model, item, task=None, groups=(), element=None, auto_save=True, **kwargs) classmethod

Generates a Document object.

By default, the generated Document 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.

Todo

• Check if Task is owned by the Item.

Parameters:

Name	Type	Description	Default
name		str: Name of the new document.	required
item	Item	Item: Parent item.	required
groups	Optional[List[Group]]	Union[List, Tuple]: If the DocumentModel has required_memberships, list of the mandatory groups (Default value = ())	()
task	Optional[Task]	Optional[Task]: Associated task. The Task must be owned by the Item.	None
model	DocumentModel	Optional[Union[DocumentModel, str]]: Model of the new document. Can be left to None if the project has a default_document_model (see link.project), or can be the string of a ItemModel slug (Default value = None)	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 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
Document	Document	Generated Document.

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

@classmethod
def generate(
    cls,
    model: DocumentModel,
    item: Item,
    task: Optional[Task] = None,
    groups: Optional[List[Group]] = (),
    element: Optional[str] = None,
    auto_save: bool = True,
    **kwargs,
) -> Document:
    """Generates a Document object.

    By default, the generated Document 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.

    Todo:
        - Check if Task is owned by the Item.

    Args:
      name: str: Name of the new document.
      item: Item: Parent item.
      groups: Union[List, Tuple]: If the DocumentModel has required_memberships, list of the
        mandatory groups (Default value = ())
      task: Optional[Task]: Associated task. The Task must be owned by the Item.
      model: Optional[Union[DocumentModel, str]]: Model of the new document. Can be left to None if the project
        has a `default_document_model` (see `link.project`),
        or can be the string of a ItemModel slug (Default value = None)
      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:
        Document: Generated Document.
    """
    if not model:
        model = get_default_document_model(item)
        if not model:
            raise ValueError(
                "There is no default DocumentModel set for this server, "
                "you must specify one manually."
            )

    document = cls()
    document.model = model
    document.element = element

    document._groups = groups
    document._task = task
    document._parent = item
    document._project = item.project

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

    if auto_save:
        document.save()

    return document

generate_filename(version_number, ext=None, suffix=None)

Generate a filename from the model pattern.

If the DocumentModel has a filename_pattern set, it is used to generate a filename.

This is useful for saving or creating new files and naming them automatically, by the Projects specifications.

Parameters:

Name	Type	Description	Default
ext	Optional[str]	Optional[str]: File extension. If None specified, the filename has no extension.	None
suffix	Optional[str]	Optional[str]: Custom suffix.	None

Raises:

Type	Description
ValueError	If the DocumentModel has no filename_pattern set.

Returns:

Name	Type	Description
str		Generated filename.

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

def generate_filename(
    self,
    version_number: int,
    ext: Optional[str] = None,
    suffix: Optional[str] = None,
):
    """Generate a filename from the model pattern.

    If the DocumentModel has a filename_pattern set, it is used to generate a filename.

    This is useful for saving or creating new files and naming them automatically, by the Projects specifications.

    Args:
        ext: Optional[str]: File extension. If None specified, the filename has no extension.
        suffix: Optional[str]: Custom suffix.

    Raises:
        ValueError: If the DocumentModel has no filename_pattern set.

    Returns:
        str: Generated filename.
    """

    raw = self.model.filename_pattern
    if not raw:
        raise ValueError(
            "Impossible to generate a filename, the model has no pattern."
        )

    if isinstance(raw, dict):
        item_model = self.parent.model.slug
        if item_model in raw.keys():
            raw = raw[item_model]
        else:
            raw = raw["_default"]

    version = self.model.format_version_number(version_number)

    filename = _internal.pattern.convert(raw, self, is_path=False, version=version)

    if suffix:
        filename += suffix

    if ext:
        filename += "." + ext

    return filename

get_children()

Alias for: Document.get_versions.

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

def get_children(self) -> List[Version]:
    """Alias for: `Document.get_versions`."""
    return self.get_versions()

get_from_filename(filename, item) classmethod

Get all the Documents with a version containing the given filename.

Parameters:

Name	Type	Description	Default
filename	str	str: Looked up filename.	required
item	Item	Item: parent Item to look into.	required

Returns:

Name	Type	Description
list	List[Document]	Collection of matching Documents.

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

@classmethod
def get_from_filename(cls, filename: str, item: Item) -> List[Document]:
    """Get all the Documents with a version containing the given filename.

    Args:
        filename: str: Looked up filename.
        item: Item: parent Item to look into.

    Returns:
        list: Collection of matching Documents.
    """
    results = sink.document.get_from_filename(filename, item.to_dict())
    documents = []
    for result in results:
        document = cls.from_dict(result)
        document._parent = item
        document._project = item.project
        documents.append(document)

    return documents

get_latest_version(published_only=False)

Convenient class implementation of: bip.link.version.get_latest_version.

Warning

The signature of Document.get_latest_version() and bip.link.version.get_latest_version() are different since Document.get_latest_version() passes itself to the function as document=self.

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

def get_latest_version(self, published_only=False) -> Version:
    """Convenient class implementation of: `bip.link.version.get_latest_version`.

    !!! warning
        The signature of `Document.get_latest_version()` and `bip.link.version.get_latest_version()`
        are different since `Document.get_latest_version()` passes itself to the function as `document=self`.
    """
    return _version.get_latest_version(self, published_only)

get_version(number)

Convenient class implementation of: bip.link.version.get_version.

Warning

The signature of Document.get_version() and bip.link.version.get_version() are different since Document.get_version() passes itself to the function as document=self.

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

def get_version(self, number: int) -> Version:
    """Convenient class implementation of: `bip.link.version.get_version`.

    !!! warning
        The signature of `Document.get_version()` and `bip.link.version.get_version()`
        are different since `Document.get_version()` passes itself to the function as `document=self`.
    """
    return _version.get_version(self, number)

get_versions()

Convenient class implementation of: bip.link.version.get_versions.

Warning

The signature of Document.get_versions() and bip.link.version.get_versions() are different since Document.get_versions() passes itself to the function as document=self.

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

def get_versions(self) -> List[Version]:
    """Convenient class implementation of: `bip.link.version.get_versions`.

    !!! warning
        The signature of `Document.get_versions()` and `bip.link.version.get_versions()`
        are different since `Document.get_versions()` passes itself to the function as `document=self`.
    """
    return _version.get_versions(self)

save()

Saves the Document to the database.

If the Document is floating, saving makes it persistent.

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

Raises:

Type	Description
ValueError	Failed validation.
TypeError	Failed validation.

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

def save(self):
    """Saves the Document to the database.

    If the Document is floating, saving makes it persistent.

    Attributes changes are not applied to the database at modification.
    Saving the Document 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._default()
    self._validate()

    sink.document.save(self.to_dict())

    was_floating = self.is_floating

    self._sink()

    if was_floating:
        sink.document.connect(self.to_dict(), self.parent.to_dict())

        if self._task:
            sink.document.link_to_task(self.to_dict(), self._task.to_dict())

        if self._groups:
            for group in self._groups:
                self.add_to(group)

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

DocumentModel()

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 Documents path generation.
requires_task	bool	If True, Documents with this model must be associated with a task.
version_prefix	str	Version prefix. (default: "v")
version_padding	int	Version padding. (default: 3)
collapsed	bool	Used for path generation. If True, the versions
has_element	bool	If True, Documents with this model must be associated with an element Elements will be entities attached to an item. They define its content, if it is not self-contained. This is the former item-list. Elements are simple entities, with a link [:SOURCE_IS] to the item they represent, and an attribute for the number

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

def __init__(self):
    super(DocumentModel, self).__init__()
    self.uid: str = ""
    self.slug: str = ""
    self.name: str = ""
    self.folder_name: str = ""
    self.root: str = ""
    self.plural: str = ""
    self.path_pattern: str = ""
    self.requires_task: bool = True
    self.version_prefix: str = "v"
    self.version_padding: int = 3
    self.directories: list = []
    self.subpath: str = ""
    self.published_subpath: str = ""
    self.force_filename_pattern: bool = False
    self.collapsed: bool = False

    self._filename_pattern: str = ""

    # Future
    self.has_element: bool = False

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

children_count: int property

Number of Documents linked to the DocumentModel.

Returns:

Name	Type	Description
int	int	Document count.

has_children: bool property

Does the DocumentModel have Documents.

Returns:

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

has_memberships: bool property

Does the DocumentModel has memberships.

Lightweight method avoiding querying the database.

Returns:

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

has_optional_memberships: bool property

Does the DocumentModel 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 DocumentModel has optional memberships, False otherwise.

has_required_memberships: bool property

Does the DocumentModel 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 DocumentModel requires memberships, False otherwise.

project: Project property

Parent project.

Returns:

Name	Type	Description
Project	Project	parent of the DocumentModel.

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/document.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 and required:
        raise ValueError(
            "This DocumentModel 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 DocumentModel.

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

Deleting the DocumentModel deletes any downstream entity: Document, Version 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 DocumentModel has children (Documents) (Default value = True)	True

Raises:

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

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

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

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

    Deleting the DocumentModel deletes any downstream entity:  Document, Version and Attribute.

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

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

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

    if self.has_children:
        for document in self.get_documents():
            document.delete(safe=False)

    sink.document.delete_model(self.to_dict())

format_version_number(number)

Format a version number according to the rules of the model.

For example, if version_prefix is set to v and version_padding is set to 3, this method would return v003.

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

def format_version_number(self, number: int) -> str:
    """Format a version number according to the rules of the model.

    For example, if version_prefix is set to `v` and version_padding is set to `3`,
    this method would return `v003`.
    """

    formatted = str(number).zfill(self.version_padding)
    if self.version_prefix:
        formatted = self.version_prefix + formatted

    return formatted

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

Generates a DocumentModel object.

By default, the generated DocumentModel 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 DocumentModel 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
DocumentModel	DocumentModel	Generated DocumentModel.

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

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

    By default, the generated DocumentModel 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 DocumentModel can be passed.

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

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

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

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

    if auto_save:
        model.save()

    return model

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

Get a specific DocumentModel or all ProjectModels.

It is possible to get a specific DocumentModel 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	Project	str: Parent Project.	required
slug	Optional[str]	Optional[str]: Slug of a DocumentModel. If specified, uid can be left blank. (Default value = None)	None
uid	Optional[str]	Optional[str]: Uid of a DocumentModel. If specified, slug can be left blank. (Default value = None)	None

Raises:

Type	Description
LookupError	No matching DocumentModel found.

Returns:

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

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

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

    It is possible to get a specific DocumentModel 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 DocumentModel. If specified, `uid` can be left blank. (Default value = None)
        uid: Optional[str]: Uid of a DocumentModel. If specified, `slug` can be left blank. (Default value = None)

    Raises:
        LookupError: No matching DocumentModel found.

    Returns:
        - list: Collection of DocumentModels, if no uid or slug specified.
        - DocumentModel: Single DocumentModel if a uid or a slug has been specified.
    """
    if uid or slug:
        result = sink.document.get_model(slug, uid, project.to_dict())
        model = cls.from_dict(result)
        model._project = project
        return model
    else:
        models = sink.document.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_documents(item)

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

Warning

The signature of DocumentModel.get_documents() and bip.link.document.get_documents() are different since DocumentModel.get_documents() passes itself to the function as model=self.

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

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

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

get_path(item)

Dynamic path of the document 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.

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

def get_path(self, item) -> str:
    """Dynamic path of the document 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:
        str: Path of the item model directory.
    """
    if self.root:
        return standardize_path(os.path.join(item.path, self.root))
    else:
        return item.path

save()

Saves the DocumentModel to the database.

If the DocumentModel is floating, saving makes it persistent.

Attributes changes are not applied to the database at modification. Saving the DocumentModel 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/document.py

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

    If the DocumentModel is floating, saving makes it persistent.

    Attributes changes are not applied to the database at modification. Saving the DocumentModel 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._default()
    self._validate()

    sink.document.save_model(self.to_dict())

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

    self._sink()

    return self

get_default_document_model(item)

Get the default DocumentModel of the Bip server, if any.

Returns:

Type	Description
Union[None, DocumentModel]	Union[None, DocumentModel]: DocumentModel if a default is set, None otherwise.

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

def get_default_document_model(item: Item) -> Union[None, DocumentModel]:
    """Get the default DocumentModel of the Bip server, if any.

    Returns:
        Union[None, DocumentModel]: DocumentModel if a default is set, None otherwise."""
    model = sink.document.get_default_document_model(item.to_dict())
    if model:
        return DocumentModel.from_dict(model)

get_document(model, item, task=None, groups=(), element=None)

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

Raises:

Type	Description
ValueError	No slug and no uid provided.

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

def get_document(
    model: DocumentModel,
    item: Item,
    task: Union[Task, str] = None,
    groups: Union[List, Tuple] = (),
    element: Optional[str] = None,
) -> Document:
    """Convenient shortcut to `Document.get` for getting a specific Document.

    Raises:
        ValueError: No slug and no uid provided.
    """
    return Document.get(model, item, task, groups, element)

get_documents(model, item)

Convenient shortcut to Document.get for getting all Documents.

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

def get_documents(model: DocumentModel, item: Item) -> List[Document]:
    """Convenient shortcut to `Document.get` for getting all Documents."""
    return Document.get_all(model, item)

get_from_filename(filename, item)

Convenient shortcut to DocumentModel.generate.

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

def get_from_filename(filename: str, item: Item) -> List[Document]:
    """Convenient shortcut to `DocumentModel.generate`."""
    return Document.get_from_filename(filename, item)

get_from_item(item, uid=None)

Convenient shortcut to Document.get_from_item for getting a specific Document or all Documents from an Item.

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

def get_from_item(
    item: Item, uid: Optional[str] = None
) -> Union[Document, List[Document]]:
    """Convenient shortcut to `Document.get_from_item` for getting a
    specific Document or all Documents from an Item."""
    return Document.get_from_item(item, uid)

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

Convenient shortcut to DocumentModel.get for specific DocumentModel.

Raises:

Type	Description
ValueError	No slug and no uid provided.

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

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

    Raises:
        ValueError: No slug and no uid provided.
    """
    return DocumentModel.get(project, slug, uid)

get_models(project)

Convenient shortcut to DocumentModel.get for all DocumentModels.

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

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

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

Convenient shortcut to Document.generate.

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

def new(
    model: DocumentModel,
    item: Item,
    task: Optional[Task] = None,
    groups: Optional[List[Group]] = (),
    element: Optional[str] = None,
    auto_save: Optional[bool] = True,
    **kwargs,
) -> Document:
    """Convenient shortcut to `Document.generate`."""
    return Document.generate(model, item, task, groups, element, auto_save, **kwargs)

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

Convenient shortcut to Document.generate.

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

def new_document(
    model: DocumentModel,
    item: Item,
    task: Optional[Task] = None,
    groups: Optional[List[Group]] = (),
    element: Optional[str] = None,
    auto_save: Optional[bool] = True,
    **kwargs,
) -> Document:
    """Convenient shortcut to `Document.generate`."""
    return Document.generate(model, item, task, groups, element, auto_save, **kwargs)

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

Convenient shortcut to DocumentModel.generate.

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

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