gRPC clients

GrpcClient and AsyncGrpcClient mirror the HTTP clients over gRPC. Requires pip install 'turboocr[grpc]'.

Two parity caveats

• The gRPC proto's bool fields lack field presence (proto3 without optional), so None is sent as False. Today the server defaults all bool options to False, so behavior matches the HTTP client — if the server ever flips a default, gRPC users would have to opt in explicitly.
• GrpcClient.recognize_pdf(reading_order=True) raises InvalidParameter — the proto lacks the reading_order field. Use the HTTP client for PDFs that need reading order.

GrpcClient

GrpcClient

GrpcClient(*, target: str | None = None, api_key: str | None = None, auth_scheme: AuthScheme = 'bearer', secure: bool = False, credentials: ChannelCredentials | None = None, timeout: float = DEFAULT_TIMEOUT, default_metadata: Mapping[str, str] | None = None, retry: RetryPolicy | None = None, channel_options: list[ChannelOption] | None = None, interceptors: Sequence[SyncInterceptor] | None = None, channel: Channel | None = None)

Bases: _BaseGrpcClient

METHOD	DESCRIPTION
from_env	Construct a GrpcClient driven by TURBO_OCR_GRPC_TARGET and friends.
close	Close the channel, but only if this client created it.
recognize_image	gRPC equivalent of Client.recognize_image.
recognize_base64	gRPC equivalent of Client.recognize_base64.
recognize_pixels	gRPC equivalent of Client.recognize_pixels.
recognize_batch	gRPC equivalent of Client.recognize_batch.
recognize_pdf	gRPC equivalent of Client.recognize_pdf.
health	Probe the gRPC server's Health RPC.
make_searchable_pdf	gRPC equivalent of

from_env classmethod

from_env(**overrides: Unpack[_GrpcClientKwargs]) -> Self

Construct a GrpcClient driven by TURBO_OCR_GRPC_TARGET and friends.

close

close() -> None

Close the channel, but only if this client created it.

When you passed channel= at construction time, ownership stays with the caller — close() is a no-op (with a DEBUG-level log) so a shared channel isn't accidentally torn down underneath other consumers.

recognize_image

recognize_image(image: ImageInput, *, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> OcrResponse

gRPC equivalent of Client.recognize_image.

recognize_base64

recognize_base64(b64: str, *, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> OcrResponse

gRPC equivalent of Client.recognize_base64.

Note: gRPC has no native base64 wire encoding, so the SDK decodes client-side and sends raw bytes. The convenience method is kept for surface parity with the HTTP client.

recognize_pixels

recognize_pixels(pixels: ImageInput, *, width: int, height: int, channels: int = 3, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> OcrResponse

gRPC equivalent of Client.recognize_pixels.

recognize_batch

recognize_batch(images: Iterable[ImageInput], *, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> BatchResponse

gRPC equivalent of Client.recognize_batch.

recognize_pdf

recognize_pdf(pdf: ImageInput, *, dpi: int | None = None, mode: PdfMode | str | None = None, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> PdfResponse

gRPC equivalent of Client.recognize_pdf.

Passing reading_order=True raises InvalidParameter — the gRPC proto lacks the field. Use the HTTP client for PDFs that need reading order.

health

health() -> HealthStatus

Probe the gRPC server's Health RPC.

make_searchable_pdf

make_searchable_pdf(source: ImageInput, *, dpi: int = 200, mode: PdfMode | str | None = None, font_path: str | None = None) -> bytes

gRPC equivalent of Client.make_searchable_pdf.

AsyncGrpcClient

AsyncGrpcClient

AsyncGrpcClient(*, target: str | None = None, api_key: str | None = None, auth_scheme: AuthScheme = 'bearer', secure: bool = False, credentials: ChannelCredentials | None = None, timeout: float = DEFAULT_TIMEOUT, default_metadata: Mapping[str, str] | None = None, retry: RetryPolicy | None = None, channel_options: list[ChannelOption] | None = None, interceptors: Sequence[AsyncInterceptor] | None = None, channel: Channel | None = None)

Bases: _BaseGrpcClient

METHOD	DESCRIPTION
from_env	Async equivalent of GrpcClient.from_env.
aclose	Async equivalent of GrpcClient.close.
recognize_image	Async gRPC equivalent of Client.recognize_image.
recognize_base64	Async gRPC equivalent of
recognize_pixels	Async gRPC equivalent of
recognize_batch	Async gRPC equivalent of Client.recognize_batch.
recognize_pdf	Async gRPC equivalent of
health	Async equivalent of GrpcClient.health.
make_searchable_pdf	Async equivalent of

from_env classmethod

from_env(**overrides: Unpack[_AsyncGrpcClientKwargs]) -> Self

Async equivalent of GrpcClient.from_env.

aclose async

aclose() -> None

Async equivalent of GrpcClient.close.

recognize_image async

recognize_image(image: ImageInput, *, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> OcrResponse

Async gRPC equivalent of Client.recognize_image.

recognize_base64 async

recognize_base64(b64: str, *, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> OcrResponse

Async gRPC equivalent of Client.recognize_base64.

recognize_pixels async

recognize_pixels(pixels: ImageInput, *, width: int, height: int, channels: int = 3, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> OcrResponse

Async gRPC equivalent of Client.recognize_pixels.

recognize_batch async

recognize_batch(images: Iterable[ImageInput], *, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> BatchResponse

Async gRPC equivalent of Client.recognize_batch.

recognize_pdf async

recognize_pdf(pdf: ImageInput, *, dpi: int | None = None, mode: PdfMode | str | None = None, layout: BoolParam = None, reading_order: BoolParam = None, include_blocks: BoolParam = None, timeout: float | None = None) -> PdfResponse

Async gRPC equivalent of GrpcClient.recognize_pdf.

health async

health() -> HealthStatus

Async equivalent of GrpcClient.health.

make_searchable_pdf async

make_searchable_pdf(source: ImageInput, *, dpi: int = 200, mode: PdfMode | str | None = None, font_path: str | None = None) -> bytes

Async equivalent of GrpcClient.make_searchable_pdf.