jina.drivers

jina.drivers.store_init_kwargs(func)[source]

Mark the args and kwargs of __init__() later to be stored via save_config() in YAML

Parameters

func (Callable) – the Callable to wrap

Return type

Callable

Returns

the wrapped Callable

class jina.drivers.QuerySetReader[source]

Bases: object

QuerySetReader allows a driver to read arguments from the protobuf message. This allows a driver to override its behavior based on the message it receives. Extremely useful in production, for example, get top_k results, doing pagination, filtering.

To register the field you want to read from the message, simply register them in __init__(). For example, __init__(self, arg1, arg2, **kwargs) will allow the driver to read field arg1 and arg2 from the message. When they are not found in the message, the value _arg1 and _arg2 will be used. Note the underscore prefix.

Note

  • To set default value of arg1, use self._arg1 =, note the underscore in the front.

  • To access arg1, simply use self.arg1. It automatically switch between default _arg1 and arg1 from the request.

For successful value reading, the following condition must be met:

  • the name in the proto must match with the current class name

  • the disabled field in the proto should not be False

  • the priority in the proto should be strictly greater than the driver’s priority (by default is 0)

  • the field name must exist in proto’s parameters

Warning

For the sake of cooperative multiple inheritance, do NOT implement __init__() for this class

property as_querylang

Render as QueryLang parameters.

class jina.drivers.DriverType(*args, **kwargs)[source]

Bases: jina.jaml.JAMLCompatibleType, type

A meta class representing a Driver

When a new Driver is created, it gets registered

Create and register a new class with this meta class.

Parameters
  • args – additional positional arguments which are just used for the parent initialization

  • kwargs – additional key value arguments which are just used for the parent initialization

Returns

the newly registered class

static register_class(cls)[source]

Register a class

Parameters

cls – the class

Returns

the class, after being registered

class jina.drivers.BaseDriver(priority=0, *args, **kwargs)[source]

Bases: jina.jaml.JAMLCompatible

A BaseDriver is a logic unit above the jina.peapods.runtimes.zmq.zed.ZEDRuntime. It reads the protobuf message, extracts/modifies the required information and then return the message back to jina.peapods.runtimes.zmq.zed.ZEDRuntime.

A BaseDriver needs to be attached to a jina.peapods.runtimes.zmq.zed.ZEDRuntime before using. This is done by attach(). Note that a deserialized BaseDriver from file is always unattached.

Parameters
  • priority (int) – the priority of its default arg values (hardcoded in Python). If the received QueryLang has a higher priority, it will override the hardcoded value

  • args – not used (kept to maintain interface)

  • kwargs – not used (kept to maintain interface)

store_args_kwargs = False

set this to True to save args (in a list) and kwargs (in a map) in YAML config

attach(runtime, *args, **kwargs)[source]

Attach this driver to a jina.peapods.runtimes.zmq.zed.ZEDRuntime

Parameters
  • runtime (ZEDRuntime) – the pea to be attached

  • args – not used (kept to maintain interface)

  • kwargs – not used (kept to maintain interface)

Return type

None

property req

Get the current (typed) request, shortcut to self.runtime.request

Return type

Request

property partial_reqs

The collected partial requests under the current request_id

Return type

Sequence[ForwardRef]

property expect_parts

The expected number of partial messages

Return type

int

property docs

The DocumentSet after applying the traversal

Return type

DocumentSet

property msg

Get the current request, shortcut to self.runtime.message

Return type

Message

property queryset
Return type

QueryLangSet

property logger

Shortcut to self.runtime.logger

Return type

JinaLogger

class jina.drivers.ContextAwareRecursiveMixin[source]

Bases: object

The full data structure version of FlatRecursiveMixin, to be mixed in with BaseRecursiveDriver. It uses traverse() in DocumentSet and allows direct manipulation of Chunk-/Match-/DocumentSets.

class jina.drivers.FlatRecursiveMixin[source]

Bases: object

