grpc package

Module contents

gRPC’s Python API.

exception grpc.FutureTimeoutError[source]

Bases: exceptions.Exception

Indicates that a method call on a Future timed out.

exception grpc.FutureCancelledError[source]

Bases: exceptions.Exception

Indicates that the computation underlying a Future was cancelled.

class grpc.Future[source]

Bases: object

A representation of a computation in another control flow.

Computations represented by a Future may be yet to be begun, may be ongoing, or may have already completed.

add_done_callback(fn)[source]

Adds a function to be called at completion of the computation.

The callback will be passed this Future object describing the outcome of the computation.

If the computation has already completed, the callback will be called immediately.

Parameters:fn – A callable taking this Future object as its single parameter.
cancel()[source]

Attempts to cancel the computation.

This method does not block.

Returns:Returns True if the computation was canceled. Returns False under all other circumstances, for example: 1. computation has begun and could not be canceled. 2. computation has finished 3. computation is scheduled for execution and it is impossible to
determine its state without blocking.
Return type:bool
cancelled()[source]

Describes whether the computation was cancelled.

This method does not block.

Returns:Returns True if the computation was cancelled before its result became available. False under all other circumstances, for example: 1. computation was not cancelled. 2. computation’s result is available.
Return type:bool
done()[source]

Describes whether the computation has taken place.

This method does not block.

Returns:Returns True if the computation already executed or was cancelled. Returns False if the computation is scheduled for execution or currently executing. This is exactly opposite of the running() method’s result.
Return type:bool
exception(timeout=None)[source]

Return the exception raised by the computation.

This method may return immediately or may block.

Parameters:

timeout – The length of time in seconds to wait for the computation to terminate or be cancelled. If None, the call will block until the computations’s termination.

Returns:

The exception raised by the computation, or None if the computation did not raise an exception.

Raises:
result(timeout=None)[source]

Returns the result of the computation or raises its exception.

This method may return immediately or may block.

Parameters:

timeout – The length of time in seconds to wait for the computation to finish or be cancelled. If None, the call will block until the computations’s termination.

Returns:

The return value of the computation.

Raises:
  • FutureTimeoutError – If a timeout value is passed and the computation does not terminate within the allotted time.
  • FutureCancelledError – If the computation was cancelled.
  • Exception – If the computation raised an exception, this call will raise the same exception.
running()[source]

Describes whether the computation is taking place.

This method does not block.

Returns:Returns True if the computation is scheduled for execution or currently executing. Returns False if the computation already executed or was cancelled.
Return type:bool
traceback(timeout=None)[source]

Access the traceback of the exception raised by the computation.

This method may return immediately or may block.

Parameters:

timeout – The length of time in seconds to wait for the computation to terminate or be cancelled. If None, the call will block until the computations’s termination.

Returns:

The traceback of the exception raised by the computation, or None if the computation did not raise an exception.

Raises:
class grpc.ChannelConnectivity[source]

Bases: enum.Enum

Mirrors grpc_connectivity_state in the gRPC Core.

IDLE

The channel is idle.

CONNECTING

The channel is connecting.

READY

The channel is ready to conduct RPCs.

TRANSIENT_FAILURE

The channel has seen a failure from which it expects to recover.

SHUTDOWN

The channel has seen a failure from which it cannot recover.

CONNECTING = (1, 'connecting')
IDLE = (0, 'idle')
READY = (2, 'ready')
SHUTDOWN = (4, 'shutdown')
TRANSIENT_FAILURE = (3, 'transient failure')
class grpc.StatusCode[source]

Bases: enum.Enum

Mirrors grpc_status_code in the gRPC Core.

ABORTED = (10, 'aborted')
ALREADY_EXISTS = (6, 'already exists')
CANCELLED = (1, 'cancelled')
DATA_LOSS = (15, 'data loss')
DEADLINE_EXCEEDED = (4, 'deadline exceeded')
FAILED_PRECONDITION = (9, 'failed precondition')
INTERNAL = (13, 'internal')
INVALID_ARGUMENT = (3, 'invalid argument')
NOT_FOUND = (5, 'not found')
OK = (0, 'ok')
OUT_OF_RANGE = (11, 'out of range')
PERMISSION_DENIED = (7, 'permission denied')
RESOURCE_EXHAUSTED = (8, 'resource exhausted')
UNAUTHENTICATED = (16, 'unauthenticated')
UNAVAILABLE = (14, 'unavailable')
UNIMPLEMENTED = (12, 'unimplemented')
UNKNOWN = (2, 'unknown')
exception grpc.RpcError[source]

