diff --git a/DESCRIPTION b/DESCRIPTION index d685ed9f..eea317e1 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: boxr Type: Package Title: Interface for the 'Box.com API' -Version: 0.3.4.99999 +Version: 0.3.5 Authors@R: c( person("Brendan", "Rocks", email = "foss@brendanrocks.com", role = c("aut")), diff --git a/NEWS.md b/NEWS.md index 4b652870..99fa375c 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,7 +1,9 @@ -# boxr 0.3.4.99999 +# boxr 0.3.5 ## Improvements +* adds automatic-retry to authentication functions, `box_auth()` and `box_auth_service()`. (#131) + * adds `box_auth_service()` to support OAuth2.0 using JWT, also adds `box_dir_invite()` to invite a collaboration on a Box folder. This makes it easier to authenticate to box.com from remote computers (e.g. RStudio Cloud, RStudio Server) (#23) * modifies `box_source()`: adds `...` argument to pass other arguments to `source()`. @@ -110,7 +112,7 @@ write function ([rio::export](https://github.com/leeper/rio)), the file type can be determined automatically from the filename provided. * `box_add_description` A simple way to add a description to a file on box.com. -These are a useful way to decribe the contents of a file, and can also be used +These are a useful way to describe the contents of a file, and can also be used like commit messages on GitHub, to describe recent changes made. * `box_fresh_auth` A convenience function for users having trouble @@ -127,11 +129,11 @@ place of a file_id string ## Improvements -* Example of usage with `magrittr` pipes is added to the [README](README.md) +* Example of usage with `magrittr` pipes is added to the README. * box file/folder id's are now validated locally before requests are sent -* Filenames are now validated locally, with helpful/informative error mesages +* Filenames are now validated locally, with helpful/informative error messages * `box_read` now accepts a user specified read function, which is now by default `rio::import` @@ -148,7 +150,7 @@ interested (`?boxr_S3_classes`) * `box_getwd` no longer logs an uninformative message * Documentation / collaboration improvements (improved function documentation, -[variable naming conventions](R/README.md), and a code of conduct) +variable naming conventions (`R/README.md`), and a code of conduct) * Improved tests @@ -157,7 +159,7 @@ interested (`?boxr_S3_classes`) * `options(boxr.progress = TRUE)` is now respected consistently -* Fix for spurious warnings comming from the latest version of `httr` (see +* Fix for spurious warnings coming from the latest version of `httr` (see jeroenooms/curl#30 and hadley/httr#252) * Fix for weird reporting for certain valid API queries, which return exactly 0 @@ -168,7 +170,7 @@ results # boxr v0.2.9 -Note: Skipped a version increment for CRAN iterationsii +Note: Skipped a version increment for CRAN iterations ## Bug Fixes @@ -176,7 +178,7 @@ Note: Skipped a version increment for CRAN iterationsii * Namespace stuff for the latest Rbuild under Windows -## Installtion +## Installation Now up on CRAN: diff --git a/R/boxr-package.R b/R/boxr-package.R index 89d3cecc..b6526687 100644 --- a/R/boxr-package.R +++ b/R/boxr-package.R @@ -1,15 +1,15 @@ #' boxr: access the Box API #' -#' A lightweight, high-level R interface for the [box.com](https://developer.box.com/docs) API +#' A lightweight, *opinionated*, high-level R interface for the [box.com](https://developer.box.com/docs) API. #' #' This package has a documentation-website (created using [pkgdown](https://pkgdown.r-lib.org/)), containing: #' -#' - [README](https://r-box.github.io/boxr) +#' - [README](https://r-box.github.io/boxr). #' - [Get-started article](https://r-box.github.io/boxr/articles/boxr.html), -#' also accessible from R: `vignette("boxr")` -#' - [Function reference](https://r-box.github.io/boxr/reference/index.html) +#' also accessible from R: `vignette("boxr")`. +#' - [Function reference](https://r-box.github.io/boxr/reference/index.html). #' -#' The `boxr` source-repository is at GitHub: . +#' The boxr source-repository is at GitHub: . #' #' If you find anything you think might be a bug, please report it as a #' [GitHub issue](https://github.com/r-box/boxr/issues)! diff --git a/R/boxr__internal_diff_and_uldl.R b/R/boxr__internal_diff_and_uldl.R index 3b7882be..106b6476 100644 --- a/R/boxr__internal_diff_and_uldl.R +++ b/R/boxr__internal_diff_and_uldl.R @@ -1,4 +1,4 @@ -#' Single Directory Operations for Downloading and Uploading mutiple Files +#' Single Directory Operations for Downloading and Uploading multiple Files #' #' Download or upload the contents of a box.com directory, not including #' subdirectories diff --git a/R/boxr__internal_dir_comparison.R b/R/boxr__internal_dir_comparison.R index e185cc05..ffc1fb5d 100644 --- a/R/boxr__internal_dir_comparison.R +++ b/R/boxr__internal_dir_comparison.R @@ -16,7 +16,6 @@ #' The reverse is true for uploads (e.g. via [box_fetch()]). #' #' `box_dir_diff` decides what should happen to a file based on three -#' peices of information: #' #' \describe{ #' \item{**Presence**}{ @@ -25,7 +24,7 @@ #' } #' \item{**Content**}{ #' If a file is present in both the origin and the destination, does it -#' have the same content? The defintion comes from the file's `sha1` +#' have the same content? The definition comes from the file's `sha1` #' hash, which for local files is determined using the #' [digest()] function from the package of the same name. For #' remote files, it is queried from the box.com API. @@ -56,7 +55,7 @@ #' #' Implementing similar functionality for local files is not possible in a #' platform-independent manner; content modified time is the only file-based -#' timestamp which has a consistent defintion for UNIX and Windows +#' timestamp which has a consistent definition for UNIX and Windows #' systems. #' #' @param dir_id The id of the box.com folder which you'd like to use for the @@ -86,7 +85,7 @@ #' [box_fetch()]/[box_push()], they will be deleted. #' } #' \item{**`to_update`**}{ -#' Files which are present in both the orign and the destination, but +#' Files which are present in both the origin and the destination, but #' which have more recently modified copies in the origin. If downloading #' with [box_fetch()], and `overwrite` set to `TRUE`, #' new files will overwrite existing local copies. If uploading with @@ -308,7 +307,7 @@ create_loc_dir_df <- function(local_dir = getwd()) { #' Obtain a data.frame of the sub-directories in a box.com folder #' #' Takes the `id` of a box folder and returns a data.frame of it's -#' subdirectories, indluding thier equivalent paths in the local directory. +#' subdirectories, including their equivalent paths in the local directory. #' #' @param dir_id The box.com id for the folder that you'd like to query #' @param local_dir The local directory which you'd like `dir_id` to diff --git a/R/boxr_auth.R b/R/boxr_auth.R index 8ab50523..ff8331a7 100644 --- a/R/boxr_auth.R +++ b/R/boxr_auth.R @@ -62,7 +62,7 @@ #' \item{[box_auth_service()]}{for authenticating to service-apps.} #' \item{[httr::oauth2.0_token()]}{for details on how tokens are handled.} #' \item{[Box Developers: Setup with OAuth 2.0](https://developer.box.com/en/guides/applications/custom-apps/oauth2-setup)}{ -#' documentation for setting up Box apps.} +#' documentation for setting up Box (interactive) apps with OAuth 2.0.} #' } #' #' @export @@ -225,7 +225,7 @@ box_auth <- function(client_id = NULL, client_secret = NULL, #' @inheritParams box_auth #' @param ... Other arguments passed to [box_auth()]. #' -#' @seealso [box_auth()] for the usual method of authorisation +#' @seealso [box_auth()] for the usual method of authentication. #' #' @export #' @@ -244,7 +244,7 @@ box_fresh_auth <- function(cache = "~/.boxr-oauth", ...) { #' Authenticate to Box (interactive) automatically #' -#' **This function is deprecated, and will be removed at the next relase.** +#' **This function is deprecated, and will be removed at the next release.** #' #' This function saves you the effort of typing [box_auth()] after #' the package loads. Executing `box_auth_on_attach(TRUE)` will mean that @@ -253,7 +253,7 @@ box_fresh_auth <- function(cache = "~/.boxr-oauth", ...) { #' current session. #' #' @note This is provided for convenience, but it's a bad idea to use, if: -#' * You'd like your code to be reporoducible. Even if your +#' * You'd like your code to be reproducible. Even if your #' collaborators have access to the same files on box.com, as the default #' behaviour is to require using [box_auth()], code is likely to #' become irreproducible. @@ -325,7 +325,7 @@ box_auth_on_attach <- function(auth_on_attach = FALSE) { #' Authenticate to Box (service-app) #' #' @description -#' How you authenticate to Box depends on how the Box-app through which you +#' How you authenticate to Box depends the Box-app through which you #' connect. A Box service-app can be useful for unattended jobs that need #' access to only a limited part of Box, e.g. one folder. #' @@ -336,10 +336,11 @@ box_auth_on_attach <- function(auth_on_attach = FALSE) { #' are your Box-admin team. You specify the JWT either as `token_file`, #' the path to the JWT file, or as `token_text`, the text of the JWT. #' -#' Using JWT-authenitcation is more convienient than using standard OAuth2 +#' Using JWT-authentication is more convenient than using standard OAuth2 #' authentication, as you do not have to go through the "OAuth Dance". This #' convenience brings additional considerations because the JWT file gives -#' its bearer uninhibited access to anything the Box service-app can access: +#' its bearer uninhibited access to anything the Box service-app can access. +#' Accordingly, you are recommended to: #' #' - give the service-account access to as little information as you need it #' to have, e.g. a single folder. @@ -383,7 +384,7 @@ box_auth_on_attach <- function(auth_on_attach = FALSE) { #' \item{[box_dir_invite()]}{for inviting a different account to collaborate on #' a Box folder.} #' \item{[Box Developers: Setup with JWT](https://developer.box.com/en/guides/applications/custom-apps/jwt-setup)}{ -#' documentation for setting up Box apps.} +#' documentation for setting up Box (service) apps with JWT.} #' } #' #' diff --git a/R/boxr_dir_verbs.R b/R/boxr_dir_verbs.R index 5eb9d934..811c03ce 100644 --- a/R/boxr_dir_verbs.R +++ b/R/boxr_dir_verbs.R @@ -12,7 +12,7 @@ #' Files present in the origin but not the destination will be #' copied over. #' -#' Behaviour when a file exists in both depends on the argumments supplied. +#' Behaviour when a file exists in both depends on the arguments supplied. #' #' @aliases box_push box_fetch #' @@ -41,7 +41,7 @@ #' However, files at Box are versioned, and most #' operating systems have file recovery features (e.g. 'Trash' #' (Ubuntu/Debian/OSX), or 'Recycle Bin' (Windows)), so unintended -#' modification of files will be revertable for most users. +#' modification of files will be revertible for most users. #' #' @section Implementation: #' diff --git a/R/boxr_s3_classes.R b/R/boxr_s3_classes.R index 16f1e357..a250f906 100644 --- a/R/boxr_s3_classes.R +++ b/R/boxr_s3_classes.R @@ -8,33 +8,33 @@ #' #' **`boxr_file_reference`** #' -#' - describes a file created, modified, or deleted at Box +#' - describes a file created, modified, or deleted at Box. #' - returned by [box_ul()], [box_save()], [box_delete_file()], etc. -#' - available methods: [print()] +#' - available methods: [print()]. #' #' **`boxr_folder_reference`** #' -#' - describes a folder created or deleted at Box -#' - returned by [box_dir_create()], [box_delete_folder()] -#' - available methods: [print()] +#' - describes a folder created or deleted at Box. +#' - returned by [box_dir_create()], [box_delete_folder()]. +#' - available methods: [print()]. #' #' **`boxr_dir_wide_operation_result`** #' -#' - describes the result of a directory-wide operation +#' - describes the result of a directory-wide operation. #' - returned by [box_fetch()] and [box_push()]. -#' - available methods: [print()], [summary()] +#' - available methods: [print()], [summary()]. #' #' **`boxr_object_list`** #' -#' - describes a collection of files at Box -#' - returned by [box_ls()], [box_search()], and related functions -#' - available methods: [print()], [as.data.frame()] +#' - describes a collection of files at Box. +#' - returned by [box_ls()], [box_search()], and related functions. +#' - available methods: [print()], [as.data.frame()]. #' #' **`boxr_dir_comparison`** #' -#' - describes the differnce between directories -#' - returned by the internal function [box_dir_diff()] -#' - available methods: [print()], [summary()] +#' - describes the difference between directories. +#' - returned by the internal function [box_dir_diff()]. +#' - available methods: [print()], [summary()]. #' #' @name boxr_S3_classes NULL diff --git a/R/boxr_search.R b/R/boxr_search.R index 486618e6..4e2ed070 100644 --- a/R/boxr_search.R +++ b/R/boxr_search.R @@ -14,10 +14,10 @@ #' - is available for many source code file types, though not including R at #' the time of writing. #' -#' * Boolean operators Are supported -#' - such as `and`, `or`, and `not` (upper or lower case) +#' * Boolean operators are supported +#' - such as `and`, `or`, and `not` (upper or lower case). #' -#' * Phrases can Be searched +#' * Phrases can be searched #' - by putting them in "quotation marks". #' #' * Search availability diff --git a/R/boxr_write.R b/R/boxr_write.R index adc74e2e..cf4bcc87 100644 --- a/R/boxr_write.R +++ b/R/boxr_write.R @@ -12,7 +12,7 @@ #' supports `data.frame`; to serialize lists, you may wish to use #' [jsonlite::toJSON()]. #' -#' Please note that `box_write()` is used to write Robjects to Box files +#' Please note that `box_write()` is used to write R objects to Box files #' using standard formats. To write R objects as `.RData` files, #' you can use [box_save()]. #' diff --git a/README.Rmd b/README.Rmd index 63e1d8dd..d00a5ef6 100644 --- a/README.Rmd +++ b/README.Rmd @@ -23,13 +23,13 @@ url_site <- function(x = "") { # boxr -A lightweight, *opinionated*, high-level R interface to the box.com API, standing on the shoulders of [`httr`](https://github.com/r-lib/httr). +A lightweight, *opinionated*, high-level R interface to the box.com API, standing on the shoulders of **[httr](https://github.com/r-lib/httr)**. [Box](https://www.box.com) is a cloud content-management and file-sharing service. The goal of the **boxr** package is to make it easier for you to conduct data analyses that interact with your Box account. ## New in boxr 0.3.5 -It has been a while since the last CRAN release of `boxr`; we are pleased to to announce: +It has been a while since the last CRAN release of boxr; we are pleased to to announce: - the package-documentation has been fortified, including a [pkgdown site](`r url_site()`). @@ -56,12 +56,10 @@ devtools::install_github("r-box/boxr") ### Documentation -The packge-documentation website is created and maintained using [pkgdown](https://pkgdown.r-lib.org). Upon the CRAN release for version 0.3.5, the documentation website will consist of: +The package-documentation website is created and maintained using [pkgdown](https://pkgdown.r-lib.org). Upon the CRAN release for version 0.3.5, the documentation website consists of: - - a [CRAN-version site](`r url_site()`) - - a [development-version site](`r url_site("dev")`) - -Until the CRAN release for version 0.3.5, the most-current version of the site will be the [development-version site](`r url_site("dev")`). + - a [CRAN-version site](`r url_site()`). + - a [development-version site](`r url_site("dev")`). ## Usage @@ -69,7 +67,7 @@ We have a [Get-started article](`r url_site("articles/boxr.html")`) that goes in ### Authentication -Any time you interact with the Box API, you will be using a Box application, i.e. a Box-app. If you've already used `boxr` to authenticate with Box, you've already used a Box app. +Any time you interact with the Box API, you will be using a Box application, i.e. a Box-app. If you've already used boxr to authenticate with Box, you've already used a Box app. #### tl;dr @@ -79,7 +77,7 @@ If you have access to `client_id` and `client_secret` for a Box-app, you can use box_auth(client_id = "your_client_id", client_secret = "your_client_secret") ``` -This will kick off a process that, all being well, will keep you authenticated for the rest of the R session. By saving this information to your `.Renviron` file, at your next R session you can use: +This will kick off a process that, all being well, will keep you authenticated for the rest of the R session. By saving this information to your `.Renviron` file, at your next R session you can use, without arguments: ```r box_auth() @@ -89,7 +87,7 @@ If you don't have access to `client_id` and `client_secret` for a Box-app, read #### Details -You can think of a Box-app as the door through which `boxr` functions can access Box. For the most part, `boxr` functions keep this "out-of-mind". During authentication, Box-apps come to the fore. +You can think of a Box-app as the door through which boxr functions can access Box. For the most part, boxr functions keep this "out-of-mind". During authentication, Box-apps come to the fore. Getting the authentication to work the first time is most difficult part of using this package. Once you get it working, it should *just work*. @@ -105,15 +103,15 @@ How you deal with Box-apps may depend on your situation: The type of Box-app you use may also depend your situation: - - **"I want to use `boxr` interactively, from my local computer"**: + - **"I want to use boxr interactively, from my local computer"**: We recommend you use a Box interactive-app, then authenticate using `box_auth()`. You can read more in this [interactive-app article](`r url_site("articles/boxr-app-interactive.html")`). - - **"I want to run an unattended scheduled process, e.g. a report, from a remote machine using `boxr`"**: + - **"I want to run an unattended scheduled process, e.g. a report, from a remote machine using boxr"**: We recommend you use a Box service-app, then authenticate using `box_auth_service()`. You can read more in this [service-app article](`r url_site("articles/boxr-app-service.html")`). - - **"I want to use `boxr` interactively using a remote machine, perhaps using RStudio Cloud or RStudio Server."**: + - **"I want to use boxr interactively using a remote machine, perhaps using RStudio Cloud or RStudio Server."**: You could go either way; this situation is covered in both the [interactive-app article](`r url_site("articles/boxr-app-interactive.html#transfer")`) and the [service-app article](`r url_site("articles/boxr-app-service.html#transfer")`). @@ -121,26 +119,26 @@ The differences between the two types of apps are discussed in this [overview ar ### Basic operations - - [Accessing Box directories](`r url_site("articles/boxr.html#accessing-box-directories-folders")`): `box_setwd()`, `box_getwd()`, `box_dir_create()`, `box_ls()`, `box_push()`, `box_fetch()` - - [Accessing Box files](`r url_site("articles/boxr.html#accessing-box-files")`): `box_ul()`, `box_dl()`, `box_previous_versions()`, `box_add_description()` - - [Searching Box](`r url_site("articles/boxr.html#searching-box")`): `box_search()` + - [Accessing Box directories](`r url_site("articles/boxr.html#accessing-box-directories-folders")`): `box_setwd()`, `box_getwd()`, `box_dir_create()`, `box_ls()`, `box_push()`, `box_fetch()`. + - [Accessing Box files](`r url_site("articles/boxr.html#accessing-box-files")`): `box_ul()`, `box_dl()`, `box_previous_versions()`, `box_add_description()`. + - [Searching Box](`r url_site("articles/boxr.html#searching-box")`): `box_search()`. ### Advanced operations - - [Using Box trash](`r url_site("articles/boxr.html#using-box-trash")`): `box_delete_file()`, `box_delete_folder()`, `box_restore_file()`, `box_restore_folder()` - - [Interacting with your R session](`r url_site("articles/boxr.html#interacting-with-your-r-session")`): `box_read()`, `box_write()`, `box_source()`, `box_save()`, `box_load()` + - [Using Box trash](`r url_site("articles/boxr.html#using-box-trash")`): `box_delete_file()`, `box_delete_folder()`, `box_restore_file()`, `box_restore_folder()`. + - [Interacting with your R session](`r url_site("articles/boxr.html#interacting-with-your-r-session")`): `box_read()`, `box_write()`, `box_source()`, `box_save()`, `box_load()`. ## Alternatives Other ways to interact with a Box account include: - - The [Box desktop apps](https://www.box.com/resources/downloads) - - The *other* boxr, [written in Ruby](https://github.com/cburnette/boxr). Its motivations are rather different, and it covers 100% of the box.com API (e.g account administration, etc.) - - Box themselves provide a [wide range of SDKs](https://github.com/box), including [one for Python](https://github.com/box/box-python-sdk) + - The [Box desktop apps](https://www.box.com/resources/downloads). + - The *other* boxr, [written in Ruby](https://github.com/cburnette/boxr). Its motivations are rather different, and it covers 100% of the box.com API (e.g account administration, etc.). + - Box themselves provide a [wide range of SDKs](https://github.com/box), including [one for Python](https://github.com/box/box-python-sdk). ## Contributing -Always very welcome! If you'd like to submit a pull request for a new feature, ideally it would be documented, come with an addtion to [NEWS.md](`r url_site("news/index.html")`), and have a test or two. This project has a standard [Code of Conduct](`r url_site("CONDUCT.html")`). +Always very welcome! If you'd like to submit a pull request for a new feature, ideally it would be documented, come with an addition to [NEWS.md](`r url_site("news/index.html")`), and have a test or two. This project has a standard [Code of Conduct](`r url_site("CONDUCT.html")`). ## License diff --git a/README.md b/README.md index c00d01d8..1617448a 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ version](https://www.r-pkg.org/badges/version/boxr)](https://cran.rstudio.com/we # boxr A lightweight, *opinionated*, high-level R interface to the box.com API, -standing on the shoulders of [`httr`](https://github.com/r-lib/httr). +standing on the shoulders of **[httr](https://github.com/r-lib/httr)**. [Box](https://www.box.com) is a cloud content-management and file-sharing service. The goal of the **boxr** package is to make it @@ -24,8 +24,8 @@ account. ## New in boxr 0.3.5 -It has been a while since the last CRAN release of `boxr`; we are -pleased to to announce: +It has been a while since the last CRAN release of boxr; we are pleased +to to announce: - the package-documentation has been fortified, including a [pkgdown site](https://r-box.github.io/boxr/). @@ -58,16 +58,12 @@ devtools::install_github("r-box/boxr") ### Documentation -The packge-documentation website is created and maintained using +The package-documentation website is created and maintained using [pkgdown](https://pkgdown.r-lib.org). Upon the CRAN release for version -0.3.5, the documentation website will consist of: +0.3.5, the documentation website consists of: - - a [CRAN-version site](https://r-box.github.io/boxr/) - - a [development-version site](https://r-box.github.io/boxr/dev) - -Until the CRAN release for version 0.3.5, the most-current version of -the site will be the [development-version -site](https://r-box.github.io/boxr/dev). + - a [CRAN-version site](https://r-box.github.io/boxr/). + - a [development-version site](https://r-box.github.io/boxr/dev). ## Usage @@ -78,8 +74,8 @@ more detail on interacting with your Box account using R. ### Authentication Any time you interact with the Box API, you will be using a Box -application, i.e. a Box-app. If you’ve already used `boxr` to -authenticate with Box, you’ve already used a Box app. +application, i.e. a Box-app. If you’ve already used boxr to authenticate +with Box, you’ve already used a Box app. #### tl;dr @@ -93,7 +89,8 @@ box_auth(client_id = "your_client_id", client_secret = "your_client_secret") This will kick off a process that, all being well, will keep you authenticated for the rest of the R session. By saving this information -to your `.Renviron` file, at your next R session you can use: +to your `.Renviron` file, at your next R session you can use, without +arguments: ``` r box_auth() @@ -104,9 +101,9 @@ Box-app, read on. #### Details -You can think of a Box-app as the door through which `boxr` functions -can access Box. For the most part, `boxr` functions keep this -“out-of-mind”. During authentication, Box-apps come to the fore. +You can think of a Box-app as the door through which boxr functions can +access Box. For the most part, boxr functions keep this “out-of-mind”. +During authentication, Box-apps come to the fore. Getting the authentication to work the first time is most difficult part of using this package. Once you get it working, it should *just work*. @@ -125,21 +122,21 @@ How you deal with Box-apps may depend on your situation: The type of Box-app you use may also depend your situation: - - **“I want to use `boxr` interactively, from my local computer”**: + - **“I want to use boxr interactively, from my local computer”**: We recommend you use a Box interactive-app, then authenticate using `box_auth()`. You can read more in this [interactive-app article](https://r-box.github.io/boxr/articles/boxr-app-interactive.html). - **“I want to run an unattended scheduled process, e.g. a report, - from a remote machine using `boxr`”**: + from a remote machine using boxr”**: We recommend you use a Box service-app, then authenticate using `box_auth_service()`. You can read more in this [service-app article](https://r-box.github.io/boxr/articles/boxr-app-service.html). - - **“I want to use `boxr` interactively using a remote machine, - perhaps using RStudio Cloud or RStudio Server.”**: + - **“I want to use boxr interactively using a remote machine, perhaps + using RStudio Cloud or RStudio Server.”**: You could go either way; this situation is covered in both the [interactive-app @@ -156,43 +153,43 @@ on Box-apps. - [Accessing Box directories](https://r-box.github.io/boxr/articles/boxr.html#accessing-box-directories-folders): `box_setwd()`, `box_getwd()`, `box_dir_create()`, `box_ls()`, - `box_push()`, `box_fetch()` + `box_push()`, `box_fetch()`. - [Accessing Box files](https://r-box.github.io/boxr/articles/boxr.html#accessing-box-files): `box_ul()`, `box_dl()`, `box_previous_versions()`, - `box_add_description()` + `box_add_description()`. - [Searching Box](https://r-box.github.io/boxr/articles/boxr.html#searching-box): - `box_search()` + `box_search()`. ### Advanced operations - [Using Box trash](https://r-box.github.io/boxr/articles/boxr.html#using-box-trash): `box_delete_file()`, `box_delete_folder()`, `box_restore_file()`, - `box_restore_folder()` + `box_restore_folder()`. - [Interacting with your R session](https://r-box.github.io/boxr/articles/boxr.html#interacting-with-your-r-session): `box_read()`, `box_write()`, `box_source()`, `box_save()`, - `box_load()` + `box_load()`. ## Alternatives Other ways to interact with a Box account include: - - The [Box desktop apps](https://www.box.com/resources/downloads) + - The [Box desktop apps](https://www.box.com/resources/downloads). - The *other* boxr, [written in Ruby](https://github.com/cburnette/boxr). Its motivations are rather different, and it covers 100% of the box.com API (e.g account - administration, etc.) + administration, etc.). - Box themselves provide a [wide range of SDKs](https://github.com/box), including [one for - Python](https://github.com/box/box-python-sdk) + Python](https://github.com/box/box-python-sdk). ## Contributing Always very welcome\! If you’d like to submit a pull request for a new -feature, ideally it would be documented, come with an addtion to +feature, ideally it would be documented, come with an addition to [NEWS.md](https://r-box.github.io/boxr/news/index.html), and have a test or two. This project has a standard [Code of Conduct](https://r-box.github.io/boxr/CONDUCT.html). diff --git a/cran-comments.md b/cran-comments.md index 18024fda..24c4192f 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,7 +1,19 @@ ## Test environments -* Ubuntu 16.04 R 3.3.2 -* Ubuntu 12.04 (on travis-ci), R 3.2.5 -* CRAN winbuilder + +* R-Hub: + * Windows Server 2008 R2 SP1, R-devel, 32/64 bit + * Ubuntu Linux 16.04 LTS, R-release, GCC + * Fedora Linux, R-devel, clang, gfortran +* ubuntu 16.04 (on travis-ci), R (oldrel, release, and devel) +* win-builder (devel) ## R CMD check results -There were no ERRORs, WARNINGs or NOTEs. + +NOTE: + +Maintainer: 'Ian Lyttle ' + +New maintainer: + Ian Lyttle +Old maintainer(s): + Brendan Rocks \ No newline at end of file diff --git a/man/box_auth.Rd b/man/box_auth.Rd index d98803ee..76cffde1 100644 --- a/man/box_auth.Rd +++ b/man/box_auth.Rd @@ -78,6 +78,6 @@ some text to your clipboard that you can paste into your \code{.Renviron} file. \item{\code{\link[=box_auth_service]{box_auth_service()}}}{for authenticating to service-apps.} \item{\code{\link[httr:oauth2.0_token]{httr::oauth2.0_token()}}}{for details on how tokens are handled.} \item{\href{https://developer.box.com/en/guides/applications/custom-apps/oauth2-setup}{Box Developers: Setup with OAuth 2.0}}{ -documentation for setting up Box apps.} +documentation for setting up Box (interactive) apps with OAuth 2.0.} } } diff --git a/man/box_auth_on_attach.Rd b/man/box_auth_on_attach.Rd index 677f6af9..f05e4b05 100644 --- a/man/box_auth_on_attach.Rd +++ b/man/box_auth_on_attach.Rd @@ -14,7 +14,7 @@ as soon as it's loaded.} \code{invisible(NULL)}, called for side-effects. } \description{ -\strong{This function is deprecated, and will be removed at the next relase.} +\strong{This function is deprecated, and will be removed at the next release.} This function saves you the effort of typing \code{\link[=box_auth]{box_auth()}} after the package loads. Executing \code{box_auth_on_attach(TRUE)} will mean that @@ -25,7 +25,7 @@ current session. \note{ This is provided for convenience, but it's a bad idea to use, if: \itemize{ -\item You'd like your code to be reporoducible. Even if your +\item You'd like your code to be reproducible. Even if your collaborators have access to the same files on box.com, as the default behaviour is to require using \code{\link[=box_auth]{box_auth()}}, code is likely to become irreproducible. diff --git a/man/box_auth_service.Rd b/man/box_auth_service.Rd index 9bdbe261..dcf76a79 100644 --- a/man/box_auth_service.Rd +++ b/man/box_auth_service.Rd @@ -18,7 +18,7 @@ that is not there, it will try \code{~/.boxr-auth/token.json}.} Invisible \code{NULL}, called for side-effects. } \description{ -How you authenticate to Box depends on how the Box-app through which you +How you authenticate to Box depends the Box-app through which you connect. A Box service-app can be useful for unattended jobs that need access to only a limited part of Box, e.g. one folder. @@ -29,10 +29,11 @@ generated by your Box-admin team. If you have a personal Box account, \emph{you} are your Box-admin team. You specify the JWT either as \code{token_file}, the path to the JWT file, or as \code{token_text}, the text of the JWT. -Using JWT-authenitcation is more convienient than using standard OAuth2 +Using JWT-authentication is more convenient than using standard OAuth2 authentication, as you do not have to go through the "OAuth Dance". This convenience brings additional considerations because the JWT file gives -its bearer uninhibited access to anything the Box service-app can access: +its bearer uninhibited access to anything the Box service-app can access. +Accordingly, you are recommended to: \itemize{ \item give the service-account access to as little information as you need it to have, e.g. a single folder. @@ -72,6 +73,6 @@ This function has some side effects: \item{\code{\link[=box_dir_invite]{box_dir_invite()}}}{for inviting a different account to collaborate on a Box folder.} \item{\href{https://developer.box.com/en/guides/applications/custom-apps/jwt-setup}{Box Developers: Setup with JWT}}{ -documentation for setting up Box apps.} +documentation for setting up Box (service) apps with JWT.} } } diff --git a/man/box_dir_diff.Rd b/man/box_dir_diff.Rd index 9c50cf32..b6866157 100644 --- a/man/box_dir_diff.Rd +++ b/man/box_dir_diff.Rd @@ -39,7 +39,7 @@ origin. If \code{delete} is set to \code{TRUE} in \code{\link[=box_fetch]{box_fetch()}}/\code{\link[=box_push]{box_push()}}, they will be deleted. } \item{\strong{\code{to_update}}}{ -Files which are present in both the orign and the destination, but +Files which are present in both the origin and the destination, but which have more recently modified copies in the origin. If downloading with \code{\link[=box_fetch]{box_fetch()}}, and \code{overwrite} set to \code{TRUE}, new files will overwrite existing local copies. If uploading with @@ -85,7 +85,6 @@ destination would be the local directory specified by \code{local_dir}. The reverse is true for uploads (e.g. via \code{\link[=box_fetch]{box_fetch()}}). \code{box_dir_diff} decides what should happen to a file based on three -peices of information: \describe{ \item{\strong{Presence}}{ @@ -94,7 +93,7 @@ Is the file present in both the origin and destination? The filename } \item{\strong{Content}}{ If a file is present in both the origin and the destination, does it -have the same content? The defintion comes from the file's \code{sha1} +have the same content? The definition comes from the file's \code{sha1} hash, which for local files is determined using the \code{\link[=digest]{digest()}} function from the package of the same name. For remote files, it is queried from the box.com API. @@ -125,7 +124,7 @@ in \code{modified_at}, but not \code{content_modified_at}). Implementing similar functionality for local files is not possible in a platform-independent manner; content modified time is the only file-based -timestamp which has a consistent defintion for UNIX and Windows +timestamp which has a consistent definition for UNIX and Windows systems. } \references{ diff --git a/man/box_fetch.Rd b/man/box_fetch.Rd index c16d3d14..cb2a600b 100644 --- a/man/box_fetch.Rd +++ b/man/box_fetch.Rd @@ -41,7 +41,7 @@ folder} Files present in the origin but not the destination will be copied over. -Behaviour when a file exists in both depends on the argumments supplied. +Behaviour when a file exists in both depends on the arguments supplied. } \section{Overwrite/Update}{ @@ -59,7 +59,7 @@ their files, and may change as a default in later releases. However, files at Box are versioned, and most operating systems have file recovery features (e.g. 'Trash' (Ubuntu/Debian/OSX), or 'Recycle Bin' (Windows)), so unintended -modification of files will be revertable for most users. +modification of files will be revertible for most users. } \section{Implementation}{ diff --git a/man/box_fresh_auth.Rd b/man/box_fresh_auth.Rd index 64b6b227..bab1467e 100644 --- a/man/box_fresh_auth.Rd +++ b/man/box_fresh_auth.Rd @@ -19,5 +19,5 @@ Deletes the cached token-file before trying to re-authenticate. This is often the solution to authentication problems. } \seealso{ -\code{\link[=box_auth]{box_auth()}} for the usual method of authorisation +\code{\link[=box_auth]{box_auth()}} for the usual method of authentication. } diff --git a/man/box_search.Rd b/man/box_search.Rd index 0d554714..03ae6fc1 100644 --- a/man/box_search.Rd +++ b/man/box_search.Rd @@ -73,11 +73,11 @@ Some notable details: \item is available for many source code file types, though not including R at the time of writing. } -\item Boolean operators Are supported +\item Boolean operators are supported \itemize{ -\item such as \code{and}, \code{or}, and \code{not} (upper or lower case) +\item such as \code{and}, \code{or}, and \code{not} (upper or lower case). } -\item Phrases can Be searched +\item Phrases can be searched \itemize{ \item by putting them in "quotation marks". } diff --git a/man/box_write.Rd b/man/box_write.Rd index ae53965c..adb82507 100644 --- a/man/box_write.Rd +++ b/man/box_write.Rd @@ -40,7 +40,7 @@ The \code{\link[rio:export]{rio::export()}} function currently only supports \code{data.frame}; to serialize lists, you may wish to use \code{\link[jsonlite:toJSON]{jsonlite::toJSON()}}. -Please note that \code{box_write()} is used to write Robjects to Box files +Please note that \code{box_write()} is used to write R objects to Box files using standard formats. To write R objects as \code{.RData} files, you can use \code{\link[=box_save]{box_save()}}. } diff --git a/man/boxr-package.Rd b/man/boxr-package.Rd index 1d8df4a5..ac6b27e3 100644 --- a/man/boxr-package.Rd +++ b/man/boxr-package.Rd @@ -6,18 +6,18 @@ \alias{boxr} \title{boxr: access the Box API} \description{ -A lightweight, high-level R interface for the \href{https://developer.box.com/docs}{box.com} API +A lightweight, \emph{opinionated}, high-level R interface for the \href{https://developer.box.com/docs}{box.com} API. } \details{ This package has a documentation-website (created using \href{https://pkgdown.r-lib.org/}{pkgdown}), containing: \itemize{ -\item \href{https://r-box.github.io/boxr}{README} +\item \href{https://r-box.github.io/boxr}{README}. \item \href{https://r-box.github.io/boxr/articles/boxr.html}{Get-started article}, -also accessible from R: \code{vignette("boxr")} -\item \href{https://r-box.github.io/boxr/reference/index.html}{Function reference} +also accessible from R: \code{vignette("boxr")}. +\item \href{https://r-box.github.io/boxr/reference/index.html}{Function reference}. } -The \code{boxr} source-repository is at GitHub: \url{https://github.com/r-box/boxr}. +The boxr source-repository is at GitHub: \url{https://github.com/r-box/boxr}. If you find anything you think might be a bug, please report it as a \href{https://github.com/r-box/boxr/issues}{GitHub issue}! diff --git a/man/boxr_S3_classes.Rd b/man/boxr_S3_classes.Rd index f0d3f663..98e34020 100644 --- a/man/boxr_S3_classes.Rd +++ b/man/boxr_S3_classes.Rd @@ -11,36 +11,36 @@ information directly, you can use \code{unclass(x)}. \details{ \strong{\code{boxr_file_reference}} \itemize{ -\item describes a file created, modified, or deleted at Box +\item describes a file created, modified, or deleted at Box. \item returned by \code{\link[=box_ul]{box_ul()}}, \code{\link[=box_save]{box_save()}}, \code{\link[=box_delete_file]{box_delete_file()}}, etc. -\item available methods: \code{\link[=print]{print()}} +\item available methods: \code{\link[=print]{print()}}. } \strong{\code{boxr_folder_reference}} \itemize{ -\item describes a folder created or deleted at Box -\item returned by \code{\link[=box_dir_create]{box_dir_create()}}, \code{\link[=box_delete_folder]{box_delete_folder()}} -\item available methods: \code{\link[=print]{print()}} +\item describes a folder created or deleted at Box. +\item returned by \code{\link[=box_dir_create]{box_dir_create()}}, \code{\link[=box_delete_folder]{box_delete_folder()}}. +\item available methods: \code{\link[=print]{print()}}. } \strong{\code{boxr_dir_wide_operation_result}} \itemize{ -\item describes the result of a directory-wide operation +\item describes the result of a directory-wide operation. \item returned by \code{\link[=box_fetch]{box_fetch()}} and \code{\link[=box_push]{box_push()}}. -\item available methods: \code{\link[=print]{print()}}, \code{\link[=summary]{summary()}} +\item available methods: \code{\link[=print]{print()}}, \code{\link[=summary]{summary()}}. } \strong{\code{boxr_object_list}} \itemize{ -\item describes a collection of files at Box -\item returned by \code{\link[=box_ls]{box_ls()}}, \code{\link[=box_search]{box_search()}}, and related functions -\item available methods: \code{\link[=print]{print()}}, \code{\link[=as.data.frame]{as.data.frame()}} +\item describes a collection of files at Box. +\item returned by \code{\link[=box_ls]{box_ls()}}, \code{\link[=box_search]{box_search()}}, and related functions. +\item available methods: \code{\link[=print]{print()}}, \code{\link[=as.data.frame]{as.data.frame()}}. } \strong{\code{boxr_dir_comparison}} \itemize{ -\item describes the differnce between directories -\item returned by the internal function \code{\link[=box_dir_diff]{box_dir_diff()}} -\item available methods: \code{\link[=print]{print()}}, \code{\link[=summary]{summary()}} +\item describes the difference between directories. +\item returned by the internal function \code{\link[=box_dir_diff]{box_dir_diff()}}. +\item available methods: \code{\link[=print]{print()}}, \code{\link[=summary]{summary()}}. } } diff --git a/man/dirTreeRecursive.Rd b/man/dirTreeRecursive.Rd index 1163d014..1dad1c0e 100644 --- a/man/dirTreeRecursive.Rd +++ b/man/dirTreeRecursive.Rd @@ -19,6 +19,6 @@ box.com folder corresponding to \code{dir_id}. } \description{ Takes the \code{id} of a box folder and returns a data.frame of it's -subdirectories, indluding thier equivalent paths in the local directory. +subdirectories, including their equivalent paths in the local directory. } \keyword{internal} diff --git a/man/downloadDirFiles.Rd b/man/downloadDirFiles.Rd index eed5c545..eff2a860 100644 --- a/man/downloadDirFiles.Rd +++ b/man/downloadDirFiles.Rd @@ -5,7 +5,7 @@ \alias{deleteRemoteObjects} \alias{downloadDirFiles} \alias{uploadDirFiles} -\title{Single Directory Operations for Downloading and Uploading mutiple Files} +\title{Single Directory Operations for Downloading and Uploading multiple Files} \usage{ deleteRemoteObjects(dir_id, local_dir = getwd()) diff --git a/vignettes/boxr-app-service.Rmd b/vignettes/boxr-app-service.Rmd index dbb72297..392b3d1c 100644 --- a/vignettes/boxr-app-service.Rmd +++ b/vignettes/boxr-app-service.Rmd @@ -48,7 +48,7 @@ How you use this vignette depends on your Box set-up; we cover these situations: ## Using a Service App {#use} -A service app is often created in support of a single task, e.g. run a set of daily-reports. Because a service-app acts of behalf of the system itself, and because the tokens are portable, it is a common pracatice to limit the scope of *a* service-app to *a* single folder or small set of folders. Thus, you might be dealing with multiple service-apps if you are working on multiple projects. +A service app is often created in support of a single task, e.g. run a set of daily-reports. Because a service-app acts of behalf of the system itself, and because the tokens are portable, it is a common practice to limit the scope of *a* service-app to *a* single folder or small set of folders. Thus, you might be dealing with multiple service-apps if you are working on multiple projects. This is why we encourage you to create a directory in your *home* directory, called `.boxr-auth`, to contain these tokens. @@ -105,7 +105,7 @@ Once the token-file is uploaded, you should be able to run `boxr::box_auth_servi ## Collaboration Workflows {#workflow} -If you are using a service-app (acting as a service-account), you may also want to interact with the same files using your interactive-app (acting as your user-account). By default, a service-account has access to only its own file-system, and your user-account has access only to its own (differnent) file-system. To solve this problem, you can invite your service-account to collaborate on a folder in your user file-system, or you can invite your user-account to collaborate on a folder in the service file-system. In either case, you can use the function `box_dir_invite()`. +If you are using a service-app (acting as a service-account), you may also want to interact with the same files using your interactive-app (acting as your user-account). By default, a service-account has access to only its own file-system, and your user-account has access only to its own (different) file-system. To solve this problem, you can invite your service-account to collaborate on a folder in your user file-system, or you can invite your user-account to collaborate on a folder in the service file-system. In either case, you can use the function `box_dir_invite()`. Which way you go depends on the purpose of the service. diff --git a/vignettes/boxr-apps.Rmd b/vignettes/boxr-apps.Rmd index fa852d54..f70ef60d 100644 --- a/vignettes/boxr-apps.Rmd +++ b/vignettes/boxr-apps.Rmd @@ -38,7 +38,7 @@ The type of Box-app you use may also depend your situation: - **"I want to use `boxr` interactively, from my local computer"**: - We recommend you use a Box interactive-app; athenticate using `box_auth()`. You can read more in this [interactive-app article](./boxr-app-interactive.html). + We recommend you use a Box interactive-app; authenticate using `box_auth()`. You can read more in this [interactive-app article](./boxr-app-interactive.html). - **"I want to run an unattended scheduled process, e.g. a report, from a remote machine using `boxr`"**: @@ -52,23 +52,23 @@ This vignette is about the two types of apps that `boxr` uses, how to authentica - **[Interactive App](./boxr-app-interactive.html)**: This is preferred for interactive use (this includes you hitting the "knit" button in the RStudio IDE). The user authenticates to the app interactively, using the "OAuth Dance": a browser-window is opened to ask the user's permission. The app has all the rights of the user who authenticates to it. The [Box documentation on OAuth 2.0 apps](https://developer.box.com/en/guides/applications/custom-apps/oauth2-setup) has even more detail. -- **[Service App](./boxr-app-service.html)**: This is useful for unattended use, e.g. on a remote computer. A token (JSON file) is generated using the Box (or Box Enterprise) website. This token can be deployed to the (presumably remote) computer; there is no "OAuth Dance". Becuase these apps can act on behalf of the Box system itself, we recommend that you configure the app with a *minimal* set of privleges, e.g. to access only the Box folder that the app will need. The [Box documentation on JWT apps](https://developer.box.com/en/guides/applications/custom-apps/jwt-setup) has even more detail. +- **[Service App](./boxr-app-service.html)**: This is useful for unattended use, e.g. on a remote computer. A token (JSON file) is generated using the Box (or Box Enterprise) website. This token can be deployed to the (presumably remote) computer; there is no "OAuth Dance". Because these apps can act on behalf of the Box system itself, we recommend that you configure the app with a *minimal* set of privileges, e.g. to access only the Box folder that the app will need. The [Box documentation on JWT apps](https://developer.box.com/en/guides/applications/custom-apps/jwt-setup) has even more detail. ## Interactive App -An interactive-app is strightforward because it acts on behalf of the user who has authenticated to it, with the privileges of that user (those privileges in the scope of the app). To authenticate using an OAuth2 app, you can use the `box_auth()` function, which may invoke the "OAuth Dance". +An interactive-app is straightforward because it acts on behalf of the user who has authenticated to it, with the privileges of that user (those privileges in the scope of the app). To authenticate using an OAuth2 app, you can use the `box_auth()` function, which may invoke the "OAuth Dance". -More than one user can authenticate to and use a given app; however, each user will be able to use the app only as themself. There is a restriction: a Box app can handle no more than one request at a time; the greater the number of users of a given app, the greater the probability of a collision. +More than one user can authenticate to and use a given app; however, each user will be able to use the app only as them-self. There is a restriction: a Box app can handle no more than one request at a time; the greater the number of users of a given app, the greater the probability of a collision. The authentication process for an interactive-app is easiest if you have physical control of the computer from which you are trying to authenticate, e.g. your laptop. If you are using a remote computer, e.g. RStudio Server, you can generate this token on a local computer, then upload the token to your RStudio Server. -Keep in mind that the token retrieved by `box_auth()` is as "powerful" as the user themself; it should be treated with all due care. The user's Box account is no more secure than the security of this token. By default, the `boxr` token is cached, unencrypted, in the user's home directory, as `~/.boxr-oauth`. Because it is unencrypted, you should take care not to commit this file to a git repository. +Keep in mind that the token retrieved by `box_auth()` is as "powerful" as the user them-self; it should be treated with all due care. The user's Box account is no more secure than the security of this token. By default, the `boxr` token is cached, unencrypted, in the user's home directory, as `~/.boxr-oauth`. Because it is unencrypted, you should take care not to commit this file to a git repository. We recommend this as the first choice for authentication; it should work well in most situations, for most `boxr` users. More details on using and creating an interactive-app are given in [the interactive-app article](./boxr-app-interactive.html). ## Service App -There may be situations you want to use `boxr` as a part of specific unattended tasks. Perhaps it is a scheduled report, perhaps a set of continuous-integration tests. Service-apps are designed for these situations, but they should be used with care - particulary because they are designed to run unattended, outside your daily attention. +There may be situations you want to use `boxr` as a part of specific unattended tasks. Perhaps it is a scheduled report, perhaps a set of continuous-integration tests. Service-apps are designed for these situations, but they should be used with care - particularly because they are designed to run unattended, outside your daily attention. This type of app uses a *service* account, which is associated with a Box account or a Box Enterprise account. A service account is similar to a user account, but with additional admin functionality. Service accounts are not linked to a particular user account, but they can be configured to act on behalf of **any and all** user accounts for that Box account. Hence, they have additional security considerations. diff --git a/vignettes/boxr.Rmd b/vignettes/boxr.Rmd index 1c13dc34..eed6f4b9 100644 --- a/vignettes/boxr.Rmd +++ b/vignettes/boxr.Rmd @@ -94,7 +94,7 @@ These functions all have `overwrite` and `delete` parameters, which are set to ` ### Piping -boxr's functions have been designed to be 'pipable'. Here's a little example: +boxr's functions have been designed to be 'pipeable'. Here's a little example: ```r library(boxr)