Documentation
¶
Overview ¶
Package starlarkproto exposes protobuf messages as starlark types.
It is geared towards emitting messages, not reading or parsing them. Thus it provides only one-way bridge from Starlark to Go (but not vice-versa), i.e. Go programs can use Starlark scripts that return protobuf messages, but not accept them.
Internally a message is stored as a tree of Starlark native values, with some type checking done when manipulating fields. For example, reading or assigning to a field not defined in a message will cause a runtime error. Similarly, trying to assign a value of a wrong type to a non-repeated field will fail.
Repeated fields currently have more lax type checks: they just have to be lists or tuples. It is possible to put wrong values inside them, which will cause runtime error at a later stage, when trying to serialize the proto message (or materialize it as proto.Message on the Go side).
Instantiating messages and default field values ¶
Each proto message in a loaded package is exposed via constructor function that takes optional keyword arguments and produces a new object of *Message type.
All unassigned fields are implicitly set to their default zero values on first access, including message-typed fields. It means, for example, if a message 'a' has a singular field 'b', that has a field 'c', it is always fine to write 'a.b.c' to read or set 'c' value, without explicitly checking that 'b' is set.
To clear a field, assign None to it (regardless of its type).
Index ¶
- func LoadProtoModule(name string) (starlark.StringDict, error)
- func ProtoLib() starlark.StringDict
- type Message
- func (m *Message) Attr(name string) (starlark.Value, error)
- func (m *Message) AttrNames() []string
- func (m *Message) Freeze()
- func (m *Message) FromDict(d *starlark.Dict) error
- func (m *Message) FromProto(p proto.Message) error
- func (m *Message) Hash() (uint32, error)
- func (m *Message) MessageType() *MessageType
- func (m *Message) SetField(name string, val starlark.Value) error
- func (m *Message) String() string
- func (m *Message) ToProto() (proto.Message, error)
- func (m *Message) Truth() starlark.Bool
- func (m *Message) Type() string
- type MessageType
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LoadProtoModule ¶
func LoadProtoModule(name string) (starlark.StringDict, error)
LoadProtoModule loads a protobuf module, specified by its full path, for example "a/b/c.proto". The module should be registered in the process's protobuf descriptors set. Returns a dict with single struct named after the proto package. It has all message constructors defined inside.
func ProtoLib ¶
func ProtoLib() starlark.StringDict
ProtoLib returns a dict with single struct named "proto" that holds helper functions to manipulate protobuf messages (in particular serialize them).
Exported functions:
def to_textpb(msg):
"""Serializes a protobuf message to text proto.
Args:
msg: a *Message to serialize.
Returns:
An str representing msg in text format.
"""
def to_jsonpb(msg, emit_defaults=False):
"""Serializes a protobuf message to JSONPB string.
Args:
msg: a *Message to serialize.
emit_defaults: if True, do not omit fields with default values.
Returns:
An str representing msg in JSONPB format.
"""
def from_textpb(ctor, text):
"""Deserializes a protobuf message given in text proto form.
Unknown fields are not allowed.
Args:
ctor: a message constructor function.
text: a string with serialized message.
Returns:
Deserialized message constructed via `ctor`.
"""
def from_jsonpb(ctor, text):
"""Deserializes a protobuf message given as JBONPB string.
Unknown fields are silently skipped.
Args:
ctor: a message constructor function.
text: a string with serialized message.
Returns:
Deserialized message constructed via `ctor`.
"""
Types ¶
type Message ¶
type Message struct {
// contains filtered or unexported fields
}
Message is a Starlark value that implements a struct-like type structured like a protobuf message.
Implements starlark.Value, starlark.HasAttrs and starlark.HasSetField interfaces.
TODO(vadimsh): Currently not safe for a cross-goroutine use without external locking, even when frozen.
func NewMessage ¶
func NewMessage(typ *MessageType) *Message
NewMessage instantiates a new empty message of the given type.
func (*Message) FromDict ¶
FromDict populates fields of this message based on values in starlark.Dict.
Doesn't reset the message. Basically does this:
for k in d: setattr(msg, k, d[k])
Returns an error on type mismatch.
func (*Message) FromProto ¶
FromProto populates fields of this message based on values in proto.Message.
Returns an error on type mismatch.
func (*Message) MessageType ¶
func (m *Message) MessageType() *MessageType
MessageType returns detailed type information about the message.
type MessageType ¶
type MessageType struct {
// contains filtered or unexported fields
}
MessageType contains information about the structure of a proto message.
It is extracted via reflection from a proto message struct type.
func GetMessageType ¶
func GetMessageType(typ reflect.Type) (*MessageType, error)
GetMessageType extracts type description for protobuf message of given type.
'typ' is expected to represent a pointer to a protobuf struct, as returned by proto.MessageType(...). Returns an error otherwise.
func (*MessageType) Name ¶
func (m *MessageType) Name() string
Name returns fully qualified proto message name.
func (*MessageType) NewProtoMessage ¶
func (m *MessageType) NewProtoMessage() reflect.Value
NewProtoMessage constructs &ProtoMessage{} and returns it as reflect.Value.
func (*MessageType) Type ¶
func (m *MessageType) Type() reflect.Type
Type returns proto message type (pointer to a proto struct).
Source Files
Directories