Documentation
¶
Overview ¶
Package protogen holds the file passes a proto generation runs over buf's output: the generated Python package's skeleton (__init__.py files, the py.typed marker) and its package-qualified imports, the protobuf-es REQUIRED-field promotion read from a descriptor set, and the clean / stash-and-settle moves that regenerate a directory without losing its committed contents on a failed run.
Index ¶
- Variables
- func CleanGenDir(dir string) error
- func DeoptionalizeTSFields(tsDir string, required map[string]map[string]struct{}) error
- func EnsurePythonInitFiles(root, genPkg string) error
- func EnsurePythonTypedMarker(root, genPkg string) error
- func ReadDescriptorSet(path string) (*descriptorpb.FileDescriptorSet, error)
- func RequiredMessageFields(fds *descriptorpb.FileDescriptorSet) map[string]map[string]struct{}
- func RewritePythonImports(root, genPkg string) error
- func SettleDir(dir, backup string, restore bool) error
- func StashDir(dir string) (string, error)
Constants ¶
This section is empty.
Variables ¶
var ImportPrefixRe = regexp.MustCompile(
`^(from )([a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*)( import .*)$`,
)
ImportPrefixRe matches "from <bare_package> import ..." lines in generated Python protobuf files.
Functions ¶
func CleanGenDir ¶
CleanGenDir removes everything in dir except go.mod and go.sum, preserving the module identity so that go mod tidy under go.work stays deterministic.
func DeoptionalizeTSFields ¶
DeoptionalizeTSFields rewrites every `_pb.ts` under tsDir, turning `name?: T | undefined` into `name: T` for each property whose enclosing message + name is in required. Files are written only when a property actually changed.
func EnsurePythonInitFiles ¶
EnsurePythonInitFiles walks the generated Python package directory and creates an empty __init__.py in every directory that lacks one.
func EnsurePythonTypedMarker ¶
EnsurePythonTypedMarker writes an empty PEP 561 py.typed marker at the root of the generated Python package, so basedpyright treats the editable-installed generated package as a typed package and reads its .py/.pyi stubs when resolving proto types for downstream consumers. It is idempotent (an existing marker is left as-is by the WriteFile overwrite of empty content).
func ReadDescriptorSet ¶
func ReadDescriptorSet(path string) (*descriptorpb.FileDescriptorSet, error)
ReadDescriptorSet reads the google.protobuf.FileDescriptorSet `buf build --as-file-descriptor-set` wrote at path, so field options (field_behavior) are read as structured data — the REQUIRED set DeoptionalizeTSFields promotes. An empty file is an empty set.
func RequiredMessageFields ¶
func RequiredMessageFields( fds *descriptorpb.FileDescriptorSet, ) map[string]map[string]struct{}
RequiredMessageFields returns, per fully-qualified message name, the set of camelCase field names (the protobuf-es property names, i.e. json_name) that are singular message fields marked field_behavior = REQUIRED — exactly the fields protoc-gen-es types `?: T | undefined` but the contract guarantees present.
func RewritePythonImports ¶
RewritePythonImports walks the generated Python package directory and rewrites bare cross-package imports to use the fully-qualified path, in both the runtime `_pb2.py`/`_pb2_grpc.py` modules and their `_pb2.pyi`/`_pb2_grpc.pyi` type stubs (the latter so basedpyright resolves proto types for consumers). Only imports whose first path segment names a real proto-package subdirectory of the generated root are qualified; stdlib and third-party imports the mypy `.pyi` stubs carry (collections, typing, grpc) are left alone.
func SettleDir ¶
SettleDir ends a StashDir: on restore (the generator failed) it puts the stashed contents back in place of whatever the generator left, so a failed generator (a buf or BSR error) never leaves committed generated output deleted; either way it removes the backup. An empty backup is a no-op.
Types ¶
This section is empty.
Source Files