grpc.beta package¶

Submodules¶

grpc.beta.implementations module¶

Entry points into the Beta API of gRPC Python.

class grpc.beta.implementations.CallCredentials(low_credentials)[source]¶

Bases: object

A value encapsulating data asserting an identity over an established channel. May be composed with ChannelCredentials to always assert identity for every call over that channel.

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

class grpc.beta.implementations.Channel(low_channel, intermediary_low_channel)[source]¶

Bases: object

A channel to a remote host through which RPCs may be conducted.

Only the “subscribe” and “unsubscribe” methods are supported for application use. This class’ instance constructor and all other attributes are unsupported.

subscribe(callback, try_to_connect=None)[source]¶

Subscribes to this Channel’s connectivity.

Parameters:

callback – A callable to be invoked and passed an interfaces.ChannelConnectivity identifying this Channel’s connectivity. The callable will be invoked immediately upon subscription and again for every change to this Channel’s connectivity thereafter until it is unsubscribed. try_to_connect – A boolean indicating whether or not this Channel should attempt to connect if it is not already connected and ready to conduct RPCs.

unsubscribe(callback)[source]¶

Unsubscribes a 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.beta.implementations.ChannelCredentials(low_credentials)[source]¶

Bases: object

A value encapsulating the data required to create a secure Channel.

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

class grpc.beta.implementations.ServerCredentials(low_credentials)[source]¶

Bases: object

A value encapsulating the data required to open a secure port on a Server.

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

class grpc.beta.implementations.ServerOptions(multi_method_implementation, request_deserializers, response_serializers, thread_pool, thread_pool_size, default_timeout, maximum_timeout)[source]¶

Bases: object

A value encapsulating the various options for creation of a Server.

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

class grpc.beta.implementations.StubOptions(host, request_serializers, response_deserializers, metadata_transformer, thread_pool, thread_pool_size)[source]¶

Bases: object

A value encapsulating the various options for creation of a Stub.

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

grpc.beta.implementations.composite_call_credentials(call_credentials, additional_call_credentials)[source]¶

Compose two CallCredentials to make a new one.

Parameters:	call_credentials – A CallCredentials object. additional_call_credentials – Another CallCredentials object to compose on top of call_credentials.
Returns:	A CallCredentials object for use in a GRPCCallOptions object.

grpc.beta.implementations.composite_channel_credentials(channel_credentials, additional_call_credentials)[source]¶

Compose ChannelCredentials on top of client credentials to make a new one.

Parameters:	channel_credentials – A ChannelCredentials object. additional_call_credentials – A CallCredentials object to compose on top of channel_credentials.
Returns:	A ChannelCredentials object for use in a GRPCCallOptions object.

grpc.beta.implementations.dynamic_stub(channel, service, cardinalities, options=None)[source]¶

Creates a face.DynamicStub with which RPCs can be invoked.

Parameters:	channel – A Channel for the returned face.DynamicStub to use. service – The package-qualified full name of the service. cardinalities – A dictionary from RPC method name to cardinality.Cardinality value identifying the cardinality of the RPC method. options – An optional StubOptions value further customizing the functionality of the returned face.DynamicStub.
Returns:	A face.DynamicStub with which RPCs can be invoked.

grpc.beta.implementations.generic_stub(channel, options=None)[source]¶

Creates a face.GenericStub on which RPCs can be made.

Parameters:	channel – A Channel for use by the created stub. options – A StubOptions customizing the created stub.
Returns:	A face.GenericStub on which RPCs can be made.

grpc.beta.implementations.insecure_channel(host, port)[source]¶

Creates an insecure Channel to a remote host.

Parameters:	host – The name of the remote host to which to connect. port – The port of the remote host to which to connect.
Returns:	A Channel to the remote host through which RPCs may be conducted.

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

Construct CallCredentials from an interfaces.GRPCAuthMetadataPlugin.

Parameters:	metadata_plugin – An interfaces.GRPCAuthMetadataPlugin to use in constructing the CallCredentials object.
Returns:	A CallCredentials object for use in a GRPCCallOptions object.

grpc.beta.implementations.secure_channel(host, port, channel_credentials)[source]¶

Creates a secure Channel to a remote host.

Parameters:	host – The name of the remote host to which to connect. port – The port of the remote host to which to connect. channel_credentials – A ChannelCredentials.
Returns:	A secure Channel to the remote host through which RPCs may be conducted.

grpc.beta.implementations.server(service_implementations, options=None)[source]¶

Creates an interfaces.Server with which RPCs can be serviced.

