Metadata-Version: 2.1
Name: easy-grpc
Version: 0.0.1b1
Summary: Helper module to build GRPC service easily
Home-page: https://gitlab.com/ist-supsi/istsosm/libs/easy-grpc
Author: IST-SUPSI
Author-email: geoservice@supsi.ch
License: UNKNOWN
Project-URL: Documentation, https://gitlab.com/ist-supsi/istsosm/libs/easy-grpc
Project-URL: Source, https://gitlab.com/ist-supsi/istsosm/libs/easy-grpc
Project-URL: Tracker, https://gitlab.com/ist-supsi/istsosm/libs/easy-grpc/issues
Description: # Easy GRPC
        
        Python (>=3.7) GRPC service helper library.
        
        ## Installation
        
        We suggest to create a virtual environment.
        
        ```bash
        python3.7 -m venv ./venv
        source venv/bin/activate
        python  -m pip install --upgrade pip
        ```
        
        Install the module:
        
        ```bash
        pip install easy-grpc
        
        ```
        
        ## Usage example
        
        Easy GRPC helps you to create a GRPC Service in three steps:
        
        1. Define and compile your proto files
        2. Implement the *Actions*
        3. Configure and run the GRPC service
        
        ### 1. Define and compile your proto files
        
        In the example folder there are files extracted from the [grpclib](https://github.com/vmagamedov/grpclib) repository, which is also the core library used to run this service. You can find the *helloworld.proto* and the relative compiled python files (*helloworld_pb2.py* and *helloworld_grpc.py*).
        
        ```proto
        syntax = "proto3";
        
        package example.helloworld;
        
        message HelloRequest {
          string name = 1;
        }
        
        message HelloReply {
          string message = 1;
        }
        
        service Greeter {
          rpc SayHello (HelloRequest) returns (HelloReply) {}
        }
        
        ```
        
        To define the service you have to create the proto files as explained in the official documentations [grpc.io](https://grpc.io/docs/guides/concepts/).
        
        To compile a proto file by yourself, just execute this command from the root directory.
        
        ```bash
        python -m grpc_tools.protoc \
          --proto_path=. \
          --python_out=. \
          --python_grpc_out=. \
          ./example/helloworld.proto
        ```
        
        > **Note:** pay attention to the *python_grpc_out* param. This is not standard in the *grpc_tools.protoc* library, it is [grpclib specific](https://grpclib.readthedocs.io/en/latest/index.html?highlight=python_grpc_out#protoc-plugin).
        
        ### 2. Implement the *Actions*
        
        In the helloworld.proto file there is declared one rpc function (you can declare more). You shall create an action for each rpc, handling the defined input message (HelloRequest) and returning the relative return message (HelloReply).
        
        In the case of the example the helloworld_action.py is created:
        
        ```python
        from easygrpc import Action
        from .helloworld_pb2 import  HelloReply
        
        
        class Hello(Action):
            async def execute(self, hello_request=None):
                return HelloReply(message=f'Hello {hello_request.name}!')
        
        ```
        
        An *Action* is a Class extending the **easygrpc.action.Action** abstract base class, and must overwrite the execute method.
        
        ### 3. Configure and run the GRPC service
        
        Finally to run the service you shall create a config file which is used to configure and run the service.
        
        ```ini
        [SERVER]
        server = example.helloworld_grpc.GreeterBase
        client = example.client.SendRequest
        host = 127.0.0.1
        port = 50051
        
        [ACTIONS]
        SayHello = example.helloworld_action.Hello
        
        ```
        
        In the *ACTIONS* section you shall declare one action for each rcp function. Of corse you can declare more then the defined rpc that can be used and exposed.
        
        To run the service just open a terminal, and:
        
        ```bash
        source venv/bin/activate
        python -m easygrpc.start
        ```
        
        To execute the client, open another teminal, and:
        
        ```bash
        source venv/bin/activate
        python -m easygrpc.start -c
        ```
        
        You should see the response from the service:
        
        ```bash
        Hello Mr. Easy!
        ```
        
        
        ## Database interaction
        
        In every implemented Action you have access to a PostgreSQL Database Client Library ([asyncpg](https://github.com/MagicStack/asyncpg)). In the config file, you define the PostgreSQL connection parameters. And the in the action implementation you can execute SQL commands to interact with the database.
        
        create a postgreSQL (versions 9.2 to 10) database named 'easy'.
        
        ```bash
        sudo -u postgres createdb -E UTF8 easy
        ```
        
        Then create a new table:
        
        ```SQL
        CREATE TABLE public.messages
        (
            id serial,
            text character varying,
            PRIMARY KEY (id)
        );
        ```
        
        And insert a row:
        
        ```SQL
        INSERT INTO public.messages(text) VALUES ('Hello PostgreSQL!');
        ```
        
        Add the following configuration section:
        
        ```ini
        [POSTGRESQL]
        user = postgres
        password = postgres
        database = easy
        host = localhost
        port = 5432
        
        ```
        
        Modify the Hello Action (example/helloword_action.py):
        
        ```python
        from easygrpc import Action
        from .helloworld_pb2 import  HelloReply
        
        
        class Hello(Action):
            async def execute(self, hello_request=None):
                rec = await self.conn.fetchval("""
                    SELECT row_to_json(t)
                    FROM (
                        SELECT
                            text as message
                        FROM public.messages
                        WHERE
                            id = $1
                    ) as t
                """, 1)
                if rec is not None:
                    return self.encode(rec, HelloReply)
                return None
        
        ```
        
        To run the service just open a terminal, and:
        
        ```bash
        source venv/bin/activate
        python -m easygrpc.start
        ```
        
        To execute the client, open another teminal, and:
        
        ```bash
        source venv/bin/activate
        python -m easygrpc.start -c
        ```
        
        
Keywords: istsos grpc
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3, <4
Description-Content-Type: text/markdown