Bases: exceptions.Exception

Raised by the gRPC library to indicate non-OK-status RPC termination.

class grpc.RpcContext[source]

Bases: object

Provides RPC-related information and action.

add_callback(callback)[source]

Registers a callback to be called on RPC termination.

Parameters:callback – A no-parameter callable to be called on RPC termination.
Returns:True if the callback was added and will be called later; False if the callback was not added and will not be called (because the RPC already terminated or some other reason).
Return type:bool
cancel()[source]

Cancels the RPC.

Idempotent and has no effect if the RPC has already terminated.

is_active()[source]

Describes whether the RPC is active or has terminated.

Returns:True if RPC is active, False otherwise.
Return type:bool
time_remaining()[source]

Describes the length of allowed time remaining for the RPC.

Returns:A nonnegative float indicating the length of allowed time in seconds remaining for the RPC to complete before it is considered to have timed out, or None if no deadline was specified for the RPC.
class grpc.Call[source]

Bases: grpc.RpcContext

Invocation-side utility object for an RPC.

code()[source]

Accesses the status code sent by the server.

This method blocks until the value is available.

Returns:The StatusCode value for the RPC.
details()[source]

Accesses the details sent by the server.

This method blocks until the value is available.

Returns:The details string of the RPC.
initial_metadata()[source]

Accesses the initial metadata sent by the server.

This method blocks until the value is available.

Returns:The initial metadata.
trailing_metadata()[source]

Accesses the trailing metadata sent by the server.

This method blocks until the value is available.

Returns:The trailing metadata.
class grpc.ChannelCredentials(credentials)[source]

Bases: object

An encapsulation of the data required to create a secure Channel.

This class has no supported interface - it exists to define the type of its instances and its instances exist to be passed to other functions. For example, ssl_channel_credentials returns an instance, and secure_channel consumes an instance of this class.

class grpc.CallCredentials(credentials)[source]

Bases: object

An encapsulation of the data required to assert an identity over a
channel.

A CallCredentials may be composed with ChannelCredentials to always assert identity for every call over that Channel.

This class has no supported interface - it exists to define the type of its instances and its instances exist to be passed to other functions.

class grpc.AuthMetadataContext[source]

Bases: object

Provides information to call credentials metadata plugins.

service_url

A string URL of the service being called into.

method_name

A string of the fully qualified method name being called.

class grpc.AuthMetadataPluginCallback[source]

Bases: object

Callback object received by a metadata plugin.

__call__(metadata, error)[source]
Inform the gRPC runtime of the metadata to construct a
CallCredentials.
Parameters:
  • metadata – The metadata used to construct the CallCredentials.
  • error – An Exception to indicate error or None to indicate success.
class grpc.AuthMetadataPlugin[source]

Bases: object

A specification for custom authentication.

__call__(context, callback)[source]

Implements authentication by passing metadata to a callback.

Implementations of this method must not block.

Parameters:
  • context – An AuthMetadataContext providing information on the RPC that the plugin is being called to authenticate.
  • callback – An AuthMetadataPluginCallback to be invoked either synchronously or asynchronously.
class grpc.ServerCredentials(credentials)[source]

Bases: object

An encapsulation of the data required to open a secure port on a Server.

This class has no supported interface - it exists to define the type of its instances and its instances exist to be passed to other functions.

class grpc.UnaryUnaryMultiCallable[source]

Bases: object

Affords invoking a unary-unary RPC from client-side.

__call__(request, timeout=None, metadata=None, credentials=None)[source]

Synchronously invokes the underlying RPC.

Parameters:
  • request – The request value for the RPC.
  • timeout – An optional duration of time in seconds to allow for the RPC.
  • metadata – Optional metadata to be transmitted to the service-side of the RPC.
  • credentials – An optional CallCredentials for the RPC.
