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