proto

package
v0.0.0-...-c05ff20 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 25, 2024 License: BSD-3-Clause Imports: 13 Imported by: 5

Documentation

Overview

Package proto defines a module of utilities for constructing and accessing protocol messages within Starlark programs.

THIS PACKAGE IS EXPERIMENTAL AND ITS INTERFACE MAY CHANGE.

This package defines several types of Starlark value: 

Message                 -- a protocol message
RepeatedField           -- a repeated field of a message, like a list

FileDescriptor          -- information about a .proto file
FieldDescriptor         -- information about a message field (or extension field)
MessageDescriptor       -- information about the type of a message
EnumDescriptor          -- information about an enumerated type
EnumValueDescriptor     -- a value of an enumerated type

A Message value is a wrapper around a protocol message instance. Starlark programs may access and update Messages using dot notation: 

x = msg.field
msg.field = x + 1
msg.field += 1

Assignments to message fields perform dynamic checks on the type and range of the value to ensure that the message is at all times valid.

The value of a repeated field of a message is represented by the list-like data type, RepeatedField. Its elements may be accessed, iterated, and updated in the usual ways. As with assignments to message fields, an assignment to an element of a RepeatedField performs a dynamic check to ensure that the RepeatedField holds only elements of the correct type. 

type(msg.uint32s)       # "proto.repeated<uint32>"
msg.uint32s[0] = 1
msg.uint32s[0] = -1     # error: invalid uint32: -1

Any iterable may be assigned to a repeated field of a message. If the iterable is itself a value of type RepeatedField, the message field holds a reference to it. 

msg2.uint32s = msg.uint32s      # both messages share one RepeatedField
msg.uint32s[0] = 123
print(msg2.uint32s[0])          # "123"

The RepeatedFields' element types must match. It is not enough for the values to be merely valid: 

msg.uint32s = [1, 2, 3]         # makes a copy
msg.uint64s = msg.uint32s       # error: repeated field has wrong type
msg.uint64s = list(msg.uint32s) # ok; makes a copy

For all other iterables, a new RepeatedField is constructed from the elements of the iterable. 

msg.uints32s = [1, 2, 3]
print(type(msg.uints32s))       # "proto.repeated<uint32>"

To construct a Message from encoded binary or text data, call Unmarshal or UnmarshalText. These two functions are exposed to Starlark programs as proto.unmarshal{,_text}.

To construct a Message from an existing Go proto.Message instance, you must first encode the Go message to binary, then decode it using Unmarshal. This ensures that messages visible to Starlark are encapsulated and cannot be mutated once their Starlark wrapper values are frozen.

TODO(adonovan): document descriptors, enums, message instantiation.

See proto_test.go for an example of how to use the 'proto' module in an application that embeds Starlark.

Index

Constants

This section is empty.

Variables

View Source 
var Module = &starlarkstruct.Module{
	Name: "proto",
	Members: starlark.StringDict{
		"file":           starlark.NewBuiltin("proto.file", file),
		"has":            starlark.NewBuiltin("proto.has", has),
		"marshal":        starlark.NewBuiltin("proto.marshal", marshal),
		"marshal_text":   starlark.NewBuiltin("proto.marshal_text", marshal),
		"set_field":      starlark.NewBuiltin("proto.set_field", setFieldStarlark),
		"get_field":      starlark.NewBuiltin("proto.get_field", getFieldStarlark),
		"unmarshal":      starlark.NewBuiltin("proto.unmarshal", unmarshal),
		"unmarshal_text": starlark.NewBuiltin("proto.unmarshal_text", unmarshal_text),
	},
}

Functions

func SetPool 

func SetPool(thread *starlark.Thread, pool DescriptorPool)

SetPool associates with the specified Starlark thread the descriptor pool used to find descriptors for .proto files and to instantiate messages from descriptors. Clients must call SetPool for a Starlark thread to use this package.

For example: 

SetPool(thread, protoregistry.GlobalFiles)

Types

type DescriptorPool 

type DescriptorPool interface {
	FindFileByPath(string) (protoreflect.FileDescriptor, error)
}

A DescriptorPool loads FileDescriptors by path name or package name, possibly on demand.

It is a superinterface of protodesc.Resolver, so any Resolver implementation is a valid pool. For example. protoregistry.GlobalFiles, which loads FileDescriptors from the compressed binary information in all the *.pb.go files linked into the process; and protodesc.NewFiles, which holds a set of FileDescriptorSet messages. See star2proto for example usage.

func Pool 

func Pool(thread *starlark.Thread) DescriptorPool

Pool returns the descriptor pool previously associated with this thread.

type EnumDescriptor 

type EnumDescriptor struct {
	Desc protoreflect.EnumDescriptor
}

An EnumDescriptor is an immutable Starlark value that describes an protocol enum type.

An EnumDescriptor contains a reference to a protoreflect.EnumDescriptor. Two EnumDescriptor values compare equal if and only if they refer to the same protoreflect.EnumDescriptor.

