tests/testthat/_snaps/roxygen-templates.md

In r-pkgs/gargle: Utilities for Working with Google APIs

PREFIX_auth_description()

Code
  writeLines(PREFIX_auth_description())
Output
  @description
  Authorize PACKAGE to view and manage YOUR STUFF. This function is a
  wrapper around [gargle::token_fetch()].

  By default, you are directed to a web browser, asked to sign in to your
  Google account, and to grant PACKAGE permission to operate on your
  behalf with A GOOGLE PRODUCT. By default, with your permission, these user
  credentials are cached in a folder below your home directory, from where
  they can be automatically refreshed, as necessary. Storage at the user
  level means the same token can be used across multiple projects and
  tokens are less likely to be synced to the cloud by accident.

PREFIX_auth_details()

Code
  writeLines(PREFIX_auth_details())
Output
  @details
  Most users, most of the time, do not need to call `PREFIX_auth()`
  explicitly -- it is triggered by the first action that requires
  authorization. Even when called, the default arguments often suffice.

  However, when necessary, `PREFIX_auth()` allows the user to explicitly:
    * Declare which Google identity to use, via an `email` specification.
    * Use a service account token or workload identity federation via
      `path`.
    * Bring your own `token`.
    * Customize `scopes`.
    * Use a non-default `cache` folder or turn caching off.
    * Explicitly request out-of-band (OOB) auth via `use_oob`.

  If you are interacting with R within a browser (applies to RStudio
  Server, Posit Workbench, Posit Cloud, and Google Colaboratory), you need
  OOB auth or the pseudo-OOB variant. If this does not happen
  automatically, you can request it explicitly with `use_oob = TRUE` or,
  more persistently, by setting an option via
  `options(gargle_oob_default = TRUE)`.

  The choice between conventional OOB or pseudo-OOB auth is determined
  by the type of OAuth client. If the client is of the "installed" type,
  `use_oob = TRUE` results in conventional OOB auth. If the client is of
  the "web" type, `use_oob = TRUE` results in pseudo-OOB auth. Packages
  that provide a built-in OAuth client can usually detect which type of
  client to use. But if you need to set this explicitly, use the
  `"gargle_oauth_client_type"` option:
  ```r
  options(gargle_oauth_client_type = "web")       # pseudo-OOB
  # or, alternatively
  options(gargle_oauth_client_type = "installed") # conventional OOB
  ```

  For details on the many ways to find a token, see
  [gargle::token_fetch()]. For deeper control over auth, use
  [PREFIX_auth_configure()] to bring your own OAuth client or API key.
  To learn more about gargle options, see [gargle::gargle_options].

PREFIX_auth_params()

Code
  writeLines(PREFIX_auth_params())
Output
  @inheritParams gargle::credentials_service_account
  @inheritParams gargle::credentials_external_account
  @inheritParams gargle::credentials_app_default
  @inheritParams gargle::credentials_gce
  @inheritParams gargle::credentials_byo_oauth2
  @inheritParams gargle::credentials_user_oauth2
  @inheritParams gargle::gargle2.0_token

PREFIX_deauth_description_with_api_key()

Code
  writeLines(PREFIX_deauth_description_with_api_key())
Output
  @description
  Put PACKAGE into a de-authorized state. Instead of sending a token,
  PACKAGE will send an API key. This can be used to access public
  resources for which no Google sign-in is required. This is handy for using
  PACKAGE in a non-interactive setting to make requests that do not
  require a token. It will prevent the attempt to obtain a token
  interactively in the browser. The user can configure their own API key
  via [PREFIX_auth_configure()] and retrieve that key via
  [PREFIX_api_key()].
  In the absence of a user-configured key, a built-in default key is used.

PREFIX_deauth_description_no_api_key()

Code
  writeLines(PREFIX_deauth_description_no_api_key())
Output
  @description
  Clears any currently stored token. The next time PACKAGE needs a token,
  the token acquisition process starts over, with a fresh call to
  [PREFIX_auth()] and, therefore, internally, a call to
  [gargle::token_fetch()]. Unlike some other packages that use gargle,
  PACKAGE is not usable in a de-authorized state. Therefore, calling
  `PREFIX_deauth()` only clears the token, i.e. it does NOT imply that
  subsequent requests are made with an API key in lieu of a token.

PREFIX_token_description()

Code
  writeLines(PREFIX_token_description())
Output
  @description
  For internal use or for those programming around the GOOGLE API.
  Returns a token pre-processed with [httr::config()]. Most users
  do not need to handle tokens "by hand" or, even if they need some
  control, [PREFIX_auth()] is what they need. If there is no current
  token, [PREFIX_auth()] is called to either load from cache or
  initiate OAuth2.0 flow.
  If auth has been deactivated via [PREFIX_deauth()], `PREFIX_token()`
  returns `NULL`.

PREFIX_token_return()

Code
  writeLines(PREFIX_token_return())
Output
  @return A `request` object (an S3 class provided by [httr][httr::httr]).

PREFIX_has_token_description()

Code
  writeLines(PREFIX_has_token_description())
Output
  @description
  Reports whether PACKAGE has stored a token, ready for use in downstream
  requests.

PREFIX_has_token_return()

Code
  writeLines(PREFIX_has_token_return())
Output
  @return Logical.

PREFIX_auth_configure_description()

Code
  writeLines(PREFIX_auth_configure_description())
Output
  @description
  These functions give more control over and visibility into the auth
  configuration than [PREFIX_auth()] does. `PREFIX_auth_configure()`
  lets the user specify their own:
    * OAuth client, which is used when obtaining a user token.
    * API key. If PACKAGE is de-authorized via [PREFIX_deauth()], all
      requests are sent with an API key in lieu of a token.

  See the `vignette("get-api-credentials", package = "gargle")`
  for more.
  If the user does not configure these settings, internal defaults
  are used.

  `PREFIX_oauth_client()` and `PREFIX_api_key()` retrieve the
  currently configured OAuth client and API key, respectively.

PREFIX_auth_configure_params()

Code
  writeLines(PREFIX_auth_configure_params())
Output
  @param client A Google OAuth client, presumably constructed via
  [gargle::gargle_oauth_client_from_json()]. Note, however, that it is
  preferred to specify the client with JSON, using the `path` argument.
  @inheritParams gargle::gargle_oauth_client_from_json
  @param api_key API key.
  @param app `r lifecycle::badge('deprecated')` Replaced by the `client`
  argument.

PREFIX_auth_configure_return()

Code
  writeLines(PREFIX_auth_configure_return())
Output
  @return
    * `PREFIX_auth_configure()`: An object of R6 class
      [gargle::AuthState], invisibly.
    * `PREFIX_oauth_client()`: the current user-configured OAuth client.
    * `PREFIX_api_key()`: the current user-configured API key.

PREFIX_user_description()

Code
  writeLines(PREFIX_user_description())
Output
  @description
  Reveals the email address of the user associated with the current token.
  If no token has been loaded yet, this function does not initiate auth.

PREFIX_user_seealso()

Code
  writeLines(PREFIX_user_seealso())
Output
  @seealso [gargle::token_userinfo()], [gargle::token_email()],
  [gargle::token_tokeninfo()]

PREFIX_user_return()

Code
  writeLines(PREFIX_user_return())
Output
  @return An email address or, if no token has been loaded, `NULL`.

r-pkgs/gargle documentation built on Sept. 3, 2023, 12:22 a.m.