async def write_async(
self,
device: str,
payload: Union[List[dict], dict],
) -> List[models.TransactionInfo]:
"""Write to the specified device asynchronously.
This method will queue up a write with the device's plugin and will
immediately return information for the transaction associated with
the write. This transaction can be checked later to ensure the write
completed successfully.
Args:
device (str): The ID of the device to write to.
payload (list[dict] | dict): The write payload.
Returns:
The Synse v3 API asynchronous write response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#write-asynchronous
"""
response = await self.make_request(
url=f'{self.url}/write/{device}',
method=POST,
json=payload,
)
return models.make_response(
models.TransactionInfo,
response,
)
async def tags(self,
ns: Union[str, Sequence[str]] = None,
ids: bool = False) -> List[str]:
"""Get a list of the tags currently associated with registered devices.
Args:
ns: The tag namespace(s) to use when searching for tags.
(default: default)
ids: Include ID tags in the response. (default: false)
Returns:
The Synse v3 API tags response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#tags
"""
params = MultiDict()
if ns:
params.add('ns', ns)
if ids:
params.add('ids', 'true')
response = await self.make_request(
url=f'{self.url}/tags',
method=GET,
params=params,
)
return models.make_response(
None,
response,
)
async def write_async(
self,
device: str,
payload: Union[List[dict], dict],
) -> List[models.TransactionInfo]:
"""Write to the specified device asynchronously.
This method will queue up a write with the device's plugin and will
immediately return information for the transaction associated with
the write. This transaction can be checked later to ensure the write
completed successfully.
Args:
device: The ID of the device to write to.
payload: The write payload.
Returns:
The Synse v3 API asynchronous write response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#write-asynchronous
"""
data = {
'device': device,
'payload': payload,
}
data = {k: v for k, v in data.items() if v is not None}
r = await self.request('request/write_async', data=data)
return models.make_response(
models.TransactionInfo,
r['data'],
)
async def write_sync(
self,
device: str,
payload: Union[List[dict], dict],
) -> List[models.TransactionStatus]:
"""Write to the specified device synchronously.
This method will wait until the write action has completed. It is up
to the caller to ensure that a suitable timeout is set for the request.
Args:
device (str): The ID of the device to write to.
payload (list[dict] | dict): The write payload.
Returns:
The Synse v3 API synchronous write response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#write-synchronous
"""
response = await self.make_request(
url=f'{self.url}/write/wait/{device}',
method=POST,
json=payload,
)
return models.make_response(
models.TransactionStatus,
response,
)
async def write_sync(
self,
device: str,
payload: Union[List[dict], dict],
) -> List[models.TransactionStatus]:
"""Write to the specified device synchronously.
This method will wait until the write action has completed. It is up
to the caller to ensure that a suitable timeout is set for the request.
Args:
device: The ID of the device to write to.
payload: The write payload.
Returns:
The Synse v3 API synchronous write response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#write-synchronous
"""
data = {
'device': device,
'payload': payload,
}
data = {k: v for k, v in data.items() if v is not None}
r = await self.request('request/write_sync', data=data)
return models.make_response(
models.TransactionStatus,
r['data'],
)
async def read(
self,
ns: str = None,
tags: Union[str, Sequence[str], Sequence[Sequence[str]]] = None,
) -> List[models.Reading]:
"""Get the latest reading(s) for all devices which match the specified selector(s).
Args:
ns: The default namespace to use for the tags which do not
include a namespace. (default: default)
tags: The tags to filter devices on. Tags may be specified in multiple ways.
A single string (e.g. 'foo/bar') will be taken as a single tag group. Multiple
strings (e.g. ['foo/bar', 'abc/123']) will be taken as a single tag group.
Multiple collections of strings (e.g. [['foo/bar'], ['abc/123', 'def/456']])
will be taken as multiple tag groups.
Returns:
The Synse v3 API read response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#read
"""
data = {
'ns': ns,
'tags': tags,
}
data = {k: v for k, v in data.items() if v is not None}
r = await self.request('request/read', data=data)
return models.make_response(
models.Reading,
r['data'],
)
async def tags(self, ns: str = None, ids: bool = None) -> List[str]:
"""Get a list of the tags currently associated with registered devices.
Args:
ns: The tag namespace(s) to use when searching for tags.
ids: Include ID tags in the response. (default: false)
Returns:
The Synse v3 API tags response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#tags
"""
data = {
'ns': ns,
'ids': ids,
}
data = {k: v for k, v in data.items() if v is not None}
r = await self.request('request/tags', data=data)
return models.make_response(
None,
r['data'],
)
async def scan(
self,
force: bool = None,
ns: str = None,
sort: str = None,
tags: Union[str, Sequence[str], Sequence[Sequence[str]]] = None,
) -> List[models.DeviceSummary]:
"""Get a summary of all devices currently exposed by the Synse Server instance.
Args:
force (bool): Force a re-scan (do not use the cache). If True, the
request will take longer since the internal device cache will
be rebuilt. Forcing a scan will ensure the set of returned devices
is up-to-date.
ns (str): The default namespace to use for the tags which do not
include a namespace. (default: default)
sort (str): Specify the fields to sort by. Multiple fields may be
specified as a comma-separated string, e.g. "plugin,id". The
"tags" field can not be used for sorting. (default:
"plugin,sort_index,id", where the sort_index is an internal sort
preference which a plugin can optionally specify.)
tags: The tags to filter devices on. Tags may be specified in multiple ways.
A single string (e.g. 'foo/bar') will be taken as a single tag group. Multiple
strings (e.g. ['foo/bar', 'abc/123']) will be taken as a single tag group.
Multiple collections of strings (e.g. [['foo/bar'], ['abc/123', 'def/456']])
will be taken as multiple tag groups.
Returns:
The Synse v3 API scan response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#scan
"""
params = MultiDict()
utils.tag_params(tags, params)
if ns:
params.add('ns', ns)
if force:
params.add('force', str(force))
if sort:
params.add('sort', sort)
response = await self.make_request(
url=f'{self.url}/scan',
method=GET,
params=params,
)
return models.make_response(
models.DeviceSummary,
response,
)
async def config(self) -> models.Config:
"""Get the unified configuration for the Synse Server instance.
Returns:
The Synse v3 API config response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#config
"""
r = await self.request('request/config')
return models.make_response(
models.Config,
r['data'],
)
async def plugin_health(self) -> models.PluginHealth:
"""Get a summary of the health of all currently registered plugins.
Returns:
The Synse v3 API plugin health response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#plugin-health
"""
r = await self.request('request/plugin_health')
return models.make_response(
models.PluginHealth,
r['data'],
)
async def plugins(self) -> List[models.PluginSummary]:
"""Get a summary of all plugins currently registered with the Synse Server instance.
Returns:
The Synse v3 API plugins response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#plugins
"""
r = await self.request('request/plugins', data={})
return models.make_response(
models.PluginSummary,
r['data'],
)
async def version(self) -> models.Version:
"""Get the version information for the configured Synse Server instance.
Returns:
The Synse v3 API version response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#version
"""
r = await self.request('request/version')
return models.make_response(
models.Version,
r['data'],
)
async def transactions(self) -> List[str]:
"""Get a list of the transactions currently tracked by Synse.
Returns:
The Synse v3 API transactions response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#transactions
"""
r = await self.request('request/transactions')
return models.make_response(
None,
r['data'],
)
async def scan(
self,
force: bool = None,
ns: str = None,
sort: str = None,
tags: Union[str, Sequence[str], Sequence[Sequence[str]]] = None,
) -> Generator[models.DeviceSummary, None, None]:
"""Get a summary of all devices currently exposed by the Synse Server instance.
Args:
force: Force a re-scan (do not use the cache). If True, the
request will take longer since the internal device cache will
be rebuilt. Forcing a scan will ensure the set of returned devices
is up-to-date.
ns: The default namespace to use for the tags which do not
include a namespace. (default: default)
sort: Specify the fields to sort by. Multiple fields may be
specified as a comma-separated string, e.g. "plugin,id". The
"tags" field can not be used for sorting. (default:
"plugin,sort_index,id", where the sort_index is an internal sort
preference which a plugin can optionally specify.)
tags: The tags to filter devices on. Tags may be specified in multiple ways.
A single string (e.g. 'foo/bar') will be taken as a single tag group. Multiple
strings (e.g. ['foo/bar', 'abc/123']) will be taken as a single tag group.
Multiple collections of strings (e.g. [['foo/bar'], ['abc/123', 'def/456']])
will be taken as multiple tag groups.
Returns:
The Synse v3 API scan response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#scan
"""
data = {
'force': force,
'ns': ns,
'sort': sort,
'tags': tags,
}
data = {k: v for k, v in data.items() if v is not None}
r = await self.request('request/scan', data=data)
return models.make_response(
models.DeviceSummary,
r['data'],
)
async def status(self) -> models.Status:
"""Check the availability and connectivity status of the Synse Server instance.
If the instance is reachable, this request will resolve; otherwise, it will
raise an error.
Returns:
The Synse v3 API status response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#test
"""
r = await self.request('request/status')
return models.make_response(
models.Status,
r['data'],
)
async def plugin_health(self) -> models.PluginHealth:
"""Get a summary of the health of all currently registered plugins.
Returns:
The Synse v3 API plugin health response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#plugin-health
"""
response = await self.make_request(
url=f'{self.url}/plugin/health',
method=GET,
)
return models.make_response(
models.PluginHealth,
response,
)
async def config(self) -> models.Config:
"""Get the unified configuration for the Synse Server instance.
Returns:
The Synse v3 API config response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#config
"""
response = await self.make_request(
url=f'{self.url}/config',
method=GET,
)
return models.make_response(
models.Config,
response,
)
async def version(self) -> models.Version:
"""Get the version information for the configured Synse Server instance.
Returns:
The Synse v3 API version response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#version
"""
response = await self.make_request(
url=f'{self.base}/version',
method=GET,
)
return models.make_response(
models.Version,
response,
)
async def plugins(self) -> List[models.PluginSummary]:
"""Get a summary of all plugins currently registered with the Synse Server instance.
Returns:
The Synse v3 API plugins response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#plugins
"""
response = await self.make_request(
url=f'{self.url}/plugin',
method=GET,
)
return models.make_response(
models.PluginSummary,
response,
)
async def transactions(self) -> List[str]:
"""Get a list of the transactions currently tracked by Synse.
Returns:
The Synse v3 API transactions response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#transactions
"""
response = await self.make_request(
url=f'{self.url}/transaction',
method=GET,
)
return models.make_response(
None,
response,
)
async def plugin(self, plugin_id: str) -> models.PluginInfo:
"""Get all information associated with the specified plugin.
Args:
plugin_id: The ID of the plugin to get information for.
Returns:
The Synse v3 API plugin response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#plugin-info
"""
r = await self.request('request/plugin', data={
'plugin': plugin_id,
})
return models.make_response(
models.PluginInfo,
r['data'],
)
async def info(self, device: str) -> models.DeviceInfo:
"""Get all information associated with the specified device.
Args:
device: The ID of the device to get information for.
Returns:
The Synse v3 API info response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#info
"""
r = await self.request('request/info', data={
'device': device,
})
return models.make_response(
models.DeviceInfo,
r['data'],
)
async def read_device(self, device: str) -> List[models.Reading]:
"""Get the latest reading(s) for the specified device.
Args:
device: The ID of the device to get readings for.
Returns:
The Synse v3 API read device response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#read-device
"""
r = await self.request('request/read_device',
data={
'device': device,
})
return models.make_response(
models.Reading,
r['data'],
)
async def info(self, device: str) -> models.DeviceInfo:
"""Get all information associated with the specified device.
Args:
device (str): The ID of the device to get information for.
Returns:
The Synse v3 API info response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#info
"""
response = await self.make_request(
url=f'{self.url}/info/{device}',
method=GET,
)
return models.make_response(
models.DeviceInfo,
response,
)
async def plugin(self, plugin_id: str) -> models.PluginInfo:
"""Get all information associated with the specified plugin.
Args:
plugin_id (str): The ID of the plugin to get information for.
Returns:
The Synse v3 API plugin response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#plugin-info
"""
response = await self.make_request(
url=f'{self.url}/plugin/{plugin_id}',
method=GET,
)
return models.make_response(
models.PluginInfo,
response,
)
async def read_device(self, device: str) -> List[models.Reading]:
"""Get the latest reading(s) for the specified device.
Args:
device (str): The ID of the device to get readings for.
Returns:
The Synse v3 API read device response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#read-device
"""
response = await self.make_request(
url=f'{self.url}/read/{device}',
method=GET,
)
return models.make_response(
models.Reading,
response,
)
async def transaction(self,
transaction_id: str) -> models.TransactionStatus:
"""Get the status of an asynchronous write transaction.
Args:
transaction_id: The ID of the transaction to get the status of.
Returns:
The Synse v3 API transaction response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#transaction
"""
r = await self.request('request/transaction',
data={
'transaction': transaction_id,
})
return models.make_response(
models.TransactionStatus,
r['data'],
)
async def transaction(self,
transaction_id: str) -> models.TransactionStatus:
"""Get the status of an asynchronous write transaction.
Args:
transaction_id (str): The ID of the transaction to get the status of.
Returns:
The Synse v3 API transaction response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#transaction
"""
response = await self.make_request(
url=f'{self.url}/transaction/{transaction_id}',
method=GET,
)
return models.make_response(
models.TransactionStatus,
response,
)
async def read_cache(
self,
start: str = None,
end: str = None) -> AsyncGenerator[models.Reading, None]:
"""Get a window of cached device readings.
Args:
start (str): An RFC3339 formatted timestamp which specifies a starting
bound on the cache data to return. If no timestamp is specified,
there will not be a starting bound.
end (str): An RFC3339 formatted timestamp which specifies an ending
bound on the cache data to return. If no timestamp is specified,
there will not be an ending bound.
Yields:
The Synse v3 API read cache response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#read-cache
"""
params = MultiDict()
if start:
params.add('start', start)
if end:
params.add('end', end)
response = self.stream_request(
url=f'{self.url}/readcache',
method=GET,
params=params,
)
async for data in response:
yield models.make_response(
models.Reading,
data,
)
async def read(
self,
ns: str = None,
tags: Union[str, Sequence[str], Sequence[Sequence[str]]] = None,
) -> List[models.Reading]:
"""Get the latest reading(s) for all devices which match the specified selector(s).
Args:
ns: The default namespace to use for the tags which do not
include a namespace. (default: default)
tags: The tags to filter devices on. Tags may be specified in multiple ways.
A single string (e.g. 'foo/bar') will be taken as a single tag group. Multiple
strings (e.g. ['foo/bar', 'abc/123']) will be taken as a single tag group.
Multiple collections of strings (e.g. [['foo/bar'], ['abc/123', 'def/456']])
will be taken as multiple tag groups.
Returns:
The Synse v3 API read response.
See Also:
https://synse.readthedocs.io/en/latest/server/api.v3/#read
"""
params = MultiDict()
utils.tag_params(tags, params)
if ns:
params.add('ns', ns)
response = await self.make_request(
url=f'{self.url}/read',
method=GET,
params=params,
)
return models.make_response(
models.Reading,
response,
)