Returns:

The response value for the RPC.

Raises:

RpcError – Indicating that the RPC terminated with non-OK status. The raised RpcError will also be a Call for the RPC affording the RPC’s metadata, status code, and details.

future(request, timeout=None, metadata=None, credentials=None)[source]

Asynchronously invokes the underlying RPC.

Parameters:
  • request – The request value for the RPC.
  • timeout – An optional duration of time in seconds to allow for the RPC.
  • metadata – Optional metadata to be transmitted to the service-side of the RPC.
  • credentials – An optional CallCredentials for the RPC.
Returns:

An object that is both a Call for the RPC and a Future. In the event of RPC completion, the return Call-Future’s result value will be the response message of the RPC. Should the event terminate with non-OK status, the returned Call-Future’s exception value will be an RpcError.

with_call(request, timeout=None, metadata=None, credentials=None)[source]

Synchronously invokes the underlying RPC.

Parameters:
  • request – The request value for the RPC.
  • timeout – An optional durating of time in seconds to allow for the RPC.
  • metadata – Optional metadata to be transmitted to the service-side of the RPC.
  • credentials – An optional CallCredentials for the RPC.
Returns:

The response value for the RPC and a Call value for the RPC.

Raises:

RpcError – Indicating that the RPC terminated with non-OK status. The raised RpcError will also be a Call for the RPC affording the RPC’s metadata, status code, and details.

class grpc.UnaryStreamMultiCallable[source]

Bases: object

Affords invoking a unary-stream RPC from client-side.

__call__(request, timeout=None, metadata=None, credentials=None)[source]

Invokes the underlying RPC.

Parameters:
  • request – The request value for the RPC.
  • timeout – An optional duration of time in seconds to allow for the RPC. If None, the timeout is considered infinite.
  • metadata – An optional metadata to be transmitted to the service-side of the RPC.
  • credentials – An optional CallCredentials for the RPC.
Returns:

An object that is both a Call for the RPC and an iterator of response values. Drawing response values from the returned Call-iterator may raise RpcError indicating termination of the RPC with non-OK status.

class grpc.StreamUnaryMultiCallable[source]

Bases: object

Affords invoking a stream-unary RPC from client-side.

__call__(request_iterator, timeout=None, metadata=None, credentials=None)[source]

Synchronously invokes the underlying RPC.

Parameters:
  • request_iterator – An iterator that yields request values for the RPC.
  • timeout – An optional duration of time in seconds to allow for the RPC. If None, the timeout is considered infinite.
  • metadata – Optional metadata to be transmitted to the service-side of the RPC.
  • credentials – An optional CallCredentials for the RPC.
Returns:

The response value for the RPC.

Raises:

RpcError – Indicating that the RPC terminated with non-OK status. The raised RpcError will also implement grpc.Call, affording methods such as metadata, code, and details.

future(request_iterator, timeout=None, metadata=None, credentials=None)[source]

Asynchronously invokes the underlying RPC on the client.

Parameters:
  • request_iterator – An iterator that yields request values for the RPC.
  • timeout – An optional duration of time in seconds to allow for the RPC. If None, the timeout is considered infinite.
  • metadata – Optional metadata to be transmitted to the service-side of the RPC.
  • credentials – An optional CallCredentials for the RPC.
Returns:

An object that is both a Call for the RPC and a Future. In the event of RPC completion, the return Call-Future’s result value will be the response message of the RPC. Should the event terminate with non-OK status, the returned Call-Future’s exception value will be an RpcError.

with_call(request_iterator, timeout=None, metadata=None, credentials=None)[source]

Synchronously invokes the underlying RPC on the client.

Parameters:
  • request_iterator – An iterator that yields request values for the RPC.
  • timeout – An optional duration of time in seconds to allow for the RPC. If None, the timeout is considered infinite.
  • metadata – Optional metadata to be transmitted to the service-side of the RPC.
  • credentials – An optional CallCredentials for the RPC.
Returns:

The response value for the RPC and a Call object for the RPC.

Raises:

RpcError – Indicating that the RPC terminated with non-OK status. The raised RpcError will also be a Call for the RPC affording the RPC’s metadata, status code, and details.