An EnumDescriptor may be called like a function. It converts its sole argument, which must be an int, string, or EnumValueDescriptor, to an EnumValueDescriptor.

The fields of an EnumDescriptor value are the values of the enumeration, each of type EnumValueDescriptor.

func (EnumDescriptor) Attr 

func (e EnumDescriptor) Attr(name string) (starlark.Value, error)

func (EnumDescriptor) AttrNames 

func (e EnumDescriptor) AttrNames() []string

func (EnumDescriptor) CallInternal 

func (e EnumDescriptor) CallInternal(_ *starlark.Thread, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

The Call method implements the starlark.Callable interface. A call to an enum descriptor converts its argument to a value of that enum type.

func (EnumDescriptor) Freeze 

func (e EnumDescriptor) Freeze()

func (EnumDescriptor) Hash 

func (e EnumDescriptor) Hash() (h uint32, err error)

func (EnumDescriptor) Name 

func (e EnumDescriptor) Name() string

func (EnumDescriptor) String 

func (e EnumDescriptor) String() string

func (EnumDescriptor) Truth 

func (e EnumDescriptor) Truth() starlark.Bool

func (EnumDescriptor) Type 

func (e EnumDescriptor) Type() string

type EnumValueDescriptor 

type EnumValueDescriptor struct {
	Desc protoreflect.EnumValueDescriptor
}

An EnumValueDescriptor is an immutable Starlark value that represents one value of an enumeration.

An EnumValueDescriptor contains a reference to a protoreflect.EnumValueDescriptor. Two EnumValueDescriptor values compare equal if and only if they refer to the same protoreflect.EnumValueDescriptor.

An EnumValueDescriptor has the following fields: 

index   -- int, index of this value within the enum sequence
name    -- string, name of this enum value
number  -- int, numeric value of this enum value
type    -- EnumDescriptor, the enum type to which this value belongs

func (EnumValueDescriptor) Attr 

func (e EnumValueDescriptor) Attr(name string) (starlark.Value, error)

func (EnumValueDescriptor) AttrNames 

func (e EnumValueDescriptor) AttrNames() []string

func (EnumValueDescriptor) CompareSameType 

func (x EnumValueDescriptor) CompareSameType(op syntax.Token, y_ starlark.Value, depth int) (bool, error)

func (EnumValueDescriptor) Freeze 

func (e EnumValueDescriptor) Freeze()

func (EnumValueDescriptor) Hash 

func (e EnumValueDescriptor) Hash() (h uint32, err error)

func (EnumValueDescriptor) String 

func (e EnumValueDescriptor) String() string

func (EnumValueDescriptor) Truth 

func (e EnumValueDescriptor) Truth() starlark.Bool

func (EnumValueDescriptor) Type 

func (e EnumValueDescriptor) Type() string

type FieldDescriptor 

type FieldDescriptor struct {
	Desc protoreflect.FieldDescriptor
}

A FieldDescriptor is an immutable Starlark value that describes a field (possibly an extension field) of protocol message.

A FieldDescriptor value contains a reference to a protoreflect.FieldDescriptor. Two FieldDescriptor values compare equal if and only if they refer to the same protoreflect.FieldDescriptor.

The primary use for FieldDescriptors is to access extension fields of a message.

A FieldDescriptor value has not attributes. TODO(adonovan): expose metadata fields (e.g. name, type).

func (FieldDescriptor) Attr 

func (d FieldDescriptor) Attr(name string) (starlark.Value, error)

func (FieldDescriptor) AttrNames 

func (d FieldDescriptor) AttrNames() []string

func (FieldDescriptor) Freeze 

func (d FieldDescriptor) Freeze()

func (FieldDescriptor) Hash 

func (d FieldDescriptor) Hash() (h uint32, err error)

func (FieldDescriptor) String 

func (d FieldDescriptor) String() string

func (FieldDescriptor) Truth 

func (d FieldDescriptor) Truth() starlark.Bool

func (FieldDescriptor) Type 

func (d FieldDescriptor) Type() string

type FileDescriptor 

type FileDescriptor struct {
	Desc protoreflect.FileDescriptor // TODO(adonovan): hide field, expose method?
}

A FileDescriptor is an immutable Starlark value that describes a .proto file. It is a reference to a protoreflect.FileDescriptor. Two FileDescriptor values compare equal if and only if they refer to the same protoreflect.FileDescriptor.

Its fields are the names of the message types (MessageDescriptor) and enum types (EnumDescriptor).

func (FileDescriptor) Attr 

func (f FileDescriptor) Attr(name string) (starlark.Value, error)

func (FileDescriptor) AttrNames 

func (f FileDescriptor) AttrNames() []string

func (FileDescriptor) Freeze 

func (f FileDescriptor) Freeze()

func (FileDescriptor) Hash 

func (f FileDescriptor) Hash() (h uint32, err error)

func (FileDescriptor) String 

func (f FileDescriptor) String() string

func (FileDescriptor) Truth 

func (f FileDescriptor) Truth() starlark.Bool

func (FileDescriptor) Type 

func (f FileDescriptor) Type() string

type Message 

type Message struct {
	// contains filtered or unexported fields
}

A Message is a Starlark value that wraps a protocol message.

Two Messages are equivalent if and only if they are identical.

When a Message value becomes frozen, a Starlark program may not modify the underlying protocol message, nor any Message or RepeatedField wrapper values derived from it.

func Unmarshal 

func Unmarshal(desc protoreflect.MessageDescriptor, data []byte) (*Message, error)

Unmarshal parses the data as a binary protocol message of the specified type, and returns it as a new Starlark message value.

func UnmarshalText 

func UnmarshalText(desc protoreflect.MessageDescriptor, data []byte) (*Message, error)

UnmarshalText parses the data as a text protocol message of the specified type, and returns it as a new Starlark message value.

func (*Message) Attr 

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

Attr returns the value of this message's field of the specified name. Extension fields are not accessible this way as their names are not unique.

func (*Message) AttrNames 

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

AttrNames returns the set of field names defined for this message. It satisfies the starlark.HasAttrs interface.

func (*Message) Freeze 

func (m *Message) Freeze()

func (*Message) Hash 

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

func (*Message) Message 

func (m *Message) Message() protoreflect.ProtoMessage

Message returns the wrapped message.

func (*Message) SetField 

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

SetField updates a non-extension field of this message. It implements the HasSetField interface.

func (*Message) String 

func (m *Message) String() string

func (*Message) Truth 

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

func (*Message) Type 

func (m *Message) Type() string

type MessageDescriptor 

type MessageDescriptor struct {
	Desc protoreflect.MessageDescriptor
}

A MessageDescriptor is an immutable Starlark value that describes a protocol message type.

A MessageDescriptor value contains a reference to a protoreflect.MessageDescriptor. Two MessageDescriptor values compare equal if and only if they refer to the same protoreflect.MessageDescriptor.

The fields of a MessageDescriptor value are the names of any message types (MessageDescriptor), fields or extension fields (FieldDescriptor), and enum types (EnumDescriptor) nested within the declaration of this message type.

func (MessageDescriptor) Attr 

func (d MessageDescriptor) Attr(name string) (starlark.Value, error)

func (MessageDescriptor) AttrNames 

func (d MessageDescriptor) AttrNames() []string

func (MessageDescriptor) CallInternal 

func (d MessageDescriptor) CallInternal(thread *starlark.Thread, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

The Call method implements the starlark.Callable interface. When a message descriptor is called, it returns a new instance of the protocol message it describes. 

Message(msg)            -- return a shallow copy of an existing message
Message(k=v, ...)       -- return a new message with the specified fields
Message(dict(...))      -- return a new message with the specified fields

func (MessageDescriptor) Freeze 

func (d MessageDescriptor) Freeze()

func (MessageDescriptor) Hash 

func (d MessageDescriptor) Hash() (h uint32, err error)

func (MessageDescriptor) Name 

func (d MessageDescriptor) Name() string

func (MessageDescriptor) String 

func (d MessageDescriptor) String() string

func (MessageDescriptor) Truth 

func (d MessageDescriptor) Truth() starlark.Bool

func (MessageDescriptor) Type 

func (d MessageDescriptor) Type() string

type RepeatedField 

type RepeatedField struct {
	// contains filtered or unexported fields
}

A RepeatedField is a Starlark value that wraps a repeated field of a protocol message.

An assignment to an element of a repeated field incurs a dynamic check that the new value has (or can be converted to) the correct type using conversions similar to those done when calling a MessageDescriptor to construct a message.

TODO(adonovan): make RepeatedField implement starlark.Comparable. Should the comparison include type, or be defined on the elements alone?

func (*RepeatedField) Freeze 

func (rf *RepeatedField) Freeze()

func (*RepeatedField) Hash 

func (rf *RepeatedField) Hash() (uint32, error)

func (*RepeatedField) Index 

func (rf *RepeatedField) Index(i int) starlark.Value

func (*RepeatedField) Iterate 

func (rf *RepeatedField) Iterate() starlark.Iterator

func (*RepeatedField) Len 

func (rf *RepeatedField) Len() int

func (*RepeatedField) SetIndex 

func (rf *RepeatedField) SetIndex(i int, v starlark.Value) error

func (*RepeatedField) String 

func (rf *RepeatedField) String() string

func (*RepeatedField) Truth 

func (rf *RepeatedField) Truth() starlark.Bool

func (*RepeatedField) Type 

func (rf *RepeatedField) Type() string

Source Files

View all Source files

Directories

Path Synopsis
cmd
star2proto
The star2proto command executes a Starlark file and prints a protocol message, which it expects to find in a module-level variable named 'result'.
 The star2proto command executes a Starlark file and prints a protocol message, which it expects to find in a module-level variable named 'result'.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.