Python Google Protocol Buffer

本篇主要介绍如何在Python语言中使用Google Protocol Buffer（后续都简写为PB）， 包括以下几个部分：

  • 为什么要使用PB？
  • 安装Google PB
  • 自定义.proto 文件
  • 编译.proto文件
  • 解析目标py文件
  • 序列化和反序列化
  • 更复杂的Message
  • 动态编译

为什么要使用PB？

PB（Protocol Buffer）是 Google 开发的用于结构化数据交换格式，作为腾讯云日志服务标准写入格式。因此用于写入日志数据前，需要将日志原始数据序列化为 PB 数据流后通过 API 写入服务端。而各个端类程序中不便操作PB格式，因此需要在端类和日志服务之间加入一层PB转化层。

当然PB格式也有自己的优点，主要是简单和快，具体测试结果参见Google序列化基准分析

安装Google PB

如果要想在Python中使用PB，需要先安装PB编译器protoc去编译你的.proto文件，安装方法如下：

下载最新的protobuf release包安装即可，当前版本为3.5.1，安装步骤如下

wget https://github.com/google/protobuf/releases/download/v3.5.1/protobuf-all-3.5.1.tar.gz
tar xvfz protobuf-all-3.5.1.tar.gz
cd protobuf-3.5.1/
./configure --prefix=/usr
make
make check
make install

check步骤全部通过即表示编译通过。

继续安装protobuf的python模块

cd ./python 
python setup.py build 
python setup.py test 
python setup.py install

安装完成验证protoc命令

root@ubuntu:~# protoc --version
libprotoc 3.5.1

protobuf的默认安装位置是 /usr/local，/usr/local/lib 不在Ubuntu系统默认的 LD_LIBRARY_PATH 里，如果在Ubuntu系统中configure时未指定安装路径为/usr， 则会出现以下错误

protoc: error while loading shared libraries: libprotoc.so.8: cannot open shared object file: No such file or directory

可以使用ldconfig命令解决，参考Protobuf cannot find shared libraries，这个错误在安装包的README中有提到。当然重新安装也可以

验证Python模块是否被正确安装

import google.protobuf

在python解释器中如果上面的import没有报错，说明安装正常。

自定义.proto 文件

首先我们需要编写一个 proto 文件，定义我们程序中需要处理的结构化数据，在 protobuf 的术语中，结构化数据被称为 Message。proto 文件非常类似 java 或者 C++ 语言的数据定义。proto示例文件cls.Log.proto如下：

syntax = "proto2";
package cls;
message Log
{
    optional uint64 time = 1; // UNIX Time Format
    required string topic_id = 2;
    required string content = 3;
}

.proto文件开头是包的声明，为了帮助防止在不同的工程中命名冲突。在Python中，包通常由目录结构决定的，所以这个.proto文件定义的包，在实际Python代码中是没有效果的。但是，按照官方的建议是坚持声明这条语句，主要作用是为了在PB的命名空间中防止名称冲突。package 名字叫做 cls，定义了一个消息 Log，该消息有三个成员，各个成员的含义如下：

字段名类型位置是否必须含义
timeuint64body否日志时间，不指定，则使用服务器收到请求的时间
topic_idstringbody是日志上报到的日志主题id
contentstringbody是日志内容

一个比较好的习惯是认真对待 proto 文件的文件名。比如将命名规则定为：packageName.MessageName.proto

编译.proto文件

使用编译器protoc直接编译即可，需要指定源文件路径和目标文件路径

SRC_DIR=/tmp/src_dir
DST_DIR=/tmp/dst_dir
protoc -I=$SRC_DIR --python_out=$DST_DIR $SRC_DIR/cls.Log.proto

生成Python类就使用--python_out选项，如果要生成C++类时使用--cpp_out选项

解析目标py文件

在目标文件夹中生成的文件目录对应如下：

root@ubuntu:/tmp/dst_dir# tree
.
└── cls
    └── Log_pb2.py

1 directory, 1 file

其中Log_pb2.py文件的内容如下（不允许编辑）：

# Generated by the protocol buffer compiler.  DO NOT EDIT!
# source: cls.Log.proto

import sys
_b=sys.version_info[0]<3 and (lambda x:x) or (lambda x:x.encode('latin1'))
from google.protobuf import descriptor as _descriptor
from google.protobuf import message as _message
from google.protobuf import reflection as _reflection
from google.protobuf import symbol_database as _symbol_database
from google.protobuf import descriptor_pb2
# @@protoc_insertion_point(imports)

_sym_db = _symbol_database.Default()




DESCRIPTOR = _descriptor.FileDescriptor(
  name='cls.Log.proto',
  package='cls',
  syntax='proto2',
  serialized_pb=_b('\n\rcls.Log.proto\x12\x03\x63ls\"6\n\x03Log\x12\x0c\n\x04time\x18\x01 \x01(\x04\x12\x10\n\x08topic_id\x18\x02 \x02(\t\x12\x0f\n\x07\x63ontent\x18\x03 \x02(\t')
)




