link.version

Version()

Bases: Data

Representation of a Bip version.

A Version object represent a file or a group of files corresponding to an iteration of a Document. For example, if a document represents a "lighting scene in Maya", the different versions, or iterations of this file are represented with the Version object.

Unlike Projects, Items and Documents, Versions are not defined by any model. Their rules are defined by the upper DocumentModel.

Info

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

Tip

All paths are standardized: They use the / Unix separator.

Attributes:

Name	Type	Description
uid	str	Bip unique identifier (uuid4). Edition is forbidden if this is an persistent (saved) entity.
slug	str	Version number. Same as the folder_name property.
created_with	str	Optional, name of the software used for creating the file(s).

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

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

    self._published: bool = False
    self._folder_name = None
    self._number = None
    self._files = []
    self._creation_time = None
    self._modification_time = None

    # Links
    self._author = None
    self._parent = None

    # Helpers
    self._standardized_files = []

author: User property

Author of the version.

Returns:

Name	Type	Description
User	User	Author of the version.

creation_time: datetime property

When the version has been added to the database.

Returns:

Name	Type	Description
datetime	datetime	creation time.

document: Document property

Convenient alias for Item.parent.

file: Union[str, None] property

First file of the version.

Warning

Only works with single file. If the version has multiple files, use full_paths instead.

Info

File can contain a substructure, with as many sub-folders as needed. For a Bip version, a file can be my_file.ext as well as sub/path/my_file.ext.

Raises:

Type	Description
ValueError	The version has multiple files.

Returns:

Name	Type	Description
list	Union[str, None]	Collection of files.

files: List[str] property

List of files.

Info

Files can contain a substructure, with as many sub-folders as needed. For a Bip version, a file can be my_file.ext as well as sub/path/my_file.ext.

Returns:

Name	Type	Description
list	List[str]	Collection of files.

folder_name: str property

Folder name of the Version.

Warning

This is no the path of the file(s). The folder name is the formatted version number. Example: "v001".

Returns:

Name	Type	Description
str	str	folder name.

full_path: str property

Full path of the version.

This path includes the file substructure.

Warning

Only works with single file. If the version has multiple files, use full_paths instead.

Raises:

Type	Description
ValueError	The version has multiple files.

Returns:

Name	Type	Description
str	str	Full path.

full_paths: List[str] property

List of full paths.

These paths include the file substructure.

If the version only has one file, prefer full_path.

Returns:

Name	Type	Description
list	List[str]	Collection of full paths for each file of the version.

is_single: bool property

Does the version has more than one file entry.

Returns:

Name	Type	Description
bool	bool	True is only one file, False otherwise.

item: Item property

Parent item.

Returns:

Name	Type	Description
Item	Item	Parent item.

modification_time: datetime property

When the version has been changed on the database.

Returns:

Name	Type	Description
datetime	datetime	modification time.

number: int property

Version number

Returns:

Name	Type	Description
int	int	Version number.

parent: Document property

Parent document.

Returns:

Name	Type	Description
Document	Document	Parent document.

path: str property

Root path of the version.

Warning

This path does not include the file(s) substructure.

If the parent Document is not collapsed (see Document.collapsed), the folder name is appended to the path:

Examples:

• Collapsed: /path/to/version/
• Not collapsed: /path/to/version/v001/

Return

str: Root path.

creation_time_to_text()

Human-readable creation time.

Format pattern: "%d/%m/%Y %H:%M:%S"

Returns:

Name	Type	Description
str	str	Formatted creation time

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

def creation_time_to_text(self) -> str:
    """Human-readable creation time.

    Format pattern: _"%d/%m/%Y %H:%M:%S"_

    Returns:
        str: Formatted creation time
    """
    return self.creation_time.strftime(DATE_FORMAT)

delete()

Deletes the Version.

Deleting the Document deletes any Attribute attached to it.

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

def delete(self):
    """Deletes the Version.

    Deleting the Document deletes any Attribute attached to it.
    """
    return sink.version.delete(self.to_dict())

generate(document, files, number=None, author=None, published=False, auto_save=True, **kwargs) classmethod

Generates a Version object.

By default, the generated Version 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
document	Document	Document: Parent document.	required
files	Union[str, List[str]]	Union[str, List[str]]: Single file name or collection of file names. The file name can contain a substructure, with as many sub-folders as needed. It can be my_file.ext as well as sub/path/my_file.ext.	required
author	Optional[User]	Optional[User]: Author of the Version. If not specified, the current user (the one running Bip when executing the operation) is used.	None
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
Version	Version	Generated Version.

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

@classmethod
def generate(
    cls,
    document: Document,
    files: Union[str, List[str]],
    number: Optional[int] = None,
    author: Optional[User] = None,
    published: Optional[bool] = False,
    auto_save: bool = True,
    **kwargs,
) -> Version:
    """Generates a Version object.

    By default, the generated Version 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:
      document: Document: Parent document.
      files: Union[str, List[str]]: Single file name or collection of file names.
        The file name can contain a substructure, with as many sub-folders as needed.
        It can be `my_file.ext` as well as `sub/path/my_file.ext`.
      author: Optional[User]: Author of the Version. If not specified,
        the current user (the one running Bip when executing the operation) is used.
      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:
        Version: Generated Version.
    """
    version = cls()
    version._author = author
    version._number = number
    version._parent = document
    version._project = document.project
    version._published = published

    version.set_files(files, auto_save=False)

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

    version._initialize_private_values(number)
    version._default()

    if auto_save:
        version.save()

    return version

get(document, number=None) classmethod

Get a specific Version or all Versions from a Document.

It is possible to get a specific Version from its number. If no number is specified, the getter becomes a global getter and returns a collection of Versions.

