Optionen handeln app16 comments
Super binary robots
This tutorial provides a basic Python programmer's introduction to working with protocol buffers. By walking through creating a simple example application, it shows you how to Define message formats in a. Use the protocol buffer compiler. Use the Python protocol buffer API to write and read messages. This isn't a comprehensive guide to using protocol buffers in Python.
Why Use Protocol Buffers? The example we're going to use is a very simple "address book" application that can read and write people's contact details to and from a file. Each person in the address book has a name, an ID, an email address, and a contact phone number.
How do you serialize and retrieve structured data like this? There are a few ways to solve this problem: You can invent an ad-hoc way to encode the data items into a single string — such as encoding 4 ints as " This is a simple and flexible approach, although it does require writing one-off encoding and parsing code, and the parsing imposes a small run-time cost. This works best for encoding very simple data.
Serialize the data to XML. This approach can be very attractive since XML is sort of human readable and there are binding libraries for lots of languages. Also, navigating an XML DOM tree is considerably more complicated than navigating simple fields in a class normally would be.
Protocol buffers are the flexible, efficient, automated solution to solve exactly this problem. With protocol buffers, you write a. From that, the protocol buffer compiler creates a class that implements automatic encoding and parsing of the protocol buffer data with an efficient binary format. The generated class provides getters and setters for the fields that make up a protocol buffer and takes care of the details of reading and writing the protocol buffer as a unit.
Importantly, the protocol buffer format supports the idea of extending the format over time in such a way that the code can still read data encoded with the old format. The example code is included in the source code package, under the "examples" directory. Defining Your Protocol Format To create your address book application, you'll need to start with a. The definitions in a. Let's go through each part of the file and see what it does.
In Python, packages are normally determined by directory structure, so the package you define in your. However, you should still declare one to avoid name collisions in the Protocol Buffers name space as well as in non-Python languages. Next, you have your message definitions.
A message is just an aggregate containing a set of typed fields. Many standard simple data types are available as field types, including bool , int32 , float , double , and string. You can also add further structure to your messages by using other message types as field types — in the above example the Person message contains PhoneNumber messages, while the AddressBook message contains Person messages.
You can even define message types nested inside other messages — as you can see, the PhoneNumber type is defined inside Person. Tag numbers require one less byte to encode than higher numbers, so as an optimization you can decide to use those tags for the commonly used or repeated elements, leaving tags 16 and higher for less-commonly used optional elements. Each element in a repeated field requires re-encoding the tag number, so repeated fields are particularly good candidates for this optimization.
Each field must be annotated with one of the following modifiers: Serializing an uninitialized message will raise an exception. Parsing an uninitialized message will fail. Other than this, a required field behaves exactly like an optional field. If an optional field value isn't set, a default value is used.
For simple types, you can specify your own default value, as we've done for the phone number type in the example. Otherwise, a system default is used: For embedded messages, the default value is always the "default instance" or "prototype" of the message, which has none of its fields set.
Calling the accessor to get the value of an optional or required field which has not been explicitly set always returns that field's default value. The order of the repeated values will be preserved in the protocol buffer. Think of repeated fields as dynamically sized arrays. Required Is Forever You should be very careful about marking fields as required. If at some point you wish to stop writing or sending a required field, it will be problematic to change the field to an optional field — old readers will consider messages without this field to be incomplete and may reject or drop them unintentionally.
You should consider writing application-specific custom validation routines for your buffers instead. Some engineers at Google have come to the conclusion that using required does more harm than good; they prefer to use only optional and repeated. However, this view is not universal. You'll find a complete guide to writing. Don't go looking for facilities similar to class inheritance, though — protocol buffers don't do that. Compiling Your Protocol Buffers Now that you have a. To do this, you need to run the protocol buffer compiler protoc on your.
In this case, you While the details of how Python metaclasses work is beyond the scope of this tutorial, you can think of them as like a template for creating classes. At load time, the GeneratedProtocolMessageType metaclass uses the specified descriptors to create all the Python methods you need to work with each message type and adds them to the relevant classes.
You can then use the fully-populated classes in your code. The end effect of all this is that you can use the Person class as if it defined each field of the Message base class as a regular field. For example, you could write: HOME Note that these assignments are not just adding arbitrary new fields to a generic Python object. If you were to try to assign a field that isn't defined in the.
If you assign a field to a value of the wrong type, a TypeError will be raised. Also, reading the value of a field before it has been set returns the default value. Enums Enums are expanded by the metaclass into a set of symbolic constants with integer values. WORK has the value 2. Standard Message Methods Each message class also contains a number of other methods that let you check or manipulate the entire message, including: Usually invoked as str message or print message.
These methods implement the Message interface. For more information, see the complete API documentation for Message. Parsing and Serialization Finally, each protocol buffer class has methods for writing and reading messages of your chosen type using the protocol buffer binary format. Note that the bytes are binary, not text; we only use the str type as a convenient container.
These are just a couple of the options provided for parsing and serialization. Again, see the Message API reference for a complete list. Protocol Buffers and O-O Design Protocol buffer classes are basically dumb data holders like structs in C ; they don't make good first class citizens in an object model.
If you want to add richer behaviour to a generated class, the best way to do this is to wrap the generated protocol buffer class in an application-specific class.
Wrapping protocol buffers is also a good idea if you don't have control over the design of the. In that case, you can use the wrapper class to craft an interface better suited to the unique environment of your application: You should never add behaviour to the generated classes by inheriting from them. This will break internal mechanisms and is not good object-oriented practice anyway.
Writing A Message Now let's try using your protocol buffer classes. The first thing you want your address book application to be able to do is write personal details to your address book file. To do this, you need to create and populate instances of your protocol buffer classes and then write them to an output stream. Here is a program which reads an AddressBook from a file, adds one new Person to it based on user input, and writes the new AddressBook back out to the file again.
The parts which directly call or reference code generated by the protocol compiler are highlighted. Reads the entire address book from a file, adds one person based on user input, then writes it back out to the same file. AddressBook Read the existing address book. Could not open file. Creating a new one. This example reads the file created by the above example and prints all the information in it. Reads the entire address book from a file and prints all the information inside.
If you want your new buffers to be backwards-compatible, and your old buffers to be forward-compatible — and you almost certainly do want this — then there are some rules you need to follow. In the new version of the protocol buffer: There are some exceptions to these rules, but they are rarely used.
If you follow these rules, old code will happily read new messages and simply ignore any new fields. To the old code, optional fields that were deleted will simply have their default value, and deleted repeated fields will be empty.
New code will also transparently read old messages. If the default value is not specified for an optional element, a type-specific default value is used instead: For booleans, the default value is false.