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 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