class grpc.StreamStreamMultiCallable[source]

Bases: object

Affords invoking a stream-stream RPC on client-side.

__call__(request_iterator, timeout=None, metadata=None, credentials=None)[source]

Invokes the underlying RPC on the client.

Parameters:
  • request_iterator – An iterator that yields request values for the RPC.
  • timeout – An optional duration of time in seconds to allow for the RPC. if not specified the timeout is considered infinite.
  • metadata – Optional metadata to be transmitted to the service-side of the RPC.
  • credentials – An optional CallCredentials for the RPC.
Returns:

An object that is both a Call for the RPC and an iterator of response values. Drawing response values from the returned Call-iterator may raise RpcError indicating termination of the RPC with non-OK status.

class grpc.Channel[source]

Bases: object

Affords RPC invocation via generic methods on client-side.

stream_stream(method, request_serializer=None, response_deserializer=None)[source]

Creates a StreamStreamMultiCallable for a stream-stream method.

Parameters:
  • method – The name of the RPC method.
  • request_serializer – Optional behaviour for serializing the request message. Request goes unserialized in case None is passed.
  • response_deserializer – Optional behaviour for deserializing the response message. Response goes undeserialized in case None is passed.
Returns:

A StreamStreamMultiCallable value for the named stream-stream method.

stream_unary(method, request_serializer=None, response_deserializer=None)[source]

Creates a StreamUnaryMultiCallable for a stream-unary method.

Parameters:
  • method – The name of the RPC method.
  • request_serializer – Optional behaviour for serializing the request message. Request goes unserialized in case None is passed.
  • response_deserializer – Optional behaviour for deserializing the response message. Response goes undeserialized in case None is passed.
Returns:

A StreamUnaryMultiCallable value for the named stream-unary method.

subscribe(callback, try_to_connect=False)[source]

Subscribe to this Channel’s connectivity state machine.

A Channel may be in any of the states described by ChannelConnectivity. This method allows application to monitor the state transitions. The typical use case is to debug or gain better visibility into gRPC runtime’s state.

Parameters:
  • callback – A callable to be invoked with ChannelConnectivity argument. ChannelConnectivity describes current state of the channel. The callable will be invoked immediately upon subscription and again for every change to ChannelConnectivity until it is unsubscribed or this Channel object goes out of scope.
  • try_to_connect – A boolean indicating whether or not this Channel should attempt to connect immediately. If set to False, gRPC runtime decides when to connect.
unary_stream(method, request_serializer=None, response_deserializer=None)[source]

Creates a UnaryStreamMultiCallable for a unary-stream method.

Parameters:
  • method – The name of the RPC method.
  • request_serializer – Optional behaviour for serializing the request message. Request goes unserialized in case None is passed.
  • response_deserializer – Optional behaviour for deserializing the response message. Response goes undeserialized in case None is passed.
Returns:

A UnaryStreamMultiCallable value for the name unary-stream method.

unary_unary(method, request_serializer=None, response_deserializer=None)[source]

Creates a UnaryUnaryMultiCallable for a unary-unary method.

Parameters:
  • method – The name of the RPC method.
  • request_serializer – Optional behaviour for serializing the request message. Request goes unserialized in case None is passed.
  • response_deserializer – Optional behaviour for deserializing the response message. Response goes undeserialized in case None is passed.
Returns:

A UnaryUnaryMultiCallable value for the named unary-unary method.

unsubscribe(callback)[source]

Unsubscribes a subscribed callback from this Channel’s connectivity.

Parameters:callback – A callable previously registered with this Channel from having been passed to its “subscribe” method.
class grpc.ServicerContext[source]

Bases: grpc.RpcContext

A context object passed to method implementations.

auth_context()[source]

Gets the auth context for the call.

Returns:A map of strings to an iterable of bytes for each auth property.
invocation_metadata()[source]

Accesses the metadata from the sent by the client.

Returns:The invocation metadata.
peer()[source]

Identifies the peer that invoked the RPC being serviced.

Returns:A string identifying the peer that invoked the RPC being serviced. The string format is determined by gRPC runtime.
peer_identities()[source]

