go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/lucicfg/starlark/stdlib/proto_doc.star (about)

     1  # Copyright 2018 The LUCI Authors.
     2  #
     3  # Licensed under the Apache License, Version 2.0 (the "License");
     4  # you may not use this file except in compliance with the License.
     5  # You may obtain a copy of the License at
     6  #
     7  #      http://www.apache.org/licenses/LICENSE-2.0
     8  #
     9  # Unless required by applicable law or agreed to in writing, software
    10  # distributed under the License is distributed on an "AS IS" BASIS,
    11  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  # See the License for the specific language governing permissions and
    13  # limitations under the License.
    14  
    15  """Some extra documentation.
    16  
    17  This module is not imported by anything. It exists only to document public
    18  native symbols exposed by `lucicfg` go code in the global namespace of all
    19  modules.
    20  """
    21  
    22  def _to_textpb(msg):
    23      """Serializes a protobuf message to a string using ASCII proto serialization.
    24  
    25      Args:
    26        msg: a proto message to serialize. Required.
    27      """
    28      _unused(msg)
    29  
    30  def _to_jsonpb(msg, use_proto_names = None):
    31      """Serializes a protobuf message to a string using JSONPB serialization.
    32  
    33      Args:
    34        msg: a proto message to serialize. Required.
    35        use_proto_names: boolean, whether to use snake_case in field names
    36          instead of camelCase. The default is False.
    37      """
    38      _unused(msg, use_proto_names)
    39  
    40  def _to_wirepb(msg):
    41      """Serializes a protobuf message to a string using binary wire encoding.
    42  
    43      Args:
    44        msg: a proto message to serialize. Required.
    45      """
    46      _unused(msg)
    47  
    48  def _from_textpb(ctor, text, discard_unknown = None):
    49      """Deserializes a protobuf message given its ASCII proto serialization.
    50  
    51      The returned message is frozen. Use proto.clone(...) to get a mutable
    52      copy if necessary.
    53  
    54      Args:
    55        ctor: a message constructor function, the same one you would normally use
    56          to create a new message. Required.
    57        text: a string with the serialized message. Required.
    58        discard_unknown: boolean, whether to discard unrecognized fields. The
    59          default is False.
    60  
    61      Returns:
    62        Deserialized frozen message constructed via `ctor`.
    63      """
    64      _unused(ctor, text, discard_unknown)
    65  
    66  def _from_jsonpb(ctor, text, discard_unknown = None):
    67      """Deserializes a protobuf message given its JSONPB serialization.
    68  
    69      The returned message is frozen. Use proto.clone(...) to get a mutable
    70      copy if necessary.
    71  
    72      Args:
    73        ctor: a message constructor function, the same one you would normally use
    74          to create a new message. Required.
    75        text: a string with the serialized message. Required.
    76        discard_unknown: boolean, whether to discard unrecognized fields. The
    77          default is True.
    78  
    79      Returns:
    80        Deserialized frozen message constructed via `ctor`.
    81      """
    82      _unused(ctor, text, discard_unknown)
    83  
    84  def _from_wirepb(ctor, blob, discard_unknown = None):
    85      """Deserializes a protobuf message given its wire serialization.
    86  
    87      The returned message is frozen. Use proto.clone(...) to get a mutable
    88      copy if necessary.
    89  
    90      Args:
    91        ctor: a message constructor function, the same one you would normally use
    92          to create a new message. Required.
    93        blob: a string with the serialized message. Required.
    94        discard_unknown: boolean, whether to discard unrecognized fields. The
    95          default is True.
    96  
    97      Returns:
    98        Deserialized frozen message constructed via `ctor`.
    99      """
   100      _unused(ctor, blob, discard_unknown)
   101  
   102  def _struct_to_textpb(s):
   103      """Converts a struct to a text proto string.
   104  
   105      Args:
   106        s: a struct object. May not contain dicts.
   107  
   108      Returns:
   109        A str containing a text format protocol buffer message.
   110      """
   111      _unused(s)
   112  
   113  def _clone(msg):
   114      """Returns a deep copy of a given proto message.
   115  
   116      Args:
   117        msg: a proto message to make a copy of. Required.
   118  
   119      Returns:
   120        A deep copy of the message.
   121      """
   122      _unused(msg)
   123  
   124  def _has(msg, field):
   125      """Checks if a proto message has the given optional field set.
   126  
   127      Following rules apply:
   128  
   129        * Fields that are not defined in the `*.proto` file are always unset.
   130        * Singular fields of primitive types (e.g. `int64`), repeated and map
   131          fields (even empty ones) are always set. There's no way to distinguish
   132          zero values of such fields from unset fields.
   133        * Singular fields of message types are set only if they were explicitly
   134          initialized (e.g. by writing to such field or reading a default value
   135          from it).
   136        * Alternatives of a `oneof` field (regardless of their type) are
   137          initialized only when they are explicitly "picked".
   138  
   139      Args:
   140        msg: a message to check. Required.
   141        field: a string name of the field to check. Required.
   142  
   143      Returns:
   144        True if the message has the field set.
   145      """
   146      _unused(msg, field)
   147  
   148  def _unused(*args):  # @unused
   149      """Used exclusively to shut up `unused-variable` lint.
   150  
   151      DocTags:
   152        Hidden.
   153      """
   154  
   155  proto = struct(
   156      to_textpb = _to_textpb,
   157      to_jsonpb = _to_jsonpb,
   158      to_wirepb = _to_wirepb,
   159      from_textpb = _from_textpb,
   160      from_jsonpb = _from_jsonpb,
   161      from_wirepb = _from_wirepb,
   162      struct_to_textpb = _struct_to_textpb,
   163      clone = _clone,
   164      has = _has,
   165  )