google ProtoBuf開發者指南

時間 2019-12-14

標籤 google protobuf 開發者指南欄目 Google 简体版

原文原文鏈接

google ProtoBuf開發者指南

ProtoBuf開發者指南html

譯者:python

gasheroios

轉自：http://www.cppblog.com/woaidongmao/archive/2009/06/23/88391.html

目錄程序員

1 概覽
- 1.1 什麼是protocol buffer
- 1.2 他們如何工做
- 1.3 爲何不用XML?
- 1.4 聽起來像是爲個人解決方案，如何開始?
- 1.5 一點歷史
2 語言指導
- 2.1 定義一個消息類型
- 2.2 值類型
- 2.3 可選字段與缺省值
- 2.4 枚舉
- 2.5 使用其餘消息類型
- 2.6 嵌套類型
- 2.7 更新一個數據類型
- 2.8 擴展
- 2.9 包
- 2.10 定義服務
- 2.11 選項
- 2.12 生成你的類
3 代碼風格指導
- 3.1 消息與字段名
- 3.2 枚舉
- 3.3 服務
4 編碼
- 4.1 一個簡單的消息
- 4.2 基於128的Varints
- 4.3 消息結構
- 4.4 更多的值類型
- 4.5 內嵌消息
- 4.6 可選的和重複的元素
- 4.7 字段順序
5 ProtocolBuffer基礎：C++
6 ProtocolBuffer基礎：Java
7 ProtocolBuffer基礎：Python
- 7.1 爲何使用ProtocolBuffer?
- 7.2 哪裏能夠找到例子代碼
- 7.3 定義你的協議格式
- 7.4 編譯你的ProtocolBuffer
- 7.5 ProtocolBuffer API
  - 7.5.1 枚舉
  - 7.5.2 標準消息方法
  - 7.5.3 解析與串行化
- 7.6 寫消息
- 7.7 讀消息
- 7.8 擴展ProtocolBuffer
- 7.9 高級使用
8 參考概覽
9 C++代碼生成
10 C++ API
11 Java代碼生成
12 Java API
13 Python代碼生成
- 13.1 編譯器的使用
- 13.2 包
- 13.3 消息
- 13.4 字段
  - 13.4.1 簡單字段
  - 13.4.2 簡單消息字段
  - 13.4.3 重複字段
  - 13.4.4 重複消息字段
  - 13.4.5 枚舉類型
  - 13.4.6 擴展
- 13.5 服務
  - 13.5.1 接口
  - 13.5.2 存根(Stub)
14 Python API
15 其餘語言

1 概覽正則表達式

歡迎來到protocol buffer的開發者指南文檔，一種語言無關、平臺無關、擴展性好的用於通訊協議、數據存儲的結構化數據串行化方法。編程

