README.rst 3.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154
  1. ========
  2. ThriftPy
  3. ========
  4. .. image:: http://img.shields.io/travis/eleme/thriftpy/develop.svg?style=flat
  5. :target: https://travis-ci.org/eleme/thriftpy
  6. .. image:: http://img.shields.io/github/release/eleme/thriftpy.svg?style=flat
  7. :target: https://github.com/eleme/thriftpy/releases
  8. .. image:: http://img.shields.io/pypi/v/thriftpy.svg?style=flat
  9. :target: https://pypi.python.org/pypi/thriftpy
  10. .. image:: http://img.shields.io/pypi/dm/thriftpy.svg?style=flat
  11. :target: https://pypi.python.org/pypi/thriftpy
  12. ThriftPy is a pure python implementation of
  13. `Apache Thrift <http://thrift.apache.org/>`_ in a pythonic way.
  14. Documentation: https://thriftpy.readthedocs.org/
  15. Installation
  16. ============
  17. Install with pip.
  18. .. code:: bash
  19. $ pip install thriftpy
  20. You may also install cython first to build cython extension locally.
  21. .. code:: bash
  22. $ pip install cython thriftpy
  23. Code Demo
  24. =========
  25. ThriftPy make it super easy to write server/client code with thrift. Let's
  26. checkout this simple pingpong service demo.
  27. We need a 'pingpong.thrift' file:
  28. ::
  29. service PingPong {
  30. string ping(),
  31. }
  32. Then we can make a server:
  33. .. code:: python
  34. import thriftpy
  35. pingpong_thrift = thriftpy.load("pingpong.thrift", module_name="pingpong_thrift")
  36. from thriftpy.rpc import make_server
  37. class Dispatcher(object):
  38. def ping(self):
  39. return "pong"
  40. server = make_server(pingpong_thrift.PingPong, Dispatcher(), '127.0.0.1', 6000)
  41. server.serve()
  42. And a client:
  43. .. code:: python
  44. import thriftpy
  45. pingpong_thrift = thriftpy.load("pingpong.thrift", module_name="pingpong_thrift")
  46. from thriftpy.rpc import make_client
  47. client = make_client(pingpong_thrift.PingPong, '127.0.0.1', 6000)
  48. print(client.ping())
  49. See, it's that easy!
  50. You can refer to 'examples' and 'tests' directory in source code for more
  51. usage examples.
  52. Features
  53. ========
  54. Currently ThriftPy have these features (also advantages over the upstream
  55. python lib):
  56. - Supports python2.6+, python3.3+, pypy and pypy3.
  57. - Pure python implementation. No longer need to compile & install the 'thrift'
  58. package. All you need is thriftpy and thrift file.
  59. - Compatible with Apache Thrift. You can use ThriftPy together with the
  60. official implementation servers and clients, such as a upstream server with
  61. a thriftpy client or the opposite.
  62. Currently implemented protocols and transports:
  63. * binary protocol (python and cython)
  64. * compact protocol (python and cython)
  65. * json protocol
  66. * buffered transport (python & cython)
  67. * framed transport
  68. * tornado server and client (with tornado 4.0)
  69. - Can directly load thrift file as module, the sdk code will be generated on
  70. the fly.
  71. For example, ``pingpong_thrift = thriftpy.load("pingpong.thrift", module_name="pingpong_thrift")``
  72. will load 'pingpong.thrift' as 'pingpong_thrift' module.
  73. Or, when import hook enabled by ``thriftpy.install_import_hook()``, you can
  74. directly use ``import pingpong_thrift`` to import the 'pingpong.thrift' file
  75. as module, you may also use ``from pingpong_thrift import PingService`` to
  76. import specific object from the thrift module.
  77. - Easy RPC server/client setup.
  78. Contribute
  79. ==========
  80. 1. Fork the repo and make changes.
  81. 2. Write a test which shows a bug was fixed or the feature works as expected.
  82. 3. Make sure ``travis-ci`` or ``tox`` tests succeed.
  83. 4. Send pull request.
  84. Contributors
  85. ============
  86. https://github.com/eleme/thriftpy/graphs/contributors
  87. Changelog
  88. =========
  89. https://github.com/eleme/thriftpy/blob/master/CHANGES.rst