preheat_open.collection.Collection

class preheat_open.collection.Collection(locations=None, adapter=None, _models_loaded=False)

Bases: object

Represents a collection of locations for building management systems.

A Collection manages multiple locations and provides unified access to their building models, measurements, and components. It supports lazy loading of building models and filtering capabilities.

Parameters:

locations (dict[LocationInformation, Location | None] | None) – Dictionary mapping LocationInformation to Location objects
adapter (Adapter | None) – Data adapter for accessing external systems
_models_loaded (bool) – Whether building models have been loaded

Note

Building models are loaded lazily when first accessed through methods like get_units(), get_devices(), etc.

Example:

>>> from preheat_open.collection import Collection
>>> from preheat_open.location import LocationInformation
>>>
>>> # Create empty collection
>>> collection = Collection()
>>> len(collection.locations)
0

>>> # Create collection with location information
>>> loc_info = LocationInformation(id=1, label="Building A")
>>> collection = Collection(locations={loc_info: None})
>>> len(collection.locations)
1

__init__(locations=None, adapter=None, _models_loaded=False)

Initialize the Collection.

Parameters:

locations (dict[LocationInformation, Location | None] | None) – The locations in the collection
adapter (Adapter | None) – The adapter for data access
_models_loaded (bool) – Whether models are loaded

Example:

>>> collection = Collection()
>>> collection.locations
{}
>>> collection._models_loaded
False

Methods

`__init__`([locations, adapter, _models_loaded])	Initialize the Collection.
`filter`(location_info_filter)	Create a filtered collection based on a filter function.
`from_location_ids`(location_ids, adapter, ...)	Create a collection from a list of location IDs.
`from_location_information_list`(...)	Create a collection from a list of LocationInformation objects.
`get_components`([query])	Retrieve components from all locations in the collection.
`get_devices`([query])	Retrieve devices from all locations in the collection.
`get_keys`(**kwargs)	Retrieve LocationInformation keys filtered by attributes.
`get_locations`()	Retrieve all loaded Location objects in the collection.
`get_measurements`(**kwargs)	Retrieve measurements for all locations in the collection.
`get_units`([query])	Retrieve units from all locations in the collection.
`get_zones`([query])	Retrieve zones from all locations in the collection.
`load_building_models`()	Load building models for locations that haven't been loaded yet.

Attributes

timezone

Get the timezone for the collection.

filter(location_info_filter)

Create a filtered collection based on a filter function.

Applies the provided filter function to LocationInformation objects and returns a new Collection containing only matching locations.

Parameters:: location_info_filter (Callable[[LocationInformation], bool]) – Function that takes LocationInformation and returns bool
Returns:: New filtered Collection instance
Return type:: Collection

Example:

>>> from preheat_open.location import LocationInformation
>>>
>>> loc1 = LocationInformation(id=1, label="Building A")
>>> loc2 = LocationInformation(id=2, label="Building B")
>>> collection = Collection(locations={loc1: None, loc2: None})
>>>
>>> # Filter by label containing "A"
>>> filtered = collection.filter(lambda loc: "A" in loc.label)
>>> len(filtered.locations)
1
>>> list(filtered.locations.keys())[0].label
'Building A'

classmethod from_location_ids(location_ids, adapter, **kwargs)

Create a collection from a list of location IDs.

This factory method retrieves location data using the provided adapter and creates a Collection instance with the loaded locations.

Parameters:

location_ids (list[int]) – List of location IDs to load
adapter (Adapter) – Data adapter for retrieving locations
kwargs – Additional keyword arguments passed to constructor

Returns:

New Collection instance with loaded locations

Return type:

Collection

Raises:

ValueError – If adapter cannot retrieve locations for given IDs

classmethod from_location_information_list(location_information_list, **kwargs)

Create a collection from a list of LocationInformation objects.

This factory method creates a Collection with placeholder entries that will be loaded lazily when needed.

Parameters:

location_information_list (list[LocationInformation]) – List of location information objects
kwargs – Additional keyword arguments passed to constructor

Returns:

New Collection instance with location placeholders

Return type:

Collection

Example:

>>> from preheat_open.location import LocationInformation
>>>
>>> loc_infos = [
...     LocationInformation(id=1, label="Building A"),
...     LocationInformation(id=2, label="Building B")
... ]
>>> collection = Collection.from_location_information_list(loc_infos)
>>> len(collection.locations)
2
>>> all(loc is None for loc in collection.locations.values())
True

get_components(query=None, **kwargs)

Retrieve components from all locations in the collection.

Automatically loads building models if needed, then yields all components that match the optional query criteria.

Parameters:

query (Query | list[Query | dict[str, str]] | None) – Query object(s) or dict to filter components
kwargs – Additional arguments passed to location component retrieval

Returns:

Generator yielding Component objects

Return type:

Generator[Component, None, None]

get_devices(query=None, **kwargs)

Retrieve devices from all locations in the collection.

Automatically loads building models if needed, then yields all devices that match the optional query criteria.

Parameters:

query (Query | list[Query | dict[str, str]] | None) – Query object(s) or dict to filter devices
kwargs – Additional arguments passed to location device retrieval

Returns:

Generator yielding Device objects

Return type:

Generator[Device, None, None]

get_keys(**kwargs)

Retrieve LocationInformation keys filtered by attributes.

Yields LocationInformation objects that match the specified attribute filters. All provided keyword arguments must match the corresponding attributes.

Parameters:: kwargs – Attribute filters (attribute_name=value)
Returns:: Generator yielding matching LocationInformation objects
Return type:: Generator[LocationInformation, None, None]

get_locations()

Retrieve all loaded Location objects in the collection.

Yields only Location objects that are not None (i.e., have been loaded).

Returns:: Generator yielding loaded Location objects
Return type:: Generator[Location, None, None]

Example:

>>> from preheat_open.location import LocationInformation
>>>
>>> # Create collection with mixed loaded/unloaded locations
>>> loc1 = LocationInformation(id=1, label="Building A")
>>> loc2 = LocationInformation(id=2, label="Building B")
>>> collection = Collection(locations={loc1: "some_location", loc2: None})
>>>
>>> # Only yields loaded locations (non-None values)
>>> loaded = list(collection.get_locations())
>>> len(loaded)
1

get_measurements(**kwargs)

Retrieve measurements for all locations in the collection.

Automatically loads building models if not already loaded, then retrieves measurements using the configured measurement system.

Parameters:: kwargs – Additional arguments passed to measurement retrieval
Returns:: DataFrame containing measurements from all locations
Return type:: pd.DataFrame