本文檔面向但願使用protocol buffer的Java、C++或Python開發者。這個概覽介紹了protocol buffer，並告訴你如何開始，你隨後能夠跟隨編程指導( http://code.google.com/apis/protocolbuffers/docs/tutorials.html )深刻了解protocol buffer編碼方式( http://code.google.com/apis/protocolbuffers/docs/encoding.html )。API參考文檔( http://code.google.com/apis/protocolbuffers/docs/reference/overview.html )一樣也是提供了這三種編程語言的版本，不夠協議語言( http://code.google.com/apis/protocolbuffers/docs/proto.html )和樣式( http://code.google.com/apis/protocolbuffers/docs/style.html )指導都是編寫 .proto 文件。api

1.1 什麼是protocol buffer服務器

ProtocolBuffer是用於結構化數據串行化的靈活、高效、自動的方法，有如XML，不過它更小、更快、也更簡單。你能夠定義本身的數據結構，而後使用代碼生成器生成的代碼來讀寫這個數據結構。你甚至能夠在無需從新部署程序的狀況下更新數據結構。數據結構

1.2 他們如何工做app

你首先須要在一個 .proto 文件中定義你須要作串行化的數據結構信息。每一個ProtocolBuffer信息是一小段邏輯記錄，包含一系列的鍵值對。這裏有個很是簡單的 .proto 文件定義了我的信息:

message Person {
    required string name=1;
    required int32 id=2;
    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;
}

有如你所見，消息格式很簡單，每一個消息類型擁有一個或多個特定的數字字段，每一個字段擁有一個名字和一個值類型。值類型能夠是數字(整數或浮點)、布爾型、字符串、原始字節或者其餘ProtocolBuffer類型，還容許數據結構的分級。你能夠指定可選字段，必選字段和重複字段。你能夠在( http://code.google.com/apis/protocolbuffers/docs/proto.html )找到更多關於如何編寫 .proto 文件的信息。

一旦你定義了本身的報文格式(message)，你就能夠運行ProtocolBuffer編譯器，將你的 .proto 文件編譯成特定語言的類。這些類提供了簡單的方法訪問每一個字段(像是 query() 和 set_query() )，像是訪問類的方法同樣將結構串行化或反串行化。例如你能夠選擇C++語言，運行編譯如上的協議文件生成類叫作 Person 。隨後你就能夠在應用中使用這個類來串行化的讀取報文信息。你能夠這麼寫代碼:

Person person;
person.set_name("John Doe");
person.set_id(1234);
person.set_email("jdoe@example.com");
fstream.output("myfile",ios::out | ios::binary);
person.SerializeToOstream(&output);

而後，你能夠讀取報文中的數據:

fstream input("myfile",ios::in | ios:binary);
Person person;
person.ParseFromIstream(&input);
cout << "Name: " << person.name() << endl;
cout << "E-mail: " << person.email() << endl;

你能夠在不影響向後兼容的狀況下隨意給數據結構增長字段，舊有的數據會忽略新的字段。因此若是使用ProtocolBuffer做爲通訊協議，你能夠無須擔憂破壞現有代碼的狀況下擴展協議。

你能夠在API參考( http://code.google.com/apis/protocolbuffers/docs/reference/overview.html )中找到完整的參考，而關於ProtocolBuffer的報文格式編碼則能夠在( http://code.google.com/apis/protocolbuffers/docs/encoding.html )中找到。

1.3 爲何不用XML?

ProtocolBuffer擁有多項比XML更高級的串行化結構數據的特性，ProtocolBuffer：

更簡單
小3-10倍
快20-100倍
更少的歧義
能夠方便的生成數據存取類

例如，讓咱們看看如何在XML中建模Person的name和email字段:

<person>
<name>John Doe</name>
<email>jdoe@example.com</email>
</person>

對應的ProtocolBuffer報文則以下:

#ProtocolBuffer的文本表示
#這不是正常時使用的二進制數據
person {
name: "John Doe"
email: "jdoe@example.com"
}

當這個報文編碼到ProtocolBuffer的二進制格式( http://code.google.com/apis/protocolbuffers/docs/encoding.html )時(上面的文本僅用於調試和編輯)，它只須要28字節和100-200ns的解析時間。而XML的版本須要69字節(除去空白)和5000-10000ns的解析時間。

固然，操做ProtocolBuffer也很簡單:

cout << "Name: " << person.name() << endl;
cout << "E-mail: " << person.email() << endl;

而XML的你須要:

cout << "Name: "
     << person.getElementsByTagName("name")->item(0)->innerText()
     << endl;
cout << "E-mail: "
     << person.getElementsByTagName("email")->item(0)->innerText()
     << end;

固然，ProtocolBuffer並非在任什麼時候候都比XML更合適，例如ProtocolBuffer沒法對一個基於標記文本的文檔建模，由於你根本無法方便的在文本中插入結構。另外，XML是便於人類閱讀和編輯的，而ProtocolBuffer則不是。還有XML是自解釋的，而ProtocolBuffer僅在你擁有報文格式定義的 .proto 文件時纔有意義。

1.4 聽起來像是爲個人解決方案，如何開始?

下載包( http://code.google.com/p/protobuf/downloads/ )，包含了Java、Python、C++的ProtocolBuffer編譯器，用於生成你須要的IO類。構建和安裝你的編譯器，跟隨README的指令就能夠作到。

一旦你安裝好了，就能夠跟着編程指導( http://code.google.com/apis/protocolbuffers/docs/tutorials.html )來選擇語言-隨後就是使用ProtocolBuffer建立一個簡單的應用了。

1.5 一點歷史

ProtocolBuffer最初是在Google開發的，用以解決索引服務器的請求、響應協議。在使用ProtocolBuffer以前，有一種格式用以處理請求和響應數據的編碼和解碼，而且支持多種版本的協議。而這最終致使了醜陋的代碼，有如:

if (version==3) {
    ...
}else if (version>4) {
    if (version==5) {
        ...
    }
    ...
}

通訊協議所以變得愈來愈複雜，由於開發者必須確保，發出請求的人和接受請求的人必須同時兼容，而且在一方開始使用新協議時，另一方也要能夠接受。

ProtocolBuffer設計用於解決這一類問題：

很方便引入新字段，而中間服務器能夠忽略這些字段，直接傳遞過去而無需理解全部的字段。
格式能夠自描述，而且能夠在多種語言中使用(C++、Java等)

然而用戶仍然須要手寫解析代碼。

隨着系統的演化，他須要一些其餘的功能：

自動生成編碼和解碼代碼，而無需本身編寫解析器。
除了用於簡短的RPC(Remote Procedure Call)請求，人們使用ProtocolBuffer來作數據存儲格式(例如BitTable)。
RPC服務器接口能夠做爲 .proto 文件來描述，而經過ProtocolBuffer的編譯器生成存根(stub)類供用戶實現服務器接口。

ProtocolBuffer如今已是Google的混合語言數據標準了，如今已經正在使用的有超過48,162種報文格式定義和超過12,183個.proto 文件。他們用於RPC系統和持續數據存儲系統。

2 語言指導

本指導描述瞭如何使用ProtocolBuffer語言來定義結構化數據類型，包括 .proto 文件的語法和如何生成存取類。

這是一份指導手冊，一步步的例子使用文檔中的多種功能，查看入門指導( http://code.google.com/apis/protocolbuffers/docs/tutorials.html )選擇你的語言。

2.1 定義一個消息類型

@waiting …

2.2 值類型

@waiting …

2.3 可選字段與缺省值

@waiting …

2.4 枚舉

@waiting …

2.5 使用其餘消息類型

@waiting …

2.6 嵌套類型

@waiting …

2.7 更新一個數據類型

@waiting …

2.8 擴展

@waiting …

2.9 包

@waiting …

2.10 定義服務

@waiting …

2.11 選項

@waiting …

2.12 生成你的類

@waiting …

3 代碼風格指導

本文檔提供了 .proto 文件的代碼風格指導。按照慣例，你將會，你將會生成一些便於閱讀和一致的ProtocolBuffer定義文件。

3.1 消息與字段名

使用駱駝風格的大小寫命名，即單詞首字母大寫，來作消息名。使用GNU的所有小寫，使用下劃線分隔的方式定義字段名:

message SongServerRequest {
required string song_name=1;
}

使用這種命名方式獲得的名字以下:

C++:
    const string& song_name() {...}
    void set_song_name(const string& x) {...}

Java:
    public String getSongName() {...}
    public Builder setSongName(String v) {...}

3.2 枚舉

使用駱駝風格作枚舉名，而用所有大寫作值的名字:

enum Foo {
FIRST_VALUE=1;
SECOND_VALUE=2;
}

每一個枚舉值最後以分號結尾，而不是逗號。

3.3 服務

若是你的 .proto 文件定義了RPC服務，你可使用駱駝風格:

service FooService {
rpc GetSomething(FooRequest) returns (FooResponse);
}

4 編碼

本文檔描述了ProtocolBuffer的串行化二進制數據格式定義。你若是僅僅是在應用中使用ProtocolBuffer，並不須要知道這些，可是這些會對你定義高效的格式有所幫助。

4.1 一個簡單的消息

@waiting …

4.2 基於128的Varints

@waiting …

4.3 消息結構

@waiting …

4.4 更多的值類型

@waiting …

4.5 內嵌消息

@waiting …

4.6 可選的和重複的元素

@waiting …

4.7 字段順序

@waiting …

5 ProtocolBuffer基礎：C++

@waiting …

6 ProtocolBuffer基礎：Java

@waiting …

7 ProtocolBuffer基礎：Python

本指南給Python程序員一個快速使用的ProtocolBuffer的指導。經過一些簡單的例子來在應用中使用ProtocolBuffer，它向你展現瞭如何：

定義 .proto 消息格式文件
使用ProtocolBuffer編譯器
使用Python的ProtocolBuffer編程接口來讀寫消息

這並非一個在Python中使用ProtocolBuffer的完整指導。更多細節請參考手冊信息，查看語言指導( http://code.google.com/apis/protocolbuffers/docs/proto.html )，Python API( http://code.google.com/apis/protocolbuffers/docs/reference/python/index.html )，和編碼手冊( http://code.google.com/apis/protocolbuffers/docs/encoding.html )。

7.1 爲何使用ProtocolBuffer?

下面的例子」地址本」應用用於讀寫人的聯繫信息。每一個人有name、ID、email，和聯繫人電話號碼。

如何串行化和讀取結構化數據呢？有以下幾種問題：

使用Python的pickle，這是語言內置的缺省方法，不過無法演化，也沒法讓其餘語言支持。
你能夠發明一種數據編碼方法，例如4個整數」12:3-23:67″，這是簡單而靈活的方法，不過你須要本身寫解析器代碼，且只適用於簡單的數據。
串行化數據到XML。這種方法由於可讀性和多種語言的兼容函數庫而顯得比較吸引人，不過這也不是最好的方法，由於XML浪費空間是臭名昭著的，編碼解碼也很浪費時間。而XML DOM樹也是很複雜的。

ProtocolBuffer提供了靈活、高效、自動化的方法來解決這些問題。經過ProtocolBuffer，只須要寫一個 .proto 數據結構描述文件，就能夠編譯到幾種語言的自動編碼解碼類。生成的類提供了setter和getter方法來控制讀寫細節。最重要的是ProtocolBuffer支持後期擴展協議，而又確保舊格式能夠兼容。

7.2 哪裏能夠找到例子代碼

源碼發行包中已經包含了，在」example」文件夾。

7.3 定義你的協議格式

想要建立你的地址本應用，須要開始於一個 .proto 文件。定義一個 .proto 文件很簡單：添加一個消息到數據結構，而後指定一個和一個類型到每個字段，以下是本次例子使用的 addressbook.proto

package tutorial;

message Person {
    required string name=1;
    required int32 id=2;
    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 AddressBook {
    repeated Person person=1;
}

有如你所見的，語法相似於C++或Java。讓咱們分塊理解他們。

@waiting …

7.4 編譯你的ProtocolBuffer

如今已經擁有了 .proto 文件，下一步就是編譯生成相關的訪問類。運行編譯器 protoc 編譯你的 .proto 文件。

1. 若是還沒安裝編譯器則下載並按照README的安裝。

2. 運行編譯器，指定源目錄和目標目錄，定位你的 .proto 文件到源目錄，而後執行:

protoc -I=$SRC_DIR --python_out=$DST_DIR addressbook.proto

由於須要使用Python類，因此 –python_out 選項指定了特定的輸出語言。

這個步驟會生成 addressbook_pb2.py 到目標目錄。

7.5 ProtocolBuffer API

不像生成的C++和Java代碼，Python生成的類並不會直接爲你生成存取數據的代碼。而是(有如你在 addressbook_pb2.py 中見到的)生成消息描述、枚舉、和字段，還有一些神祕的空類，每一個對應一個消息類型:

class Person(message.Message):
    __metaclass__=reflection.GeneratedProtocolMessageType

    class PhoneNumber(message.Message):
        __metaclass__=reflection.GeneratedProtocolMessageType
        DESCRIPTION=_PERSON_PHONENUMBER

    DESCRIPTOR=_PERSON

class AddressBook(message.Message):
    __metaclass__=reflection.GeneratedProtocolMessageType
    DESCRIPTOR=_ADDRESSBOOK

這裏每一個類最重要的一行是 __metaclass__=reflection.GeneratedProtocolMessageType 。經過Python的元類機制工做，你能夠把他們看作是生成類的模板。在載入時， GeneratedProtocolMessageType 元類使用特定的描述符建立Python方法。隨後你就可使用完整的功能了。

最後就是你可使用 Person 類來操做相關字段了。例如你能夠寫:

import addressbook_pb2
person=addressbook_pb2.Person()
person.id=1234
person.name="John Doe"
person.email="jdoe@example.com"
phone=person.phone.add()
phone.number="555-4321"
phone.type=addressbook_pb2.Person.HOME

須要注意的是這些賦值屬性並非簡單的增長新字段到Python對象，若是你嘗試給一個 .proto 文件中沒有定義的字段賦值，就會拋出 AttributeError 異常，若是賦值類型錯誤會拋出 TypeError 。在給一個字段賦值以前讀取會返回缺省值:

person.no_such_field=1 #raise AttributeError
person.id="1234" #raise TypeError

更多相關信息參考( http://code.google.com/apis/protocolbuffers/docs/reference/python-generated.html )。

7.5.1 枚舉

枚舉在元類中定義爲一些符號常量對應的數字。例如常量 addressbook_pb2.Person.WORK 擁有值2。

7.5.2 標準消息方法

每一個消息類包含一些其餘方法容許你檢查和控制整個消息，包括：

IsInitialized() ：檢查是否全部必須(required)字段都已經被賦值了。
__str__() ：返回人類可讀的消息表示，便於調試。
CopyFrom(other_msg) ：使用另一個消息的值來覆蓋本消息。
Clear() ：清除全部元素的值，回到初識狀態。

這些方法是經過接口 Message 實現的，更多消息參考( http://code.google.com/apis/protocolbuffers/docs/reference/python/google.protobuf.message.Message-class.html )。

7.5.3 解析與串行化

最後，每一個ProtocolBuffer類有些方法用於讀寫消息的二進制數據( http://code.google.com/apis/protocolbuffers/docs/encoding.html )。包括：

SerializeToString() ：串行化，並返回字符串。注意是二進制格式而非文本。
ParseFromString(data) ：解析數據。

他們是成對使用的，提供二進制數據的串行化和解析。另外參考消息API參考( http://code.google.com/apis/protocolbuffers/docs/reference/python/google.protobuf.message.Message-class.html )瞭解更多信息。

Note

ProtocolBuffer與面向對象設計

ProtocolBuffer類只是用於存取數據的，相似於C++中的結構體，他們並無在面向對象方面作很好的設計。若是你想要給這些類添加更多的行爲，最好的方法是包裝(wrap)。包裝一樣適合於複用別人寫好的 .proto 文件。這種狀況下，你能夠把ProtocolBuffer生成類包裝的很適合於你的應用，並隱藏一些數據和方法，暴露有用的函數等等。 你不能夠經過繼承來給自動生成的類添加行爲。 這會破壞他們的內部工做機制。

7.6 寫消息

如今開始嘗試使用ProtocolBuffer的類。第一件事是讓地址本應用能夠記錄聯繫人的細節信息。想要作這些須要先建立聯繫人實例，而後寫入到輸出流。

這裏的程序從文件讀取地址本，添加新的聯繫人信息，而後寫回新的地址本到文件。

#! /usr/bin/python
import addressbook_pb2
import sys

#這個函數使用用戶輸入填充聯繫人信息
def PromptForAddress(person):
    person.id=int(raw_input("Enter person ID number: "))
    person.name=raw_input("Enter name: ")
    email=raw_input("Enter email address (blank for none): ")
    if email!="":
        person.email=email
    while True:
        number=raw_input("Enter a phone number (or leave blank to finish): ")
        if number=="":
            break
        phone_number=person.phone.add()
        phone_number.number=number
        type=raw_input("Is this a mobile, home, or work phone? ")
        if type=="mobile":
            phone_number.type=addressbook_pb2.Person.MOBILE
        elif type=="home":
            phone_number.type=addressbook_pb2.Person.HOME
        elif type=="work":
            phone_number.type=addressbook_pb2.Person.WORK
        else:
            print "Unknown phone type; leaving as default value."

#主函數，從文件讀取地址本，添加新的聯繫人，而後寫回到文件
if len(sys.argv)!=2:
    print "Usage:",sys.argv[0],"ADDRESS_BOOK_FILE"
    sys.exit(-1)

address_book=addressbook_pb2.AddressBook()

#讀取已經存在的地址本
try:
    f=open(sys.argv[1],"fb")
    address_book.ParseFromString(f.read())
    f.close()
except OSError:
    print sys.argv[1]+": Count open file. Creating a new one."

#添加地址
PromptFromAddress(address_book.person.add())

#寫入到文件
f=open(sys.argv[1],"wb")
f.write(address_book.SerializeToString())
f.close()

7.7 讀消息

固然，一個沒法讀取的地址本是沒什麼用處的，這個例子讀取剛纔建立的文件並打印全部信息:

#! /usr/bin/python

import addressbook_pb2
import sys

#遍歷地址本中全部的人並打印出來
def ListPeople(address_book):
    for person in address_book.person:
        print "Person ID:",person.id
        print "  Name:",person.name
        if person.HasField("email"):
            print "  E-mail:",person.email
        for phone_number in person.phone:
            if phone_number.type==addressbook_pb2.Person.MOBILE:
                print "  Mobile phone #:",
            elif phone_number.type==addressbook_pb2.Person.HOME:
                print "  Home phone #:",
            elif phone_number.type==addressbook_pb2.Person.WORK:
                print "  Work phone #:",
            print phone_number.number

#主函數，從文件讀取地址本
if len(sys.argv)!=2:
    print "Usage:",sys.argv[0],"ADDRESS_BOOK_FILE"
    sys.exit(-1)

address_book=addressbook_pb2.AddressBook()

#讀取整個地址本文件
f=open(sys.argv[1],"rb")
address_book.ParseFromString(f.read())
f.close()

ListPeople(address_book)

7.8 擴展ProtocolBuffer

在你發不了代碼之後，可能會想要改進ProtocolBuffer的定義。若是你想新的數據結構向後兼容，而你的舊數據能夠向前兼容，那麼你就找對了東西了，不過有些規則須要遵照。在新版本的ProtocolBuffer中：

必須不能夠改變已經存在的標籤的數字。
必須不能夠增長或刪除必須(required)字段。
能夠刪除可選(optional)或重複(repeated)字段。
能夠添加新的可選或重複字段，可是必須使用新的標籤數字，必須是以前的字段所沒有用過的。

這些規則也有例外( http://code.google.com/apis/protocolbuffers/docs/proto.html#updating )，不過不多使用。

若是你聽從這些規則，舊代碼會很容易的讀取新的消息，並簡單的忽略新的字段。而對舊的被刪除的可選字段也會簡單的使用他們的缺省值，被刪除的重複字段會自動爲空。新的代碼也會透明的讀取舊的消息。然而，須要注意的是新的可選消息不會在舊的消息中顯示，因此你須要使用 has_ 嚴格的檢查他們是否存在，或者在 .proto 文件中提供一個缺省值。若是沒有缺省值，就會有一個類型相關的默認缺省值：對於字符串就是空字符串；對於布爾型則是false；對於數字類型默認爲0。同時要注意的是若是你添加了新的重複字段，你的新代碼不會告訴你這個字段爲空(新代碼)也不會，也不會(舊代碼)包含 has_ 標誌。

7.9 高級使用

ProtocolBuffer不只僅提供了數據結構的存取和串行化。查看Python API參考( http://code.google.com/apis/protocolbuffers/docs/reference/python/index.html )瞭解更多功能。

一個核心功能是經過消息類的映射(reflection)提供的。你能夠經過它遍歷消息的全部字段，和管理他們的值。關於映射的一個頗有用的地方是轉換到其餘編碼，如XML或JSON。一個使用映射的更高級的功能是尋找同類型兩個消息的差別，或者開發出排序、正則表達式等功能。使用你的創造力，還能夠用ProtocolBuffer實現比你之前想象的更多的問題。

映射是經過消息接口提供的。

8 參考概覽

@waiting …

9 C++代碼生成

@waiting …

10 C++ API

@waiting …

11 Java代碼生成

@waiting …

12 Java API

@waiting …

13 Python代碼生成

本頁提供了Python生成類的相關細節。你能夠在閱讀本文檔以前查看語言指導。

Python的ProtocolBuffer實現與C++和Java的略有不一樣，編譯器只輸出構建代碼的描述符來生成類，而由Python的元類來執行工做。本文檔描述了元類開始生效之後的東西。

13.1 編譯器的使用

ProtocolBuffer經過編譯器的 –python_out= 選項來生成Python的相關類。這個參數其實是指定輸出的Python類放在哪一個目錄下。編譯器會爲每一個 .proto 文件生成一個對應的 .py 文件。輸出文件名與輸入文件名相關，不過有兩處修改：

擴展名 .proto 改成 .py 。
路徑名的修改。

若是你按照以下調用編譯器:

protoc --proto_path=src --python_out=build/gen src/foo.proto src/bar/baz.proto

編譯器會自動讀取兩個 .proto 文件而後產生兩個輸出文件。在須要時編譯器會自動建立目錄，不過 –python_out 指定的目錄不會自動建立。

須要注意的是，若是 .proto 文件名或路徑包含有沒法在Python中使用的模塊名(如連字符)，就會被自動轉換爲下劃線。因此文件 foo-bar.proto 會變成 foo_bar_pb2.py 。

Note

在每一個文件後綴的 _pb2.py 中的2表明ProtocolBuffer版本2。版本1僅在Google內部使用，可是你仍然能夠在之前發佈的一些代碼中找到它。自動版本2開始，ProtocolBuffer開始使用徹底不一樣的接口了，今後Python也沒有編譯時類型檢查了，咱們加上這個版本號來標誌Python文件名。

13.2 包

Python代碼生成根本不在意包的名字。由於Python使用目錄名來作包名。

13.3 消息

先看看一個簡單的消息聲明:

message Foo {}

ProtocolBuffer編譯器會生成類Foo，它是 google.protobuf.Message 的子類。這個實體類，不含有虛擬方法。不像C++和Java，Python生成類對優化選項不感冒；實際上Python的生成代碼已經爲代碼大小作了優化。

你不能繼承Foo的子類。生成類被設計不能夠被繼承，不然會被打破一些設計。另外，繼承本類也是很差的設計。

Python的消息類沒有特定的公共成員，而是定義接口，極其嵌套的字段、消息和枚舉類型。

一個消息能夠在另一個消息中聲明，例如 message Foo { message Bar {}} 。在這種狀況下，Bar類定義爲Foo的一個靜態成員，因此你能夠經過 Foo.Bar 來引用。

13.4 字段

對於消息類型中的每個字段，都有對應的同名成員。

13.4.1 簡單字段

若是你有一個簡單字段(包括可選的和重複的)，也就是非消息字段，你能夠經過簡單字段的方式來管理，例如foo字段的類型是int32，你能夠:

message.foo=123
print message.foo

注意設置foo的值，若是類型錯誤會拋出TypeError。

若是foo在賦值以前就讀取，就會使用缺省值。想要檢查是否已經賦值，能夠用 HasField() ，而清除該字段的值用ClearField() 。例如:

assert not message.HasField("foo")
message.foo=123
assert message.HasField("foo")
message.ClearField("foo")
assert not message.HasField("foo")

13.4.2 簡單消息字段

消息類型工做方式略有不一樣。你沒法爲一個嵌入消息字段賦值。而是直接操做這個消息的成員。由於實例化上層消息時，其包含的子消息同時也實例化了，例如定義:

message Foo {
optional Bar bar=1;
}

message bar {
optional int32 i=1;
}

你不能夠這麼作，由於不能作消息類型字段的賦值:

foo=Foo()
foo.bar=Bar() #WRONG!

而是能夠直接對消息類型字段的成員賦值:

foo=Foo()
assert not foo.HasField("bar")
foo.bar.i=1
assert foo.HasField("bar")

注意簡單的讀取消息類型字段的未賦值成員只不過是打印其缺省值:

foo=Foo()
assert not foo.HasField("bar")
print foo.bar.i #打印i的缺省值
assert not foo.HasField("bar")

13.4.3 重複字段

重複字段表現的像是Python的序列類型。若是是嵌入的消息，你沒法爲字段直接賦值，可是你能夠管理。例如給定的定義:

message Foo {
repeated int32 nums=1;
}

你就能夠這麼作:

foo=Foo()
foo.nums.append(15)
foo.nums.append(32)
assert len(foo.nums)==2
assert foo.nums[0]==15
assert foo.nums[1]==32
for i in foo.nums:
print i
foo.nums[1]=56
assert foo.nums[1]==56

做爲一種簡單字段，清除該字段必須使用 ClearField() 。

13.4.4 重複消息字段

重複消息字段工做方式與重複字段很像，除了 add() 方法用於返回新的對象之外。例如以下定義:

message Foo {
repeated Bar bar=1;
}

message Bar {
optional int32 i=1;
}

你能夠這麼作:

foo=Foo()
bar=foo.bars.add()
bar.i=15
bar=foo.bars.add()
bar.i=32
assert len(foo.bars)==2
assert foo.bars[0].i==15
assert foo.bars[1].i==32
for bar in foo.bars:
print bar.i
foo.bars[1].i=56
assert foo.bars[1].i==56

13.4.5 枚舉類型

@waiting …

13.4.6 擴展

@waiting …

13.5 服務

13.5.1 接口

一個簡單的接口定義:

service Foo {
rpc Bar(FooRequest) returns(FooResponse);
}

ProtocolBuffer的編譯器會生成類 Foo 來展現這個服務。 Foo 將會擁有每一個服務定義的方法。在這種狀況下 Bar 方法的定義是:

def Bar(self,rpc_controller,request,done)

參數等效於 Service.CallMethod() ，除了隱含的 method_descriptor 參數。

這些生成的方法被定義爲能夠被子類重載。缺省實現只是簡單的調用 controller.SetFailed() 而拋出錯誤信息告之還沒有實現。而後調用done回調。在實現你本身的服務時，你必須繼承生成類，而後重載各個接口方法。