The batch optimized version of ContextAwareRecursiveMixin, to be mixed in with BaseRecursiveDriver. It uses traverse_flattened_per_path() in DocumentSet and yield much better performance when no context is needed and batching is possible.

class jina.drivers.DocsExtractUpdateMixin[source]

Bases: object

A Driver pattern for extracting attributes from Documents, feeding to an executor and updating the Documents with the results.

Drivers equipped with this mixin will have :method:`_apply_all` inherited.

The :method:`_apply_all` implements the following logics:
The following shortcut logics are implemented:
  • while extracting: attributes defined :method:`exec_fn`’s arguments are extracted from docs;

  • while extracting: attributes annotated with ndarray are stacked into Numpy NdArray objects;

  • while updating: if exec_fn returns a List of Dict, then doc.set_attrs(**exec_result) is called;

  • while updating: if exec_fn returns a Document, then ``doc.update(exec_result)` is called.

  • while updating: if none of above applies, then calling update_single_doc()

To override the update behavior, you can choose to override:
update_docs(docs_pts, exec_results)[source]

Update Documents with the Executor returned results.

Param

docs_pts: the set of document to be updated

Param

exec_results: the results from exec_fn()

Return type

None

update_single_doc(doc, exec_result)[source]

Update a single Document with the Executor returned result.

Parameters
  • doc (Document) – the Document object

  • exec_result (Any) – the single result from exec_fn()

Return type

None

class jina.drivers.BaseRecursiveDriver(traversal_paths=('c', 'r'), *args, **kwargs)[source]

Bases: jina.drivers.BaseDriver

A BaseRecursiveDriver is an abstract Driver class containing information about the traversal_paths that a Driver must apply its logic. It is intended to be mixed in with either FlatRecursiveMixin or ContextAwareRecursiveMixin

Initialize a BaseRecursiveDriver

Parameters
  • traversal_paths (Tuple[str]) – Describes the leaves of the document tree on which _apply_all are called

  • args – additional positional arguments which are just used for the parent initialization

  • kwargs – additional key value arguments which are just used for the parent initialization

runtime: Optional[ZEDRuntime]
class jina.drivers.BaseExecutableDriver(executor=None, method=None, strict_method_args=True, *args, **kwargs)[source]

Bases: jina.drivers.BaseRecursiveDriver

A BaseExecutableDriver is an intermediate logic unit between the jina.peapods.runtimes.zmq.zed.ZEDRuntime and jina.executors.BaseExecutor It reads the protobuf message, extracts/modifies the required information and then sends to the jina.executors.BaseExecutor, finally it returns the message back to jina.peapods.runtimes.zmq.zed.ZEDRuntime.

A BaseExecutableDriver needs to be attached to a jina.peapods.runtimes.zmq.zed.ZEDRuntime and jina.executors.BaseExecutor before using. This is done by attach(). Note that a deserialized BaseDriver from file is always unattached.

Initialize a BaseExecutableDriver

Parameters
  • executor (Optional[str]) – the name of the sub-executor, only necessary when jina.executors.compound.CompoundExecutor is used

  • method (Optional[str]) – the function name of the executor that the driver feeds to

  • strict_method_args (bool) – if set, then the input args of executor.method must be valid Document attributes

  • args – additional positional arguments which are just used for the parent initialization

  • kwargs – additional key value arguments which are just used for the parent initialization

property exec

the executor that to which the instance is attached

Return type

AnyExecutor

property exec_fn

the function of jina.executors.BaseExecutor() to call

Return type

Callable

Returns

the Callable to execute in the driver

attach(executor, req_type=None, *args, **kwargs)[source]

Attach the driver to a jina.executors.BaseExecutor

Parameters
  • executor (AnyExecutor) – the executor to which we attach

  • req_type (Optional[str]) – the request type to attach to

  • args – additional positional arguments for the call of super().attach()

  • kwargs – additional key value arguments for the call of super().attach()

Return type

None

runtime: Optional[ZEDRuntime]