protobuf/python/protobuf_distutils/README.md

Python setuptools extension

This is an extension for Python setuptools which uses an installed protobuf compiler (protoc) to generate Python sources.

Installing

To use this extension, it needs to be installed so it can be imported by other projects' setup.py.

$ python setup.py build
$ python -m pip install .

(If you want to test changes to the extension, you can use python setup.py develop.)

Usage

Example setup.py configuration

from setuptools import setup
setup(
    # ...
    name='example_project',

    # Require this package, but only for setup (not installation):
    setup_requires=['protobuf_distutils'],

    options={
        # See below for details.
        'generate_py_protobufs': {
            'source_dir':        'path/to/protos',
            'extra_proto_paths': ['path/to/other/project/protos'],
            'output_dir':        'path/to/project/sources',  # default '.'
            'proto_files':       ['relative/path/to/just_this_file.proto'],
            'protoc':            'path/to/protoc.exe',
        },
    },
)

Example build invocation

These steps will generate protobuf sources so they are included when building and installing example_project (see above):

$ python setup.py generate_py_protobufs
$ python setup.py build
$ python -m pip install .

Options

• source_dir:

  This is the directory holding .proto files to be processed.

  The default behavior is to generate sources for all .proto files found under source_dir, recursively. This behavior can be controlled with options below.

• proto_root_path:

  This is the root path for resolving imports in source .proto files.

  The default is the shortest prefix of source_dir among [source_dir] + self.extra_proto_paths.

• extra_proto_paths:

  Specifies additional paths that should be used to find imports, in addition to source_dir.

  This option can be used to specify the path to other protobuf sources, which are imported by files under source_dir. No Python code will be generated for .proto files under extra_proto_paths.

• output_dir:

  Specifies where generated code should be placed.

  Typically, this should be the root package that generated Python modules should be below.

  The generated files will be placed under output_dir according to the relative source paths under proto_root_path. For example, the source file ${proto_root_path}/subdir/message.proto will be generated as the Python module ${output_dir}/subdir/message_pb2.py.

• proto_files:

  A list of strings, specific .proto file paths for generating code, instead of searching for all .proto files under source_path.

  These paths are relative to source_dir. For example, to generate code for just ${source_dir}/subdir/message.proto, specify ['subdir/message.proto'].

• protoc:

  By default, the protoc binary (the Protobuf compiler) is found by searching the environment path. To use a specific protoc binary, its path can be specified. Resolution of the protoc value is as follows:

  1. If the --protoc=VALUE flag is passed to generate_py_protobufs, then VALUE will be used. For example:

     $ python setup.py generate_py_protobufs --protoc=/path/to/protoc
     

  2. Otherwise, if a value was set in the options, it will be used. (See "Example setup.py configuration," above.)
  3. Otherwise, if the PROTOC environment variable is set, it will be used. For example: For example:

     $ PROTOC=/path/to/protoc python setup.py generate_py_protobufs
     

  4. Otherwise, $PATH will be searched.