thriftpy2

ThriftPy2 is a Pythonic implementation of Apache Thrift that is compatible with official Apache Thrift servers and clients.

Key Features:

• No Code Generation Required: Load .thrift files on the fly using thriftpy2.load() or an import hook.
• Pure Python: No need to compile the official thrift package.
• Compatibility: Works with official Apache Thrift implementations.
• Supported Protocols & Transports:
  • Binary protocol (Python and Cython versions)
  • Compact protocol (Python and Cython versions)
  • JSON protocol
  • Buffered transport (Python and Cython versions)
  • Framed transport
• Runtime Support: Python 3.6+ and PyPy3.

Install the ThriftPy2 package using pip to get a pure Python implementation of the Apache Thrift protocol.

$ pip install thriftpy2

Install ThriftPy2 using pip. For better performance, you can install cython first to allow ThriftPy2 to build Cython extensions locally, which enables accelerated binary and compact protocols.

$ pip install thriftpy2

# Recommended for performance (enables Cython extensions)
$ pip install cython thriftpy2

ThriftPy2 is a drop-in replacement for the deprecated thriftpy. To migrate, simply update your import statement to use thriftpy2.

import thriftpy2 as thriftpy

In a THttpServer, handlers can raise a ResponseException to override the default behavior of always sending a 200 OK response.

The ResponseException constructor takes a handler callable. This callable receives the RequestHandler (which is a subclass of http_server.BaseHTTPRequestHandler) as its only argument, allowing you to manually call methods like send_response, send_header, and end_headers to simulate different HTTP status codes or error scenarios.

TPayload is the base class for all generated Thrift structs (payloads). It provides standard methods for serialization and comparison:

• read(iprot): Reads the struct from the input protocol.
• write(oprot): Writes the struct to the output protocol.
• __eq__(other): Compares two payloads based on their field values.
• __hash__(): Provides a hash consistent with __eq__, allowing structs to be used as keys in dictionaries or members of sets.
• __repr__ / __str__: Provides a string representation of the struct fields.

To create a client, use thriftpy2.rpc.make_client. You must provide the service definition and the server's address and port.

import thriftpy2
from thriftpy2.rpc import make_client

# 1. Load the thrift definition
pingpong_thrift = thriftpy2.load("pingpong.thrift", module_name="pingpong_thrift")

# 2. Connect to the server
client = make_client(pingpong_thrift.PingPong, '127.0.0.1', 6000)

# 3. Call methods
print(client.ping())

To set up a synchronous RPC server, use thriftpy2.rpc.make_server. You must provide the service definition (from the loaded thrift module), an instance of a dispatcher class that implements the service methods, and the host/port.

import thriftpy2
from thriftpy2.rpc import make_server

pingpong_thrift = thriftpy2.load("pingpong.thrift", module_name="pingpong_thrift")


class Dispatcher(object):
    def ping(self):
        return "pong"


server = make_server(pingpong_thrift.PingPong, Dispatcher(), '127.0.0.1', 6000)
server.serve()

To use an asynchronous client, use thriftpy2.rpc.make_aio_client. This returns a coroutine that must be awaited to obtain the client instance. Remember to call client.close() when finished.

import asyncio
import thriftpy2
from thriftpy2.rpc import make_aio_client

pingpong_thrift = thriftpy2.load("pingpong.thrift", module_name="pingpong_thrift")


async def main():
    client = await make_aio_client(pingpong_thrift.PingPong, '127.0.0.1', 6000)
    print(await client.ping())  # prints "pong"
    client.close()


if __name__ == '__main__':
    asyncio.run(main())

To connect to a Thrift server, use thriftpy2.rpc.make_client. Pass the service definition, host, and port to create a client instance that mirrors the service interface.

import thriftpy2
from thriftpy2.rpc import make_client

pingpong_thrift = thriftpy2.load("pingpong.thrift", module_name="pingpong_thrift")

client = make_client(pingpong_thrift.PingPong, '127.0.0.1', 6000)
print(client.ping())  # prints "pong"

For asynchronous support, use thriftpy2.rpc.make_aio_server. The dispatcher class methods must be defined as async def.

import thriftpy2
from thriftpy2.rpc import make_aio_server

pingpong_thrift = thriftpy2.load("pingpong.thrift", module_name="pingpong_thrift")


class Dispatcher(object):
    async def ping(self):
        return "pong"


server = make_aio_server(pingpong_thrift.PingPong, Dispatcher(), '127.0.0.1', 6000)
server.serve()