1gRPC Python Tools 2================= 3 4Package for gRPC Python tools. 5 6Supported Python Versions 7------------------------- 8Python >= 3.6 9 10Installation 11------------ 12 13The gRPC Python tools package is available for Linux, Mac OS X, and Windows. 14 15Installing From PyPI 16~~~~~~~~~~~~~~~~~~~~ 17 18If you are installing locally... 19 20:: 21 22 $ pip install grpcio-tools 23 24Else system wide (on Ubuntu)... 25 26:: 27 28 $ sudo pip install grpcio-tools 29 30If you're on Windows make sure that you installed the :code:`pip.exe` component 31when you installed Python (if not go back and install it!) then invoke: 32 33:: 34 35 $ pip.exe install grpcio-tools 36 37Windows users may need to invoke :code:`pip.exe` from a command line ran as 38administrator. 39 40n.b. On Windows and on Mac OS X one *must* have a recent release of :code:`pip` 41to retrieve the proper wheel from PyPI. Be sure to upgrade to the latest 42version! 43 44You might also need to install Cython to handle installation via the source 45distribution if gRPC Python's system coverage with wheels does not happen to 46include your system. 47 48Installing From Source 49~~~~~~~~~~~~~~~~~~~~~~ 50 51Building from source requires that you have the Python headers (usually a 52package named :code:`python-dev`) and Cython installed. It further requires a 53GCC-like compiler to go smoothly; you can probably get it to work without 54GCC-like stuff, but you may end up having a bad time. 55 56:: 57 58 $ export REPO_ROOT=grpc # REPO_ROOT can be any directory of your choice 59 $ git clone -b RELEASE_TAG_HERE https://github.com/grpc/grpc $REPO_ROOT 60 $ cd $REPO_ROOT 61 $ git submodule update --init 62 63 $ cd tools/distrib/python/grpcio_tools 64 $ python ../make_grpcio_tools.py 65 66 # For the next command do `sudo pip install` if you get permission-denied errors 67 $ GRPC_PYTHON_BUILD_WITH_CYTHON=1 pip install . 68 69You cannot currently install Python from source on Windows. Things might work 70out for you in MSYS2 (follow the Linux instructions), but it isn't officially 71supported at the moment. 72 73Troubleshooting 74~~~~~~~~~~~~~~~ 75 76Help, I ... 77 78* **... see compiler errors on some platforms when either installing from source or from the source distribution** 79 80 If you see 81 82 :: 83 84 /tmp/pip-build-U8pSsr/cython/Cython/Plex/Scanners.c:4:20: fatal error: Python.h: No such file or directory 85 #include "Python.h" 86 ^ 87 compilation terminated. 88 89 You can fix it by installing `python-dev` package. i.e 90 91 :: 92 93 sudo apt-get install python-dev 94 95 If you see something similar to: 96 97 :: 98 99 third_party/protobuf/src/google/protobuf/stubs/mathlimits.h:173:31: note: in expansion of macro 'SIGNED_INT_MAX' 100 static const Type kPosMax = SIGNED_INT_MAX(Type); \\ 101 ^ 102 103 And your toolchain is GCC (at the time of this writing, up through at least 104 GCC 6.0), this is probably a bug where GCC chokes on constant expressions 105 when the :code:`-fwrapv` flag is specified. You should consider setting your 106 environment with :code:`CFLAGS=-fno-wrapv` or using clang (:code:`CC=clang`). 107 108Usage 109----- 110 111Given protobuf include directories :code:`$INCLUDE`, an output directory 112:code:`$OUTPUT`, and proto files :code:`$PROTO_FILES`, invoke as: 113 114:: 115 116 $ python -m grpc_tools.protoc -I$INCLUDE --python_out=$OUTPUT --grpc_python_out=$OUTPUT $PROTO_FILES 117 118To use as a build step in setuptools-based projects, you may use the provided 119command class in your :code:`setup.py`: 120 121:: 122 123 setuptools.setup( 124 # ... 125 cmdclass={ 126 'build_proto_modules': grpc_tools.command.BuildPackageProtos, 127 } 128 # ... 129 ) 130 131Invocation of the command will walk the project tree and transpile every 132:code:`.proto` file into a :code:`_pb2.py` file in the same directory. 133 134Note that this particular approach requires :code:`grpcio-tools` to be 135installed on the machine before the setup script is invoked (i.e. no 136combination of :code:`setup_requires` or :code:`install_requires` will provide 137access to :code:`grpc_tools.command.BuildPackageProtos` if it isn't already 138installed). One way to work around this can be found in our 139:code:`grpcio-health-checking` 140`package <https://pypi.python.org/pypi/grpcio-health-checking>`_: 141 142:: 143 144 class BuildPackageProtos(setuptools.Command): 145 """Command to generate project *_pb2.py modules from proto files.""" 146 # ... 147 def run(self): 148 from grpc_tools import command 149 command.build_package_protos(self.distribution.package_dir['']) 150 151Now including :code:`grpcio-tools` in :code:`setup_requires` will provide the 152command on-setup as desired. 153 154For more information on command classes, consult :code:`setuptools` documentation. 155