compiler/python/generator.h

0001 // Protocol Buffers - Google's data interchange format
0002 // Copyright 2008 Google Inc.  All rights reserved.
0003 //
0004 // Use of this source code is governed by a BSD-style
0005 // license that can be found in the LICENSE file or at
0006 // https://developers.google.com/open-source/licenses/bsd
0007
0008 // Author: robinson@google.com (Will Robinson)
0009 //
0010 // Generates Python code for a given .proto file.
0011
0012 #ifndef GOOGLE_PROTOBUF_COMPILER_PYTHON_GENERATOR_H__
0013 #define GOOGLE_PROTOBUF_COMPILER_PYTHON_GENERATOR_H__
0014
0015 #include <cstdint>
0016 #include <string>
0017 #include <vector>
0018
0019 #include "absl/strings/string_view.h"
0020 #include "absl/synchronization/mutex.h"
0021 #include "google/protobuf/compiler/code_generator.h"
0022 #include "google/protobuf/descriptor.pb.h"
0023
0024 // Must be included last.
0025 #include "google/protobuf/port_def.inc"
0026
0027 namespace google {
0028 namespace protobuf {
0029
0030 class Descriptor;
0031 class EnumDescriptor;
0032 class EnumValueDescriptor;
0033 class FieldDescriptor;
0034 class OneofDescriptor;
0035 class ServiceDescriptor;
0036
0037 namespace io {
0038 class Printer;
0039 }
0040
0041 namespace compiler {
0042 namespace python {
0043
0044 // CodeGenerator implementation for generated Python protocol buffer classes.
0045 // If you create your own protocol compiler binary and you want it to support
0046 // Python output, you can do so by registering an instance of this
0047 // CodeGenerator with the CommandLineInterface in your main() function.
0048
0049 struct GeneratorOptions {
0050   bool generate_pyi = false;
0051   bool annotate_pyi = false;
0052   bool bootstrap = false;
0053   bool strip_nonfunctional_codegen = false;
0054 };
0055
0056 class PROTOC_EXPORT Generator : public CodeGenerator {
0057  public:
0058   Generator();
0059   Generator(const Generator&) = delete;
0060   Generator& operator=(const Generator&) = delete;
0061   ~Generator() override;
0062
0063   // CodeGenerator methods.
0064   bool Generate(const FileDescriptor* file, const std::string& parameter,
0065                 GeneratorContext* generator_context,
0066                 std::string* error) const override;
0067
0068   uint64_t GetSupportedFeatures() const override {
0069     return Feature::FEATURE_PROTO3_OPTIONAL |
0070            Feature::FEATURE_SUPPORTS_EDITIONS;
0071   }
0072   Edition GetMinimumEdition() const override { return Edition::EDITION_PROTO2; }
0073   Edition GetMaximumEdition() const override { return Edition::EDITION_2023; }
0074   std::vector<const FieldDescriptor*> GetFeatureExtensions() const override {
0075     return {};
0076   }
0077
0078   void set_opensource_runtime(bool opensource) {
0079     opensource_runtime_ = opensource;
0080   }
0081
0082  private:
0083   GeneratorOptions ParseParameter(absl::string_view parameter,
0084                                   std::string* error) const;
0085   void PrintImports() const;
0086   template <typename DescriptorT>
0087   std::string GetResolvedFeatures(const DescriptorT& descriptor) const;
0088   void PrintResolvedFeatures() const;
0089   void PrintFileDescriptor() const;
0090   void PrintAllEnumsInFile() const;
0091   void PrintNestedEnums(const Descriptor& descriptor,
0092                         const DescriptorProto& proto) const;
0093   void PrintEnum(const EnumDescriptor& enum_descriptor,
0094                  const EnumDescriptorProto& proto) const;
0095
0096   void PrintFieldDescriptor(const FieldDescriptor& field,
0097                             const FieldDescriptorProto& proto) const;
0098   void PrintFieldDescriptorsInDescriptor(
0099       const Descriptor& message_descriptor, const DescriptorProto& proto,
0100       bool is_extension, absl::string_view list_variable_name) const;
0101   void PrintFieldsInDescriptor(const Descriptor& message_descriptor,
0102                                const DescriptorProto& proto) const;
0103   void PrintExtensionsInDescriptor(const Descriptor& message_descriptor,
0104                                    const DescriptorProto& proto) const;
0105   void PrintMessageDescriptors() const;
0106   void PrintDescriptor(const Descriptor& message_descriptor,
0107                        const DescriptorProto& proto) const;
0108   void PrintNestedDescriptors(const Descriptor& containing_descriptor,
0109                               const DescriptorProto& proto) const;
0110
0111   void PrintMessages() const;
0112   void PrintMessage(const Descriptor& message_descriptor,
0113                     absl::string_view prefix,
0114                     std::vector<std::string>* to_register,
0115                     bool is_nested) const;
0116   void PrintNestedMessages(const Descriptor& containing_descriptor,
0117                            absl::string_view prefix,
0118                            std::vector<std::string>* to_register) const;
0119
0120   void FixForeignFieldsInDescriptors() const;
0121   void FixForeignFieldsInDescriptor(
0122       const Descriptor& descriptor,
0123       const Descriptor* containing_descriptor) const;
0124   void FixForeignFieldsInField(const Descriptor* containing_type,
0125                                const FieldDescriptor& field,
0126                                absl::string_view python_dict_name) const;
0127   void AddMessageToFileDescriptor(const Descriptor& descriptor) const;
0128   void AddEnumToFileDescriptor(const EnumDescriptor& descriptor) const;
0129   void AddExtensionToFileDescriptor(const FieldDescriptor& descriptor) const;
0130   void AddServiceToFileDescriptor(const ServiceDescriptor& descriptor) const;
0131   std::string FieldReferencingExpression(
0132       const Descriptor* containing_type, const FieldDescriptor& field,
0133       absl::string_view python_dict_name) const;
0134   template <typename DescriptorT>
0135   void FixContainingTypeInDescriptor(
0136       const DescriptorT& descriptor,
0137       const Descriptor* containing_descriptor) const;
0138
0139   void PrintTopBoilerplate() const;
0140   void PrintServices() const;
0141   void PrintServiceDescriptors() const;
0142   void PrintServiceDescriptor(const ServiceDescriptor& descriptor) const;
0143   void PrintServiceClass(const ServiceDescriptor& descriptor) const;
0144   void PrintServiceStub(const ServiceDescriptor& descriptor) const;
0145   void PrintDescriptorKeyAndModuleName(
0146       const ServiceDescriptor& descriptor) const;
0147
0148   void PrintEnumValueDescriptor(const EnumValueDescriptor& descriptor,
0149                                 const EnumValueDescriptorProto& proto) const;
0150   bool GeneratingDescriptorProto() const;
0151
0152   template <typename DescriptorT>
0153   std::string ModuleLevelDescriptorName(const DescriptorT& descriptor) const;
0154   std::string ModuleLevelMessageName(const Descriptor& descriptor) const;
0155   std::string ModuleLevelServiceDescriptorName(
0156       const ServiceDescriptor& descriptor) const;
0157
0158   template <typename DescriptorProtoT>
0159   void PrintSerializedPbInterval(const DescriptorProtoT& descriptor_proto,
0160                                  absl::string_view name) const;
0161
0162   template <typename DescriptorT>
0163   bool PrintDescriptorOptionsFixingCode(
0164       const DescriptorT& descriptor, const typename DescriptorT::Proto& proto,
0165       absl::string_view descriptor_str) const;
0166
0167   void FixAllDescriptorOptions() const;
0168   void FixOptionsForField(const FieldDescriptor& field,
0169                           const FieldDescriptorProto& proto) const;
0170   void FixOptionsForOneof(const OneofDescriptor& oneof,
0171                           const OneofDescriptorProto& proto) const;
0172   void FixOptionsForEnum(const EnumDescriptor& descriptor,
0173                          const EnumDescriptorProto& proto) const;
0174   void FixOptionsForService(const ServiceDescriptor& descriptor,
0175                             const ServiceDescriptorProto& proto) const;
0176   void FixOptionsForMessage(const Descriptor& descriptor,
0177                             const DescriptorProto& proto) const;
0178
0179   void SetSerializedPbInterval(const FileDescriptorProto& file) const;
0180   void SetMessagePbInterval(const DescriptorProto& message_proto,
0181                             const Descriptor& descriptor) const;
0182
0183   void CopyPublicDependenciesAliases(absl::string_view copy_from,
0184                                      const FileDescriptor* file) const;
0185
0186   // Very coarse-grained lock to ensure that Generate() is reentrant.
0187   // Guards file_, printer_ and file_descriptor_serialized_.
0188   mutable absl::Mutex mutex_;
0189   mutable const FileDescriptor* file_;  // Set in Generate().  Under mutex_.
0190   mutable FileDescriptorProto proto_;   // Set in Generate().  Under mutex_.
0191   mutable std::string file_descriptor_serialized_;
0192   mutable io::Printer* printer_;  // Set in Generate().  Under mutex_.
0193
0194   bool opensource_runtime_ = true;
0195 };
0196
0197 }  // namespace python
0198 }  // namespace compiler
0199 }  // namespace protobuf
0200 }  // namespace google
0201
0202 #include "google/protobuf/port_undef.inc"
0203
0204 #endif  // GOOGLE_PROTOBUF_COMPILER_PYTHON_GENERATOR_H__