jina.clients.http module#

class jina.clients.http.HTTPClient(args=None, **kwargs)[source]#

Bases: HTTPBaseClient, PostMixin, ProfileMixin, MutateMixin, HealthCheckMixin

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='http', asyncio=False, host='http://my.awesome.flow:1234'
)  # returns HTTPClient 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 inputs

  • kwargs – 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

mutate(mutation, variables=None, timeout=None, headers=None)#

Perform a GraphQL mutation

Parameters:

  • mutation (str) – the GraphQL mutation as a single string.

  • variables (Optional[dict]) – variables to be substituted in the mutation. Not needed if no variables are present in the mutation string.

  • timeout (Optional[float]) – HTTP request timeout

  • headers (Optional[dict]) – HTTP headers

Returns:

dict containing the optional keys data and errors, for response data and errors.

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 the Request object is resolved.

  • on_error (Optional[CallbackFnType]) – the function to be called when the Request object is rejected.

  • on_always (Optional[CallbackFnType]) – the function to be called when the Request object is either resolved or rejected.

  • parameters (Optional[Dict]) – the kwargs that will be sent to the executor

  • target_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.7

  • return_responses (bool) – if set to True, the result will come as Response and not as a DocumentArray

  • kwargs – additional parameters

Return type:

Union[DocumentArray, List[Response], None]

Returns:

None or DocumentArray containing all response Documents

Warning

target_executor uses re.match for checking if the pattern is matched. target_executor=='foo' will match both deployments with the name foo and foo_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.http.AsyncHTTPClient(args=None, **kwargs)[source]#

Bases: HTTPBaseClient, AsyncPostMixin, AsyncMutateMixin, AsyncProfileMixin, AsyncHealthCheckMixin

Asynchronous client connecting to a Gateway using HTTP protocol.

Instantiate this class through the jina.Client() convenience method.

Unlike HTTPClient, here post() 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().

AsyncHTTPClient 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 the asyncio.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='http', asyncio=True, host='http://my.awesome.flow:1234'
)  # returns AsyncHTTPClient 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 inputs

  • kwargs – 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 mutate(mutation, variables=None, timeout=None, headers=None)#

Perform a GraphQL mutation, asynchronously

Parameters:

  • mutation (str) – the GraphQL mutation as a single string.

  • variables (Optional[dict]) – variables to be substituted in the mutation. Not needed if no variables are present in the mutation string.

  • timeout (Optional[float]) – HTTP request timeout

  • headers (Optional[dict]) – HTTP headers

Returns:

dict containing the optional keys data and errors, for response data and errors.

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 the Request object is resolved.

  • on_error (Optional[CallbackFnType]) – the function to be called when the Request object is rejected.

  • on_always (Optional[CallbackFnType]) – the function to be called when the Request object is either resolved or rejected.

  • parameters (Optional[Dict]) – the kwargs that will be sent to the executor

  • target_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 DocumentArray

  • kwargs – additional parameters, can be used to pass metadata or authentication information in the server call

Yield:

Response object

Warning

target_executor uses re.match for checking if the pattern is matched. target_executor=='foo' will match both deployments with the name foo and foo_what_ever_suffix.

Return type:

AsyncGenerator[None, Union[DocumentArray, Response]]

async 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) → 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]]#