Gets one or more peer identity(s).

Equivalent to servicer_context.auth_context().get(

servicer_context.peer_identity_key())
Returns:An iterable of the identities, or None if the call is not authenticated. Each identity is returned as a raw bytes type.
peer_identity_key()[source]

The auth property used to identify the peer.

For example, “x509_common_name” or “x509_subject_alternative_name” are used to identify an SSL peer.

Returns:The auth property (string) that indicates the peer identity, or None if the call is not authenticated.
send_initial_metadata(initial_metadata)[source]

Sends the initial metadata value to the client.

This method need not be called by implementations if they have no metadata to add to what the gRPC runtime will transmit.

Parameters:initial_metadata – The initial metadata.
set_code(code)[source]

Sets the value to be used as status code upon RPC completion.

This method need not be called by method implementations if they wish the gRPC runtime to determine the status code of the RPC.

Parameters:code – A StatusCode object to be sent to the client.
set_details(details)[source]

Sets the value to be used as detail string upon RPC completion.

This method need not be called by method implementations if they have no details to transmit.

Parameters:details – An arbitrary string to be sent to the client upon completion.
set_trailing_metadata(trailing_metadata)[source]

Sends the trailing metadata for the RPC.

This method need not be called by implementations if they have no metadata to add to what the gRPC runtime will transmit.

Parameters:trailing_metadata – The trailing metadata.
class grpc.RpcMethodHandler[source]

Bases: object

An implementation of a single RPC method.

request_streaming

Whether the RPC supports exactly one request message or any arbitrary number of request messages.

response_streaming

Whether the RPC supports exactly one response message or any arbitrary number of response messages.

request_deserializer

A callable behavior that accepts a byte string and returns an object suitable to be passed to this object’s business logic, or None to indicate that this object’s business logic should be passed the raw request bytes.

response_serializer

A callable behavior that accepts an object produced by this object’s business logic and returns a byte string, or None to indicate that the byte strings produced by this object’s business logic should be transmitted on the wire as they are.

unary_unary

This object’s application-specific business logic as a callable value that takes a request value and a ServicerContext object and returns a response value. Only non-None if both request_streaming and response_streaming are False.

unary_stream

This object’s application-specific business logic as a callable value that takes a request value and a ServicerContext object and returns an iterator of response values. Only non-None if request_streaming is False and response_streaming is True.

stream_unary

This object’s application-specific business logic as a callable value that takes an iterator of request values and a ServicerContext object and returns a response value. Only non-None if request_streaming is True and response_streaming is False.

stream_stream

This object’s application-specific business logic as a callable value that takes an iterator of request values and a ServicerContext object and returns an iterator of response values. Only non-None if request_streaming and response_streaming are both True.

class grpc.HandlerCallDetails[source]

Bases: object

Describes an RPC that has just arrived for service. .. attribute:: method

The method name of the RPC.
invocation_metadata

The metadata sent by the client.

class grpc.GenericRpcHandler[source]

Bases: object

An implementation of arbitrarily many RPC methods.

service(handler_call_details)[source]

Returns the handler for servicing the RPC.

Parameters:handler_call_details – A HandlerCallDetails describing the RPC.
Returns:An RpcMethodHandler with which the RPC may be serviced if the implementation chooses to service this RPC, or None otherwise.
class grpc.ServiceRpcHandler[source]

Bases: grpc.GenericRpcHandler

An implementation of RPC methods belonging to a service.

A service handles RPC methods with structured names of the form ‘/Service.Name/Service.Method’, where ‘Service.Name’ is the value returned by service_name(), and ‘Service.Method’ is the method name. A service can have multiple method names, but only a single service name.

service_name()[source]

Returns this service’s name.

Returns:The service name.
class grpc.Server[source]

Bases: object

Services RPCs.

add_generic_rpc_handlers(generic_rpc_handlers)[source]

Registers GenericRpcHandlers with this Server.

This method is only safe to call before the server is started.

Parameters:
  • generic_rpc_handlers – An iterable of GenericRpcHandlers that will be used
  • service RPCs. (to) –
add_insecure_port(address)[source]

Opens an insecure port for accepting RPCs.

This method may only be called before starting the server.

