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, )