Parameters:	service_implementations – A dictionary from service name-method name pair to face.MethodImplementation. options – An optional ServerOptions value further customizing the functionality of the returned Server.
Returns:	An interfaces.Server with which RPCs can be serviced.

grpc.beta.implementations.server_options(multi_method_implementation=None, request_deserializers=None, response_serializers=None, thread_pool=None, thread_pool_size=None, default_timeout=None, maximum_timeout=None)[source]¶

Creates a ServerOptions value to be passed at server creation.

All parameters are optional and should always be passed by keyword.

Parameters:

multi_method_implementation – A face.MultiMethodImplementation to be called to service an RPC if the server has no specific method implementation for the name of the RPC for which service was requested. request_deserializers – A dictionary from service name-method name pair to request deserialization behavior. response_serializers – A dictionary from service name-method name pair to response serialization behavior. thread_pool – A thread pool to use in stubs. thread_pool_size – The size of thread pool to create for use in stubs; ignored if thread_pool has been passed. default_timeout – A duration in seconds to allow for RPC service when servicing RPCs that did not include a timeout value when invoked. maximum_timeout – A duration in seconds to allow for RPC service when servicing RPCs no matter what timeout value was passed when the RPC was invoked.

Returns:

A StubOptions value created from the passed parameters.

grpc.beta.implementations.ssl_channel_credentials(root_certificates, private_key, certificate_chain)[source]¶

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

Parameters:	root_certificates – The PEM-encoded root certificates or None to ask for them to be retrieved from a default location. private_key – The PEM-encoded private key to use or None if no private key should be used. certificate_chain – The PEM-encoded certificate chain to use or None if no certificate chain should be used.
Returns:	A ChannelCredentials for use with an SSL-enabled Channel.

grpc.beta.implementations.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 nonempty sequence each element of which is a pair the first element of which is a PEM-encoded private key and the second element of which is the corresponding PEM-encoded certificate chain. root_certificates – PEM-encoded client root certificates to be used for verifying authenticated clients. If omitted, require_client_auth must also be omitted or 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.

grpc.beta.implementations.stub_options(host=None, request_serializers=None, response_deserializers=None, metadata_transformer=None, thread_pool=None, thread_pool_size=None)[source]¶

Creates a StubOptions value to be passed at stub creation.

All parameters are optional and should always be passed by keyword.

Parameters:

host – A host string to set on RPC calls. request_serializers – A dictionary from service name-method name pair to request serialization behavior. response_deserializers – A dictionary from service name-method name pair to response deserialization behavior. metadata_transformer – A callable that given a metadata object produces another metadata object to be used in the underlying communication on the wire. thread_pool – A thread pool to use in stubs. thread_pool_size – The size of thread pool to create for use in stubs; ignored if thread_pool has been passed.

Returns:

A StubOptions value created from the passed parameters.

grpc.beta.interfaces module¶

Constants and interfaces of the Beta API of gRPC Python.

class grpc.beta.interfaces.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.

FATAL_FAILURE¶

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

CONNECTING = <ChannelConnectivity.CONNECTING: (<ConnectivityState.CONNECTING: 1>, 'connecting')>

FATAL_FAILURE = <ChannelConnectivity.FATAL_FAILURE: (<ConnectivityState.FATAL_FAILURE: 4>, 'fatal failure')>

IDLE = <ChannelConnectivity.IDLE: (<ConnectivityState.IDLE: 0>, 'idle')>

READY = <ChannelConnectivity.READY: (<ConnectivityState.READY: 2>, 'ready')>

TRANSIENT_FAILURE = <ChannelConnectivity.TRANSIENT_FAILURE: (<ConnectivityState.TRANSIENT_FAILURE: 3>, 'transient failure')>

