{"id":2312,"library":"thriftpy2","title":"ThriftPy2","description":"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.","status":"active","version":"0.6.0","language":"python","source_language":"en","source_url":"https://github.com/Thriftpy/thriftpy2","tags":["thrift","rpc","protocol","apache thrift","idl","asyncio"],"install":[{"cmd":"pip install thriftpy2","lang":"bash","label":"Install stable version"},{"cmd":"pip install cython thriftpy2","lang":"bash","label":"Install with Cython for performance"}],"dependencies":[{"reason":"Required for parsing Thrift IDL files.","package":"ply","optional":false},{"reason":"Provides backported and experimental type hints.","package":"typing-extensions","optional":false},{"reason":"Optional for improved performance of binary and compact protocols.","package":"cython","optional":true}],"imports":[{"note":"Main library import for dynamic IDL loading and core functionalities.","symbol":"thriftpy2","correct":"import thriftpy2"},{"note":"Used to create synchronous Thrift RPC servers.","symbol":"make_server","correct":"from thriftpy2.rpc import make_server"},{"note":"Used to create asynchronous Thrift RPC clients with asyncio.","symbol":"make_aio_client","correct":"from thriftpy2.rpc import make_aio_client"},{"note":"The original 'thriftpy' library is deprecated. For compatibility, migrate to 'thriftpy2' and import it with an alias if needed.","wrong":"import thriftpy","symbol":"thriftpy","correct":"import thriftpy2 as thriftpy"}],"quickstart":{"code":"import asyncio\nimport thriftpy2\nfrom thriftpy2.rpc import make_aio_client\nimport os\n\n# Define a simple Thrift service IDL in a temporary file\nTHRIFT_FILE_PATH = \"pingpong.thrift\"\nwith open(THRIFT_FILE_PATH, \"w\") as f:\n    f.write(\"service PingPong {\\n    string ping(),\\n}\")\n\n# Load the thrift file dynamically\npingpong_thrift = thriftpy2.load(THRIFT_FILE_PATH, module_name=\"pingpong_thrift\")\n\nasync def main():\n    print(\"Attempting to create ThriftPy2 async client...\")\n    client = None\n    try:\n        # For this quickstart, we'll demonstrate client instantiation and a call pattern.\n        # Note: This client will attempt to connect to '127.0.0.1:6000'.\n        # A running ThriftPy2 server on this address would be required for a successful RPC call.\n        # This example focuses on demonstrating the client API, not a full RPC pair.\n        client = await make_aio_client(\n            pingpong_thrift.PingPong,\n            '127.0.0.1',\n            6000,\n            timeout=1000 # Milliseconds for connection/read timeout\n        )\n        print(\"Client created. Attempting to call ping()... (This will likely fail without a running server)\")\n        # Example of calling a service method\n        # result = await client.ping()\n        # print(f\"Ping result: {result}\")\n\n    except Exception as e:\n        print(f\"Error setting up client (expected if no server is running at 127.0.0.1:6000): {e}\")\n    finally:\n        if client:\n            client.close()\n        # Clean up the dummy thrift file\n        if os.path.exists(THRIFT_FILE_PATH):\n            os.remove(THRIFT_FILE_PATH)\n\nif __name__ == '__main__':\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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`.","message":"Support 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.","severity":"deprecated","affected_versions":">=0.6.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"If 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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'0.6.0':14 'activ':37 'allow':16 'apach':10,54 'asyncio':57 'beta':45 'clients/servers':26 'code':29 'compil':32 'creat':24 'develop':17,38 'dynam':27 'file':22 'generat':30 'idl':21,56 'implement':7 'includ':43 'lead':47 'librari':34 'maintain':35 'pars':19 'protocol':12,53 'pure':5 'python':6 'recent':44 'regular':41 'releas':46 'rpc':25,52 'stabl':49 'status':39 'thrift':11,20,51,55 'thriftpy2':1,2 'updat':42 'version':13,50 'without':28","created_at":"2026-04-09T18:52:36.087751+00:00","updated_at":"2026-04-16T22:56:23.929357+00:00","problems":[{"fix":"Install `thriftpy2` (`pip install thriftpy2`) and update all imports from `thriftpy` to `thriftpy2`.","cause":"The user is trying to import the old `thriftpy` library, or made a typo when intending to use `thriftpy2`.","error":"ModuleNotFoundError: No module named 'thriftpy'"},{"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.","cause":"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.","error":"thriftpy2.parser.exc.ThriftParserError: Line X: Expected identifier."},{"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()`).","cause":"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.","error":"TProtocolException: Bad version in readMessageBegin"},{"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.","cause":"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.","error":"AttributeError: 'Client' object has no attribute 'yourMethodName'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.7.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://thriftpy2.readthedocs.io/","github":"https://github.com/Thriftpy/thriftpy2","docs":null,"changelog":null,"pypi":"https://pypi.org/project/thriftpy2/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}