protobuf - Registry for Google Protocol Buffer messages and enums

Overview

This module provides central registry for Google Protocol Buffer messages and enums. The generated *_pb2.py protobuf files could be registered using register_decriptor or load_registered function. The registry could be then used to obtain information about protobuf messages or enum types, or to create message instances or enum values.

Constants

firebird.base.protobuf.PROTO_EMPTY = 'google.protobuf.Empty'

Name of well-known EMPTY protobuf message (for use with create_message())

firebird.base.protobuf.PROTO_ANY = 'google.protobuf.Any'

Name of well-known ANY protobuf message (for use with create_message())

firebird.base.protobuf.PROTO_DURATION = 'google.protobuf.Duration'

Name of well-known DURATION protobuf message (for use with create_message())

firebird.base.protobuf.PROTO_TIMESTAMP = 'google.protobuf.Timestamp'

Name of well-known TIMESTAMP protobuf message (for use with create_message())

firebird.base.protobuf.PROTO_STRUCT = 'google.protobuf.Struct'

Name of well-known STRUCT protobuf message (for use with create_message())

firebird.base.protobuf.PROTO_VALUE = 'google.protobuf.Value'

Name of well-known VALUE protobuf message (for use with create_message())

firebird.base.protobuf.PROTO_LISTVALUE = 'google.protobuf.ListValue'

Name of well-known LISTVALUE protobuf message (for use with create_message())

firebird.base.protobuf.PROTO_FIELDMASK = 'google.protobuf.FieldMask'

Name of well-known FIELDMASK protobuf message (for use with create_message())

Functions

firebird.base.protobuf.register_decriptor(file_descriptor) → None

Registers enums and messages defined by protobuf file DESCRIPTOR.

Return type:

None

firebird.base.protobuf.load_registered(group: str) → None

Load registered protobuf packages.

Protobuf packages must register the pb2-file DESCRIPTOR in entry_points section of setup.cfg or pyproject.toml file.

Parameters:

group (str) – Entry-point group name.

Return type:

None

Example

# setup.cfg:

[options.entry_points]
firebird.base.protobuf =
    firebird.base.lib_a = firebird.base.lib_a_pb2:DESCRIPTOR
    firebird.base.lib_b = firebird.base.lib_b_pb2:DESCRIPTOR
    firebird.base.lib_c = firebird.base.lib_c_pb2:DESCRIPTOR

# pyproject.toml

[project.entry-points."firebird.base.protobuf"]
"firebird.base.lib_a" = "firebird.base.lib_a_pb2:DESCRIPTOR"
"firebird.base.lib_b" = "firebird.base.lib_b_pb2:DESCRIPTOR"
"firebird.base.lib_c" = "firebird.base.lib_c_pb2:DESCRIPTOR"

# will be loaded with:

load_registered('firebird.base.protobuf')

firebird.base.protobuf.is_msg_registered(name: str) → bool

Returns True if specified name refers to registered protobuf message type.

Parameters:

name (str) –

Return type:

bool

firebird.base.protobuf.is_enum_registered(name: str) → bool

Returns True if specified name refers to registered protobuf enum type.

Parameters:

name (str) –

Return type:

bool

firebird.base.protobuf.get_enum_type(name: str) → ProtoEnumType

Returns wrapper instance for protobuf enum type with specified name.

Raises:

KeyError – When enum type is not registered.

Parameters:

name (str) –

Return type:

ProtoEnumType

firebird.base.protobuf.get_enum_value_name(enum_type_name: str, value: int) → str

Returns name for the enum value.

Parameters:

• enum_type_name (str) –

• value (int) –

Return type:

str

firebird.base.protobuf.create_message(name: str, serialized: bytes | None = None) → Message

Returns new protobuf message instance.

Parameters:

• name (str) – Fully qualified protobuf message name.

• serialized (bytes | None) – Serialized message.

Raises:

• KeyError – When message type is not registered.

• google.protobuf.message.DecodeError – When deserializations fails.

Return type:

Message

firebird.base.protobuf.get_enum_field_type(msg, field_name: str) → str

Returns name of enum type for message enum field.

Raises:

KeyError – When message does not have specified field.

Parameters:

field_name (str) –

Return type:

str

firebird.base.protobuf.struct2dict(struct: Struct) → Dict

Unpacks google.protobuf.Struct message to Python dict value.

Parameters:

struct (Struct) –

Return type:

Dict

firebird.base.protobuf.dict2struct(value: Dict) → Struct

Returns dict packed into google.protobuf.Struct message.

Parameters:

value (Dict) –

Return type:

Struct

Data classes

class firebird.base.protobuf.ProtoMessageType(name: str, constructor: Callable)

Bases: Distinct

Google protobuf message type.

Parameters:

• name (str) –

• constructor (Callable) –

get_key() → Any

Returns name.

Return type:

Any

constructor: Callable

name: str

class firebird.base.protobuf.ProtoEnumType(descriptor: EnumDescriptor)

Bases: Distinct

Google protobuf enum type

Parameters:

descriptor (EnumDescriptor) –

__getattr__(name)

Returns the value corresponding to the given enum name.

get_key() → Any

Returns name.

Return type:

Any

get_value_name(number: int) → str

Returns a string containing the name of an enum value.

Raises:

KeyError – If there is no value for specified name.

Parameters:

number (int) –

Return type:

str

items()

Return a list of the (name, value) pairs of the enum.

These are returned in the order they were defined in the .proto file.

keys()

Return a list of the string names in the enum.

These are returned in the order they were defined in the .proto file.

values()

Return a list of the integer values in the enum.

These are returned in the order they were defined in the .proto file.

descriptor: EnumDescriptor

property name: str

Full enum type name.