Connection

Connection

Connection(api_token, host, workspace=None, project=None)

Connect to the Vectice backend (application).

The Connection class encapsulates a connection to the Vectice App. Thus, it authenticates and connects to Vectice. This allows you to start interacting with your Vectice assets.

A Connection can be initialized in three ways:

1. Passing the relevant arguments to authenticate and connect to Vectice:

   import vectice
   
   connection = vectice.connect(
       api_token="API_TOKEN_FROM_VECTICE",
       host="https://app.vectice.com",
   )
   

2. Passing the path to a configuration file:

   import vectice
   
   connection = vectice.connect(config="vectice_config.json")
   

3. Letting Vectice find the configuration file in specific locations:

   import vectice
   
   connection = vectice.connect()
   

See Connection.connect for more info.

Parameters:

Name	Type	Description	Default
api_token	str	Your private api token.	required
host	str	The address of the Vectice application.	required
workspace	str | int | None	The workspace you want to work in.	None
project	str | int | None	The project you want to work in.	None

Raises:

Type	Description
RuntimeError	When the API and backend versions are incompatible.

Source code in src/vectice/connection.py

def __init__(
    self,
    api_token: str,
    host: str,
    workspace: str | int | None = None,
    project: str | int | None = None,
):
    """Initialize a connection.

    Parameters:
        api_token: Your private api token.
        host: The address of the Vectice application.
        workspace: The workspace you want to work in.
        project: The project you want to work in.

    Raises:
        RuntimeError: When the API and backend versions are incompatible.
    """
    logging.getLogger("Client").propagate = True
    self._client = Client(
        workspace=workspace,
        project=project,
        token=api_token,
        api_endpoint=host,
        auto_connect=True,
        allow_self_certificate=True,
    )
    compatibility = self._client.check_compatibility()
    if compatibility.status != "OK":
        if compatibility.status == "Error":
            _logger.error(f"compatibility error: {compatibility.message}")
            raise RuntimeError(f"compatibility error: {compatibility.message}")
        else:
            _logger.warning(f"compatibility warning: {compatibility.message}")

last_workspace property

last_workspace: Workspace

Retrieve last workspace with activity.

Returns:

Type	Description
Workspace	Last workspace with activity.

my_workspace property

my_workspace: Workspace

Retrieve your personal workspace.

Returns:

Type	Description
Workspace	Personal workspace.

workspaces property

workspaces: list[Workspace] | None

List the workspaces to which this connection has access.

Returns:

Type	Description
list[Workspace] | None	The workspaces to which this connection has access.

connect staticmethod

connect(
    api_token=None,
    host=None,
    config=None,
    workspace=None,
    project=None,
)

Method to connect to the Vectice backend (application).

Authentication credentials are retrieved, in order, from:

1. keyword arguments
2. configuration file (config parameter)
3. environment variables
4. environment files in the following order
   • .vectice of the working directory
   • .vectice of the user home directory
   • .env of the working directory
   • .env of the user home directory
   • /etc/vectice/api.cfg file

This method uses the api_token, host, workspace, project arguments or the JSON config provided. The JSON config file is available from the Vectice webapp when creating an API token.

Parameters:

Name	Type	Description	Default
api_token	str | None	The api token provided by the Vectice webapp.	None
host	str | None	The backend host to which the client will connect. If not found, the default endpoint https://app.vectice.com is used.	None
config	str | None	A JSON config file containing keys VECTICE_API_TOKEN and VECTICE_API_ENDPOINT as well as optionally WORKSPACE and PROJECT.	None
workspace	str | int | None	The name of an optional workspace to return.	None
project	str | None	The name of an optional project to return.	None

Raises:

Type	Description
ValueError	When a project is specified without a workspace.

Returns:

Type	Description
Connection | Workspace | Project | None	A Connection, Workspace, or Project.

Source code in src/vectice/connection.py

