Muffin-GRPC
############
.. _description:
Muffin-GRPC -- GRPC support for Muffin_ framework.
Features:
- Automatically build proto files and python helpers for them;
- Automatically connect to default channel;
- Automatically create and run GRPC server from your services;
.. _badges:
.. image:: https://github.com/klen/muffin-grpc/workflows/tests/badge.svg
:target: https://github.com/klen/muffin-grpc/actions
:alt: Tests Status
.. image:: https://img.shields.io/pypi/v/muffin-grpc
:target: https://pypi.org/project/muffin-grpc/
:alt: PYPI Version
.. _contents:
.. contents::
.. _requirements:
Requirements
=============
- python >= 3.8
.. note:: The plugin supports only asyncio evenloop (not trio)
.. _installation:
Installation
=============
**Muffin-GRPC** should be installed using pip: ::
pip install muffin-grpc
.. _usage:
Usage
=====
Setup the plugin and connect it into your app:
.. code-block:: python
from muffin import Application
from muffin_grpc import Plugin as GRPC
# Create Muffin Application
app = Application('example')
# Initialize the plugin
# As alternative: grpc = GRPC(app, **options)
grpc = GRPC(default_channel='server:50051')
grpc.setup(app)
Lets build a simple helloworld service, with the proto: ::
syntax = "proto3";
package helloworld;
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply) {}
}
message HelloRequest {
string name = 1;
}
message HelloReply {
string message = 1;
}
Put it somewhere and add the file into the grpc plugin:
.. code-block:: python
grpc.add_proto('project_name/proto/helloworld.proto')
Run the command to build proto files:
.. code-block:: shell
$ muffin project_name grpc_build
The command will build the files:
- ``project_name/proto/helloworld_pb2.py`` - with the proto's messages
- ``project_name/proto/helloworld_pb2_grpc.py`` - with the proto's GRPC services
- ``project_name/proto/helloworld.py`` - with the messages and services together
- ``project_name/proto/__init__.py`` - to make the build directory a package
.. note:: Muffin-GRPC fixes python imports automatically
Let's implement the Greeter service:
.. code-block:: python
from .proto.helloworld import GreeterServicer, HelloRequest, HelloReply
# Connect the service to GRPC server
@grpc.add_to_server
class Greeter(GreeterServicer):
async def SayHello(self, request: HelloRequest,
context: grpc_aio.ServicerContext) -> HelloReply:
return HelloReply(message='Hello, %s!' % request.name)
Run the server with the command:
.. code-block:: shell
$ muffin package_name grpc_server
The server is working and accepts GRPC request, let's start building a client
.. code-block:: python
from .proto.helloworld import GreeterStub, HelloRequest
@app.route('/')
async def index(request):
name = request.url.query.get('name') or 'anonymous'
try:
async with grpc.get_channel() as channel:
stub = GreeterStub(channel)
response = await stub.SayHello(
HelloRequest(name=request.url.query['name']), timeout=10)
message = response.message
except AioRpcError as exc:
message = exc.details()
return message
The ``/`` endpoint will make a request to the GRPC server and return a message
from the server.
Configuration options
----------------------
=========================== ======================================= ===========================
Name Default value Desctiption
--------------------------- --------------------------------------- ---------------------------
**build_dir** ``None`` A directory to build proto files
**server_listen** ``"[::]:50051"`` Server address
**ssl_server** ``False`` Enable SSL for server
**ssl_server_params** ``None`` SSL Server Params
**ssl_client** ``False`` Enable SSL for client
**ssl_client_params** ``None`` SSL Client Params
**default_channel** ``localhost:50051`` Default Client Channel Address
**default_channel_options** ``{}`` GRPC options for the default channel
=========================== ======================================= ===========================
You are able to provide the options when you are initiliazing the plugin:
.. code-block:: python
grpc.setup(app, server_listen='localhost:40000')
Or setup it from ``Muffin.Application`` configuration using the ``GRPC_`` prefix:
.. code-block:: python
GRPC_SERVER_LISTERN = 'locahost:40000'
``Muffin.Application`` configuration options are case insensitive
CLI Commands
------------
::
$ muffin project_name grpc_build --help
usage: muffin grpc_build [-h]
Build registered proto files.
optional arguments:
-h, --help show this help message and exit
::
$ muffin project_name grpc_server --help
usage: muffin grpc_server [-h]
Start GRPC server with the registered endpoints.
optional arguments:
-h, --help show this help message and exit
.. _bugtracker:
Bug tracker
===========
If you have any suggestions, bug reports or
annoyances please report them to the issue tracker
at https://github.com/klen/muffin-grpc/issues
.. _contributing:
Contributing
============
Development of Muffin-GRPC happens at: https://github.com/klen/muffin-grpc
Contributors
=============
* klen_ (Kirill Klenov)
.. _license:
License
========
Licensed under a `MIT license`_.
.. _links:
.. _klen: https://github.com/klen
.. _Muffin: https://github.com/klen/muffin
.. _MIT license: http://opensource.org/licenses/MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/klen/muffin-grpc",
"name": "muffin-grpc",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "grpc, muffin, asyncio, asgi, web",
"author": "Kirill Klenov",
"author_email": "horneds@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ba/0a/2f0c7d19dd4b2afb619f7b6799c1279e9d69db705e284ca243a7f0f17238/muffin_grpc-0.8.0.tar.gz",
"platform": null,
"description": "Muffin-GRPC\n############\n\n.. _description:\n\nMuffin-GRPC -- GRPC support for Muffin_ framework.\n\nFeatures:\n\n- Automatically build proto files and python helpers for them;\n- Automatically connect to default channel;\n- Automatically create and run GRPC server from your services;\n\n.. _badges:\n\n.. image:: https://github.com/klen/muffin-grpc/workflows/tests/badge.svg\n :target: https://github.com/klen/muffin-grpc/actions\n :alt: Tests Status\n\n.. image:: https://img.shields.io/pypi/v/muffin-grpc\n :target: https://pypi.org/project/muffin-grpc/\n :alt: PYPI Version\n\n.. _contents:\n\n.. contents::\n\n.. _requirements:\n\nRequirements\n=============\n\n- python >= 3.8\n\n.. note:: The plugin supports only asyncio evenloop (not trio)\n\n.. _installation:\n\nInstallation\n=============\n\n**Muffin-GRPC** should be installed using pip: ::\n\n pip install muffin-grpc\n\n.. _usage:\n\nUsage\n=====\n\nSetup the plugin and connect it into your app:\n\n.. code-block:: python\n\n from muffin import Application\n from muffin_grpc import Plugin as GRPC\n\n # Create Muffin Application\n app = Application('example')\n\n # Initialize the plugin\n # As alternative: grpc = GRPC(app, **options)\n grpc = GRPC(default_channel='server:50051')\n grpc.setup(app)\n\n\nLets build a simple helloworld service, with the proto: ::\n\n syntax = \"proto3\";\n\n package helloworld;\n\n service Greeter {\n rpc SayHello (HelloRequest) returns (HelloReply) {}\n }\n\n message HelloRequest {\n string name = 1;\n }\n\n message HelloReply {\n string message = 1;\n }\n\nPut it somewhere and add the file into the grpc plugin:\n\n.. code-block:: python\n\n grpc.add_proto('project_name/proto/helloworld.proto')\n\n\nRun the command to build proto files:\n\n.. code-block:: shell\n\n $ muffin project_name grpc_build\n\nThe command will build the files:\n\n- ``project_name/proto/helloworld_pb2.py`` - with the proto's messages\n- ``project_name/proto/helloworld_pb2_grpc.py`` - with the proto's GRPC services\n- ``project_name/proto/helloworld.py`` - with the messages and services together\n- ``project_name/proto/__init__.py`` - to make the build directory a package\n\n.. note:: Muffin-GRPC fixes python imports automatically\n\nLet's implement the Greeter service:\n\n.. code-block:: python\n\n from .proto.helloworld import GreeterServicer, HelloRequest, HelloReply\n\n # Connect the service to GRPC server\n @grpc.add_to_server\n class Greeter(GreeterServicer):\n\n async def SayHello(self, request: HelloRequest,\n context: grpc_aio.ServicerContext) -> HelloReply:\n return HelloReply(message='Hello, %s!' % request.name)\n\n\nRun the server with the command:\n\n.. code-block:: shell\n\n $ muffin package_name grpc_server\n\nThe server is working and accepts GRPC request, let's start building a client\n\n.. code-block:: python\n\n from .proto.helloworld import GreeterStub, HelloRequest\n\n @app.route('/')\n async def index(request):\n name = request.url.query.get('name') or 'anonymous'\n try:\n async with grpc.get_channel() as channel:\n stub = GreeterStub(channel)\n response = await stub.SayHello(\n HelloRequest(name=request.url.query['name']), timeout=10)\n message = response.message\n\n except AioRpcError as exc:\n message = exc.details()\n\n return message\n\nThe ``/`` endpoint will make a request to the GRPC server and return a message\nfrom the server.\n\n\nConfiguration options\n----------------------\n\n=========================== ======================================= ===========================\nName Default value Desctiption\n--------------------------- --------------------------------------- ---------------------------\n**build_dir** ``None`` A directory to build proto files\n**server_listen** ``\"[::]:50051\"`` Server address\n**ssl_server** ``False`` Enable SSL for server\n**ssl_server_params** ``None`` SSL Server Params\n**ssl_client** ``False`` Enable SSL for client\n**ssl_client_params** ``None`` SSL Client Params\n**default_channel** ``localhost:50051`` Default Client Channel Address\n**default_channel_options** ``{}`` GRPC options for the default channel\n=========================== ======================================= ===========================\n\nYou are able to provide the options when you are initiliazing the plugin:\n\n.. code-block:: python\n\n grpc.setup(app, server_listen='localhost:40000')\n\nOr setup it from ``Muffin.Application`` configuration using the ``GRPC_`` prefix:\n\n.. code-block:: python\n\n GRPC_SERVER_LISTERN = 'locahost:40000'\n\n``Muffin.Application`` configuration options are case insensitive\n\nCLI Commands\n------------\n\n::\n\n $ muffin project_name grpc_build --help\n\n usage: muffin grpc_build [-h]\n\n Build registered proto files.\n\n optional arguments:\n -h, --help show this help message and exit\n\n::\n\n $ muffin project_name grpc_server --help\n\n usage: muffin grpc_server [-h]\n\n Start GRPC server with the registered endpoints.\n\n optional arguments:\n -h, --help show this help message and exit\n\n\n.. _bugtracker:\n\nBug tracker\n===========\n\nIf you have any suggestions, bug reports or\nannoyances please report them to the issue tracker\nat https://github.com/klen/muffin-grpc/issues\n\n.. _contributing:\n\nContributing\n============\n\nDevelopment of Muffin-GRPC happens at: https://github.com/klen/muffin-grpc\n\n\nContributors\n=============\n\n* klen_ (Kirill Klenov)\n\n.. _license:\n\nLicense\n========\n\nLicensed under a `MIT license`_.\n\n.. _links:\n\n\n.. _klen: https://github.com/klen\n.. _Muffin: https://github.com/klen/muffin\n.. _MIT license: http://opensource.org/licenses/MIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "GRPC support for Muffin framework.",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/klen/muffin-grpc",
"Repository": "https://github.com/klen/muffin-grpc"
},
"split_keywords": [
"grpc",
" muffin",
" asyncio",
" asgi",
" web"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ffcda5138976549e2f40a6c6f049c531cc5a078cd75686d94ce13ee0ae57c4ee",
"md5": "0125293ad982baef2c7ac7e6fe25310a",
"sha256": "8eb6ebeb5858723217b7aa46a8ed0a500d596947cc396777d82fc706e0a024a8"
},
"downloads": -1,
"filename": "muffin_grpc-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0125293ad982baef2c7ac7e6fe25310a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 6270,
"upload_time": "2024-07-31T17:33:23",
"upload_time_iso_8601": "2024-07-31T17:33:23.819129Z",
"url": "https://files.pythonhosted.org/packages/ff/cd/a5138976549e2f40a6c6f049c531cc5a078cd75686d94ce13ee0ae57c4ee/muffin_grpc-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ba0a2f0c7d19dd4b2afb619f7b6799c1279e9d69db705e284ca243a7f0f17238",
"md5": "895a74750f140fdc1fcdb97ec5fcb3f8",
"sha256": "1f9c532ffb36c46569562d920feea7c1efef633eea7d89987d93197529f0e9fd"
},
"downloads": -1,
"filename": "muffin_grpc-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "895a74750f140fdc1fcdb97ec5fcb3f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 5944,
"upload_time": "2024-07-31T17:33:25",
"upload_time_iso_8601": "2024-07-31T17:33:25.589908Z",
"url": "https://files.pythonhosted.org/packages/ba/0a/2f0c7d19dd4b2afb619f7b6799c1279e9d69db705e284ca243a7f0f17238/muffin_grpc-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-31 17:33:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "klen",
"github_project": "muffin-grpc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "muffin-grpc"
}
JSON
