CRUD

delete_project(name, cascade=True, clean_context=True, local=False, **kwargs)

Delete a project.

Parameters:

Name	Type	Description	Default
name	str	Project name.	required
cascade	bool	Flag to determine if delete is cascading.	True
clean_context	bool	Flag to determine if context will be deleted. If a context is deleted, all its objects are unreacheable.	True
local	bool	Flag to determine if backend is local.	False
**kwargs	dict	Parameters to pass to the API call.	{}

Returns:

Type	Description
dict	Response from backend.

Examples:

>>> delete_project("my-project")

Source code in digitalhub_core/entities/project/crud.py

def delete_project(
    name: str,
    cascade: bool = True,
    clean_context: bool = True,
    local: bool = False,
    **kwargs,
) -> list[dict]:
    """
    Delete a project.

    Parameters
    ----------
    name : str
        Project name.
    cascade : bool
        Flag to determine if delete is cascading.
    clean_context : bool
        Flag to determine if context will be deleted. If a context is deleted,
        all its objects are unreacheable.
    local : bool
        Flag to determine if backend is local.
    **kwargs : dict
        Parameters to pass to the API call.

    Returns
    -------
    dict
        Response from backend.

    Examples
    --------
    >>> delete_project("my-project")
    """
    client = get_client(local)
    obj = delete_entity_api_base(client, ENTITY_TYPE, name, cascade=cascade, **kwargs)
    if clean_context:
        delete_context(name)
    return obj

get_or_create_project(name, local=False, config=None, context=None, setup_kwargs=None, **kwargs)

Try to get project. If not exists, create it.

Parameters:

Name	Type	Description	Default
name	str	Project name.	required
local	bool	Flag to determine if backend is local.	False
config	dict	DHCore environment configuration.	None
context	str	Folder where the project will saves its context locally.	None
setup_kwargs	dict	Setup keyword arguments passed to setup_project() function.	None
**kwargs	dict	Keyword arguments.	{}

Returns:

Type	Description
Project	Object instance.

Source code in digitalhub_core/entities/project/crud.py

def get_or_create_project(
    name: str,
    local: bool = False,
    config: dict | None = None,
    context: str | None = None,
    setup_kwargs: dict | None = None,
    **kwargs,
) -> Project:
    """
    Try to get project. If not exists, create it.

    Parameters
    ----------
    name : str
        Project name.
    local : bool
        Flag to determine if backend is local.
    config : dict
        DHCore environment configuration.
    context : str
        Folder where the project will saves its context locally.
    setup_kwargs : dict
        Setup keyword arguments passed to setup_project() function.
    **kwargs : dict
        Keyword arguments.

    Returns
    -------
    Project
        Object instance.
    """
    try:
        return get_project(
            name,
            local=local,
            config=config,
            setup_kwargs=setup_kwargs,
            **kwargs,
        )
    except BackendError:
        return new_project(
            name,
            local=local,
            config=config,
            setup_kwargs=setup_kwargs,
            context=context,
            **kwargs,
        )

get_project(name, local=False, config=None, setup_kwargs=None, **kwargs)

Retrieves project details from backend.

Parameters:

Name	Type	Description	Default
name	str	The Project name.	required
local	bool	Flag to determine if backend is local.	False
config	dict	DHCore environment configuration.	None
setup_kwargs	dict	Setup keyword arguments passed to setup_project() function.	None
**kwargs	dict	Parameters to pass to the API call.	{}

Returns:

Type	Description
Project	Object instance.

Examples:

>>> obj = get_project("my-project")

Source code in digitalhub_core/entities/project/crud.py

def get_project(
    name: str,
    local: bool = False,
    config: dict | None = None,
    setup_kwargs: dict | None = None,
    **kwargs,
) -> Project:
    """
    Retrieves project details from backend.

    Parameters
    ----------
    name : str
        The Project name.
    local : bool
        Flag to determine if backend is local.
    config : dict
        DHCore environment configuration.
    setup_kwargs : dict
        Setup keyword arguments passed to setup_project() function.
    **kwargs : dict
        Parameters to pass to the API call.

    Returns
    -------
    Project
        Object instance.

    Examples
    --------
    >>> obj = get_project("my-project")
    """
    build_client(local, config)
    client = get_client(local)
    obj = read_entity_api_base(client, ENTITY_TYPE, name, **kwargs)
    obj["local"] = local
    project = project_from_dict(obj)
    return _setup_project(project, setup_kwargs)

import_project(file, local=False, config=None, setup_kwargs=None)

Import object from a YAML file.

Parameters:

Name	Type	Description	Default
file	str	Path to YAML file.	required
local	bool	Flag to determine if backend is local.	False
config	dict	DHCore environment configuration.	None
setup_kwargs	dict	Setup keyword arguments passed to setup_project() function.	None

Returns:

Type	Description
Project	Object instance.

Examples:

>>> obj = import_project("my-project.yaml")

Source code in digitalhub_core/entities/project/crud.py

