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: |
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 |
bool: |
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