_LOG = _descriptor.Descriptor(
  name='Log',
  full_name='cls.Log',
  filename=None,
  file=DESCRIPTOR,
  containing_type=None,
  fields=[
    _descriptor.FieldDescriptor(
      name='time', full_name='cls.Log.time', index=0,
      number=1, type=4, cpp_type=4, label=1,
      has_default_value=False, default_value=0,
      message_type=None, enum_type=None, containing_type=None,
      is_extension=False, extension_scope=None,
      options=None, file=DESCRIPTOR),
    _descriptor.FieldDescriptor(
      name='topic_id', full_name='cls.Log.topic_id', index=1,
      number=2, type=9, cpp_type=9, label=2,
      has_default_value=False, default_value=_b("").decode('utf-8'),
      message_type=None, enum_type=None, containing_type=None,
      is_extension=False, extension_scope=None,
      options=None, file=DESCRIPTOR),
    _descriptor.FieldDescriptor(
      name='content', full_name='cls.Log.content', index=2,
      number=3, type=9, cpp_type=9, label=2,
      has_default_value=False, default_value=_b("").decode('utf-8'),
      message_type=None, enum_type=None, containing_type=None,
      is_extension=False, extension_scope=None,
      options=None, file=DESCRIPTOR),
  ],
  extensions=[
  ],
  nested_types=[],
  enum_types=[
  ],
  options=None,
  is_extendable=False,
  syntax='proto2',
  extension_ranges=[],
  oneofs=[
  ],
  serialized_start=22,
  serialized_end=76,
)

DESCRIPTOR.message_types_by_name['Log'] = _LOG
_sym_db.RegisterFileDescriptor(DESCRIPTOR)

Log = _reflection.GeneratedProtocolMessageType('Log', (_message.Message,), dict(
  DESCRIPTOR = _LOG,
  __module__ = 'cls.Log_pb2'
  # @@protoc_insertion_point(class_scope:cls.Log)
  ))
_sym_db.RegisterMessage(Log)


# @@protoc_insertion_point(module_scope)

关于pb生成的py文件的源代码的解析暂时搁置，可以参见附件中的资料

序列化和反序列化

#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""
Created on 1/30/18 4:23 PM
@author: Chen Liang
@function: pb test
"""

import sys

reload(sys)
sys.setdefaultencoding('utf-8')
import Log_pb2
import json


def serialize_to_string(msg_obj):
    ret_str = msg_obj.SerializeToString()
    return ret_str


def parse_from_string(s):
    log = Log_pb2.Log()
    log.ParseFromString(s)
    return log

if __name__ == '__main__':
    # serialize_to_string
    content_dict = {"live_id": "1239182389648923", "identify": "zxc_unique"}
    tencent_log = Log_pb2.Log()
    tencent_log.time = 1510109254
    tencent_log.topic_id = "John Doe"
    tencent_log.content = json.dumps(content_dict)
    ret_s = serialize_to_string(tencent_log)
    print(type(ret_s))
    print(ret_s)

    # parse_from_string
    log_obj = parse_from_string(ret_s)
    print(log_obj)

其中关键的操作在于message对象的写入和读取以及序列化函数SerializeToString和反序列化函数ParseFromString

更复杂的Message

到这里为止，我们只给出了一个简单的上传日志的例子。在实际应用中，人们往往需要定义更加复杂的 Message。我们用“复杂”这个词，不仅仅是指从个数上说有更多的 fields 或者更多类型的 fields，而是指更加复杂的数据结构：

  • Message嵌套
  • Import Message

下面分别介绍

Message嵌套

嵌套是一个神奇的概念，一旦拥有嵌套能力，消息的表达能力就会非常强大。具体的嵌套 Message 的例子如下

message Person { 
 required string name = 1; 
 required int32 id = 2;        // Unique ID number for this person. 
 optional string email = 3; 
 
 enum PhoneType { 
   MOBILE = 0; 
   HOME = 1; 
   WORK = 2; 
 } 
 
 message PhoneNumber { 
   required string number = 1; 
   optional PhoneType type = 2 [default = HOME]; 
 } 
 repeated PhoneNumber phone = 4; 
}

在 Message Person 中，定义了嵌套消息 PhoneNumber，并用来定义 Person 消息中的 phone 域。这使得人们可以定义更加复杂的数据结构。

Import Message

在一个 .proto 文件中，还可以用 Import 关键字引入在其他 .proto 文件中定义的消息，这可以称做 Import Message，或者 Dependency Message。具体的import message的例子如下

import common.header; 
 
message youMsg{ 
 required common.info_header header = 1; 
 required string youPrivateData = 2; 
}

其中 ,common.info_header定义在common.header包内。

Import Message 的用处主要在于提供了方便的代码管理机制，类似 C 语言中的头文件。您可以将一些公用的 Message 定义在一个 package 中，然后在别的 .proto 文件中引入该 package，进而使用其中的消息定义。

Google Protocol Buffer 可以很好地支持嵌套 Message 和引入 Message，从而让定义复杂的数据结构的工作变得非常轻松愉快。

动态编译

一般情况下，使用 Protobuf 的人们都会先写好 .proto 文件，再用 Protobuf 编译器生成目标语言所需要的源代码文件。将这些生成的代码和应用程序一起编译。

可是在某且情况下，人们无法预先知道 .proto 文件，他们需要动态处理一些未知的 .proto 文件。比如一个通用的消息转发中间件，它不可能预知需要处理怎样的消息。这需要动态编译 .proto 文件，并使用其中的 Message。

详细解释参见：Google Protocol Buffer 的使用和原理

参考：

  1. https://developers.google.com/protocol-buffers/docs/reference/python/
  2. https://developers.google.com/protocol-buffers/docs/reference/python-generated
  3. http://hzy3774.iteye.com/blog/2323428
  4. https://github.com/google/protobuf/tree/master/python
  5. https://github.com/google/protobuf/tree/master/examples
  6. https://blog.csdn.net/losophy/article/details/17006573
  7. https://www.ibm.com/developerworks/cn/linux/l-cn-gpb/
  8. https://github.com/google/protobuf
  9. https://github.com/google/protobuf/releases/download/v3.5.1/protobuf-all-3.5.1.tar.gz
  10. Python Google Protocol Buffer： https://developers.google.com/protocol-buffers/docs/pythontutorial
python
#Python #Google #PB #Protocol Buffer
Python Google Protocol Buffer
https://suncle.me/posts/2114861712/
作者
Suncle Chen
发布于
2018年2月6日
许可协议