OLD | NEW |
1 Protocol Buffers - Google's data interchange format | 1 Protocol Buffers - Google's data interchange format |
| 2 =================================================== |
| 3 |
| 4 [![Build Status](https://travis-ci.org/google/protobuf.svg?branch=master)](https
://travis-ci.org/google/protobuf) |
| 5 |
2 Copyright 2008 Google Inc. | 6 Copyright 2008 Google Inc. |
3 | 7 |
4 This directory contains the Python Protocol Buffers runtime library. | 8 This directory contains the Python Protocol Buffers runtime library. |
5 | 9 |
6 Normally, this directory comes as part of the protobuf package, available | 10 Normally, this directory comes as part of the protobuf package, available |
7 from: | 11 from: |
8 | 12 |
9 http://code.google.com/p/protobuf | 13 https://developers.google.com/protocol-buffers/ |
10 | 14 |
11 The complete package includes the C++ source code, which includes the | 15 The complete package includes the C++ source code, which includes the |
12 Protocol Compiler (protoc). If you downloaded this package from PyPI | 16 Protocol Compiler (protoc). If you downloaded this package from PyPI |
13 or some other Python-specific source, you may have received only the | 17 or some other Python-specific source, you may have received only the |
14 Python part of the code. In this case, you will need to obtain the | 18 Python part of the code. In this case, you will need to obtain the |
15 Protocol Compiler from some other source before you can use this | 19 Protocol Compiler from some other source before you can use this |
16 package. | 20 package. |
17 | 21 |
18 Development Warning | 22 Development Warning |
19 =================== | 23 =================== |
20 | 24 |
21 The Python implementation of Protocol Buffers is not as mature as the C++ | 25 The Python implementation of Protocol Buffers is not as mature as the C++ |
22 and Java implementations. It may be more buggy, and it is known to be | 26 and Java implementations. It may be more buggy, and it is known to be |
23 pretty slow at this time. If you would like to help fix these issues, | 27 pretty slow at this time. If you would like to help fix these issues, |
24 join the Protocol Buffers discussion list and let us know! | 28 join the Protocol Buffers discussion list and let us know! |
25 | 29 |
26 Installation | 30 Installation |
27 ============ | 31 ============ |
28 | 32 |
29 1) Make sure you have Python 2.4 or newer. If in doubt, run: | 33 1) Make sure you have Python 2.6 or newer. If in doubt, run: |
30 | 34 |
31 $ python -V | 35 $ python -V |
32 | 36 |
33 2) If you do not have setuptools installed, note that it will be | 37 2) If you do not have setuptools installed, note that it will be |
34 downloaded and installed automatically as soon as you run setup.py. | 38 downloaded and installed automatically as soon as you run setup.py. |
35 If you would rather install it manually, you may do so by following | 39 If you would rather install it manually, you may do so by following |
36 the instructions on this page: | 40 the instructions on this page: |
37 | 41 |
38 http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructio
ns | 42 https://packaging.python.org/en/latest/installing.html#setup-for-installing
-packages |
39 | 43 |
40 3) Build the C++ code, or install a binary distribution of protoc. If | 44 3) Build the C++ code, or install a binary distribution of protoc. If |
41 you install a binary distribution, make sure that it is the same | 45 you install a binary distribution, make sure that it is the same |
42 version as this package. If in doubt, run: | 46 version as this package. If in doubt, run: |
43 | 47 |
44 $ protoc --version | 48 $ protoc --version |
45 | 49 |
46 4) Run the tests: | 50 4) Build and run the tests: |
47 | 51 |
| 52 $ python setup.py build |
48 $ python setup.py test | 53 $ python setup.py test |
49 | 54 |
| 55 To build, test, and use the C++ implementation, you must first compile |
| 56 libprotobuf.so: |
| 57 |
| 58 $ (cd .. && make) |
| 59 |
| 60 On OS X: |
| 61 |
| 62 If you are running a homebrew-provided python, you must make sure another |
| 63 version of protobuf is not already installed, as homebrew's python will |
| 64 search /usr/local/lib for libprotobuf.so before it searches ../src/.libs |
| 65 You can either unlink homebrew's protobuf or install the libprotobuf you |
| 66 built earlier: |
| 67 |
| 68 $ brew unlink protobuf |
| 69 or |
| 70 $ (cd .. && make install) |
| 71 |
| 72 On other *nix: |
| 73 |
| 74 You must make libprotobuf.so dynamically available. You can either |
| 75 install libprotobuf you built earlier, or set LD_LIBRARY_PATH: |
| 76 |
| 77 $ export LD_LIBRARY_PATH=../src/.libs |
| 78 or |
| 79 $ (cd .. && make install) |
| 80 |
| 81 To build the C++ implementation run: |
| 82 $ python setup.py build --cpp_implementation |
| 83 |
| 84 Then run the tests like so: |
| 85 $ python setup.py test --cpp_implementation |
| 86 |
50 If some tests fail, this library may not work correctly on your | 87 If some tests fail, this library may not work correctly on your |
51 system. Continue at your own risk. | 88 system. Continue at your own risk. |
52 | 89 |
53 Please note that there is a known problem with some versions of | 90 Please note that there is a known problem with some versions of |
54 Python on Cygwin which causes the tests to fail after printing the | 91 Python on Cygwin which causes the tests to fail after printing the |
55 error: "sem_init: Resource temporarily unavailable". This appears | 92 error: "sem_init: Resource temporarily unavailable". This appears |
56 to be a bug either in Cygwin or in Python: | 93 to be a bug either in Cygwin or in Python: |
57 http://www.cygwin.com/ml/cygwin/2005-07/msg01378.html | 94 http://www.cygwin.com/ml/cygwin/2005-07/msg01378.html |
58 We do not know if or when it might me fixed. We also do not know | 95 We do not know if or when it might me fixed. We also do not know |
59 how likely it is that this bug will affect users in practice. | 96 how likely it is that this bug will affect users in practice. |
60 | 97 |
61 5) Install: | 98 5) Install: |
62 | 99 |
63 $ python setup.py install | 100 $ python setup.py install |
| 101 |
| 102 or: |
| 103 |
| 104 $ (cd .. && make install) |
| 105 $ python setup.py install --cpp_implementation |
64 | 106 |
65 This step may require superuser privileges. | 107 This step may require superuser privileges. |
66 NOTE: To use C++ implementation, you need to install C++ protobuf runtime | 108 NOTE: To use C++ implementation, you need to export an environment |
67 library of the same version and export the environment variable before this | 109 variable before running your program. See the "C++ Implementation" |
68 step. See the "C++ Implementation" section below for more details. | 110 section below for more details. |
69 | 111 |
70 Usage | 112 Usage |
71 ===== | 113 ===== |
72 | 114 |
73 The complete documentation for Protocol Buffers is available via the | 115 The complete documentation for Protocol Buffers is available via the |
74 web at: | 116 web at: |
75 | 117 |
76 http://code.google.com/apis/protocolbuffers/ | 118 https://developers.google.com/protocol-buffers/ |
77 | 119 |
78 C++ Implementation | 120 C++ Implementation |
79 ================== | 121 ================== |
80 | 122 |
81 WARNING: This is EXPERIMENTAL and only available for CPython platforms. | |
82 | |
83 The C++ implementation for Python messages is built as a Python extension to | 123 The C++ implementation for Python messages is built as a Python extension to |
84 improve the overall protobuf Python performance. | 124 improve the overall protobuf Python performance. |
85 | 125 |
86 To use the C++ implementation, you need to: | 126 To use the C++ implementation, you need to: |
87 1) Install the C++ protobuf runtime library, please see instructions in the | 127 1) Install the C++ protobuf runtime library, please see instructions in the |
88 parent directory. | 128 parent directory. |
89 2) Export an environment variable: | 129 2) Export an environment variable: |
90 | 130 |
91 $ export PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=cpp | 131 $ export PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=cpp |
92 | 132 |
93 You need to export this variable before running setup.py script to build and | 133 You must set this variable at runtime, before running your program, otherwise |
94 install the extension. You must also set the variable at runtime, otherwise | |
95 the pure-Python implementation will be used. In a future release, we will | 134 the pure-Python implementation will be used. In a future release, we will |
96 change the default so that C++ implementation is used whenever it is available. | 135 change the default so that C++ implementation is used whenever it is available. |
97 It is strongly recommended to run `python setup.py test` after setting the | |
98 variable to "cpp", so the tests will be against C++ implemented Python | |
99 messages. | |
100 | |
OLD | NEW |