diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 087f0b05..ed7650c7 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -19,6 +19,8 @@ jobs: group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} env: GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + permissions: + contents: write steps: - uses: actions/checkout@v3 diff --git a/.github/workflows/test-coverage.yaml b/.github/workflows/test-coverage.yaml index 2c5bb502..27d45283 100644 --- a/.github/workflows/test-coverage.yaml +++ b/.github/workflows/test-coverage.yaml @@ -31,7 +31,7 @@ jobs: covr::codecov( quiet = FALSE, clean = FALSE, - install_path = file.path(Sys.getenv("RUNNER_TEMP"), "package") + install_path = file.path(normalizePath(Sys.getenv("RUNNER_TEMP"), winslash = "/"), "package") ) shell: Rscript {0} diff --git a/DESCRIPTION b/DESCRIPTION index 40a0c2c8..5aa8c203 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -17,7 +17,7 @@ License: GPL-3 URL: https://bigrquery.r-dbi.org, https://github.com/r-dbi/bigrquery BugReports: https://github.com/r-dbi/bigrquery/issues Depends: - R (>= 3.3) + R (>= 3.6) Imports: assertthat, bit64, @@ -52,6 +52,8 @@ LinkingTo: progress, rapidjsonr, Rcpp +Config/Needs/website: tidyverse/tidytemplate +Config/testthat/edition: 3 Encoding: UTF-8 Roxygen: list(markdown = TRUE) RoxygenNote: 7.2.3 @@ -93,4 +95,3 @@ Collate: 'old-tabledata.R' 'utils.R' 'zzz.R' -Config/testthat/edition: 3 diff --git a/_pkgdown.yml b/_pkgdown.yml index 45557634..0d9e4c98 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -1,8 +1,15 @@ url: https://bigrquery.r-dbi.org -authors: - Jennifer Bryan: - href: https://jennybryan.org +template: + package: tidytemplate + bootstrap: 5 + + includes: + in_header: | + + +development: + mode: auto reference: - title: DBI and dplyr @@ -14,10 +21,6 @@ reference: contents: - starts_with("bq") -template: - params: - ganalytics: UA-115082821-1 - news: releases: - text: "bigrquery 1.4.0" diff --git a/man/bq_auth.Rd b/man/bq_auth.Rd index 4ba88965..f7902183 100644 --- a/man/bq_auth.Rd +++ b/man/bq_auth.Rd @@ -15,18 +15,28 @@ bq_auth( ) } \arguments{ -\item{email}{Optional. Allows user to target a specific Google identity. If -specified, this is used for token lookup, i.e. to determine if a suitable -token is already available in the cache. If no such token is found, \code{email} -is used to pre-select the targetted Google identity in the OAuth chooser. -Note, however, that the email associated with a token when it's cached is -always determined from the token itself, never from this argument. Use \code{NA} -or \code{FALSE} to match nothing and force the OAuth dance in the browser. Use -\code{TRUE} to allow email auto-discovery, if exactly one matching token is -found in the cache. Specify just the domain with a glob pattern, e.g. -\code{"*@example.com"}, to create code that "just works" for both -\code{alice@example.com} and \code{bob@example.com}. Defaults to the option named -"gargle_oauth_email", retrieved by \code{\link[gargle:gargle_oauth_email]{gargle_oauth_email()}}.} +\item{email}{Optional. If specified, \code{email} can take several different +forms: +\itemize{ +\item \code{"jane@gmail.com"}, i.e. an actual email address. This allows the user to +target a specific Google identity. If specified, this is used for token +lookup, i.e. to determine if a suitable token is already available in the +cache. If no such token is found, \code{email} is used to pre-select the targeted +Google identity in the OAuth chooser. (Note, however, that the email +associated with a token when it's cached is always determined from the token +itself, never from this argument). +\item \code{"*@example.com"}, i.e. a domain-only glob pattern. This can be helpful if +you need code that "just works" for both \code{alice@example.com} and +\code{bob@example.com}. +\item \code{TRUE} means that you are approving email auto-discovery. If exactly one +matching token is found in the cache, it will be used. +\item \code{FALSE} or \code{NA} mean that you want to ignore the token cache and force a +new OAuth dance in the browser. +} + +Defaults to the option named \code{"gargle_oauth_email"}, retrieved by +\code{\link[gargle:gargle_oauth_email]{gargle_oauth_email()}} (unless a wrapper package implements different +default behavior).} \item{path}{JSON identifying the service account, in one of the forms supported for the \code{txt} argument of \code{\link[jsonlite:fromJSON]{jsonlite::fromJSON()}} (typically, a @@ -38,8 +48,18 @@ Pick from those listed at \url{https://developers.google.com/identity/protocols/ \item{cache}{Specifies the OAuth token cache. Defaults to the option named \code{"gargle_oauth_cache"}, retrieved via \code{\link[gargle:gargle_oauth_cache]{gargle_oauth_cache()}}.} -\item{use_oob}{Whether to prefer out-of-band authentication. Defaults to the -value returned by \code{\link[gargle:gargle_oob_default]{gargle_oob_default()}}.} +\item{use_oob}{Whether to use out-of-band authentication (or, perhaps, a +variant implemented by gargle and known as "pseudo-OOB") when first +acquiring the token. Defaults to the value returned by +\code{\link[gargle:gargle_oob_default]{gargle_oob_default()}}. Note that (pseudo-)OOB auth only affects +the initial OAuth dance. If we retrieve (and possibly refresh) a +cached token, \code{use_oob} has no effect. + +If the OAuth client is provided implicitly by a wrapper package, its type +probably defaults to the value returned by +\code{\link[gargle:gargle_oauth_client_type]{gargle_oauth_client_type()}}. You can take control of the client +type by setting \code{options(gargle_oauth_client_type = "web")} or +\code{options(gargle_oauth_client_type = "installed")}.} \item{token}{A token with class \link[httr:Token-class]{Token2.0} or an object of httr's class \code{request}, i.e. a token that has been prepared with @@ -57,40 +77,47 @@ 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. - -If you are interacting with R within a browser (applies to RStudio Server, -Posit Workbench, and Posit Cloud), you need a variant of this flow, -known as out-of-band auth ("oob"). If this does not happen -automatically, you can request it yourself with \code{use_oob = TRUE} or, -more persistently, by setting an option via -\code{options(gargle_oob_default = TRUE)}. } \details{ Most users, most of the time, do not need to call \code{bq_auth()} explicitly -- it is triggered by the first action that requires authorization. Even when called, the default arguments often suffice. -However, when necessary, this function allows the user to explicitly: + +However, when necessary, \code{bq_auth()} allows the user to explicitly: \itemize{ -\item Declare which Google identity to use, via an email address. If there -are multiple cached tokens, this can clarify which one to use. It can -also force bigrquery to switch from one identity to another. If -there's no cached token for the email, this triggers a return to the -browser to choose the identity and give consent. You can specify just -the domain by using a glob pattern. This means that a script -containing \code{email = "*@example.com"} can be run without further -tweaks on the machine of either \code{alice@example.com} or -\code{bob@example.com}. -\item Use a service account token or workload identity federation. -\item Bring their own \link[httr:Token-class]{Token2.0}. -\item Specify non-default behavior re: token caching and out-of-bound -authentication. -\item Customize scopes. +\item Declare which Google identity to use, via an \code{email} specification. +\item Use a service account token or workload identity federation via +\code{path}. +\item Bring your own \code{token}. +\item Customize \code{scopes}. +\item Use a non-default \code{cache} folder or turn caching off. +\item Explicitly request out-of-band (OOB) auth via \code{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 \code{use_oob = TRUE} or, +more persistently, by setting an option via +\code{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, +\code{use_oob = TRUE} results in conventional OOB auth. If the client is of +the "web" type, \code{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 +\code{"gargle_oauth_client_type"} option: + +\if{html}{\out{
}}\preformatted{options(gargle_oauth_client_type = "web") # pseudo-OOB +# or, alternatively +options(gargle_oauth_client_type = "installed") # conventional OOB +}\if{html}{\out{
}} + For details on the many ways to find a token, see \code{\link[gargle:token_fetch]{gargle::token_fetch()}}. For deeper control over auth, use \code{\link[=bq_auth_configure]{bq_auth_configure()}} to bring your own OAuth client or API key. -Read more about gargle options, see \link[gargle:gargle_options]{gargle::gargle_options}. +To learn more about gargle options, see \link[gargle:gargle_options]{gargle::gargle_options}. } \examples{ \dontrun{ diff --git a/src/RcppExports.cpp b/src/RcppExports.cpp index da73b8cf..e50c93e7 100644 --- a/src/RcppExports.cpp +++ b/src/RcppExports.cpp @@ -49,7 +49,7 @@ BEGIN_RCPP END_RCPP } -RcppExport SEXP null_to_na_(SEXP); +RcppExport SEXP null_to_na_(void *); static const R_CallMethodDef CallEntries[] = { {"_bigrquery_bq_parse", (DL_FUNC) &_bigrquery_bq_parse, 2},