go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/lucicfg/starlark/stdlib/native_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  # TODO(vadimsh): Figure out how to document 'load'. The AST parser refuses to
    23  # parse a function named 'load' :(
    24  #
    25  # @unused
    26  def __load(module, *args, **kwargs):
    27      """Loads a Starlark module as a library (if it hasn't been loaded before).
    28  
    29      Extracts one or more values from it, and binds them to names in the current
    30      module.
    31  
    32      A load statement requires at least two "arguments". The first must be a
    33      literal string, it identifies the module to load. The remaining arguments
    34      are a mixture of literal strings, such as `'x'`, or named literal strings,
    35      such as `y='x'`.
    36  
    37      The literal string (`'x'`), which must denote a valid identifier not
    38      starting with `_`, specifies the name to extract from the loaded module. In
    39      effect, names starting with `_` are not exported. The name (`y`) specifies
    40      the local name. If no name is given, the local name matches the quoted name.
    41  
    42      ```
    43      load('//module.star', 'x', 'y', 'z')       # assigns x, y, and z
    44      load('//module.star', 'x', y2='y', 'z')    # assigns x, y2, and z
    45      ```
    46  
    47      A load statement within a function is a static error.
    48  
    49      See also [Modules and packages](#modules-and-packages) for how load(...)
    50      interacts with exec(...).
    51  
    52      Args:
    53        module: module to load, i.e. `//path/within/current/package.star` or
    54          `@<pkg>//path/within/pkg.star` or `./relative/path.star`. Required.
    55        *args: what values to import under their original names.
    56        **kwargs: what values to import and bind under new names.
    57      """
    58      _unused(module, args, kwargs)
    59  
    60  def exec(module):
    61      """Executes another Starlark module for its side effects.
    62  
    63      See also [Modules and packages](#modules_and_packages) for how load(...)
    64      interacts with exec(...).
    65  
    66      Args:
    67        module: module to execute, i.e. `//path/within/current/package.star` or
    68          `@<pkg>//path/within/pkg.star` or `./relative/path.star`. Required.
    69  
    70      Returns:
    71        A struct with all exported symbols of the executed module.
    72      """
    73      _unused(module)
    74  
    75  def fail(msg, trace = None):
    76      """Aborts the execution with an error message.
    77  
    78      Args:
    79        msg: the error message string. Required.
    80        trace: a custom trace, as returned by stacktrace(...) to attach to
    81          the error. This may be useful if the root cause of the error is far
    82          from where `fail` is called.
    83      """
    84      _unused(msg, trace)
    85  
    86  def stacktrace(skip = None):
    87      """Captures and returns a stack trace of the caller.
    88  
    89      A captured stacktrace is an opaque object that can be stringified to get a
    90      nice looking trace (e.g. for error messages).
    91  
    92      Args:
    93        skip: how many innermost call frames to skip. Default is 0.
    94      """
    95      _unused(skip)
    96  
    97  def struct(**kwargs):
    98      """Returns an immutable struct object with given fields.
    99  
   100      Can be used to define namespaces, for example:
   101  
   102      ```python
   103      def _func1():
   104          ...
   105  
   106      def _func2():
   107          ...
   108  
   109      exported = struct(
   110          func1 = _func1,
   111          func2 = _func2,
   112      )
   113      ```
   114  
   115      Then `_func1` can be called as `exported.func1()`.
   116  
   117      Args:
   118        **kwargs: fields to put into the returned struct object.
   119      """
   120      _unused(kwargs)
   121  
   122  def to_json(value):
   123      """Serializes a value to a compact JSON string.
   124  
   125      Doesn't support integers that do not fit int64. Fails if the value has
   126      cycles.
   127  
   128      *** note
   129      **Deprecated.** Use json.encode(...) instead. Note that json.encode(...)
   130      will retain the order of dict keys, unlike to_json(...) that always sorts
   131      them alphabetically.
   132      ***
   133  
   134      Args:
   135        value: a primitive Starlark value: a scalar, or a list/tuple/dict
   136          containing only primitive Starlark values. Required.
   137      """
   138      _unused(value)
   139  
   140  def _unused(*args):  # @unused
   141      """Used exclusively to shut up `unused-variable` lint.
   142  
   143      DocTags:
   144        Hidden.
   145      """