README.rst 5.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224
  1. ============
  2. ThriftPy2
  3. ============
  4. .. image:: https://travis-ci.com/Thriftpy/thriftpy2.svg?branch=develop
  5. :target: https://travis-ci.com/Thriftpy/thriftpy2
  6. .. image:: https://img.shields.io/codecov/c/github/Thriftpy/thriftpy2.svg
  7. :target: https://codecov.io/gh/Thriftpy/thriftpy2
  8. .. image:: https://img.shields.io/pypi/dm/thriftpy2.svg
  9. :target: https://pypi.org/project/thriftpy2/
  10. .. image:: https://img.shields.io/pypi/v/thriftpy2.svg
  11. :target: https://pypi.org/project/thriftpy2/
  12. .. image:: https://img.shields.io/pypi/pyversions/thriftpy2.svg
  13. :target: https://pypi.org/project/thriftpy2/
  14. .. image:: https://img.shields.io/pypi/implementation/thriftpy2.svg
  15. :target: https://pypi.org/project/thriftpy2/
  16. ThriftPy: https://github.com/eleme/thriftpy has been deprecated, ThriftPy2 aims to provide long term support.
  17. Migrate from Thriftpy?
  18. ======================
  19. All you need is:
  20. .. code:: python
  21. import thriftpy2 as thriftpy
  22. That's it! thriftpy2 is fully compatible with thriftpy.
  23. Installation
  24. ============
  25. Install with pip.
  26. .. code:: bash
  27. $ pip install thriftpy2
  28. You may also install cython first to build cython extension locally.
  29. .. code:: bash
  30. $ pip install cython thriftpy2
  31. Code Demo
  32. =========
  33. ThriftPy make it super easy to write server/client code with thrift. Let's
  34. checkout this simple pingpong service demo.
  35. We need a 'pingpong.thrift' file:
  36. ::
  37. service PingPong {
  38. string ping(),
  39. }
  40. Then we can make a server:
  41. .. code:: python
  42. import thriftpy2
  43. pingpong_thrift = thriftpy2.load("pingpong.thrift", module_name="pingpong_thrift")
  44. from thriftpy2.rpc import make_server
  45. class Dispatcher(object):
  46. def ping(self):
  47. return "pong"
  48. server = make_server(pingpong_thrift.PingPong, Dispatcher(), '127.0.0.1', 6000)
  49. server.serve()
  50. And a client:
  51. .. code:: python
  52. import thriftpy2
  53. pingpong_thrift = thriftpy2.load("pingpong.thrift", module_name="pingpong_thrift")
  54. from thriftpy2.rpc import make_client
  55. client = make_client(pingpong_thrift.PingPong, '127.0.0.1', 6000)
  56. print(client.ping())
  57. And it also supports asyncio on Python 3.5 or later:
  58. .. code:: python
  59. import thriftpy2
  60. import asyncio
  61. from thriftpy2.rpc import make_aio_client
  62. echo_thrift = thriftpy2.load("echo.thrift", module_name="echo_thrift")
  63. async def request():
  64. client = await make_aio_client(
  65. echo_thrift.EchoService, '127.0.0.1', 6000)
  66. print(await client.echo('hello, world'))
  67. client.close()
  68. .. code:: python
  69. import asyncio
  70. import thriftpy2
  71. from thriftpy2.rpc import make_aio_server
  72. echo_thrift = thriftpy2.load("echo.thrift", module_name="echo_thrift")
  73. class Dispatcher(object):
  74. async def echo(self, param):
  75. print(param)
  76. await asyncio.sleep(0.1)
  77. return param
  78. def main():
  79. server = make_aio_server(
  80. echo_thrift.EchoService, Dispatcher(), '127.0.0.1', 6000)
  81. server.serve()
  82. if __name__ == '__main__':
  83. main()
  84. See, it's that easy!
  85. You can refer to 'examples' and 'tests' directory in source code for more
  86. usage examples.
  87. Features
  88. ========
  89. Currently ThriftPy have these features (also advantages over the upstream
  90. python lib):
  91. - Supports Python 2.7, Python 3.4+, PyPy and PyPy3.
  92. - Pure python implementation. No longer need to compile & install the 'thrift'
  93. package. All you need is thriftpy2 and thrift file.
  94. - Compatible with Apache Thrift. You can use ThriftPy together with the
  95. official implementation servers and clients, such as a upstream server with
  96. a thriftpy2 client or the opposite.
  97. Currently implemented protocols and transports:
  98. * binary protocol (python and cython)
  99. * compact protocol (python and cython)
  100. * json protocol
  101. * buffered transport (python & cython)
  102. * framed transport
  103. * tornado server and client (with tornado 4.0)
  104. * http server and client
  105. * asyncio support (python 3.5 or later)
  106. - Can directly load thrift file as module, the sdk code will be generated on
  107. the fly.
  108. For example, ``pingpong_thrift = thriftpy2.load("pingpong.thrift", module_name="pingpong_thrift")``
  109. will load 'pingpong.thrift' as 'pingpong_thrift' module.
  110. Or, when import hook enabled by ``thriftpy2.install_import_hook()``, you can
  111. directly use ``import pingpong_thrift`` to import the 'pingpong.thrift' file
  112. as module, you may also use ``from pingpong_thrift import PingService`` to
  113. import specific object from the thrift module.
  114. - Easy RPC server/client setup.
  115. Contribute
  116. ==========
  117. 1. Fork the repo and make changes.
  118. 2. Write a test which shows a bug was fixed or the feature works as expected.
  119. 3. Make sure ``travis-ci`` or ``tox`` tests succeed.
  120. 4. Send pull request.
  121. Contributors
  122. ============
  123. https://github.com/Thriftpy/thriftpy2/graphs/contributors
  124. Sponsors:
  125. ============
  126. .. image:: ./docs/jetbrains.svg
  127. :target: https://www.jetbrains.com/?from=ThriftPy
  128. Changelog
  129. =========
  130. https://github.com/Thriftpy/thriftpy2/blob/master/CHANGES.rst