README.rst
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 a** :code:`pkg_resources.VersionConflict` **when I try to install
79 grpc**
80
81 This is likely because :code:`pip` doesn't own the offending dependency,
82 which in turn is likely because your operating system's package manager owns
83 it. You'll need to force the installation of the dependency:
84
85 :code:`pip install --ignore-installed $OFFENDING_DEPENDENCY`
86
87 For example, if you get an error like the following:
88
89 ::
90
91 Traceback (most recent call last):
92 File "<string>", line 17, in <module>
93 ...
94 File "/usr/lib/python2.7/dist-packages/pkg_resources.py", line 509, in find
95 raise VersionConflict(dist, req)
96 pkg_resources.VersionConflict: (six 1.8.0 (/usr/lib/python2.7/dist-packages), Requirement.parse('six>=1.10'))
97
98 You can fix it by doing:
99
100 ::
101
102 sudo pip install --ignore-installed six
103
104* **... see compiler errors on some platforms when either installing from source or from the source distribution**
105
106 If you see
107
108 ::
109
110 /tmp/pip-build-U8pSsr/cython/Cython/Plex/Scanners.c:4:20: fatal error: Python.h: No such file or directory
111 #include "Python.h"
112 ^
113 compilation terminated.
114
115 You can fix it by installing `python-dev` package. i.e
116
117 ::
118
119 sudo apt-get install python-dev
120
121 If you see something similar to:
122
123 ::
124
125 third_party/protobuf/src/google/protobuf/stubs/mathlimits.h:173:31: note: in expansion of macro 'SIGNED_INT_MAX'
126 static const Type kPosMax = SIGNED_INT_MAX(Type); \\
127 ^
128
129 And your toolchain is GCC (at the time of this writing, up through at least
130 GCC 6.0), this is probably a bug where GCC chokes on constant expressions
131 when the :code:`-fwrapv` flag is specified. You should consider setting your
132 environment with :code:`CFLAGS=-fno-wrapv` or using clang (:code:`CC=clang`).
133
134Usage
135-----
136
137Given protobuf include directories :code:`$INCLUDE`, an output directory
138:code:`$OUTPUT`, and proto files :code:`$PROTO_FILES`, invoke as:
139
140::
141
142 $ python -m grpc.tools.protoc -I$INCLUDE --python_out=$OUTPUT --grpc_python_out=$OUTPUT $PROTO_FILES
143
144To use as a build step in distutils-based projects, you may use the provided
145command class in your :code:`setup.py`:
146
147::
148
149 setuptools.setup(
150 # ...
151 cmdclass={
152 'build_proto_modules': grpc.tools.command.BuildPackageProtos,
153 }
154 # ...
155 )
156
157Invocation of the command will walk the project tree and transpile every
158:code:`.proto` file into a :code:`_pb2.py` file in the same directory.
159
160Note that this particular approach requires :code:`grpcio-tools` to be
161installed on the machine before the setup script is invoked (i.e. no
162combination of :code:`setup_requires` or :code:`install_requires` will provide
163access to :code:`grpc.tools.command.BuildPackageProtos` if it isn't already
164installed). One way to work around this can be found in our
165:code:`grpcio-health-checking`
166`package <https://pypi.python.org/pypi/grpcio-health-checking>`_:
167
168::
169
170 class BuildPackageProtos(setuptools.Command):
171 """Command to generate project *_pb2.py modules from proto files."""
172 # ...
173 def run(self):
174 from grpc.tools import command
175 command.build_package_protos(self.distribution.package_dir[''])
176
177Now including :code:`grpcio-tools` in :code:`setup_requires` will provide the
178command on-setup as desired.
179
180For more information on command classes, consult :code:`distutils` and
181:code:`setuptools` documentation.
182