def save_state(
self,
store_name: str,
key: str,
value: Union[bytes, str],
etag: Optional[str] = None,
options: Optional[StateOptions] = None,
metadata: Optional[MetadataTuple] = ()
) -> DaprResponse:
"""Saves key-value pairs to a statestore
This saves a value to the statestore with a given key and state store name.
Options for request can be passed with the options field and custom
metadata can be passed with metadata field.
The example saves states to a statestore:
from dapr import DaprClient
with DaprClient() as d:
resp = d.save_state(
store_name='state_store'
states=[{'key': 'key1', 'value': 'value1'}],
etag='etag',
metadata=(
('header1', 'value1')
),
)
Args:
store_name (str): the state store name to save to
key (str): the key to be saved
value (bytes or str): the value to be saved
etag (str, optional): the etag to save with
options (StateOptions, optional): custom options
for concurrency and consistency
metadata (tuple, optional): custom metadata
Returns:
:class:`DaprResponse` gRPC metadata returned from callee
"""
if not isinstance(value, (bytes, str)):
raise ValueError(f'invalid type for data {type(value)}')
req_value = value
if len(store_name) == 0 or len(store_name.strip()) == 0:
raise ValueError("State store name cannot be empty")
if options is None:
state_options = None
else:
state_options = options.get_proto()
state = common_v1.StateItem(key=key,
value=to_bytes(req_value),
etag=etag,
options=state_options)
req = api_v1.SaveStateRequest(store_name=store_name, states=[state])
response, call = self._stub.SaveState.with_call(req, metadata=metadata)
return DaprResponse(headers=call.initial_metadata())
def test_convert_metadata(self):
# act
resp = DaprResponse(self.test_headers)
# assert
self.assertEqual(3, len(resp.headers))
for k, v in self.test_headers:
self.assertEqual(resp.headers[k], [v])
def execute_state_transaction(
self,
store_name: str,
operations: Sequence[TransactionalStateOperation],
transactional_metadata: Optional[Dict[str, str]] = dict(),
metadata: Optional[MetadataTuple] = ()
) -> DaprResponse:
"""Saves or deletes key-value pairs to a statestore as a transaction
This saves or deletes key-values to the statestore as part of a single transaction,
transaction_metadata is used for the transaction operation, while metadata is used
for the GRPC call.
The example saves states to a statestore:
from dapr import DaprClient
with DaprClient() as d:
resp = d.execute_state_transaction(
store_name='state_store',
operations=[
TransactionalStateOperation(key=key, data=value),
TransactionalStateOperation(key=another_key, data=another_value),
TransactionalStateOperation(
operation_type=TransactionOperationType.delete,
key=key_to_delete),
],
transactional_metadata={"header1": "value1"},
metadata=(
('header1', 'value1')
),
)
Args:
store_name (str): the state store name to save to
operations (Sequence[TransactionalStateOperation]): the transaction operations
transactional_metadata (Dict[str, str], optional): custom metadata for transaction
metadata (tuple, optional): custom grpc metadata
Returns:
:class:`DaprResponse` gRPC metadata returned from callee
"""
if not store_name or len(store_name) == 0 or len(
store_name.strip()) == 0:
raise ValueError("State store name cannot be empty")
req_ops = [
api_v1.TransactionalStateOperation(
operationType=o.operation_type.value,
request=common_v1.StateItem(key=o.key,
value=to_bytes(o.data),
etag=o.etag)) for o in operations
]
req = api_v1.ExecuteStateTransactionRequest(
storeName=store_name,
operations=req_ops,
metadata=transactional_metadata)
_, call = self._stub.ExecuteStateTransaction.with_call(
req, metadata=metadata)
return DaprResponse(headers=call.initial_metadata())
def delete_state(
self,
store_name: str,
key: str,
etag: Optional[str] = None,
options: Optional[StateOptions] = None,
state_metadata: Optional[Dict[str, str]] = dict(),
metadata: Optional[MetadataTuple] = ()
) -> DaprResponse:
"""Deletes key-value pairs from a statestore
This deletes a value from the statestore with a given key and state store name.
Options for request can be passed with the options field and custom
metadata can be passed with metadata field.
The example deletes states from a statestore:
from dapr import DaprClient
with DaprClient() as d:
resp = d.delete_state(
store_name='state_store',
key='key1',
etag='etag',
state_metadata={"header1": "value1"},
metadata=(
('header1', 'value1')
)
)
Args:
store_name (str): the state store name to delete from
key (str): the key of the key-value pair to delete
etag (str, optional): the etag to delete with
options (StateOptions, optional): custom options
for concurrency and consistency
state_metadata (Dict[str, str], optional): custom metadata for state request
metadata (tuple, optional): custom metadata
Returns:
:class:`DaprResponse` gRPC metadata returned from callee
"""
if not store_name or len(store_name) == 0 or len(
store_name.strip()) == 0:
raise ValueError("State store name cannot be empty")
if options is None:
state_options = None
else:
state_options = options.get_proto()
etag_object = common_v1.Etag(value=etag) if etag is not None else None
req = api_v1.DeleteStateRequest(store_name=store_name,
key=key,
etag=etag_object,
options=state_options,
metadata=state_metadata)
_, call = self._stub.DeleteState.with_call(req, metadata=metadata)
return DaprResponse(headers=call.initial_metadata())
def save_bulk_state(
self,
store_name: str,
states: List[StateItem],
metadata: Optional[MetadataTuple] = ()
) -> DaprResponse:
"""Saves state items to a statestore
This saves a given state item into the statestore specified by store_name.
The example saves states to a statestore:
from dapr import DaprClient
with DaprClient() as d:
resp = d.save_bulk_state(
store_name='state_store',
states=[StateItem(key='key1', value='value1'),
StateItem(key='key2', value='value2', etag='etag'),],
)
Args:
store_name (str): the state store name to save to
states (List[StateItem]): list of states to save
metadata (tuple, optional): gRPC custom metadata
Returns:
:class:`DaprResponse` gRPC metadata returned from callee
Raises:
ValueError: states is empty
ValueError: store_name is empty
"""
if metadata is not None:
warn(
'metadata argument is deprecated. Dapr already intercepts API token headers '
'and this is not needed.',
DeprecationWarning,
stacklevel=2)
if not states or len(states) == 0:
raise ValueError("States to be saved cannot be empty")
if not store_name or len(store_name) == 0 or len(
store_name.strip()) == 0:
raise ValueError("State store name cannot be empty")
req_states = [
common_v1.StateItem(
key=i.key,
value=to_bytes(i.value),
etag=common_v1.Etag(
value=i.etag) if i.etag is not None else None,
options=i.options,
metadata=i.metadata) for i in states
]
req = api_v1.SaveStateRequest(store_name=store_name, states=req_states)
_, call = self._stub.SaveState.with_call(req, metadata=metadata)
return DaprResponse(headers=call.initial_metadata())
def execute_state_transaction(
self,
store_name: str,
operations: Sequence[TransactionalStateOperation],
transactional_metadata: Optional[Dict[str, str]] = dict(),
metadata: Optional[MetadataTuple] = None) -> DaprResponse:
"""Saves or deletes key-value pairs to a statestore as a transaction
This saves or deletes key-values to the statestore as part of a single transaction,
transaction_metadata is used for the transaction operation, while metadata is used
for the GRPC call.
The example saves states to a statestore:
from dapr import DaprClient
with DaprClient() as d:
resp = d.execute_state_transaction(
store_name='state_store',
operations=[
TransactionalStateOperation(key=key, data=value),
TransactionalStateOperation(key=another_key, data=another_value),
TransactionalStateOperation(
operation_type=TransactionOperationType.delete,
key=key_to_delete),
],
transactional_metadata={"header1": "value1"},
)
Args:
store_name (str): the state store name to save to
operations (Sequence[TransactionalStateOperation]): the transaction operations
transactional_metadata (Dict[str, str], optional): Dapr metadata for transaction
metadata (tuple, optional, DEPRECATED): gRPC custom metadata
Returns:
:class:`DaprResponse` gRPC metadata returned from callee
"""
if metadata is not None:
warn('metadata argument is deprecated. Dapr already intercepts API token headers '
'and this is not needed.', DeprecationWarning, stacklevel=2)
if not store_name or len(store_name) == 0 or len(store_name.strip()) == 0:
raise ValueError("State store name cannot be empty")
req_ops = [api_v1.TransactionalStateOperation(
operationType=o.operation_type.value,
request=common_v1.StateItem(
key=o.key,
value=to_bytes(o.data),
etag=common_v1.Etag(value=o.etag) if o.etag is not None else None))
for o in operations]
req = api_v1.ExecuteStateTransactionRequest(
storeName=store_name,
operations=req_ops,
metadata=transactional_metadata)
_, call = self._stub.ExecuteStateTransaction.with_call(req, metadata=metadata)
return DaprResponse(
headers=call.initial_metadata())
def publish_event(
self,
pubsub_name: str,
topic_name: str,
data: Union[bytes, str],
metadata: Optional[MetadataTuple] = (),
data_content_type: Optional[str] = None) -> DaprResponse:
"""Publish to a given topic.
This publishes an event with bytes array or str data to a specified topic and
specified pubsub component. The str data is encoded into bytes with default
charset of utf-8. Custom metadata can be passed with the metadata field which
will be passed on a gRPC metadata.
The example publishes a byte array event to a topic:
from dapr.clients import DaprClient
with DaprClient() as d:
resp = d.publish_event(
pubsub_name='pubsub_1'
topic_name='TOPIC_A'
data=b'message',
metadata=(
('header1', 'value1')
),
)
# resp.headers includes the gRPC initial metadata.
Args:
pubsub_name (str): the name of the pubsub component
topic_name (str): the topic name to publish to
data (bytes or str): bytes or str for data
metadata (tuple, optional): custom metadata
data_content_type: (str, optional): content type of the data payload
Returns:
:class:`DaprResponse` gRPC metadata returned from callee
"""
if not isinstance(data, bytes) and not isinstance(data, str):
raise ValueError(f'invalid type for data {type(data)}')
req_data = data
if isinstance(data, str):
req_data = data.encode('utf-8')
req = api_v1.PublishEventRequest(
pubsub_name=pubsub_name,
topic=topic_name,
data=req_data,
data_content_type=data_content_type)
# response is google.protobuf.Empty
_, call = self._stub.PublishEvent.with_call(req, metadata=metadata)
return DaprResponse(call.initial_metadata())
def save_bulk_state(
self,
store_name: str,
states: List[StateItem],
metadata: Optional[MetadataTuple] = ()
) -> DaprResponse:
"""Saves state items to a statestore
This saves a given state item into the statestore specified by store_name.
The example saves states to a statestore:
from dapr import DaprClient
with DaprClient() as d:
resp = d.save_bulk_state(
store_name='state_store'
states=[StateItem(key='key1', value='value1'),
StateItem(key='key2', value='value2', etag='etag'),],
metadata=(
('header1', 'value1')
),
)
Args:
store_name (str): the state store name to save to
states (List[StateItem]): list of states to save
metadata (tuple, optional): custom metadata
Returns:
:class:`DaprResponse` gRPC metadata returned from callee
Raises:
ValueError: states is empty
ValueError: store_name is empty
"""
if not states or len(states) == 0:
raise ValueError("States to be saved cannot be empty")
if not store_name or len(store_name) == 0 or len(
store_name.strip()) == 0:
raise ValueError("State store name cannot be empty")
req_states = [
common_v1.StateItem(key=i.key,
value=to_bytes(i.value),
etag=i.etag,
options=i.options,
metadata=i.metadata) for i in states
]
req = api_v1.SaveStateRequest(store_name=store_name, states=req_states)
_, call = self._stub.SaveState.with_call(req, metadata=metadata)
return DaprResponse(headers=call.initial_metadata())
def publish_event(
self,
topic: str,
data: Union[bytes, str],
metadata: Optional[MetadataTuple] = ()
) -> DaprResponse:
"""Publish to a given topic.
This publishes an event with bytes array or str data to a specified topic.
The str data is encoded into bytes with default charset of utf-8.
Custom metadata can be passed with the metadata field which will be passed
on a gRPC metadata.
The example publishes a byte array event to a topic:
from dapr import DaprClient
with DaprClient() as d:
resp = d.publish_event(
topic='TOPIC_A'
data=b'message',
metadata=(
('header1', 'value1')
),
)
# resp.headers includes the gRPC initial metadata.
# resp.trailers includes that gRPC trailing metadata.
Args:
topic (str): the topic name to publish to
data (bytes or str): bytes or str for data
metadata (tuple, optional): custom metadata
Returns:
:class:`DaprResponse` gRPC metadata returned from callee
"""
if not isinstance(data, bytes) and not isinstance(data, str):
raise ValueError(f'invalid type for data {type(data)}')
req_data = data
if isinstance(data, str):
req_data = data.encode('utf-8')
req = api_v1.PublishEventRequest(topic=topic, data=req_data)
# response is google.protobuf.Empty
response, call = self._stub.PublishEvent.with_call(req,
metadata=metadata)
return DaprResponse(headers=call.initial_metadata(),
trailers=call.trailing_metadata())
def shutdown(self) -> DaprResponse:
"""Shutdown the sidecar.
This will ask the sidecar to gracefully shutdown.
The example shutdown the sidecar:
from dapr.clients import DaprClient
with DaprClient() as d:
resp = d.shutdown()
Returns:
:class:`DaprResponse` gRPC metadata returned from callee
"""
_, call = self._stub.Shutdown.with_call(GrpcEmpty())
return DaprResponse(call.initial_metadata())
def save_state(
self,
store_name: str,
key: str,
value: Union[bytes, str],
etag: Optional[str] = None,
options: Optional[StateOptions] = None,
state_metadata: Optional[Dict[str, str]] = dict(),
metadata: Optional[MetadataTuple] = ()
) -> DaprResponse:
"""Saves key-value pairs to a statestore
This saves a value to the statestore with a given key and state store name.
Options for request can be passed with the options field and custom
metadata can be passed with metadata field.
The example saves states to a statestore:
from dapr import DaprClient
with DaprClient() as d:
resp = d.save_state(
store_name='state_store',
key='key1',
value='value1',
etag='etag',
state_metadata={"metakey": "metavalue"},
)
Args:
store_name (str): the state store name to save to
key (str): the key to be saved
value (bytes or str): the value to be saved
etag (str, optional): the etag to save with
options (StateOptions, optional): custom options
for concurrency and consistency
state_metadata (Dict[str, str], optional): Dapr metadata for state request
metadata (tuple, optional, DEPRECATED): gRPC custom metadata
Returns:
:class:`DaprResponse` gRPC metadata returned from callee
Raises:
ValueError: value is not bytes or str
ValueError: store_name is empty
"""
if metadata is not None:
warn(
'metadata argument is deprecated. Dapr already intercepts API token headers '
'and this is not needed.',
DeprecationWarning,
stacklevel=2)
if not isinstance(value, (bytes, str)):
raise ValueError(f'invalid type for data {type(value)}')
req_value = value
if not store_name or len(store_name) == 0 or len(
store_name.strip()) == 0:
raise ValueError("State store name cannot be empty")
if options is None:
state_options = None
else:
state_options = options.get_proto()
state = common_v1.StateItem(
key=key,
value=to_bytes(req_value),
etag=common_v1.Etag(value=etag) if etag is not None else None,
options=state_options,
metadata=state_metadata)
req = api_v1.SaveStateRequest(store_name=store_name, states=[state])
_, call = self._stub.SaveState.with_call(req, metadata=metadata)
return DaprResponse(headers=call.initial_metadata())
def publish_event(self,
pubsub_name: str,
topic_name: str,
data: Union[bytes, str],
publish_metadata: Dict[str, str] = {},
metadata: Optional[MetadataTuple] = (),
data_content_type: Optional[str] = None) -> DaprResponse:
"""Publish to a given topic.
This publishes an event with bytes array or str data to a specified topic and
specified pubsub component. The str data is encoded into bytes with default
charset of utf-8. Custom metadata can be passed with the metadata field which
will be passed on a gRPC metadata.
The example publishes a byte array event to a topic:
from dapr.clients import DaprClient
with DaprClient() as d:
resp = d.publish_event(
pubsub_name='pubsub_1',
topic_name='TOPIC_A',
data=b'message',
publish_metadata={'ttlInSeconds': '100', 'rawPayload': 'false'},
)
# resp.headers includes the gRPC initial metadata.
Args:
pubsub_name (str): the name of the pubsub component
topic_name (str): the topic name to publish to
data (bytes or str): bytes or str for data
publish_metadata (Dict[str, str], optional): Dapr metadata per Pub/Sub message
metadata (tuple, optional, DEPRECATED): gRPC custom metadata
data_content_type: (str, optional): content type of the data payload
Returns:
:class:`DaprResponse` gRPC metadata returned from callee
"""
if metadata is not None:
warn(
'metadata argument is deprecated. Dapr already intercepts API token headers '
'and this is not needed.',
DeprecationWarning,
stacklevel=2)
if not isinstance(data, bytes) and not isinstance(data, str):
raise ValueError(f'invalid type for data {type(data)}')
req_data: bytes
if isinstance(data, bytes):
req_data = data
else:
if isinstance(data, str):
req_data = data.encode('utf-8')
content_type = ""
if data_content_type:
content_type = data_content_type
req = api_v1.PublishEventRequest(pubsub_name=pubsub_name,
topic=topic_name,
data=req_data,
data_content_type=content_type,
metadata=publish_metadata)
# response is google.protobuf.Empty
_, call = self._stub.PublishEvent.with_call(req, metadata=metadata)
return DaprResponse(call.initial_metadata())