Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/protocolbuffers/protobuf/llms.txt

Use this file to discover all available pages before exploring further.

The examples/ directory in the protobuf repository contains a complete address book application that demonstrates the core Protocol Buffers workflow: define a schema, generate code, serialize data, and read it back. The same binary data file is compatible across every language, so you can write an entry with the C++ program and read it with the Python program.

​
The address book schema

All examples share a single addressbook.proto definition:
addressbook.proto
syntax = "proto3";
package tutorial;

import "google/protobuf/timestamp.proto";

option java_multiple_files = true;
option java_package = "com.example.tutorial.protos";
option java_outer_classname = "AddressBookProtos";
option csharp_namespace = "Google.Protobuf.Examples.AddressBook";
option go_package = "github.com/protocolbuffers/protobuf/examples/go/tutorialpb";

message Person {
  string name = 1;
  int32 id = 2;  // Unique ID number for this person.
  string email = 3;

  enum PhoneType {
    MOBILE = 0;
    HOME = 1;
    WORK = 2;
  }

  message PhoneNumber {
    string number = 1;
    PhoneType type = 2;
  }

  repeated PhoneNumber phones = 4;

  google.protobuf.Timestamp last_updated = 5;
}

// Our address book file is just one of these.
message AddressBook {
  repeated Person people = 1;
}
The schema uses proto3 syntax and imports the well-known Timestamp type to record when a person’s entry was last modified.

​
Adding a person

The add_person program reads an address book file (creating it if it doesn’t exist), prompts for a new person’s details, appends the entry, and writes the file back. 
#! /usr/bin/env python

import addressbook_pb2
import sys

try:
  raw_input          # Python 2
except NameError:
  raw_input = input  # Python 3


# This function fills in a Person message based on user input.
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.phones.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.")


# Main procedure:  Reads the entire address book from a file,
#   adds one person based on user input, then writes it back out to the same
#   file.
if len(sys.argv) != 2:
  print("Usage:", sys.argv[0], "ADDRESS_BOOK_FILE")
  sys.exit(-1)

address_book = addressbook_pb2.AddressBook()

# Read the existing address book.
try:
  with open(sys.argv[1], "rb") as f:
    address_book.ParseFromString(f.read())
except IOError:
  print(sys.argv[1] + ": File not found.  Creating a new file.")

# Add an address.
PromptForAddress(address_book.people.add())

# Write the new address book back to disk.
with open(sys.argv[1], "wb") as f:
  f.write(address_book.SerializeToString())

​
Listing people

The list_people program reads an existing address book file and prints every entry to stdout. 
#! /usr/bin/env python

from __future__ import print_function
import addressbook_pb2
import sys


# Iterates though all people in the AddressBook and prints info about them.
def ListPeople(address_book):
  for person in address_book.people:
    print("Person ID:", person.id)
    print("  Name:", person.name)
    if person.email != "":
      print("  E-mail address:", person.email)

    for phone_number in person.phones:
      if phone_number.type == addressbook_pb2.Person.MOBILE:
        print("  Mobile phone #:", end=" ")
      elif phone_number.type == addressbook_pb2.Person.HOME:
        print("  Home phone #:", end=" ")
      elif phone_number.type == addressbook_pb2.Person.WORK:
        print("  Work phone #:", end=" ")
      print(phone_number.number)


# Main procedure:  Reads the entire address book from a file and prints all
#   the information inside.
if len(sys.argv) != 2:
  print("Usage:", sys.argv[0], "ADDRESS_BOOK_FILE")
  sys.exit(-1)

address_book = addressbook_pb2.AddressBook()

with open(sys.argv[1], "rb") as f:
  address_book.ParseFromString(f.read())

ListPeople(address_book)

​
Cross-language compatibility

Because all programs encode and decode the same binary wire format, the data files are interoperable: 
# Write an entry using C++
./add_person_cpp addressbook.data

# Read it back using Python
python list_people.py addressbook.data

# Or with Java
java -cp . ListPeople addressbook.data

​
Building the examples

Bazel 0.5.4 or newer is required. Download from bazel’s release page.
# Build all targets in the examples directory
bazel build :all

# Run the C++ binary
bazel-bin/add_person_cpp addressbook.data

Build docs developers (and LLMs) love

Get started for freeTalk to us