def import_project(
    file: str,
    local: bool = False,
    config: dict | None = None,
    setup_kwargs: dict | None = None,
) -> Project:
    """
    Import object from a YAML file.

    Parameters
    ----------
    file : str
        Path to YAML file.
    local : bool
        Flag to determine if backend is local.
    config : dict
        DHCore environment configuration.
    setup_kwargs : dict
        Setup keyword arguments passed to setup_project() function.

    Returns
    -------
    Project
        Object instance.

    Examples
    --------
    >>> obj = import_project("my-project.yaml")
    """
    build_client(local, config)
    obj: dict = read_yaml(file)
    obj["local"] = local
    project = project_from_dict(obj)
    return _setup_project(project, setup_kwargs)

load_project(name=None, filename=None, local=False, config=None, setup_kwargs=None, **kwargs)

Load project and context from backend or file. Name or filename must be provided. Name takes precedence over filename.

Parameters:

Name	Type	Description	Default
name	str	Project name.	None
filename	str	Path to YAML file.	None
local	bool	Flag to determine if backend is local.	False
config	dict	DHCore environment configuration.	None
setup_kwargs	dict	Setup keyword arguments passed to setup_project() function.	None
**kwargs	dict	Keyword arguments.	{}

Returns:

Type	Description
Project	Object instance.

Examples:

If name is provided, load project from backend.

>>> obj = load_project(name="my-project")

If filename is provided, load project from file.

>>> obj = load_project(filename="my-project.yaml")

Source code in digitalhub_core/entities/project/crud.py

def load_project(
    name: str | None = None,
    filename: str | None = None,
    local: bool = False,
    config: dict | None = None,
    setup_kwargs: dict | None = None,
    **kwargs,
) -> Project:
    """
    Load project and context from backend or file. Name or
    filename must be provided. Name takes precedence over filename.

    Parameters
    ----------
    name : str
        Project name.
    filename : str
        Path to YAML file.
    local : bool
        Flag to determine if backend is local.
    config : dict
        DHCore environment configuration.
    setup_kwargs : dict
        Setup keyword arguments passed to setup_project() function.
    **kwargs : dict
        Keyword arguments.

    Returns
    -------
    Project
        Object instance.

    Examples
    --------
    If name is provided, load project from backend.
    >>> obj = load_project(name="my-project")

    If filename is provided, load project from file.
    >>> obj = load_project(filename="my-project.yaml")
    """
    if name is not None:
        return get_project(name=name, local=local, config=config, setup_kwargs=setup_kwargs, **kwargs)
    if filename is not None:
        return import_project(filename, local=local, config=config, setup_kwargs=setup_kwargs)
    raise EntityError("Either name or filename must be provided.")

new_project(name, description=None, labels=None, local=False, config=None, context=None, setup_kwargs=None, **kwargs)

Create a new object.

Parameters:

Name	Type	Description	Default
name	str	Object name.	required
description	str	Description of the object (human readable).	None
labels	list[str]	List of labels.	None
local	bool	If True, use local backend, if False use DHCore backend. Default to False.	False
config	dict	DHCore environment configuration.	None
context	str	The context local folder of the project.	None
setup_kwargs	dict	Setup keyword arguments passed to setup_project() function.	None
**kwargs	dict	Keyword arguments.	{}

Returns:

Type	Description
Project	Object instance.

Examples:

>>> obj = new_project("my-project")

Source code in digitalhub_core/entities/project/crud.py

def new_project(
    name: str,
    description: str | None = None,
    labels: list[str] | None = None,
    local: bool = False,
    config: dict | None = None,
    context: str | None = None,
    setup_kwargs: dict | None = None,
    **kwargs,
) -> Project:
    """
    Create a new object.

    Parameters
    ----------
    name : str
        Object name.
    description : str
        Description of the object (human readable).
    labels : list[str]
        List of labels.
    local : bool
        If True, use local backend, if False use DHCore backend. Default to False.
    config : dict
        DHCore environment configuration.
    context : str
        The context local folder of the project.
    setup_kwargs : dict
        Setup keyword arguments passed to setup_project() function.
    **kwargs : dict
        Keyword arguments.

    Returns
    -------
    Project
        Object instance.

    Examples
    --------
    >>> obj = new_project("my-project")
    """
    build_client(local, config)
    if context is None:
        context = name
    obj = project_from_parameters(
        name=name,
        kind="project",
        description=description,
        labels=labels,
        local=local,
        context=context,
        **kwargs,
    )
    obj.save()
    return _setup_project(obj, setup_kwargs)

update_project(entity, local=False, **kwargs)

Update object. Note that object spec are immutable.

Parameters:

Name	Type	Description	Default
entity	Project	Object to update.	required
local	bool	Flag to determine if backend is local.	False
**kwargs	dict	Parameters to pass to the API call.	{}

Returns:

Type	Description
Project	The updated object.

Examples:

>>> obj = update_project(obj)

Source code in digitalhub_core/entities/project/crud.py

def update_project(entity: Project, local: bool = False, **kwargs) -> Project:
    """
    Update object. Note that object spec are immutable.

    Parameters
    ----------
    entity : Project
        Object to update.
    local : bool
        Flag to determine if backend is local.
    **kwargs : dict
        Parameters to pass to the API call.

    Returns
    -------
    Project
        The updated object.

    Examples
    --------
    >>> obj = update_project(obj)
    """
    client = get_client(local)
    obj = update_entity_api_base(client, ENTITY_TYPE, entity.name, entity.to_dict(), **kwargs)
    return project_from_dict(obj)