# grpc-helper
<!-- NMK-BADGES-BEGIN -->
[](https://github.com/dynod/grpc-helper/blob/main/LICENSE)
[](https://github.com/dynod/grpc-helper/actions?query=branch%3Amain)
[](https://github.com/dynod/grpc-helper/issues?q=is%3Aopen+is%3Aissue)
[](https://www.python.org/)
[](https://pypi.org/project/grpc-helper/)
[](https://github.com/psf/black)
[](https://flake8.pycqa.org/)
[](https://app.codecov.io/gh/dynod/grpc-helper)
[](https://protobuf.dev/)
<!-- NMK-BADGES-END -->
Miscellaneous GRPC helpers (API versioning, retry, config, etc...)
## Python API
Provided classes in this module API help to deal with RPC servers/clients handling.
---
### RPC Server
The **`RpcServer`** class handles the lifecycle of a GRPC server. To initialize, it basically needs:
* a port on which to server RPC requests
* a list of **`RpcServiceDescriptor`** objects
* an optional **`Folders`** instance (usually provided by the **`RpcCliParser`** CLI parsing)
* an optional dict of string:string, providing config items defaults initialized from CLI (usually provided by the **`RpcCliParser`** CLI parsing)
* an optional list of **`Config`** or **`ConfigHolder`** instances, which will be this server's *static* config items
* an optional list of **`Config`** or **`ConfigHolder`** instances, which will be this server's *user* config items
* a boolean flag stating if the events service has to be started in this server instance (default: **`False`**)
* a boolean flag stating if the debug signal has to be listened (see below; default: **`True`**)
The **`Folders`** class handle the different folders used by the server:
* a *system* folder, used to store config shared by multiple users and applications. This folder doesn't need to be writable by the server running user.
* a *user* folder, used to store config shared by multiple applications for the server running user.
* a *workspace* folder, used to store config and other persistent information by the current server.
The **`RpcServiceDescriptor`** class describes a given service to be hooked in a server instance. Its attributes are:
* a Python module (from which name and version will be used for the RpcServerService items registration)
* a service name (used for service identification in RpcServerService items, and for auto-client setup)
* a version enum:
* lowest value in the enum will be considered to be the minimum supported version for this service API
* highest value in the enum will be considered to be the current version for this service API
* a manager instance, to which all RPC calls will be delegated. When registering a proxied service, this has to be a simple instance of the generated servicer.
* the GRPC generated hooking method for this service
* the GRPC generated client stub class
* a boolean stating if this service is a proxied service or not
The manager class must:
* inherit from the GRPC generated servicer class, in order to use the default implementation if any of the service method is not implemented by this manager
* for each implemented service method:
* declare a single input parameter, which will be the input request
* declare the return type
A manager class can also inherit from **`RpcManager`** class, which provides some usefull features:
* a **`_load`** method, called by the server once all services are alive (typically to perform some internal initializations)
* a **`_shutdown`** method, called by the server once it is shutdown (typically to perform some internal finalization operations + interrupt long-running ones)
* a **`logger`** instance, to be used for all logging inside this manager and dependencies
* a **`lock`** instance, to be used to protect manager inner fields against reentrance
* a **`client`** instance, initialized to the server own auto-client (see below)
* a **`folders`** instance, initialized to the server **`Folders`** (see above)
#### Lifecycle
The RPC server will live its life in its own thread. When the application is about to terminate, it is advised to call the **`shutdown`** method
in order to turn off the RPC server properly. This method can also be called remotely as a **RpcServerService** servive method.
When the shutdown method is called:
* the server will stop accepting new requests
* it will notify all managers through their own **`_shutdown`** method
* then it will wait for pending operations to terminate (within the **`rpc-shutdown-grace`** configured timeout)method.
* if called through RPC, if will wait for the required timeout (using by default the **`rpc-shutdown-timeout`** value), if this one is >0
* then the shutdown will be finalized (all non-daemon threads terminated)
Note that the code which created the server instance may use the **`wait_shutdown`** method to block until the RPC server is shutdown.
#### Default services
Note that the RPC server instance will automatically serve:
* the [server handling service](https://github.com/dynod/grpc-helper-api/blob/main/doc/server.md),
for basic RPC server operations handling.
* the [config service](https://github.com/dynod/grpc-helper-api/blob/main/doc/config.md),
allowing to remotely get/update/reset user configuration items.
* the [logger service](https://github.com/dynod/grpc-helper-api/blob/main/doc/logger.md),
allowing to remotely get/update/reset loggers configuration.
#### API version checks
For requests received from the **`RpcClient`** implementation on a given service, the client api version is checked against the server "supported - current"
range for this service:
* if the client version is older than the server supported version, the request will raise a **`ResultCode.ERROR_API_CLIENT_TOO_OLD`** error
* if the client version is newer than the server current version, the request will raise a **`ResultCode.ERROR_API_SERVER_TOO_OLD`** error
#### Debug
The RPC server will hook to the USR2 signal for debug purpose (if required). When receiving this signal, following debug information will be dumped in a file
name **RpcServerDump-YYYYMMDDhhmmss.txt** (with dump timestamp) in the logging folder (see below):
* all the live threads call stacks
* all the pending RPC requests
#### Auto-client
An initialized RPC server instance provides an **`auto_client`** attribute, providing an **`RpcClient`** instance pointing on everything
served by this server. Note that the timeout for this client can be configured through the **`rpc-client-timeout`** config item.
#### Proxied services
Services declared as proxied ones (see **`RpcServiceDescriptor`** above) will be forwarded to the required server/port as soon as this server calls the
**`proxy_register`** method of the proxying server. Note that if this method is not called within the **`rpc-client-timeout`** time, the method call will
end with an **`ERROR_PROXY_UNREGISTERED`** error.
Configuration of proxied services is persisted in the workspace, in order to restore them when the proxying server restarts.
An **`RpcProxiedManager`** abstract class is available for managers who are designed to be proxied. Such managers will automatically register in main proxy
server, with following details:
* registered services names list has to be returned by **`_proxied_services`** method
* registered services version string has to be returned by **`_proxied_version`** method
* extra stubs available in the **`self.proxy_client`** attribute can be provided by **`_proxy_stubs`** method
* if current host IP needs excpilicitely to be used for registration, **`_proxy_use_current_host`** method needs to return **`True`**
When handling proxy servers, if the proxying server is started with events service enabled, it will send:
* an **`RPC_PROXY_REGISTER`** event on each **`proxy_register`** method successful call
* an **`RPC_PROXY_FORGET`** event on each **`proxy_forget`** method successful call
Properties of the events will be inherited from the method input message.
#### Rolling logs
Each manager of the RPC server through its **`logger`** attribute, will have his logs persisted in a **\<name\>/\<name\>.log** rolling file (relative to the
logging folder). The complete logs will also be persisted in the **root** folder.
Both logging folder and rollover cadency can be configured -- see **Configuration** chapter below.
#### Configuration
The RPC server behavior can be configured through the following static configuration items:
Name | Description | Type | Default
---- | ----------- | ---- | -------
**rpc-max-workers** | Maximum parallel RPC worker threads | Positive integer | **`30`**
**rpc-shutdown-grace** | Grace period for pending calls to be terminated on shutdown (seconds) | Positive float | **`30`**
**rpc-shutdown-timeout** | Final timeout before real shutdown (i.e. end of process; seconds) | Positive float | **`60`**
**rpc-logs-folder** | Folder (absolute or workspace-relative) where to store rolling logs | String | **`"logs"`**
**rpc-logs-backup** | Backup log files to be persisted for each manager on rollover | Integer | **`10`**
**rpc-logs-interval-unit** | Logs rollover interval unit (see [TimedRotatingFileHandler documentation](https://docs.python.org/3/library/logging.handlers.html#logging.handlers.TimedRotatingFileHandler)) | Custom (see [doc](https://docs.python.org/3/library/logging.handlers.html#logging.handlers.TimedRotatingFileHandler)) | **`H`**
**rpc-logs-interval** | Logs rollover interval (see [TimedRotatingFileHandler documentation](https://docs.python.org/3/library/logging.handlers.html#logging.handlers.TimedRotatingFileHandler)) | Positive integer | **`1`**
**rpc-main-host** | Main RPC server host (to be used by proxied services) | String | **`"localhost"`**
**rpc-main-port** | Main RPC server port (to be used by proxied services) | Positive integer | **`54321`**
**rpc-client-timeout** | Timeout for RPC client when server is unreachable or proxy not registered yet (seconds) | Positive float | **`60`**
**rpc-event-retain-timeout** | Retain timeout for event queues on interruption (seconds) | Positive integer | **`300`**
**rpc-event-keepalive-timeout** | Timeout for sending keep alive empty events (seconds) | Positive integer | **`60`**
#### Usage example
```python
import my_package
from my_package.api import MyStatus, MyConfig, MyApiVersion
from my_package.api.my_pb2_grpc import add_MyServiceServicer_to_server, MyServiceServicer, MyServiceStub
from grpc_helper import RpcServer, RpcServiceDescriptor, RpcManager
class MySampleManager(MyServiceServicer, RpcManager):
# Custom implementation for sample service
def update(self, request: MyConfig) -> MyStatus:
# Note that return message *MUST* be explicitely annoted for each implemented method!
return MyStatus()
def start():
# Create an RPC server on port 12345
srv = RpcServer(12345, [RpcServiceDescriptor(my_package, "my", MyApiVersion, MySampleManager(), add_MyServiceServicer_to_server, MyServiceStub)])
# Server is running in its own thread; we need to wait it for shutdown (on Ctrl-C or remote shutdown call)
srv.wait_shutdown()
```
---
### RPC Client
The **`RpcClient`** class provides an access to client side of a GRPC service. To initialize, it basically needs:
* a host name or IP address for the RPC server to connect to
* a port for the RPC server
* a map of service stubs to access:
* keys are used to define fields names on the generated client object, holding the client stubs
* values are tuple providing:
* the GRPC generated stub name
* the client current API version (coming from the version enum)
Optional inputs can also be provided:
* a timeout if RPC server is unreachable (default: **60s**)
* a name allowing to identify the client on the server side
* a boolean flag stating if the client shall raise exceptions when receiving non-OK **`ResultCode`** status (default: **true**)
* an exception type to be raised (instead of **`RpcException`**) when receiving non-OK **`ResultCode`** status
Once created, a client instance provide as many stubs as configured in the service map. Each of this stubs expose the generated methods of the
corresponding service. These methods take the following arguments:
* the method input request message (see corresponding proto file)
* a timeout parameter (in seconds) for this particular request. If set to None (default), there is no timeout
#### Usage example
```python
from my_package.api import MyStatus, MyApiVersion, Empty
from my_package.api.my_pb2_grpc import MyServiceStub
from grpc_helper import RpcClient
def start():
# Get a client access to my service
c = RpcClient("127.0.0.1", 12345, {"my": (MyServiceStub, MyApiVersion.MY_API_CURRENT)}, name="myclient")
# Use API
s: MyStatus = c.my.list(Empty())
```
---
### Configuration items
Instances of the **`Config`** class can be provided to initialize list of static and user configuration items known to a RPC server:
* *static* items are immutable, and are only initialized once when the RPC server instance is created
* *user* items can be modified remotely through the [config service](https://github.com/dynod/grpc-helper-api/blob/main/doc/config.md)
The **`Config`** constructor arguments are the same than the public API **`ConfigItem`** ones (see [config service](https://github.com/dynod/grpc-helper-api/blob/main/doc/config.md)).
It also supports an additional **`custom_validator`** one, allowing to provide a validation method when **`validator`** argument is set to **`CONFIG_VALID_CUSTOM`**.
This method takes two arguments:
* a **`name`** string: may be useful to raise meaningful validation errors
* a **`value`** string: value to be validated. The method shall raise an **`RpcException`** if the value is invalid.
#### Default value
Configuration items default value are loaded in the following order:
1. hard-coded value (the one provided in the item constructor)
2. system folder **config.json** file value (if system folder is configured)
3. user folder **config.json** file value (if user folder is configured)
4. environment provided value. Environment variable name for a given item is obtained by capitalizing it and replacing hyphens ("-") by underscores ("_").
E.g. the environment variable name for a **my-own-setting** config item will be **MY_OWN_SETTING**.
5. **-c / --config** command-line option provided value
Note that if the default value fails to be validated with a given item validator (or if it is empty while not allowed), the server will refuse to launch with a
thrown relevant exception.
#### Current value
Static items current value will be initialized with the default value. User items are initialized to either the default value, or to the user configured value
(thanks to the [config service](https://github.com/dynod/grpc-helper-api/blob/main/doc/config.md)) if it was ever modified. User modified values are
persisted in the workspace folder **config.json** file.
Current value may be programmatically accessed through one of the following property accessors:
* **`item.str_val`**: raw string value
* **`item.int_val`**: value converted as an integer
#### Config holders
Configuration items may be defined as attributes of a class inheriting from the **`ConfigHolder`** one. Such classes can be provided directly to **`RpcServer`**
constructor to initialize configuration items (which is more convenient that referencing items one by one).
---
### Command-line options
A ready-to-use CLI parser is provided through the **`RpcCliParser`** class, allowing to rapidly instantiate an RPC server from CLI options.
Constructor arguments are:
* a **`description`** string, which will be displayed when using the **-h / --help** option
* an optional **`version`** string, which will be displayed when using the **-V / --version** option
#### Options
The options defined by this parser are:
Name | Description
---- | -----------
**--help** | displays the program help and exit
**-V / --version** | displays the program version and exit
**--system PATH** | overrides the default system folder
**--user PATH** | overrides the default user folder
**-w / --workspace PATH** | defines the workspace folder
**-p / --port PORT** | overrides the RPC server default listening port
**-c / --config NAME=VALUE** | overrides the default value of a given configuration item
After parsing:
* the system/user/workspace folders are used to initialize a **`Folders`** object (see above), available in the **`folders`** argument of the namespace.
* the configuration items default values are gathered in a dict, available in the **`config`** argument of the namespace.
#### Usage
The following methods are available to tune the parser behavior:
* **`with_rpc_args`**: adds the options listed above, and returns the **`RpcCliParser`** instance (for fluent API usage). Arguments are:
* **`default_port`**: default RPC listening port
* **`default_sys`**: default system folder
* **`default_usr`**: default user folder
* **`default_wks`**: default workspace folder
* **`parse`**: will parse input arguments, and return the namespace. Arguments are program command-line ones by default, or may be provided as a string list
(e.g. for testing purpose)
Following example shows how to use this parser to create an **`RpcServer`** instance:
```python
from grpc_helper import RpcCliParser, RpcServer
def start():
# Parse arguments to create RPC server instance
args = RpcCliParser("My custom RPC server", "1.0.0").with_rpc_args(12345, "/etc/my_srv", "~/.local/my_srv", "my_srv_wks").parse()
srv = RpcServer(args.port, [], args.folders, args.config)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/dynod/grpc-helper",
"name": "grpc-helper",
"maintainer": "The dynod project",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "The dynod project",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/0c/03/4c773884ea2f6b8c27dcb480b5254531be0788343235d25c9ef197ddc7a1/grpc-helper-2.3.1.tar.gz",
"platform": null,
"description": "# grpc-helper\n\n<!-- NMK-BADGES-BEGIN -->\n[](https://github.com/dynod/grpc-helper/blob/main/LICENSE)\n[](https://github.com/dynod/grpc-helper/actions?query=branch%3Amain)\n[](https://github.com/dynod/grpc-helper/issues?q=is%3Aopen+is%3Aissue)\n[](https://www.python.org/)\n[](https://pypi.org/project/grpc-helper/)\n[](https://github.com/psf/black)\n[](https://flake8.pycqa.org/)\n[](https://app.codecov.io/gh/dynod/grpc-helper)\n[](https://protobuf.dev/)\n<!-- NMK-BADGES-END -->\n\nMiscellaneous GRPC helpers (API versioning, retry, config, etc...)\n\n## Python API\n\nProvided classes in this module API help to deal with RPC servers/clients handling.\n\n---\n### RPC Server\n\nThe **`RpcServer`** class handles the lifecycle of a GRPC server. To initialize, it basically needs:\n* a port on which to server RPC requests\n* a list of **`RpcServiceDescriptor`** objects\n* an optional **`Folders`** instance (usually provided by the **`RpcCliParser`** CLI parsing)\n* an optional dict of string:string, providing config items defaults initialized from CLI (usually provided by the **`RpcCliParser`** CLI parsing)\n* an optional list of **`Config`** or **`ConfigHolder`** instances, which will be this server's *static* config items\n* an optional list of **`Config`** or **`ConfigHolder`** instances, which will be this server's *user* config items\n* a boolean flag stating if the events service has to be started in this server instance (default: **`False`**)\n* a boolean flag stating if the debug signal has to be listened (see below; default: **`True`**)\n\nThe **`Folders`** class handle the different folders used by the server:\n* a *system* folder, used to store config shared by multiple users and applications. This folder doesn't need to be writable by the server running user.\n* a *user* folder, used to store config shared by multiple applications for the server running user.\n* a *workspace* folder, used to store config and other persistent information by the current server.\n\nThe **`RpcServiceDescriptor`** class describes a given service to be hooked in a server instance. Its attributes are:\n* a Python module (from which name and version will be used for the RpcServerService items registration)\n* a service name (used for service identification in RpcServerService items, and for auto-client setup)\n* a version enum:\n * lowest value in the enum will be considered to be the minimum supported version for this service API\n * highest value in the enum will be considered to be the current version for this service API\n* a manager instance, to which all RPC calls will be delegated. When registering a proxied service, this has to be a simple instance of the generated servicer.\n* the GRPC generated hooking method for this service\n* the GRPC generated client stub class\n* a boolean stating if this service is a proxied service or not\n\n\nThe manager class must:\n* inherit from the GRPC generated servicer class, in order to use the default implementation if any of the service method is not implemented by this manager\n* for each implemented service method:\n * declare a single input parameter, which will be the input request\n * declare the return type\n\nA manager class can also inherit from **`RpcManager`** class, which provides some usefull features:\n* a **`_load`** method, called by the server once all services are alive (typically to perform some internal initializations)\n* a **`_shutdown`** method, called by the server once it is shutdown (typically to perform some internal finalization operations + interrupt long-running ones)\n* a **`logger`** instance, to be used for all logging inside this manager and dependencies\n* a **`lock`** instance, to be used to protect manager inner fields against reentrance\n* a **`client`** instance, initialized to the server own auto-client (see below)\n* a **`folders`** instance, initialized to the server **`Folders`** (see above)\n\n#### Lifecycle\n\nThe RPC server will live its life in its own thread. When the application is about to terminate, it is advised to call the **`shutdown`** method\nin order to turn off the RPC server properly. This method can also be called remotely as a **RpcServerService** servive method.\n\nWhen the shutdown method is called:\n* the server will stop accepting new requests\n* it will notify all managers through their own **`_shutdown`** method\n* then it will wait for pending operations to terminate (within the **`rpc-shutdown-grace`** configured timeout)method.\n* if called through RPC, if will wait for the required timeout (using by default the **`rpc-shutdown-timeout`** value), if this one is >0\n* then the shutdown will be finalized (all non-daemon threads terminated)\n\nNote that the code which created the server instance may use the **`wait_shutdown`** method to block until the RPC server is shutdown.\n\n#### Default services\n\nNote that the RPC server instance will automatically serve:\n* the [server handling service](https://github.com/dynod/grpc-helper-api/blob/main/doc/server.md),\nfor basic RPC server operations handling.\n* the [config service](https://github.com/dynod/grpc-helper-api/blob/main/doc/config.md),\nallowing to remotely get/update/reset user configuration items.\n* the [logger service](https://github.com/dynod/grpc-helper-api/blob/main/doc/logger.md),\nallowing to remotely get/update/reset loggers configuration.\n\n#### API version checks\n\nFor requests received from the **`RpcClient`** implementation on a given service, the client api version is checked against the server \"supported - current\" \nrange for this service:\n* if the client version is older than the server supported version, the request will raise a **`ResultCode.ERROR_API_CLIENT_TOO_OLD`** error\n* if the client version is newer than the server current version, the request will raise a **`ResultCode.ERROR_API_SERVER_TOO_OLD`** error\n\n#### Debug\n\nThe RPC server will hook to the USR2 signal for debug purpose (if required). When receiving this signal, following debug information will be dumped in a file\nname **RpcServerDump-YYYYMMDDhhmmss.txt** (with dump timestamp) in the logging folder (see below):\n* all the live threads call stacks\n* all the pending RPC requests\n\n#### Auto-client\n\nAn initialized RPC server instance provides an **`auto_client`** attribute, providing an **`RpcClient`** instance pointing on everything\nserved by this server. Note that the timeout for this client can be configured through the **`rpc-client-timeout`** config item.\n\n#### Proxied services\n\nServices declared as proxied ones (see **`RpcServiceDescriptor`** above) will be forwarded to the required server/port as soon as this server calls the \n**`proxy_register`** method of the proxying server. Note that if this method is not called within the **`rpc-client-timeout`** time, the method call will\nend with an **`ERROR_PROXY_UNREGISTERED`** error.\n\nConfiguration of proxied services is persisted in the workspace, in order to restore them when the proxying server restarts.\n\nAn **`RpcProxiedManager`** abstract class is available for managers who are designed to be proxied. Such managers will automatically register in main proxy\nserver, with following details:\n* registered services names list has to be returned by **`_proxied_services`** method\n* registered services version string has to be returned by **`_proxied_version`** method\n* extra stubs available in the **`self.proxy_client`** attribute can be provided by **`_proxy_stubs`** method\n* if current host IP needs excpilicitely to be used for registration, **`_proxy_use_current_host`** method needs to return **`True`**\n\nWhen handling proxy servers, if the proxying server is started with events service enabled, it will send:\n* an **`RPC_PROXY_REGISTER`** event on each **`proxy_register`** method successful call\n* an **`RPC_PROXY_FORGET`** event on each **`proxy_forget`** method successful call\n\nProperties of the events will be inherited from the method input message.\n\n#### Rolling logs\n\nEach manager of the RPC server through its **`logger`** attribute, will have his logs persisted in a **\\<name\\>/\\<name\\>.log** rolling file (relative to the \nlogging folder). The complete logs will also be persisted in the **root** folder.\nBoth logging folder and rollover cadency can be configured -- see **Configuration** chapter below.\n\n#### Configuration\n\nThe RPC server behavior can be configured through the following static configuration items:\nName | Description | Type | Default\n---- | ----------- | ---- | -------\n**rpc-max-workers** | Maximum parallel RPC worker threads | Positive integer | **`30`**\n**rpc-shutdown-grace** | Grace period for pending calls to be terminated on shutdown (seconds) | Positive float | **`30`**\n**rpc-shutdown-timeout** | Final timeout before real shutdown (i.e. end of process; seconds) | Positive float | **`60`**\n**rpc-logs-folder** | Folder (absolute or workspace-relative) where to store rolling logs | String | **`\"logs\"`**\n**rpc-logs-backup** | Backup log files to be persisted for each manager on rollover | Integer | **`10`**\n**rpc-logs-interval-unit** | Logs rollover interval unit (see [TimedRotatingFileHandler documentation](https://docs.python.org/3/library/logging.handlers.html#logging.handlers.TimedRotatingFileHandler)) | Custom (see [doc](https://docs.python.org/3/library/logging.handlers.html#logging.handlers.TimedRotatingFileHandler)) | **`H`**\n**rpc-logs-interval** | Logs rollover interval (see [TimedRotatingFileHandler documentation](https://docs.python.org/3/library/logging.handlers.html#logging.handlers.TimedRotatingFileHandler)) | Positive integer | **`1`**\n**rpc-main-host** | Main RPC server host (to be used by proxied services) | String | **`\"localhost\"`**\n**rpc-main-port** | Main RPC server port (to be used by proxied services) | Positive integer | **`54321`**\n**rpc-client-timeout** | Timeout for RPC client when server is unreachable or proxy not registered yet (seconds) | Positive float | **`60`**\n**rpc-event-retain-timeout** | Retain timeout for event queues on interruption (seconds) | Positive integer | **`300`**\n**rpc-event-keepalive-timeout** | Timeout for sending keep alive empty events (seconds) | Positive integer | **`60`**\n\n#### Usage example\n\n```python\nimport my_package\nfrom my_package.api import MyStatus, MyConfig, MyApiVersion\nfrom my_package.api.my_pb2_grpc import add_MyServiceServicer_to_server, MyServiceServicer, MyServiceStub\nfrom grpc_helper import RpcServer, RpcServiceDescriptor, RpcManager\n\nclass MySampleManager(MyServiceServicer, RpcManager):\n # Custom implementation for sample service\n\n def update(self, request: MyConfig) -> MyStatus:\n # Note that return message *MUST* be explicitely annoted for each implemented method!\n return MyStatus()\n\ndef start():\n # Create an RPC server on port 12345\n srv = RpcServer(12345, [RpcServiceDescriptor(my_package, \"my\", MyApiVersion, MySampleManager(), add_MyServiceServicer_to_server, MyServiceStub)])\n\n # Server is running in its own thread; we need to wait it for shutdown (on Ctrl-C or remote shutdown call)\n srv.wait_shutdown()\n```\n\n---\n### RPC Client\n\nThe **`RpcClient`** class provides an access to client side of a GRPC service. To initialize, it basically needs:\n* a host name or IP address for the RPC server to connect to\n* a port for the RPC server\n* a map of service stubs to access:\n * keys are used to define fields names on the generated client object, holding the client stubs\n * values are tuple providing:\n * the GRPC generated stub name\n * the client current API version (coming from the version enum)\n\nOptional inputs can also be provided:\n* a timeout if RPC server is unreachable (default: **60s**)\n* a name allowing to identify the client on the server side\n* a boolean flag stating if the client shall raise exceptions when receiving non-OK **`ResultCode`** status (default: **true**)\n* an exception type to be raised (instead of **`RpcException`**) when receiving non-OK **`ResultCode`** status\n\nOnce created, a client instance provide as many stubs as configured in the service map. Each of this stubs expose the generated methods of the \ncorresponding service. These methods take the following arguments:\n* the method input request message (see corresponding proto file)\n* a timeout parameter (in seconds) for this particular request. If set to None (default), there is no timeout\n\n#### Usage example\n\n```python\nfrom my_package.api import MyStatus, MyApiVersion, Empty\nfrom my_package.api.my_pb2_grpc import MyServiceStub\nfrom grpc_helper import RpcClient\n\ndef start():\n # Get a client access to my service\n c = RpcClient(\"127.0.0.1\", 12345, {\"my\": (MyServiceStub, MyApiVersion.MY_API_CURRENT)}, name=\"myclient\")\n\n # Use API\n s: MyStatus = c.my.list(Empty())\n```\n\n---\n### Configuration items\n\nInstances of the **`Config`** class can be provided to initialize list of static and user configuration items known to a RPC server:\n* *static* items are immutable, and are only initialized once when the RPC server instance is created\n* *user* items can be modified remotely through the [config service](https://github.com/dynod/grpc-helper-api/blob/main/doc/config.md)\n\nThe **`Config`** constructor arguments are the same than the public API **`ConfigItem`** ones (see [config service](https://github.com/dynod/grpc-helper-api/blob/main/doc/config.md)).\nIt also supports an additional **`custom_validator`** one, allowing to provide a validation method when **`validator`** argument is set to **`CONFIG_VALID_CUSTOM`**.\nThis method takes two arguments:\n* a **`name`** string: may be useful to raise meaningful validation errors\n* a **`value`** string: value to be validated. The method shall raise an **`RpcException`** if the value is invalid.\n\n#### Default value\n\nConfiguration items default value are loaded in the following order:\n1. hard-coded value (the one provided in the item constructor)\n2. system folder **config.json** file value (if system folder is configured)\n3. user folder **config.json** file value (if user folder is configured)\n4. environment provided value. Environment variable name for a given item is obtained by capitalizing it and replacing hyphens (\"-\") by underscores (\"_\").\nE.g. the environment variable name for a **my-own-setting** config item will be **MY_OWN_SETTING**.\n5. **-c / --config** command-line option provided value\n\nNote that if the default value fails to be validated with a given item validator (or if it is empty while not allowed), the server will refuse to launch with a\nthrown relevant exception.\n\n#### Current value\n\nStatic items current value will be initialized with the default value. User items are initialized to either the default value, or to the user configured value\n(thanks to the [config service](https://github.com/dynod/grpc-helper-api/blob/main/doc/config.md)) if it was ever modified. User modified values are\npersisted in the workspace folder **config.json** file.\n\nCurrent value may be programmatically accessed through one of the following property accessors:\n* **`item.str_val`**: raw string value\n* **`item.int_val`**: value converted as an integer\n\n#### Config holders\n\nConfiguration items may be defined as attributes of a class inheriting from the **`ConfigHolder`** one. Such classes can be provided directly to **`RpcServer`**\nconstructor to initialize configuration items (which is more convenient that referencing items one by one).\n\n---\n### Command-line options\n\nA ready-to-use CLI parser is provided through the **`RpcCliParser`** class, allowing to rapidly instantiate an RPC server from CLI options.\nConstructor arguments are:\n* a **`description`** string, which will be displayed when using the **-h / --help** option\n* an optional **`version`** string, which will be displayed when using the **-V / --version** option\n\n#### Options\n\nThe options defined by this parser are:\nName | Description\n---- | -----------\n**--help** | displays the program help and exit\n**-V / --version** | displays the program version and exit\n**--system PATH** | overrides the default system folder\n**--user PATH** | overrides the default user folder\n**-w / --workspace PATH** | defines the workspace folder\n**-p / --port PORT** | overrides the RPC server default listening port\n**-c / --config NAME=VALUE** | overrides the default value of a given configuration item\n\nAfter parsing:\n* the system/user/workspace folders are used to initialize a **`Folders`** object (see above), available in the **`folders`** argument of the namespace.\n* the configuration items default values are gathered in a dict, available in the **`config`** argument of the namespace.\n\n#### Usage\n\nThe following methods are available to tune the parser behavior:\n* **`with_rpc_args`**: adds the options listed above, and returns the **`RpcCliParser`** instance (for fluent API usage). Arguments are:\n * **`default_port`**: default RPC listening port\n * **`default_sys`**: default system folder\n * **`default_usr`**: default user folder\n * **`default_wks`**: default workspace folder\n* **`parse`**: will parse input arguments, and return the namespace. Arguments are program command-line ones by default, or may be provided as a string list\n(e.g. for testing purpose)\n\nFollowing example shows how to use this parser to create an **`RpcServer`** instance:\n```python\nfrom grpc_helper import RpcCliParser, RpcServer\n\ndef start():\n # Parse arguments to create RPC server instance\n args = RpcCliParser(\"My custom RPC server\", \"1.0.0\").with_rpc_args(12345, \"/etc/my_srv\", \"~/.local/my_srv\", \"my_srv_wks\").parse()\n srv = RpcServer(args.port, [], args.folders, args.config)\n```\n\n\n",
"bugtrack_url": null,
"license": "Mozilla Public License Version 2.0",
"summary": "Helpers supercharging grpc features (API versioning, retry, etc...)",
"version": "2.3.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "69d01c501fd7fb73b17a3c3be7f525548ebaedf34cd06e15b62a21c0f91c81ad",
"md5": "e24bcc7a430c4c2e8c7ef8a594d25e5a",
"sha256": "47e6117cb4c1fd09aa53c4668231ad1c80dfddff50b8c0b4b9d153ee7d78f6df"
},
"downloads": -1,
"filename": "grpc_helper-2.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e24bcc7a430c4c2e8c7ef8a594d25e5a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 43134,
"upload_time": "2023-01-29T16:14:17",
"upload_time_iso_8601": "2023-01-29T16:14:17.369536Z",
"url": "https://files.pythonhosted.org/packages/69/d0/1c501fd7fb73b17a3c3be7f525548ebaedf34cd06e15b62a21c0f91c81ad/grpc_helper-2.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0c034c773884ea2f6b8c27dcb480b5254531be0788343235d25c9ef197ddc7a1",
"md5": "c279e3633280f1fb138148bf0dd33df5",
"sha256": "8cef9838c90e0f8875ea307d7b9525fe0b23fe03b2dccfa4ed9596ef3406eb2d"
},
"downloads": -1,
"filename": "grpc-helper-2.3.1.tar.gz",
"has_sig": false,
"md5_digest": "c279e3633280f1fb138148bf0dd33df5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 42451,
"upload_time": "2023-01-29T16:14:18",
"upload_time_iso_8601": "2023-01-29T16:14:18.595948Z",
"url": "https://files.pythonhosted.org/packages/0c/03/4c773884ea2f6b8c27dcb480b5254531be0788343235d25c9ef197ddc7a1/grpc-helper-2.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-29 16:14:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "dynod",
"github_project": "grpc-helper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "grpc-helper"
}
JSON
