Locations

Manage storage locations, including nested hierarchies and location trees.

LocationsClient

Sub-client for location management endpoints.

Accessed via HomeboxClient.locations.

Source code in homebox/client.py

class LocationsClient:
    """Sub-client for location management endpoints.

    Accessed via ``HomeboxClient.locations``.
    """

    def __init__(self, client: HomeboxClient):
        """Initialise the locations sub-client with the shared root client."""
        self.client = client

    def get_all_locations(self, filterChildren: bool | None = None) -> list[LocationOutCount]:
        """Return all locations in the group.

        Args:
            filterChildren: When ``True`` only top-level (root) locations are
                returned; nested child locations are excluded.

        Returns:
            list[LocationOutCount]: Each location summary includes an
                ``itemCount`` field with the number of items stored there.
        """
        params = {}
        if filterChildren is not None:
            params["filterChildren"] = filterChildren
        data = self.client._request("get", "/v1/locations", params=params)
        return [LocationOutCount(**item) for item in data["data"]]

    def create_location(self, data: LocationCreate) -> LocationSummary:
        """Create a new location.

        Args:
            data: Location creation payload.  ``name`` is optional; you can also
                supply ``description`` and a ``parentId`` to nest it under an
                existing location.

        Returns:
            LocationSummary: Summary representation of the newly created location.
        """
        return LocationSummary(**self.client._request("post", "/v1/locations", data=data.model_dump()))

    def get_locations_tree(self, withItems: bool | None = None) -> list[TreeItem]:
        """Return all locations as a nested tree structure.

        Args:
            withItems: When ``True`` items are embedded as leaf nodes in the
                tree alongside child locations.

        Returns:
            list[TreeItem]: Root-level tree nodes; each node may have a
                ``children`` list of nested nodes.
        """
        params = {}
        if withItems:
            params["withItems"] = withItems
        data = self.client._request("get", "/v1/locations/tree", params=params)
        return [TreeItem(**item) for item in data.get("data", [])]

    def get_location(self, id: str) -> LocationOut:
        """Return the details of a single location.

        Args:
            id: UUID of the location.

        Returns:
            LocationOut: Full location representation including parent summary,
                child summaries, and total item price.
        """
        return LocationOut(**self.client._request("get", f"/v1/locations/{id}"))

    def update_location(self, id: str, data: LocationUpdate) -> LocationOut:
        """Replace a location's fields with the provided data.

        Args:
            id: UUID of the location to update.
            data: Updated location payload (name, description, parentId).

        Returns:
            LocationOut: Updated full location representation.
        """
        return LocationOut(**self.client._request("put", f"/v1/locations/{id}", data=data.model_dump()))

    def delete_location(self, id: str):
        """Permanently delete a location.

        Args:
            id: UUID of the location to delete.
        """
        self.client._request("delete", f"/v1/locations/{id}")

__init__

__init__(client: HomeboxClient)

Initialise the locations sub-client with the shared root client.

Source code in homebox/client.py

def __init__(self, client: HomeboxClient):
    """Initialise the locations sub-client with the shared root client."""
    self.client = client

get_all_locations

get_all_locations(filterChildren: bool | None = None) -> list[LocationOutCount]

Return all locations in the group.

Parameters:

Name	Type	Description	Default
filterChildren	bool | None	When True only top-level (root) locations are returned; nested child locations are excluded.	None

Returns:

Type	Description
list[LocationOutCount]	list[LocationOutCount]: Each location summary includes an itemCount field with the number of items stored there.

Source code in homebox/client.py

def get_all_locations(self, filterChildren: bool | None = None) -> list[LocationOutCount]:
    """Return all locations in the group.

    Args:
        filterChildren: When ``True`` only top-level (root) locations are
            returned; nested child locations are excluded.

    Returns:
        list[LocationOutCount]: Each location summary includes an
            ``itemCount`` field with the number of items stored there.
    """
    params = {}
    if filterChildren is not None:
        params["filterChildren"] = filterChildren
    data = self.client._request("get", "/v1/locations", params=params)
    return [LocationOutCount(**item) for item in data["data"]]

create_location

create_location(data: LocationCreate) -> LocationSummary

Create a new location.

Parameters:

Name	Type	Description	Default
data	LocationCreate	Location creation payload. name is optional; you can also supply description and a parentId to nest it under an existing location.	required

Returns:

Name	Type	Description
LocationSummary	LocationSummary	Summary representation of the newly created location.

Source code in homebox/client.py

def create_location(self, data: LocationCreate) -> LocationSummary:
    """Create a new location.

    Args:
        data: Location creation payload.  ``name`` is optional; you can also
            supply ``description`` and a ``parentId`` to nest it under an
            existing location.

    Returns:
        LocationSummary: Summary representation of the newly created location.
    """
    return LocationSummary(**self.client._request("post", "/v1/locations", data=data.model_dump()))

get_locations_tree

get_locations_tree(withItems: bool | None = None) -> list[TreeItem]

Return all locations as a nested tree structure.

Parameters:

Name	Type	Description	Default
withItems	bool | None	When True items are embedded as leaf nodes in the tree alongside child locations.	None

Returns:

Type	Description
list[TreeItem]	list[TreeItem]: Root-level tree nodes; each node may have a children list of nested nodes.

Source code in homebox/client.py

def get_locations_tree(self, withItems: bool | None = None) -> list[TreeItem]:
    """Return all locations as a nested tree structure.

    Args:
        withItems: When ``True`` items are embedded as leaf nodes in the
            tree alongside child locations.

    Returns:
        list[TreeItem]: Root-level tree nodes; each node may have a
            ``children`` list of nested nodes.
    """
    params = {}
    if withItems:
        params["withItems"] = withItems
    data = self.client._request("get", "/v1/locations/tree", params=params)
    return [TreeItem(**item) for item in data.get("data", [])]

get_location

get_location(id: str) -> LocationOut

Return the details of a single location.

Parameters:

Name	Type	Description	Default
id	str	UUID of the location.	required

Returns:

Name	Type	Description
LocationOut	LocationOut	Full location representation including parent summary, child summaries, and total item price.

Source code in homebox/client.py

def get_location(self, id: str) -> LocationOut:
    """Return the details of a single location.

    Args:
        id: UUID of the location.

    Returns:
        LocationOut: Full location representation including parent summary,
            child summaries, and total item price.
    """
    return LocationOut(**self.client._request("get", f"/v1/locations/{id}"))

update_location

update_location(id: str, data: LocationUpdate) -> LocationOut

Replace a location's fields with the provided data.

Parameters:

Name	Type	Description	Default
id	str	UUID of the location to update.	required
data	LocationUpdate	Updated location payload (name, description, parentId).	required

Returns:

Name	Type	Description
LocationOut	LocationOut	Updated full location representation.

Source code in homebox/client.py

def update_location(self, id: str, data: LocationUpdate) -> LocationOut:
    """Replace a location's fields with the provided data.

    Args:
        id: UUID of the location to update.
        data: Updated location payload (name, description, parentId).

    Returns:
        LocationOut: Updated full location representation.
    """
    return LocationOut(**self.client._request("put", f"/v1/locations/{id}", data=data.model_dump()))

delete_location

delete_location(id: str)

Permanently delete a location.

Parameters:

Name	Type	Description	Default
id	str	UUID of the location to delete.	required

Source code in homebox/client.py

def delete_location(self, id: str):
    """Permanently delete a location.

    Args:
        id: UUID of the location to delete.
    """
    self.client._request("delete", f"/v1/locations/{id}")