Parameters:
  • address – The address for which to open a port.
  • the port is 0, or not specified in the address, then gRPC runtime (if) –
  • choose a port. (will) –
Returns:

An integer port on which server will accept RPC requests.

Return type:

integer

add_secure_port(address, server_credentials)[source]

Opens a secure port for accepting RPCs.

This method may only be called before starting the server.

Parameters:
  • address – The address for which to open a port. if the port is 0, or not specified in the address, then gRPC runtime will choose a port.
  • server_credentials – A ServerCredentials object.
Returns:

An integer port on which server will accept RPC requests.

Return type:

integer

start()[source]

Starts this Server.

This method may only be called once. (i.e. it is not idempotent).

stop(grace)[source]

Stops this Server.

This method immediately stop service of new RPCs in all cases. If a grace period is specified, this method returns immediately and all RPCs active at the end of the grace period are aborted.

If a grace period is not specified, then all existing RPCs are teriminated immediately and the this method blocks until the last RPC handler terminates.

This method is idempotent and may be called at any time. Passing a smaller grace value in subsequentcall will have the effect of stopping the Server sooner. Passing a larger grace value in subsequent call will not have the effect of stopping the server later (i.e. the most restrictive grace value is used).

Parameters:grace – A duration of time in seconds or None.
Returns:A threading.Event that will be set when this Server has completely stopped, i.e. when running RPCs either complete or are aborted and all handlers have terminated.
grpc.unary_unary_rpc_method_handler(behavior, request_deserializer=None, response_serializer=None)[source]

Creates an RpcMethodHandler for a unary-unary RPC method.

Parameters:
  • behavior – The implementation of an RPC that accepts one request and returns
  • response. (one) –
  • request_deserializer – An optional behavior for request deserialization.
  • response_serializer – An optional behavior for response serialization.
Returns:

An RpcMethodHandler object that is typically used by grpc.Server.

grpc.unary_stream_rpc_method_handler(behavior, request_deserializer=None, response_serializer=None)[source]

Creates an RpcMethodHandler for a unary-stream RPC method.

Parameters:
  • behavior – The implementation of an RPC that accepts one request and returns an iterator of response values.
  • request_deserializer – An optional behavior for request deserialization.
  • response_serializer – An optional behavior for response serialization.
Returns:

An RpcMethodHandler object that is typically used by grpc.Server.

grpc.stream_unary_rpc_method_handler(behavior, request_deserializer=None, response_serializer=None)[source]

Creates an RpcMethodHandler for a stream-unary RPC method.

Parameters:
  • behavior – The implementation of an RPC that accepts an iterator of request
  • and returns a single response value. (values) –
  • request_deserializer – An optional behavior for request deserialization.
  • response_serializer – An optional behavior for response serialization.
Returns:

An RpcMethodHandler object that is typically used by grpc.Server.

grpc.stream_stream_rpc_method_handler(behavior, request_deserializer=None, response_serializer=None)[source]

Creates an RpcMethodHandler for a stream-stream RPC method.

Parameters:
  • behavior – The implementation of an RPC that accepts an iterator of request
  • and returns an iterator of response values. (values) –
  • request_deserializer – An optional behavior for request deserialization.
  • response_serializer – An optional behavior for response serialization.
Returns:

An RpcMethodHandler object that is typically used by grpc.Server.

grpc.method_handlers_generic_handler(service, method_handlers)[source]

Creates a GenericRpcHandler from RpcMethodHandlers.

Parameters:
  • service – The name of the service that is implemented by the method_handlers.
  • method_handlers – A dictionary that maps method names to corresponding
  • RpcMethodHandler.
Returns:

A GenericRpcHandler. This is typically added to the grpc.Server object with add_generic_rpc_handlers() before starting the server.

grpc.ssl_channel_credentials(root_certificates=None, private_key=None, certificate_chain=None)[source]

Creates a ChannelCredentials for use with an SSL-enabled Channel.

Parameters:
  • root_certificates – The PEM-encoded root certificates as a byte string,
  • None to retrieve them from a default location chosen by gRPC runtime. (or) –
  • private_key – The PEM-encoded private key as a byte string, or None if no
  • key should be used. (private) –
  • certificate_chain – The PEM-encoded certificate chain as a byte string
  • use or or None if no certificate chain should be used. (to) –
