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