docs: def use_options(allowed):
      """
      Decorator that logs warnings when unpermitted options are passed into its
      wrapped function.
  
      Requires that wrapped function has an keyword-only argument named
      `options`. If wrapped function has {options} in its docstring, fills in
      with the docs for allowed options.
  
      Args:
          allowed (list str): list of option keys allowed. If the wrapped
              function is called with an option not in allowed, log a warning.
              All values in allowed must also be present in `defaults`.
  
      Returns:
          Wrapped function with options validation.
  
      >>> @use_options(['title'])
      ... def test(*, options={}): return options['title']
  
      >>> test(options={'title': 'Hello'})
      'Hello'
  
      >>> # test(options={'not_allowed': 123}) # Also logs error message
      ''
      """
  
      def update_docstring(f):
          _update_option_docstring(f, allowed)
  
          @functools.wraps(f)
          def check_options(*args, **kwargs):
              options = kwargs.get('options', {})
              not_allowed = [
                  option for option in options if option not in allowed
                  # Don't validate private options
                  and not option.startswith('_')
              ]
              if not_allowed:
                  logging.warning(
                      'The following options are not supported by '
                      'this function and will likely result in '
                      'undefined behavior: {}.'.format(not_allowed)
                  )
  
              return f(*args, **kwargs)
  
          return check_options
  
      return update_docstring