@staticmethod
def connect(
    api_token: str | None = None,
    host: str | None = None,
    config: str | None = None,
    workspace: str | int | None = None,
    project: str | None = None,
) -> Connection | Workspace | Project | None:
    """Method to connect to the Vectice backend (application).

    Authentication credentials are retrieved, in order, from:

    1. keyword arguments
    2. configuration file (`config` parameter)
    3. environment variables
    4. environment files in the following order
        - `.vectice` of the working directory
        - `.vectice` of the user home directory
        - `.env` of the working directory
        - `.env` of the user home directory
        - `/etc/vectice/api.cfg` file

    This method uses the `api_token`, `host`, `workspace`, `project` arguments
    or the JSON config provided. The JSON config file is available from the Vectice
    webapp when creating an API token.

    Parameters:
        api_token: The api token provided by the Vectice webapp.
        host: The backend host to which the client will connect.
            If not found, the default endpoint https://app.vectice.com is used.
        config: A JSON config file containing keys VECTICE_API_TOKEN and
            VECTICE_API_ENDPOINT as well as optionally WORKSPACE and PROJECT.
        workspace: The name of an optional workspace to return.
        project: The name of an optional project to return.

    Raises:
        ValueError: When a project is specified without a workspace.

    Returns:
        A Connection, Workspace, or Project.
    """
    host = host or Connection._get_host(config)
    api_token = api_token or Connection._get_api_token(host, config)
    workspace = workspace or Connection._get_workspace(config)
    project = project or Connection._get_project(config)
    connection = Connection(api_token=api_token, host=host, workspace=workspace, project=project)
    user_name, workspace_id = _get_last_user_and_default_workspace(connection._client)
    url = connection._client.auth.api_base_url
    if workspace and not project:
        return connection.get_workspace(workspace, user_name, url)
    if workspace and project:
        return connection.get_project(workspace, project, user_name, url)
    _connection_logging(_logger, user_name, url, workspace_id)
    return connection

list_workspaces

list_workspaces()

Prints a list of workspaces in a tabular format, limited to the first 10 items. A link is provided to view the remaining workspaces.

Returns:

Type	Description
None	None

Source code in src/vectice/connection.py

def list_workspaces(self) -> None:
    """Prints a list of workspaces in a tabular format, limited to the first 10 items. A link is provided to view the remaining workspaces.

    Returns:
        None
    """
    workspace_outputs = self._client.list_workspaces().list
    user_name, _ = _get_last_user_and_default_workspace(self._client)

    rich_table = Table(expand=True, show_edge=False)

    rich_table.add_column("workspace id", justify="left", no_wrap=True, min_width=4, max_width=10)
    rich_table.add_column("name", justify="left", no_wrap=True, max_width=20)
    rich_table.add_column("description", justify="left", no_wrap=True, max_width=50)

    for count, workspace in enumerate(workspace_outputs, 1):
        if count > 10:
            break
        rich_table.add_row(str(workspace.id), workspace.name, format_description(workspace.description))

    description = f"""There are {len(workspace_outputs)} workspaces."""
    tips = dedent(
        """
    >> To access your personal workspace, use connection.my_workspace or connect.workspaces[0]
    >> To access a specific workspace, use connection.workspace(Workspace ID)"""
    ).lstrip()
    link = dedent(
        f"""
    For quick access to the list of workspaces in the Vectice web app, visit:
    {self._client.auth._API_BASE_URL}/workspaces"""
    ).lstrip()
    _temp_print(description)
    _temp_print(table=rich_table)
    _temp_print(tips)
    _temp_print(link)

workspace

workspace(workspace)

Get a workspace.

Parameters:

Name	Type	Description	Default
workspace	str | int	The id or the name of the desired workspace.	required

Returns:

Type	Description
Workspace	The desired workspace.

Source code in src/vectice/connection.py

def workspace(self, workspace: str | int) -> Workspace:
    """Get a workspace.

    Parameters:
        workspace: The id or the name of the desired workspace.

    Returns:
        The desired workspace.
    """
    output = self._client.get_workspace(workspace)
    result = Workspace(output.id, output.name, output.description)
    result.__post_init__(self._client, self)
    return result