luci: Index | Files | Directories

package starlarkproto

import ""

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).


Package Files

conversions.go default.go doc.go functions.go loader.go message.go message_ctor.go type.go

func LoadProtoModule Uses

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 Uses

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.

    msg: a *Message to serialize.

    A str representing msg in text format.

def to_jsonpb(msg, emit_defaults=False):
  """Serializes a protobuf message to JSONPB string.

    msg: a *Message to serialize.
    emit_defaults: if True, do not omit fields with default values.

    A 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.

    ctor: a message constructor function.
    text: a string with serialized message.

    Deserialized message constructed via `ctor`.

def from_jsonpb(ctor, text):
  """Deserializes a protobuf message given as JBONPB string.

  Unknown fields are silently skipped.

    ctor: a message constructor function.
    text: a string with serialized message.

    Deserialized message constructed via `ctor`.

def struct_to_textpb(s):
  """Converts a struct to a text proto string.

    s: a struct object. May not contain dicts.

    A str containing a text format protocol buffer message.

type Message Uses

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 Uses

func NewMessage(typ *MessageType) *Message

NewMessage instantiates a new empty message of the given type.

func (*Message) Attr Uses

func (m *Message) Attr(name string) (starlark.Value, error)

Attr implements starlark.HasAttrs.

func (*Message) AttrNames Uses

func (m *Message) AttrNames() []string

AttrNames implements starlark.HasAttrs.

func (*Message) Freeze Uses

func (m *Message) Freeze()

Freeze implements starlark.Value.

func (*Message) FromDict Uses

func (m *Message) FromDict(d *starlark.Dict) error

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 Uses

func (m *Message) FromProto(p proto.Message) error

FromProto populates fields of this message based on values in proto.Message.

Returns an error on type mismatch.

func (*Message) Hash Uses

func (m *Message) Hash() (uint32, error)

Hash implements starlark.Value.

func (*Message) MessageType Uses

func (m *Message) MessageType() *MessageType

MessageType returns detailed type information about the message.

func (*Message) SetField Uses

func (m *Message) SetField(name string, val starlark.Value) error

SetField implements starlark.HasSetField.

func (*Message) String Uses

func (m *Message) String() string

String implements starlark.Value.

func (*Message) ToProto Uses

func (m *Message) ToProto() (proto.Message, error)

ToProto returns a new populated proto message of an appropriate type.

Returns an error if the data inside the Starlark representation of the message has a wrong type.

func (*Message) Truth Uses

func (m *Message) Truth() starlark.Bool

Truth implements starlark.Value.

func (*Message) Type Uses

func (m *Message) Type() string

Type implements starlark.Value.

type MessageType Uses

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 Uses

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 Uses

func (m *MessageType) Name() string

Name returns fully qualified proto message name.

func (*MessageType) NewProtoMessage Uses

func (m *MessageType) NewProtoMessage() reflect.Value

NewProtoMessage constructs &ProtoMessage{} and returns it as reflect.Value.

func (*MessageType) Type Uses

func (m *MessageType) Type() reflect.Type

Type returns proto message type (pointer to a proto struct).



Package starlarkproto imports 14 packages (graph) and is imported by 2 packages. Updated 2019-08-17. Refresh now. Tools for package owners.