class grpc.beta.interfaces.GRPCAuthMetadataContext[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.beta.interfaces.GRPCAuthMetadataPlugin[source]¶

Bases: object

class grpc.beta.interfaces.GRPCAuthMetadataPluginCallback[source]¶

Bases: object

Callback object received by a metadata plugin.

class grpc.beta.interfaces.GRPCCallOptions(disable_compression, subcall_of, credentials)[source]¶

Bases: object

A value encapsulating gRPC-specific options passed on RPC invocation.

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

class grpc.beta.interfaces.GRPCInvocationContext[source]¶

Bases: object

Exposes gRPC-specific options and behaviors to code invoking RPCs.

disable_next_request_compression()[source]¶

Disables compression of the next request passed by the application.

class grpc.beta.interfaces.GRPCServicerContext[source]¶

Bases: object

Exposes gRPC-specific options and behaviors to code servicing RPCs.

disable_next_response_compression()[source]¶

Disables compression of the next response passed by the application.

peer()[source]¶

Identifies the peer that invoked the RPC being serviced.

Returns:	A string identifying the peer that invoked the RPC being serviced.

class grpc.beta.interfaces.Server[source]¶

Bases: object

Services RPCs.

add_insecure_port(address)[source]¶

Reserves a port for insecure RPC service once this Server becomes active.

This method may only be called before calling this Server’s start method is called.

Parameters:	address – The address for which to open a port.
Returns:	An integer port on which RPCs will be serviced after this link has been started. This is typically the same number as the port number contained in the passed address, but will likely be different if the port number contained in the passed address was zero.

add_secure_port(address, server_credentials)[source]¶

Reserves a port for secure RPC service after this Server becomes active.

This method may only be called before calling this Server’s start method is called.

Parameters:	address – The address for which to open a port. server_credentials – A ServerCredentials.
Returns:	An integer port on which RPCs will be serviced after this link has been started. This is typically the same number as the port number contained in the passed address, but will likely be different if the port number contained in the passed address was zero.

start()[source]¶

Starts this Server’s service of RPCs.

This method may only be called while the server is not serving RPCs (i.e. it is not idempotent).

stop(grace)[source]¶

Stops this Server’s service of RPCs.

All calls to this method immediately stop service of new RPCs. When existing RPCs are aborted is controlled by the grace period parameter passed to this method.

This method may be called at any time and is idempotent. Passing a smaller grace value than has been passed in a previous call will have the effect of stopping the Server sooner. Passing a larger grace value than has been passed in a previous call will not have the effect of stopping the sooner later.

Parameters:	grace – A duration of time in seconds to allow existing RPCs to complete before being aborted by this Server’s stopping. May be zero for immediate abortion of all in-progress RPCs.
Returns:	A threading.Event that will be set when this Server has completely stopped. The returned event may not be set until after the full grace period (if some ongoing RPC continues for the full length of the period) of it may be set much sooner (such as if this Server had no RPCs underway at the time it was stopped or if all RPCs that it had underway completed very early in the grace period).

class grpc.beta.interfaces.StatusCode[source]¶

Bases: enum.Enum

Mirrors grpc_status_code in the C core.

ABORTED = <StatusCode.ABORTED: 10>¶

ALREADY_EXISTS = <StatusCode.ALREADY_EXISTS: 6>¶

CANCELLED = <StatusCode.CANCELLED: 1>¶

DATA_LOSS = <StatusCode.DATA_LOSS: 15>¶

DEADLINE_EXCEEDED = <StatusCode.DEADLINE_EXCEEDED: 4>¶

FAILED_PRECONDITION = <StatusCode.FAILED_PRECONDITION: 9>¶

INTERNAL = <StatusCode.INTERNAL: 13>¶

INVALID_ARGUMENT = <StatusCode.INVALID_ARGUMENT: 3>¶

NOT_FOUND = <StatusCode.NOT_FOUND: 5>¶

OK = <StatusCode.OK: 0>¶

OUT_OF_RANGE = <StatusCode.OUT_OF_RANGE: 11>¶

PERMISSION_DENIED = <StatusCode.PERMISSION_DENIED: 7>¶

RESOURCE_EXHAUSTED = <StatusCode.RESOURCE_EXHAUSTED: 8>¶

UNAUTHENTICATED = <StatusCode.UNAUTHENTICATED: 16>¶

UNAVAILABLE = <StatusCode.UNAVAILABLE: 14>¶

UNIMPLEMENTED = <StatusCode.UNIMPLEMENTED: 12>¶

UNKNOWN = <StatusCode.UNKNOWN: 2>¶

grpc.beta.interfaces.grpc_call_options(disable_compression=False, credentials=None)[source]¶

Creates a GRPCCallOptions value to be passed at RPC invocation.

All parameters are optional and should always be passed by keyword.

Parameters:	disable_compression – A boolean indicating whether or not compression should be disabled for the request object of the RPC. Only valid for request-unary RPCs. credentials – A CallCredentials object to use for the invoked RPC.

grpc.beta.utilities module¶

Utilities for the gRPC Python Beta API.

grpc.beta.utilities.channel_ready_future(channel)[source]¶

Creates a future.Future tracking when an implementations.Channel is ready.

Cancelling the returned future.Future does not tell the given implementations.Channel to abandon attempts it may have been making to connect; cancelling merely deactivates the return future.Future’s subscription to the given implementations.Channel’s connectivity.

Parameters:	channel – An implementations.Channel.
Returns:	A future.Future that matures when the given Channel has connectivity interfaces.ChannelConnectivity.READY.

Module contents¶