README.md
1# Python setuptools extension
2
3This is an extension for Python setuptools which uses an installed protobuf
4compiler (`protoc`) to generate Python sources.
5
6## Installing
7
8To use this extension, it needs to be installed so it can be imported by other
9projects' setup.py.
10
11```shell
12$ python setup.py build
13$ python -m pip install .
14```
15
16(If you want to test changes to the extension, you can use `python setup.py
17develop`.)
18
19## Usage
20
21### Example setup.py configuration
22
23```python
24from setuptools import setup
25setup(
26 # ...
27 name='example_project',
28
29 # Require this package, but only for setup (not installation):
30 setup_requires=['protobuf_distutils'],
31
32 options={
33 # See below for details.
34 'generate_py_protobufs': {
35 'source_dir': 'path/to/protos',
36 'extra_proto_paths': ['path/to/other/project/protos'],
37 'output_dir': 'path/to/project/sources', # default '.'
38 'proto_files': ['relative/path/to/just_this_file.proto'],
39 'protoc': 'path/to/protoc.exe',
40 },
41 },
42)
43```
44
45### Example build invocation
46
47These steps will generate protobuf sources so they are included when building
48and installing `example_project` (see above):
49
50```shell
51$ python setup.py generate_py_protobufs
52$ python setup.py build
53$ python -m pip install .
54```
55
56## Options
57
58- `source_dir`:
59
60 This is the directory holding .proto files to be processed.
61
62 The default behavior is to generate sources for all .proto files found under
63 `source_dir`, recursively. This behavior can be controlled with options below.
64
65- `proto_root_path`:
66
67 This is the root path for resolving imports in source .proto files.
68
69 The default is the shortest prefix of `source_dir` among `[source_dir] +
70 self.extra_proto_paths`.
71
72- `extra_proto_paths`:
73
74 Specifies additional paths that should be used to find imports, in
75 addition to `source_dir`.
76
77 This option can be used to specify the path to other protobuf sources,
78 which are imported by files under `source_dir`. No Python code will
79 be generated for .proto files under `extra_proto_paths`.
80
81- `output_dir`:
82
83 Specifies where generated code should be placed.
84
85 Typically, this should be the root package that generated Python modules
86 should be below.
87
88 The generated files will be placed under `output_dir` according to the
89 relative source paths under `proto_root_path`. For example, the source file
90 `${proto_root_path}/subdir/message.proto` will be generated as the Python
91 module `${output_dir}/subdir/message_pb2.py`.
92
93- `proto_files`:
94
95 A list of strings, specific .proto file paths for generating code, instead of
96 searching for all .proto files under `source_path`.
97
98 These paths are relative to `source_dir`. For example, to generate code
99 for just `${source_dir}/subdir/message.proto`, specify
100 `['subdir/message.proto']`.
101
102- `protoc`:
103
104 By default, the protoc binary (the Protobuf compiler) is found by
105 searching the environment path. To use a specific protoc binary, its
106 path can be specified. Resolution of the `protoc` value is as follows:
107 1. If the `--protoc=VALUE` flag is passed to `generate_py_protobufs`,
108 then `VALUE` will be used.
109 For example:
110 ```shell
111 $ python setup.py generate_py_protobufs --protoc=/path/to/protoc
112 ```
113 2. Otherwise, if a value was set in the `options`, it will be used.
114 (See "Example setup.py configuration," above.)
115 3. Otherwise, if the `PROTOC` environment variable is set, it will be
116 used. For example:
117 For example:
118 ```shell
119 $ PROTOC=/path/to/protoc python setup.py generate_py_protobufs
120 ```
121 4. Otherwise, `$PATH` will be searched.
122