structurizr.StructurizrClient

Define a Structurizr client.

A client for the Structurizr API (https://api.structurizr.com) that allows you to get and put Structurizr workspaces in a JSON format.

Attributes:

Name	Type	Description
url	str	The Structurizr API URL.
workspace_id	int	The Structurizr workspace identifier.
api_key	str	The Structurizr workspace API key.
api_secret	str	The Structurizr workspace API secret.
user	str	A string identifying the user (e.g. an e-mail address or username).
agent	str	A string identifying the agent (e.g. 'structurizr-java/1.2.0').
workspace_archive_location	pathlib.Path	A directory for archiving downloaded workspaces, or None to suppress archiving.

get_workspace(self)

Retrieve a Structurizr workspace from the API.

Returns:

Type	Description
Workspace	A workspace instance that represents the online state.

Exceptions:

Type	Description
httpx.HTTPError	If anything goes wrong in connecting to the API.

Source code in structurizr/api/structurizr_client.py

def get_workspace(self) -> Workspace:
    """
    Retrieve a Structurizr workspace from the API.

    Returns:
        Workspace: A workspace instance that represents the online state.

    Raises:
        httpx.HTTPError: If anything goes wrong in connecting to the API.

    """
    request = self._client.build_request("GET", self._workspace_url)
    request.headers.update(self._add_headers(request))
    response = self._client.send(request)
    if response.status_code != 200:
        raise StructurizrClientException(
            f"Failed to retrieve the Structurizr workspace {self.workspace_id}.\n"
            f"Response {response.status_code} - {response.reason_phrase}"
        )
    logger.debug(response.text)
    self._archive_workspace(response.text)
    return Workspace.loads(response.text)

lock_workspace(self)

Lock the Structurizr workspace.

Returns:

Type	Description
bool	True if the workspace could be locked, False otherwise.

Note that free plan Structurizr licences do not support locking, so this will fail but continue anyway.

Source code in structurizr/api/structurizr_client.py

def lock_workspace(self) -> bool:
    """Lock the Structurizr workspace.

    Returns:
        bool: `True` if the workspace could be locked, `False` otherwise.

    Note that free plan Structurizr licences do not support locking, so this
    will fail but continue anyway.
    """
    success, paid_plan = self._lock_workspace()
    if not success and not paid_plan:
        # Free plans can't lock so ignore.
        success = True
    return success

put_workspace(self, workspace)

Update the remote Structurizr workspace with the given instance.

Parameters:

Name	Type	Description	Default
workspace	Workspace	The new workspace to update with.	required

Exceptions:

Type	Description
httpx.HTTPError	If anything goes wrong in connecting to the API.

Source code in structurizr/api/structurizr_client.py

def put_workspace(self, workspace: Workspace) -> None:
    """
    Update the remote Structurizr workspace with the given instance.

    Args:
        workspace (Workspace): The new workspace to update with.

    Raises:
        httpx.HTTPError: If anything goes wrong in connecting to the API.

    """
    assert workspace.id == self.workspace_id

    if self.merge_from_remote:
        remote_workspace = self.get_workspace()
        if remote_workspace:
            workspace.views.copy_layout_information_from(remote_workspace.views)
            # TODO:
            # workspace.views.configuration.copy_configuration_from(remote_workspace.views.configuration)

    ws_io = WorkspaceIO.from_orm(workspace)
    ws_io.thumbnail = None
    ws_io.last_modified_date = datetime.now(timezone.utc)
    ws_io.last_modified_agent = self.agent
    ws_io.last_modified_user = self.user
    workspace_json = ws_io.json()
    logger.debug(workspace_json)
    request = self._client.build_request(
        method="PUT",
        url=self._workspace_url,
        data=workspace_json,
    )
    request.headers.update(
        self._add_headers(
            request,
            content=workspace_json,
            content_type=self._application_json,
        )
    )
    response = self._client.send(request)
    if response.status_code != 200:
        body = response.json()
        raise StructurizrClientException(
            f"Failed to update the Structurizr workspace {self.workspace_id}.\n"
            f"HTTP Status {response.status_code} - {response.reason_phrase}\n"
            f"Error message: {body.get('message', '')}"
        )

unlock_workspace(self)

Unlock the Structurizr workspace.

Returns:

Type	Description
bool	True if the workspace could be unlocked, False otherwise.

Source code in structurizr/api/structurizr_client.py

def unlock_workspace(self) -> bool:
    """
    Unlock the Structurizr workspace.

    Returns:
        bool: `True` if the workspace could be unlocked, `False` otherwise.

    """
    request = self._client.build_request(
        "DELETE", self._lock_url, params=self._params
    )
    request.headers.update(self._add_headers(request))
    response = self._client.send(request)
    response.raise_for_status()
    response = APIResponse.parse_raw(response.text)
    success = response.success
    if not response.success:
        logger.warning(
            f"Failed to unlock workspace {self.workspace_id}. {response.message}"
        )
        if not self._paid_plan(response):
            logger.warning("Unlocking not supported on free plan.  Ignoring.")
            success = True
    return success