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	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	bool: True if the workspace could be locked, False otherwise.

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.

    """
    request = self._client.build_request("PUT", self._lock_url, params=self._params)
    request.headers.update(self._add_headers(request))
    response = self._client.send(request)
    logger.debug("%r", response.json())
    response.raise_for_status()
    response = APIResponse.parse_raw(response.text)
    if not response.success:
        logger.error(
            f"Failed to lock workspace {self.workspace_id}. {response.message}"
        )
    return response.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	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)
    if not response.success:
        logger.error(
            f"Failed to unlock workspace {self.workspace_id}. {response.message}"
        )
    return response.success