def read_cache(self, start=None, end=None):
"""Get the cached readings from the plugin. If the plugin is not configured
to cache readings, a snapshot of the current reading state for all devices
is returned.
Args:
start (str): An RFC3339 formatted timestamp which defines a starting
bound on the cache data to return. If no timestamp is specified,
there will not be a starting bound. (default: None)
end (str): An RFC3339 formatted timestamp which defines an ending
bound on the cache data to return. If no timestamp is specified,
there will not be an ending bound. (default: None)
Yields:
api.V3Reading: The cached reading values for plugin devices.
"""
request = api.V3Bounds(
start=start or '',
end=end or '',
)
try:
for reading in self.client.ReadCache(request,
timeout=self.timeout):
yield reading
except Exception as e:
errors.wrap_and_raise(e)
def read_stream(self, devices=None, tag_groups=None):
"""Get a stream of device readings as plugins read from the devices.
Args:
devices (iterable[string]): An iterable which specifies the IDs of the
devices to stream reading data from.
tag_groups (iterable[tuple]): An iterable which specifies tuples containing
a set of tags to filter by. Each tag group on its own is subtractive (e.g.
all tags in the group refine the search space). The resulting set of
devices found by matching all tag groups is then collected and joined
to produce an additive set of devices to stream reading data from.
Yields:
api.V3Reading: The reading data being streamed from the targeted devices.
"""
selectors = []
if devices:
for device in devices:
selectors.append(api.V3DeviceSelector(id=device, ))
if tag_groups:
for group in tag_groups:
selectors.append(
api.V3DeviceSelector(
tags=[utils.tag_to_message(tag) for tag in group], ))
request = api.V3StreamRequest(selectors=selectors, )
try:
for reading in self.client.ReadStream(request, timeout=None):
yield reading
except Exception as e:
errors.wrap_and_raise(e)
def read(self, device_id=None, tags=None):
"""Get readings from specified plugin devices.
Args:
device_id (str): The ID of the device to get information on. If this
argument is specified, the ``tags`` argument is ignored.
tags (list[str]): The tags matching the devices to get information
on. If this is empty and ``id`` is not specified, all devices
are returned.
Yields:
api.V3Reading: The reading(s) from the specified device(s).
"""
request = api.V3ReadRequest(selector=api.V3DeviceSelector())
if device_id:
request.selector.id = device_id
elif tags:
request.selector.tags.extend(
[utils.tag_to_message(tag) for tag in tags])
try:
for reading in self.client.Read(request, timeout=self.timeout):
yield reading
except Exception as e:
errors.wrap_and_raise(e)
def devices(self, device_id=None, tags=None):
"""Get devices that the plugin manages.
Args:
device_id (str): The ID of the device to get information on. If this
argument is specified, the ``tags`` argument is ignored.
tags (list[str]): The tags matching the devices to get information
on. If this is empty and ``id`` is not specified, all devices
are returned.
Yields:
api.V3Device: The plugin-managed device(s) matching the provided
filter parameters. If no parameters are given, all devices are
returned.
"""
request = api.V3DeviceSelector()
if device_id:
request.id = device_id
elif tags:
request.tags.extend([utils.tag_to_message(tag) for tag in tags])
try:
for device in self.client.Devices(request, timeout=self.timeout):
yield device
except Exception as e:
errors.wrap_and_raise(e)
def version(self):
"""Get the version information for the plugin.
Returns:
api.V3Version: The version information for the plugin.
"""
try:
return self.client.Version(self.empty, timeout=self.timeout)
except Exception as e:
errors.wrap_and_raise(e)
def test(self):
"""Check whether the plugin is reachable and ready.
Returns:
api.V3TestStatus: The test status of the plugin.
"""
try:
return self.client.Test(self.empty, timeout=self.timeout)
except Exception as e:
errors.wrap_and_raise(e)
def metadata(self):
"""Get the static plugin meta-information.
Returns:
api.V3Metadata: The static plugin meta-information.
"""
try:
return self.client.Metadata(self.empty, timeout=self.timeout)
except Exception as e:
errors.wrap_and_raise(e)
def health(self):
"""Get the health status of the plugin.
Returns:
api.V3Health: The health status of the plugin.
"""
try:
return self.client.Health(self.empty, timeout=self.timeout)
except Exception as e:
errors.wrap_and_raise(e)
def transactions(self):
"""Get all actively tracked transactions from the plugin.
Yields:
api.V3TransactionStatus: The transactions currently tracked
by the plugin.
"""
try:
for status in self.client.Transactions(request=self.empty,
timeout=self.timeout):
yield status
except Exception as e:
errors.wrap_and_raise(e)
def transaction(self, transaction_id):
"""Get the status of a write transaction for an asynchronous write action.
Args:
transaction_id (str): The ID of the transaction to check.
Returns:
api.V3TransactionStatus: The transaction status for the
asynchronous write.
"""
request = api.V3TransactionSelector(id=transaction_id, )
try:
return self.client.Transaction(request, timeout=self.timeout)
except Exception as e:
errors.wrap_and_raise(e)
def write_async(self, device_id, data):
"""Write data to the specified plugin device. A transaction ID is returned
so the write status can be checked asynchronously.
Args:
device_id (str): The device to write to.
data (list[dict] | dict): The data to write to the device.
Yields:
api.V3WriteTransaction: The transaction(s) generated for the
asynchronous write request.
"""
request = api.V3WritePayload(
selector=api.V3DeviceSelector(id=device_id, ),
data=utils.write_data_to_messages(data),
)
try:
for txn in self.client.WriteAsync(request, timeout=self.timeout):
yield txn
except Exception as e:
errors.wrap_and_raise(e)
def write_sync(self, device_id, data):
"""Write data to the specified plugin device. This request blocks until
the write resolves so no asynchronous checking is required.
Args:
device_id (str): The device to write to.
data (list[dict] | dict): The data to write to the device.
Returns:
list[api.V3TransactionStatus]: The status of the transaction(s)
associated with the write.
"""
request = api.V3WritePayload(
selector=api.V3DeviceSelector(id=device_id, ),
data=utils.write_data_to_messages(data),
)
try:
return [
x for x in self.client.WriteSync(request, timeout=self.timeout)
]
except Exception as e:
errors.wrap_and_raise(e)
def test_wrap_and_raise(exception, expected):
"""Wrap and re-raise an exception."""
with pytest.raises(expected):
errors.wrap_and_raise(exception)