Returns:

A ChannelCredentials for use with an SSL-enabled Channel.

grpc.metadata_call_credentials(metadata_plugin, name=None)[source]

Construct CallCredentials from an AuthMetadataPlugin.

Parameters:
  • metadata_plugin – An AuthMetadataPlugin to use for authentication.
  • name – An optional name for the plugin.
Returns:

A CallCredentials.

grpc.access_token_call_credentials(access_token)[source]

Construct CallCredentials from an access token.

Parameters:access_token – A string to place directly in the http request authorization header, for example “authorization: Bearer <access_token>”.
Returns:A CallCredentials.
grpc.composite_call_credentials(*call_credentials)[source]

Compose multiple CallCredentials to make a new CallCredentials.

Parameters:*call_credentials – At least two CallCredentials objects.
Returns:A CallCredentials object composed of the given CallCredentials objects.
grpc.composite_channel_credentials(channel_credentials, *call_credentials)[source]

Compose a ChannelCredentials and one or more CallCredentials objects.

Parameters:
  • channel_credentials – A ChannelCredentials object.
  • *call_credentials – One or more CallCredentials objects.
Returns:

A ChannelCredentials composed of the given ChannelCredentials and CallCredentials objects.

grpc.ssl_server_credentials(private_key_certificate_chain_pairs, root_certificates=None, require_client_auth=False)[source]

Creates a ServerCredentials for use with an SSL-enabled Server.

Parameters:
  • private_key_certificate_chain_pairs – A list of pairs of the form [PEM-encoded private key, PEM-encoded certificate chain].
  • root_certificates – An optional byte string of PEM-encoded client root certificates that the server will use to verify client authentication. If omitted, require_client_auth must also be False.
  • require_client_auth – A boolean indicating whether or not to require clients to be authenticated. May only be True if root_certificates is not None.
Returns:

A ServerCredentials for use with an SSL-enabled Server. Typically, this object is an argument to add_secure_port() method during server setup.

grpc.channel_ready_future(channel)[source]

Creates a Future that tracks when a Channel is ready.

Cancelling the Future does not affect the channel’s state machine. It merely decouples the Future from channel state machine.

Parameters:channel – A Channel object.
Returns:A Future object that matures when the channel connectivity is ChannelConnectivity.READY.
grpc.insecure_channel(target, options=None)[source]

Creates an insecure Channel to a server.

Parameters:
  • target – The server address
  • options – An optional list of key-value pairs (channel args in gRPC runtime)
  • configure the channel. (to) –
Returns:

A Channel object.

grpc.secure_channel(target, credentials, options=None)[source]

Creates a secure Channel to a server.

Parameters:
  • target – The server address.
  • credentials – A ChannelCredentials instance.
  • options – An optional list of key-value pairs (channel args in gRPC runtime)
  • configure the channel. (to) –
Returns:

A Channel object.

grpc.server(thread_pool, handlers=None, options=None, maximum_concurrent_rpcs=None)[source]

Creates a Server with which RPCs can be serviced.

Parameters:
  • thread_pool – A futures.ThreadPoolExecutor to be used by the Server to execute RPC handlers.
  • handlers – An optional list of GenericRpcHandlers used for executing RPCs. More handlers may be added by calling add_generic_rpc_handlers any time before the server is started.
  • options – An optional list of key-value pairs (channel args in gRPC runtime)
  • configure the channel. (to) –
  • maximum_concurrent_rpcs – The maximum number of concurrent RPCs this server will service before returning RESOURCE_EXHAUSTED status, or None to indicate no limit.
Returns:

A Server object.

Glossary

metadatum
A key-value pair included in the HTTP header. It is a 2-tuple where the first entry is the key and the second is the value, i.e. (key, value). The metadata key is an ASCII str, and must be a valid HTTP header name. The metadata value can be either a valid HTTP ASCII str, or bytes. If bytes are provided, the key must end with ‘-bin’, i.e. ('binary-metadata-bin', b'\x00\xFF')
metadata
A sequence of metadatum.