History

Tim Swast 29c83baecc python: add sphinx docs (#6525 ) * python: generate documentation with Sphinx and Read the Docs Background: Formerly, the Python protobuf reference documentation was built with [Epydoc](http://epydoc.sourceforge.net/). This package has not been updated since 2008, and it has inconsistent formatting (see internal issue 131415575) with most Python documentation. Sphinx is used for the official docs.python.org docs as well as most other Python packages, including the Google client libraries and related packages, such as https://googleapis.dev/python/google-api-core/latest/ To build the docs with Sphinx: 1. Install the needed packages (`sphinx`, `sphinxcontrib-napoleon` for Google-style docstring support). I've created a conda environment file to make this easier: ``` conda env create -f python/docs/environment.yml ``` 2. (Optional) Generate reference docs files and regenerate index: ``` cd python python generate_docs.py cd .. ``` 3. Run Sphinx. ``` cd python/docs make html ``` About this change: The script at `python/generate_docs.py` creates a ReStructured Text file for each public module in the protobuf Python package. The script also updates the table of contents in `python/docs/index.rst` to point to these module references. Future work: Testing the docs build on PRs requires contributors to actually do some setup work to configure builds on their fork. It'd be better if CI had a docs build session to verify that the Sphinx docs generation at least runs. There are many warnings due to not-quite-correct docstrings in the actual Python code itself. I'm choosing to ignore these errors to keep the PR small, but I recommend you fix these and then enable "fail on warnings" in the docs build on CI. * add docs to EXTRA_DIST * add instructions to build documentation to generate_docs.py * exclude python/odcs from cpp_distcheck		2020-02-11 11:40:17 -08:00
..
compatibility_tests/v2.5.0	Maven requires https connection (#7110 )	2020-01-20 19:23:06 -08:00
docs	python: add sphinx docs (#6525 )	2020-02-11 11:40:17 -08:00
google	Merge pull request #7064 from rafi-kamal/3.11.x-202001071136	2020-01-08 12:24:20 -08:00
release/wheel	Replace repo links.	2018-08-22 11:55:30 -07:00
MANIFEST.in	Include .cc and .h files in source distribution	2017-11-17 15:30:31 -08:00
mox.py	Fix typos (#7050 )	2020-01-08 10:18:20 -08:00
README.md	add compatibility check badges to README	2019-06-10 14:40:51 -07:00
release.sh	Add several fixes for python toolchain (#5667 )	2019-02-01 18:43:55 -08:00
setup.cfg	add setup.cfg for building wheels	2016-07-29 14:02:07 -07:00
setup.py	Down integrate to GitHub	2019-06-11 16:00:16 -07:00
stubout.py	import inspect (#3507 )	2018-06-11 14:17:46 -07:00
tox.ini	delete all duplicate empty blanks (#5758 )	2019-02-20 19:28:50 -08:00

README.md

Protocol Buffers - Google's data interchange format

This directory contains the Python Protocol Buffers runtime library.

Normally, this directory comes as part of the protobuf package, available from:

https://developers.google.com/protocol-buffers/

The complete package includes the C++ source code, which includes the Protocol Compiler (protoc). If you downloaded this package from PyPI or some other Python-specific source, you may have received only the Python part of the code. In this case, you will need to obtain the Protocol Compiler from some other source before you can use this package.

Development Warning

The Python implementation of Protocol Buffers is not as mature as the C++ and Java implementations. It may be more buggy, and it is known to be pretty slow at this time. If you would like to help fix these issues, join the Protocol Buffers discussion list and let us know!

Installation

Make sure you have Python 2.7 or newer. If in doubt, run:
```
$ python -V
```
If you do not have setuptools installed, note that it will be downloaded and installed automatically as soon as you run setup.py. If you would rather install it manually, you may do so by following the instructions on this page.
Build the C++ code, or install a binary distribution of protoc. If you install a binary distribution, make sure that it is the same version as this package. If in doubt, run:
```
$ protoc --version
```
Build and run the tests:
```
$ python setup.py build
$ python setup.py test
```
To build, test, and use the C++ implementation, you must first compile libprotobuf.so:
```
$ (cd .. && make)
```
On OS X:

If you are running a Homebrew-provided Python, you must make sure another version of protobuf is not already installed, as Homebrew's Python will search /usr/local/lib for libprotobuf.so before it searches ../src/.libs.

You can either unlink Homebrew's protobuf or install the libprotobuf you built earlier:
```
$ brew unlink protobuf
```
or
```
$ (cd .. && make install)
```
On other *nix:

You must make libprotobuf.so dynamically available. You can either install libprotobuf you built earlier, or set LD_LIBRARY_PATH:
```
$ export LD_LIBRARY_PATH=../src/.libs
```
or
```
$ (cd .. && make install)
```
To build the C++ implementation run:
```
$ python setup.py build --cpp_implementation
```
Then run the tests like so:
```
$ python setup.py test --cpp_implementation
```
If some tests fail, this library may not work correctly on your system. Continue at your own risk.

Please note that there is a known problem with some versions of Python on Cygwin which causes the tests to fail after printing the error: sem_init: Resource temporarily unavailable. This appears to be a bug either in Cygwin or in Python.

We do not know if or when it might be fixed. We also do not know how likely it is that this bug will affect users in practice.
Install:
```
$ python setup.py install
```
or:
```
$ (cd .. && make install)
$ python setup.py install --cpp_implementation
```
This step may require superuser privileges. NOTE: To use C++ implementation, you need to export an environment variable before running your program. See the "C++ Implementation" section below for more details.

Usage

The complete documentation for Protocol Buffers is available via the web at:

https://developers.google.com/protocol-buffers/

C++ Implementation

The C++ implementation for Python messages is built as a Python extension to improve the overall protobuf Python performance.

To use the C++ implementation, you need to install the C++ protobuf runtime library, please see instructions in the parent directory.