Parameters:

Name	Type	Description	Default
document	Document	Document: Document object to search within.	required
number	Optional[int]	Optional[str]: Specific version number. (Default value = None)	None

Raises:

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

Returns:

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

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

@classmethod
def get(
    cls, document: Document, number: Optional[int] = None
) -> Union[List[Version], Version]:
    """Get a specific Version or all Versions from a Document.

    It is possible to get a specific Version from its `number`.
    If no number is specified, the getter becomes a global getter and returns a collection of Versions.

    Args:
        document: Document: Document object to search within.
        number: Optional[str]: Specific version number. (Default value = None)

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

    Returns:
        - list: Collection of Versions, if no uid or slug specified.
        - Version: Single Version if a uid or a slug has been specified.
    """
    if number is not None and number <= 0:
        raise ValueError("number bust be equal or greater than 1.")
    if number is not None:
        result = sink.version.get_version(document.to_dict(), number)
        if result:
            version = cls.from_dict(result)
            version._parent = document
            version._project = document.project
            return version
    else:
        versions = sink.version.get_versions(document.to_dict())
        versions = [cls.from_dict(c) for c in versions]

        for version in versions:
            version._parent = document
            version._project = document.project

        return versions

get_from_filename(filename, document) classmethod

Get all the Versions containing the given filename.

Parameters:

Name	Type	Description	Default
filename	str	str: Looked up filename.	required
document	Document	Document: parent Document to look into.	required

Returns:

Name	Type	Description
list	List[Version]	Collection of matching Versions.

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

@classmethod
def get_from_filename(cls, filename: str, document: Document) -> List[Version]:
    """Get all the Versions containing the given filename.

    Args:
        filename: str: Looked up filename.
        document: Document: parent Document to look into.

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

    return versions

get_latest(document, published_only=False) classmethod

Get only the latest version of a Document.

Parameters:

Name	Type	Description	Default
document	Document	Document: parent Document to look into.	required

Returns:

Name	Type	Description
list	Optional[Version]	Collection of matching Versions.

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

@classmethod
def get_latest(
    cls, document: Document, published_only: bool = False
) -> Optional[Version]:
    """Get only the latest version of a Document.

    Args:
        document: Document: parent Document to look into.

    Returns:
        list: Collection of matching Versions.
    """
    try:
        result = sink.version.get_latest_version(
            document.to_dict(), published_only
        )
    except LookupError:
        return None
    else:
        version = cls.from_dict(result)
        version._parent = document
        version._project = document.project
        return version

modification_time_to_text()

Human-readable modification time.

Format pattern: "%d/%m/%Y %H:%M:%S"

Returns:

Name	Type	Description
str	str	Formatted modification time

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

def modification_time_to_text(self) -> str:
    """Human-readable modification time.

    Format pattern: _"%d/%m/%Y %H:%M:%S"_

    Returns:
        str: Formatted modification time
    """
    return self.modification_time.strftime(DATE_FORMAT)

save(force=False)

Saves the Version to the database.

If the Version is floating, saving makes it persistent.

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

Raises:

Type	Description
ValueError	Failed validation.
TypeError	Failed validation.

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

def save(self, force=False):
    """Saves the Version to the database.

    If the Version is floating, saving makes it persistent.

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

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

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

    if not self.uid:
        self._generate_uid()

    # Set private values
    if self.is_floating:
        self._creation_time = datetime.now()

    self._modification_time = datetime.now()

    self._default()
    self._validate()

    sink.version.save(self.to_dict())

    if self.is_floating:
        sink.version.connect(self.to_dict(), self.parent.to_dict())
        sink.version.link_to_user(self.to_dict(), self.author.to_dict())

    self._sink()

get(document, number=None)

Convenient shortcut to Version.get for getting a specific Version or all Versions.

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

def get(
    document: Document, number: Optional[int] = None
) -> Union[Version, List[Version]]:
    """Convenient shortcut to `Version.get` for getting a specific Version or all Versions."""
    return Version.get(document, number)

get_from_filename(filename, document)

Convenient shortcut to Version.get_from_filename.

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

def get_from_filename(filename: str, document: Document) -> List[Version]:
    """Convenient shortcut to `Version.get_from_filename`."""
    return Version.get_from_filename(filename, document)

get_latest_version(document, published_only=False)

Convenient shortcut to Version.get_latest.

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

def get_latest_version(document: Document, published_only: bool = False) -> Version:
    """Convenient shortcut to `Version.get_latest`."""
    return Version.get_latest(document, published_only)

get_version(document, number=None)

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

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

def get_version(document: Document, number: int = None) -> Version:
    """Convenient shortcut to `Version.get` for getting a specific Version."""
    return Version.get(document, number)

get_versions(document)

Convenient shortcut to Version.get for getting all Versions.

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

def get_versions(document: Document) -> List[Version]:
    """Convenient shortcut to `Version.get` for getting all Versions."""
    return Version.get(document)

new(document, files, author=None, auto_save=True, **kwargs)

Convenient shortcut to Version.generate.

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

def new(
    document: Document,
    files: Union[str, List[str]],
    author: Optional[User] = None,
    auto_save=True,
    **kwargs,
) -> Version:
    """Convenient shortcut to `Version.generate`."""
    return Version.generate(document, files, author, auto_save, **kwargs)

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

Convenient shortcut to Version.generate.

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

def new_version(
    document: Document,
    files: Union[str, List[str]],
    number: Optional[int] = None,
    author: Optional[User] = None,
    published: Optional[bool] = False,
    auto_save=True,
    **kwargs,
) -> Version:
    """Convenient shortcut to `Version.generate`."""
    return Version.generate(
        document, files, number, author, published, auto_save, **kwargs
    )