jina.clients.asyncio

Module wrapping AsyncIO ops for clients.

class jina.clients.asyncio.AsyncClient(args)[source]

Bases: jina.clients.base.BaseClient

AsyncClient is the asynchronous version of the Client.

They share the same interface, except in AsyncClient train(), index(), search() methods are coroutines (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().

AsyncClient 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.

For example, say you have the Flow running in remote. You want to use Client to connect to it do some index and search, but meanwhile you have some other IO-bounded jobs and want to do them concurrently. You can use AsyncClient,

from jina.clients.asyncio import AsyncClient

ac = AsyncClient(...)

async def jina_client_query():
    await ac.search(...)

async def heavylifting():
    await other_library.download_big_files(...)

async def concurrent_main():
    await asyncio.gather(jina_client_query(), heavylifting())


if __name__ == '__main__':
    # under python
    asyncio.run(concurrent_main())

One can think of Client as Jina-managed eventloop, whereas AsyncClient is self-managed eventloop.

train(inputs, on_done=None, on_error=None, on_always=None, **kwargs)[source]

Issue ‘train’ request to the Flow.

Parameters
  • inputs (Union[Document, Iterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]], AsyncIterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]], Callable[…, Union[Document, Iterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]], AsyncIterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]]]]]) – input data which can be an Iterable, a function which returns an Iterable, or a single Document

  • on_done (Optional[Callable[…, None]]) – the function to be called when the Request object is resolved.

  • on_error (Optional[Callable[…, None]]) – the function to be called when the Request object is rejected.

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

  • kwargs – additional parameters

Yield

result

Return type

None

search(inputs, on_done=None, on_error=None, on_always=None, **kwargs)[source]

Issue ‘search’ request to the Flow.

Parameters
  • inputs (Union[Document, Iterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]], AsyncIterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]], Callable[…, Union[Document, Iterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]], AsyncIterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]]]]]) – input data which can be an Iterable, a function which returns an Iterable, or a single Document

  • on_done (Optional[Callable[…, None]]) – the function to be called when the Request object is resolved.

  • on_error (Optional[Callable[…, None]]) – the function to be called when the Request object is rejected.

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

  • kwargs – additional parameters

Yield

result

Return type

None

index(inputs, on_done=None, on_error=None, on_always=None, **kwargs)[source]

Issue ‘index’ request to the Flow.

Parameters
  • inputs (Union[Document, Iterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]], AsyncIterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]], Callable[…, Union[Document, Iterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]], AsyncIterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]]]]]) – input data which can be an Iterable, a function which returns an Iterable, or a single Document

  • on_done (Optional[Callable[…, None]]) – the function to be called when the Request object is resolved.

  • on_error (Optional[Callable[…, None]]) – the function to be called when the Request object is rejected.

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

  • kwargs – additional parameters

Yield

result

Return type

None

delete(inputs, on_done=None, on_error=None, on_always=None, **kwargs)[source]

Issue ‘delete’ request to the Flow.

Parameters
  • inputs (Union[str, Iterable[str], Callable[…, Iterable[str]]]) – input data which can be an Iterable, a function which returns an Iterable, or a single Document id

  • on_done (Optional[Callable[…, None]]) – the function to be called when the Request object is resolved.

  • on_error (Optional[Callable[…, None]]) – the function to be called when the Request object is rejected.

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

  • kwargs – additional parameters

Yield

result

Return type

None

update(inputs, on_done=None, on_error=None, on_always=None, **kwargs)[source]

Issue ‘update’ request to the Flow.

Parameters
  • inputs (Union[Document, Iterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]], AsyncIterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]], Callable[…, Union[Document, Iterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]], AsyncIterable[Union[~DocumentContentType, ~DocumentSourceType, Document, Tuple[~DocumentContentType, ~DocumentContentType], Tuple[~DocumentSourceType, ~DocumentSourceType]]]]]]) – input data which can be an Iterable, a function which returns an Iterable, or a single Document

  • on_done (Optional[Callable[…, None]]) – the function to be called when the Request object is resolved.

  • on_error (Optional[Callable[…, None]]) – the function to be called when the Request object is rejected.

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

  • kwargs – additional parameters

Yield

result

Return type

None

reload(targets, on_done=None, on_error=None, on_always=None, **kwargs)[source]

Send ‘reload’ request to the Flow.

Parameters
  • targets (Union[str, List[str]]) – the regex string or list of regex strings to match the pea/pod names.

  • on_done (Optional[Callable[…, None]]) – the function to be called when the Request object is resolved.

  • on_error (Optional[Callable[…, None]]) – the function to be called when the Request object is rejected.

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

  • kwargs – additional parameters

Yield

result

class jina.clients.asyncio.AsyncWebSocketClient(args)[source]

Bases: jina.clients.asyncio.AsyncClient, jina.clients.websocket.WebSocketClientMixin

AsyncWebSocketClient is the asynchronous version of the WebSocketClient.

They share the same interface, except in AsyncWebSocketClient train(), index(), search() methods are coroutines (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 eventloop, e.g. via asyncio.run(), asyncio.create_task().

AsyncWebSocketClient 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, WebSocketClient is controlling and wrapping the eventloop internally, making the Client looks synchronous from outside.

For example, say you have the Flow running in remote. You want to use Client to connect to it do some index and search, but meanwhile you have some other IO-bounded jobs and want to do them concurrently. You can use AsyncWebSocketClient,

from jina.clients.asyncio import AsyncWebSocketClient

ac = AsyncWebSocketClient(...)

async def jina_client_query():
    await ac.search(...)

async def heavylifting():
    await other_library.download_big_files(...)

async def concurrent_main():
    await asyncio.gather(jina_client_query(), heavylifting())


if __name__ == '__main__':
    # under python
    asyncio.run(concurrent_main())

One can think of WebSocketClient as Jina-managed eventloop, whereas AsyncWebSocketClient is self-managed eventloop.