Registry / serialization / thriftpy2

thriftpy2

JSON →
library0.7.0pypypi✓ verified 29d ago

ThriftPy2 is a pure Python implementation of the Apache Thrift protocol, version 0.6.0. It allows developers to parse Thrift IDL files and create RPC clients/servers dynamically without code generation or compilation. The library maintains an active development status with regular updates, including recent beta releases leading to stable versions.

pip install thriftpy2
INSTALL
IMPORT
SIG · THRIFTPY2
T
thriftpy2
serializationpythonv0.7.0
Install
2.5s avg
Import
143ms
Disk
42MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.148s · 41.5MB
glibc
py 3.10–3.910 runs
installs and imports cleanly · install 2.5s · import 0.137s · 44MB
42MB installed
● package 42MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

thriftpy2
✓ import thriftpy2
Main library import for dynamic IDL loading and core functionalities.
make_server
✓ from thriftpy2.rpc import make_server
Used to create synchronous Thrift RPC servers.
make_aio_client
✓ from thriftpy2.rpc import make_aio_client
Used to create asynchronous Thrift RPC clients with asyncio.
thriftpy
✓ import thriftpy2 as thriftpy
✗ import thriftpy
The original 'thriftpy' library is deprecated. For compatibility, migrate to 'thriftpy2' and import it with an alias if needed.

This quickstart demonstrates how to dynamically load a Thrift IDL file and instantiate an asynchronous client using `thriftpy2.rpc.make_aio_client`. It creates a temporary `pingpong.thrift` file, loads it, and attempts to connect to a local server. Note that for a successful RPC call, a ThriftPy2 server must be running at the specified address and port.

import asyncio import thriftpy2 from thriftpy2.rpc import make_aio_client import os # Define a simple Thrift service IDL in a temporary file THRIFT_FILE_PATH = "pingpong.thrift" with open(THRIFT_FILE_PATH, "w") as f: f.write("service PingPong {\n string ping(),\n}") # Load the thrift file dynamically pingpong_thrift = thriftpy2.load(THRIFT_FILE_PATH, module_name="pingpong_thrift") async def main(): print("Attempting to create ThriftPy2 async client...") client = None try: # For this quickstart, we'll demonstrate client instantiation and a call pattern. # Note: This client will attempt to connect to '127.0.0.1:6000'. # A running ThriftPy2 server on this address would be required for a successful RPC call. # This example focuses on demonstrating the client API, not a full RPC pair. client = await make_aio_client( pingpong_thrift.PingPong, '127.0.0.1', 6000, timeout=1000 # Milliseconds for connection/read timeout ) print("Client created. Attempting to call ping()... (This will likely fail without a running server)") # Example of calling a service method # result = await client.ping() # print(f"Ping result: {result}") except Exception as e: print(f"Error setting up client (expected if no server is running at 127.0.0.1:6000): {e}") finally: if client: client.close() # Clean up the dummy thrift file if os.path.exists(THRIFT_FILE_PATH): os.remove(THRIFT_FILE_PATH) if __name__ == '__main__': asyncio.run(main())
Debug
Known issues
deprecatedSupport for Tornado-based servers and clients has been deprecated in v0.6.0. Users relying on `thriftpy2.tornado` modules should migrate to `asyncio` or other HTTP transports.
fix
Migrate your server and client implementations to use `asyncio` (e.g., `make_aio_server`, `make_aio_client`) or other supported HTTP transports available in `thriftpy2`.
affects: >=0.6.0
gotchaWhen migrating from the original `thriftpy` library, simply changing import statements from `import thriftpy` to `import thriftpy2` might cause issues if other parts of your code still expect the `thriftpy` namespace. While `thriftpy2` is designed for compatibility, direct renaming is safer.
fix
For full compatibility, change `import thriftpy` to `import thriftpy2 as thriftpy`. This ensures your code continues to reference the library under the original name while using `thriftpy2`'s implementation.
affects: all
gotchaIf you install `thriftpy2` in a PyPy virtual environment, `pip` might generate a universal wheel without Cython extensions. Using this cached wheel later in a CPython environment can lead to `ModuleNotFoundError: No module named 'thriftpy2.protocol.cybin'` because CPython expects the Cython-compiled modules.
fix
When installing `thriftpy2` in a CPython environment, explicitly install `cython` first (`pip install cython thriftpy2`) or use `pip install --no-binary thriftpy2 thriftpy2` to force a source build. Alternatively, clear your `pip` cache if you've previously installed in PyPy.
affects: all
gotchaWhen dynamically loading Thrift IDL files using `thriftpy2.load()`, if you do not provide the `module_name` argument, the generated Thrift objects cannot be pickled. This can cause issues with serialization in distributed systems or caching.
fix
Always provide a `module_name` argument when calling `thriftpy2.load()`, e.g., `my_thrift = thriftpy2.load('my.thrift', module_name='my_thrift_module')`. This ensures the generated objects are pickleable.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'thriftpy'
The user is trying to import the old `thriftpy` library, or made a typo when intending to use `thriftpy2`.
fix
Install `thriftpy2` (`pip install thriftpy2`) and update all imports from `thriftpy` to `thriftpy2`.
thriftpy2.parser.exc.ThriftParserError: Line X: Expected identifier.
There is a syntax error or a semantic issue in the Thrift IDL (.thrift) file that `thriftpy2` is trying to load. The specific message 'Expected identifier' indicates a name is missing or incorrectly placed.
fix
Review and correct the syntax of the Thrift IDL file at the specified line number. Ensure all identifiers (like struct names, field names, method names) are correctly defined and that there are no missing semicolons or incorrect keywords.
TProtocolException: Bad version in readMessageBegin
The client and server are using incompatible Thrift protocol versions or transport layers. This often occurs when `thriftpy2` communicates with a service implemented in a different language or Thrift library that uses a different default protocol (e.g., TBinaryProtocol vs TCompactProtocol) or an incompatible transport.
fix
Ensure both the client and server are configured to use the exact same Thrift protocol factory (e.g., `TBinaryProtocol.TBinaryProtocolFactory()`, `TCompactProtocol.TCompactProtocolFactory()`) and transport factory (e.g., `TSocket.TSocketFactory()`, `TBufferedTransport.TBufferedTransportFactory()`).
AttributeError: 'Client' object has no attribute 'yourMethodName'
The Thrift client code is attempting to call a method that is not defined in the Thrift IDL service description used to create the client. This typically means the IDL file used by the client is outdated, incorrect, or different from the one used by the server.
fix
Verify that the Thrift IDL file used to generate the client is correct and includes the method `yourMethodName` in its `service` definition. Ensure consistency between the client's and server's IDL files and re-parse/re-initialize the client with the correct IDL.
Upgrade
Version history
0.7.0latest on PyPI · released Aug 9, 2026
Audit
Dependencies
plyrequiredRequired for parsing Thrift IDL files.
typing-extensionsrequiredProvides backported and experimental type hints.
cythonoptionalOptional for improved performance of binary and compact protocols.
Agent activity
18 hits · last 30 days
node
16
OpenAI (training)
1
Resources
thriftpy2 — pip install thriftpy2 · libregistry