Metadata-Version: 2.1
Name: purerpc
Version: 0.7.0
Summary: Native, async Python gRPC client and server implementation supporting asyncio, uvloop, trio
Home-page: https://github.com/python-trio/purerpc
Author: Andrew Stepanov
License: Apache License Version 2.0
Keywords: async,await,grpc,pure-python,pypy,network,rpc,http2
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: BSD
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Framework :: AsyncIO
Classifier: Framework :: Trio
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: test
License-File: LICENSE

# purerpc

[![Build Status](https://img.shields.io/github/workflow/status/python-trio/purerpc/CI)](https://github.com/python-trio/purerpc/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/purerpc.svg?style=flat)](https://pypi.org/project/purerpc/)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/purerpc.svg)](https://pypi.org/project/purerpc)

_purerpc_ is a native, async Python gRPC client and server implementation supporting
[asyncio](https://docs.python.org/3/library/asyncio.html),
[uvloop](https://github.com/MagicStack/uvloop), and
[trio](https://github.com/python-trio/trio) (achieved with [anyio](https://github.com/agronholm/anyio) compatibility layer).

This project is in maintenance mode.  Updates will primarily be limited to fixing
severe bugs, keeping the package usable for actively developed projects, and
easing maintenance.

For use cases limited to asyncio, consider the Python package published by the
main [grpc](https://github.com/grpc/grpc) project instead.

## Requirements

* CPython >= 3.7
* PyPy >= 3.7

NOTE: PyPy support is tentative, as the grpcio dependency [doesn't officially
  suport it](https://github.com/grpc/grpc/issues/4221).  (The dependency should
be removed, since it's only used by tests, examples, and offline tools.)

## Installation

Latest PyPI version:

```bash
pip install purerpc
```

Latest development version:

```bash
pip install git+https://github.com/python-trio/purerpc.git
```

By default purerpc uses asyncio event loop, if you want to use uvloop or trio, please install them manually.

## protoc plugin

purerpc adds `protoc-gen-purerpc` plugin for `protoc` to your `PATH` enviroment variable
so you can use it to generate service definition and stubs: 

```bash
protoc --purerpc_out=. --python_out=. -I. greeter.proto
```

or, if you installed `grpcio_tools` Python package:

```bash
python -m grpc_tools.protoc --purerpc_out=. --python_out=. -I. greeter.proto
```

## Usage

NOTE: `greeter_grpc` module is generated by purerpc's `protoc-gen-purerpc` plugin.

### Server

```python
from purerpc import Server
from greeter_pb2 import HelloRequest, HelloReply
from greeter_grpc import GreeterServicer


class Greeter(GreeterServicer):
    async def SayHello(self, message):
        return HelloReply(message="Hello, " + message.name)

    async def SayHelloToMany(self, input_messages):
        async for message in input_messages:
            yield HelloReply(message=f"Hello, {message.name}")


if __name__ == '__main__':
    server = Server(50055)
    server.add_service(Greeter().service)
    # NOTE: if you already have an async loop running, use "await server.serve_async()"
    import anyio
    anyio.run(server.serve_async)  # or set explicit backend="asyncio" or "trio"
```

### Client

```python
import purerpc
from greeter_pb2 import HelloRequest, HelloReply
from greeter_grpc import GreeterStub


async def gen():
    for i in range(5):
        yield HelloRequest(name=str(i))


async def listen():
    async with purerpc.insecure_channel("localhost", 50055) as channel:
        stub = GreeterStub(channel)
        reply = await stub.SayHello(HelloRequest(name="World"))
        print(reply.message)

        async for reply in stub.SayHelloToMany(gen()):
            print(reply.message)


if __name__ == '__main__':
    # NOTE: if you already have an async loop running, use "await listen()"
    import anyio
    anyio.run(listen)  # or set explicit backend="asyncio" or "trio"
```

You can mix server and client code, for example make a server that requests something using purerpc from another gRPC server, etc.

More examples in `misc/` folder

# Project history

purerpc was originally written by [Andrew Stepanov](https://github.com/standy66)
and used the curio async event loop.  Later it
was migrated to the [anyio](https://github.com/agronholm/anyio) API, supporting
asyncio, curio, uvloop, and trio (though curio support has since been dropped
from the API).

After going a few years unmaintained, the project was adopted by the [python-trio
organization](https://github.com/python-trio) with the intent of ensuring a
continued gRPC solution for Trio users.


