protobuf-extra -- Extra tools to deal with Protocol Buffers
***********************************************************

protobuf-extra provides a program and a library to convert between
ASCII, Python dictionary, and binary Protocol Buffer message
representations.

| Download: https://pypi.python.org/pypi/protobuf-extra
| Source code: https://github.com/vmj/protobuf_extra
| Build status: https://travis-ci.org/vmj/protobuf_extra

.. contents::


Basic usage
===========

Typical usage of the program might look like this::

    $ export PYTHONPATH=.
    $ pb --type test.Person.Person >person-template.txt

The 'PYTHONPATH' should contain the path to the Python protobuf message definitions,
those generated by the 'protoc' protobuf compiler.

Now edit the `person-template.txt`.

Then generate protobuf message from it::

    $ pb --type test.Person.Person --in ascii --out bin >person.gpb <person-template.txt
    $ pb --type test.Person.Person --in bin --out dict <person.gpb
    {'age': 39, 'birthday': {'month': 8, 'day': 4, 'year': 1978}, 'name': u'Mikko', 'children': [{'age': 4, 'birthday': {'month': 3, 'day': 18, 'year': 2013}, 'name': u'Sonja'}]}
    $ pb --type test.Person.Person --in bin --out ascii <person.gpb
    name: "Mikko"
    age: 39
    birthday {
      year: 1978
      month: 8
      day: 4
    }
    children {
      name: "Sonja"
      age: 4
      birthday {
        year: 2013
        month: 3
        day: 18
      }
    }

See 'pb --help' for a complete listing of options.

The included Python library provides the ability to make, for example,
protobuf Message instances from a Python dictionary::

    #!/usr/bin/env python
    from test.Person_pb2 import Person
    from protobuf_extra import MessageFromDictionary

    person = MessageFromDictionary(Person, {
        "name": "John Doe",
        "birthday": {"year": 1970, "month": 1, "day": 1}
    })

See 'pydoc protobuf_extra' for a lot more documentation.


Requirements
============

In addition to Python (2.7 or 3.3 - 3.6), `protobuf
<https://pypi.python.org/pypi/protobuf/>`_ (3.0.0 - 3.3.0) is required.


Installation
============

Use either ``pip install protobut-extra`` or download the source
archive and use ``python setup.py install``.

The source code is available at `Python Package Index (PyPI)
<http://pypi.python.org/pypi/protobuf-extra>`_ or, if you want the
unreleased version, from `Github
<https://github.com/vmj/protobuf_extra>`_ git repository.


Authors
=======

Original author and current maintainer is Mikko Värri
(vmj@linuxbox.fi).


License
=======

protobuf-extra is Free Software, licensed under GNU General Public
License (GPL), version 3 or later.  See LICENSE.txt file for details.
