grpcserver — SR OS gRPC server
Note
This module is available when executing on SR OS only. On a remote machine, the gRPC server and it’s functionality are not supported.
The grpcserver module allows a Python 3 application to act as a handler for gRPC calls providing
functionality to handle gRPC calls within a Python application running on SR OS and issue responses through
the SR OS gRPC server.
Note
In order to use this module, the Python application must be configured as a python-script within
the SR OS configuration and referenced from the gRPC server configuration.
To use this library to handle gRPC packages, services and RPCs the workflow is:
Define a handler function for each RPC in the gRPC package/service proto file. This function will perform the activities that should happen when the RPC is called
Add the handler function to the gRPC server library. This is the glue between the package/service/RPC and the Python application code
Use the
handle_rpc()function to ready the Python interpreter and gRPC server to handle the RPC
Classes
- class grpcserver.Context
gRPC context object passed to each handler function.
- rpc
Name of the RPC called, including the gRPC package and service.
- abort(code, details=None)
Sets the status code and details message to be returned to the gRPC client.
- Parameters:
code (int) – Status code to set (defined in
StatusCode)details (str, optional) – Message provided. This is derived from the code when omitted
- Raises:
AbortError – Terminate the handler function
- class grpcserver.StatusCode
Available gRPC status codes.
- OK = 0
- CANCELLED = 1
- UNKNOWN = 2
- INVALID_ARGUMENT = 3
- DEADLINE_EXCEEDED = 4
- NOT_FOUND = 5
- ALREADY_EXISTS = 6
- PERMISSION_DENIED = 7
- RESOURCE_EXHAUSTED = 8
- FAILED_PRECONDITION = 9
- ABORTED = 10
- OUT_OF_RANGE = 11
- UNIMPLEMENTED = 12
- INTERNAL = 13
- UNAVAILABLE = 14
- DATA_LOSS = 15
- UNAUTHENTICATED = 16
Functions
- grpcserver.add_handler(service, rpc, handler, *, package=None)
Adds a handler function for the specified Package/Service/RPC.
- Parameters:
package (str, optional) – gRPC package name
service (str) – gRPC service name
rpc (str) – RPC name
handler – Handler function name
- grpcserver.handle_rpc()
Handle any incoming configured Packages/Services/RPCs.
The response(s) generated by the handler function will be sent to the gRPC client. This function does not return any data. It will either complete successfully or raise an exception.
Note
This function should only be called once all handlers have been added using the
add_handler()function.- Raises:
RpcError – When an error occurs during handling of the RPC
NotImplementedError – When no handler is found for the current RPC
Exceptions
If a handler function returns a response that does not conform to the expected message format, an error will occur when the library
attempts to serialize and send the response to the gRPC client. In this case, a ValueError or TypeError will be raised.
When an exception occurs in the handler function, the library will catch this exception and send an error reponse to the gRPC client with the StatusCode INTERNAL.
The exception is than allowed to propagate and can either be caught by the script or will result in termination of the script.
- exception grpcserver.RpcError(Exception)
Exception raised when an error occurs during the handling of an RPC. For example, the connection closed while reading a request or sending a response.