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