jina.clients.grpc module#
- class jina.clients.grpc.GRPCClient(args=None, **kwargs)[source]#
Bases:
GRPCBaseClient
,PostMixin
,HealthCheckMixin
,ProfileMixin
A client connecting to a Gateway using gRPC protocol.
Instantiate this class through the
jina.Client()
convenience method.EXAMPLE USAGE
from jina import Client from docarray import Document # select host address to connect to c = Client( protocol='grpc', asyncio=False, host='grpc://my.awesome.flow:1234' ) # returns GRPCClient instance c.post(on='/index', inputs=Document(text='hello!'))
- static check_input(inputs=None, **kwargs)#
Validate the inputs and print the first request if success.
- Parameters:
inputs (
Optional
[InputType]) – the inputskwargs – keyword arguments
- Return type:
None
- property client: T#
Return the client object itself
- Return type:
TypeVar
(T
)- Returns:
the Client object
- delete(inputs: Optional[InputType] = None, on_done: Optional[CallbackFnType] = None, on_error: Optional[CallbackFnType] = None, on_always: Optional[CallbackFnType] = None, parameters: Optional[Dict] = None, target_executor: Optional[str] = None, request_size: int = 100, show_progress: bool = False, continue_on_error: bool = False, return_responses: bool = False, **kwargs) Optional[Union[DocumentArray, List[Response]]] #
- dry_run(**kwargs)#
Sends a dry run to the Flow to validate if the Flow is ready to receive requests
- Parameters:
kwargs – potential kwargs received passed from the public interface
- Return type:
bool
- Returns:
boolean indicating the health/readiness of the Flow
- index(inputs: Optional[InputType] = None, on_done: Optional[CallbackFnType] = None, on_error: Optional[CallbackFnType] = None, on_always: Optional[CallbackFnType] = None, parameters: Optional[Dict] = None, target_executor: Optional[str] = None, request_size: int = 100, show_progress: bool = False, continue_on_error: bool = False, return_responses: bool = False, **kwargs) Optional[Union[DocumentArray, List[Response]]] #
- property inputs: InputType#
An iterator of bytes, each element represents a Document’s raw content.
inputs
defined in the protobuf- Return type:
InputType
- Returns:
inputs
- post(on, inputs=None, on_done=None, on_error=None, on_always=None, parameters=None, target_executor=None, request_size=100, show_progress=False, continue_on_error=False, return_responses=False, **kwargs)#
Post a general data request to the Flow.
- Parameters:
inputs (
Optional
[InputType]) – input data which can be an Iterable, a function which returns an Iterable, or a single Document.on (
str
) – the endpoint which is invoked. All the functions in the executors decorated by @requests(on=…) with the same endpoint are invoked.on_done (
Optional
[CallbackFnType]) – the function to be called when theRequest
object is resolved.on_error (
Optional
[CallbackFnType]) – the function to be called when theRequest
object is rejected.on_always (
Optional
[CallbackFnType]) – the function to be called when theRequest
object is either resolved or rejected.parameters (
Optional
[Dict
]) – the kwargs that will be sent to the executortarget_executor (
Optional
[str
]) – a regex string. Only matching Executors will process the request.request_size (
int
) – the number of Documents per request. <=0 means all inputs in one request.show_progress (
bool
) – if set, client will show a progress bar on receiving every request.continue_on_error (
bool
) – if set, a Request that causes callback error will be logged only without blocking the further requests.7return_responses (
bool
) – if set to True, the result will come as Response and not as a DocumentArraykwargs – additional parameters
- Return type:
Union
[DocumentArray
,List
[Response],None
]- Returns:
None or DocumentArray containing all response Documents
Warning
target_executor
usesre.match
for checking if the pattern is matched.target_executor=='foo'
will match both deployments with the namefoo
andfoo_what_ever_suffix
.
- profiling(show_table=True)#
Profiling a single query’s roundtrip including network and computation latency. Results is summarized in a Dict.
- Parameters:
show_table (
bool
) – whether to show the table or not.- Return type:
Dict
[str
,float
]- Returns:
the latency report in a dict.
- search(inputs: Optional[InputType] = None, on_done: Optional[CallbackFnType] = None, on_error: Optional[CallbackFnType] = None, on_always: Optional[CallbackFnType] = None, parameters: Optional[Dict] = None, target_executor: Optional[str] = None, request_size: int = 100, show_progress: bool = False, continue_on_error: bool = False, return_responses: bool = False, **kwargs) Optional[Union[DocumentArray, List[Response]]] #
- update(inputs: Optional[InputType] = None, on_done: Optional[CallbackFnType] = None, on_error: Optional[CallbackFnType] = None, on_always: Optional[CallbackFnType] = None, parameters: Optional[Dict] = None, target_executor: Optional[str] = None, request_size: int = 100, show_progress: bool = False, continue_on_error: bool = False, return_responses: bool = False, **kwargs) Optional[Union[DocumentArray, List[Response]]] #
- class jina.clients.grpc.AsyncGRPCClient(args=None, **kwargs)[source]#
Bases:
GRPCBaseClient
,AsyncPostMixin
,AsyncHealthCheckMixin
Asynchronous client connecting to a Gateway using gRPC protocol.
Instantiate this class through the
jina.Client()
convenience method.Unlike
GRPCClient
, herepost()
is a coroutine (i.e. declared with the async/await syntax), simply calling them will not schedule them to be executed.To actually run a coroutine, user need to put them in an event loop, e.g. via
asyncio.run()
,asyncio.create_task()
.AsyncGRPCClient
can be very useful in the integration settings, where Jina/Flow/Client is NOT the main logic, but rather served as a part of other program. In this case, users often do NOT want to let Jina control theasyncio.eventloop
. On contrary,Client
is controlling and wrapping the event loop internally, making the Client looks synchronous from outside.EXAMPLE USAGE
from jina import Client from docarray import Document # async inputs for the client async def async_inputs(): for _ in range(10): yield Document() await asyncio.sleep(0.1) # select host address to connect to c = Client( protocol='grpc', asyncio=True, host='grpc://my.awesome.flow:1234' ) # returns AsyncGRPCClient instance async for resp in client.post(on='/index', async_inputs, request_size=1): print(resp)
- static check_input(inputs=None, **kwargs)#
Validate the inputs and print the first request if success.
- Parameters:
inputs (
Optional
[InputType]) – the inputskwargs – keyword arguments
- Return type:
None
- property client: T#
Return the client object itself
- Return type:
TypeVar
(T
)- Returns:
the Client object
- delete(inputs: Optional[InputType] = None, on_done: Optional[CallbackFnType] = None, on_error: Optional[CallbackFnType] = None, on_always: Optional[CallbackFnType] = None, parameters: Optional[Dict] = None, target_executor: Optional[str] = None, request_size: int = 100, show_progress: bool = False, continue_on_error: bool = False, return_responses: bool = False, **kwargs) AsyncGenerator[None, Union[DocumentArray, Response]] #
- async dry_run(**kwargs)#
Sends a dry run to the Flow to validate if the Flow is ready to receive requests
- Parameters:
kwargs – potential kwargs received passed from the public interface
- Return type:
bool
- Returns:
boolean indicating the health/readiness of the Flow
- index(inputs: Optional[InputType] = None, on_done: Optional[CallbackFnType] = None, on_error: Optional[CallbackFnType] = None, on_always: Optional[CallbackFnType] = None, parameters: Optional[Dict] = None, target_executor: Optional[str] = None, request_size: int = 100, show_progress: bool = False, continue_on_error: bool = False, return_responses: bool = False, **kwargs) AsyncGenerator[None, Union[DocumentArray, Response]] #
- property inputs: InputType#
An iterator of bytes, each element represents a Document’s raw content.
inputs
defined in the protobuf- Return type:
InputType
- Returns:
inputs
- async post(on, inputs=None, on_done=None, on_error=None, on_always=None, parameters=None, target_executor=None, request_size=100, show_progress=False, continue_on_error=False, return_responses=False, **kwargs)#
Async Post a general data request to the Flow.
- Parameters:
inputs (
Optional
[InputType]) – input data which can be an Iterable, a function which returns an Iterable, or a single Document.on (
str
) – the endpoint which is invoked. All the functions in the executors decorated by @requests(on=…) with the same endpoint are invoked.on_done (
Optional
[CallbackFnType]) – the function to be called when theRequest
object is resolved.on_error (
Optional
[CallbackFnType]) – the function to be called when theRequest
object is rejected.on_always (
Optional
[CallbackFnType]) – the function to be called when theRequest
object is either resolved or rejected.parameters (
Optional
[Dict
]) – the kwargs that will be sent to the executortarget_executor (
Optional
[str
]) – a regex string. Only matching Executors will process the request.request_size (
int
) – the number of Documents per request. <=0 means all inputs in one request.show_progress (
bool
) – if set, client will show a progress bar on receiving every request.continue_on_error (
bool
) – if set, a Request that causes callback error will be logged only without blocking the further requests.return_responses (
bool
) – if set to True, the result will come as Response and not as a DocumentArraykwargs – additional parameters, can be used to pass metadata or authentication information in the server call
- Yield:
Response object
Warning
target_executor
usesre.match
for checking if the pattern is matched.target_executor=='foo'
will match both deployments with the namefoo
andfoo_what_ever_suffix
.- Return type:
AsyncGenerator
[None
,Union
[DocumentArray
, Response]]
- search(inputs: Optional[InputType] = None, on_done: Optional[CallbackFnType] = None, on_error: Optional[CallbackFnType] = None, on_always: Optional[CallbackFnType] = None, parameters: Optional[Dict] = None, target_executor: Optional[str] = None, request_size: int = 100, show_progress: bool = False, continue_on_error: bool = False, return_responses: bool = False, **kwargs) AsyncGenerator[None, Union[DocumentArray, Response]] #
- update(inputs: Optional[InputType] = None, on_done: Optional[CallbackFnType] = None, on_error: Optional[CallbackFnType] = None, on_always: Optional[CallbackFnType] = None, parameters: Optional[Dict] = None, target_executor: Optional[str] = None, request_size: int = 100, show_progress: bool = False, continue_on_error: bool = False, return_responses: bool = False, **kwargs) AsyncGenerator[None, Union[DocumentArray, Response]] #