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