Merge branch 'main' into managesecrets

R/bucket.R

@@ -4,6 +4,7 @@
 #' @param bucket (character) bucket name. required
 #' @note internally uses
 #' [head_bucket](https://www.paws-r-sdk.com/docs/s3_head_bucket/)
+#' @family buckets
 #' @examples \dontrun{
 #' # exists
 #' aws_bucket_exists(bucket = "s64-test-2")
@@ -28,6 +29,7 @@ aws_bucket_exists <- function(bucket) {
 #' [list_objects](https://www.paws-r-sdk.com/docs/s3_create_bucket/)
 #' @note Requires the env var `AWS_REGION`
 #' @return the bucket path (character)
+#' @family buckets
 #' @examples \dontrun{
 #' aws_bucket_create(bucket = "s64-test-2")
 #' }
@@ -67,6 +69,7 @@ bucket_create_if_not <- function(bucket, force = FALSE) {
 #' [delete_bucket](https://www.paws-r-sdk.com/docs/s3_delete_bucket/)
 #' @note Requires the env var `AWS_REGION`. This function prompts you to make
 #' sure that you want to delete the bucket.
+#' @family buckets
 #' @return an empty list
 #' @examples \dontrun{
 #' aws_bucket_create(bucket = "bucket-to-delete-111")
@@ -92,6 +95,7 @@ aws_bucket_delete <- function(bucket, force = FALSE, ...) {
 #' @param ... named parameters passed on to [s3fs::s3_dir_download()]
 #' @note Requires the env var `AWS_REGION`. This function prompts you to make
 #' sure that you want to delete the bucket.
+#' @family buckets
 #' @examples \dontrun{
 #' aws_bucket_create(bucket = "tmp-bucket-369")
 #' desc_file <- file.path(system.file(), "DESCRIPTION")
@@ -118,6 +122,7 @@ aws_bucket_download <- function(bucket, dest_path, ...) {
 #' @param ... named parameters passed on to [s3fs::s3_dir_upload()]
 #' @note Requires the env var `AWS_REGION`. This function prompts you to make
 #' sure that you want to delete the bucket.
+#' @family buckets
 #' @examples \dontrun{
 #' library(fs)
 #' tdir <- path(tempdir(), "apples")
@@ -155,6 +160,7 @@ aws_bucket_upload <- function(
 #' @importFrom s3fs s3_dir_info
 #' @param bucket (character) bucket name. required
 #' @param ... named parameters passed on to [s3fs::s3_dir_info()]
+#' @family buckets
 #' @return if no objects found, an empty tibble. if tibble has rows each
 #' is an S3 bucket, with 8 columns:
 #' * bucket_name (character)
@@ -184,6 +190,7 @@ aws_bucket_list_objects <- function(bucket, ...) {
 #' @inherit aws_bucket_list_objects
 #' @note we set `refresh=TRUE` internally to make sure we return up to date
 #' information about your buckets rather than what's cached locally
+#' @family buckets
 #' @examples \dontrun{
 #' aws_buckets()
 #' }
@@ -204,6 +211,7 @@ aws_buckets <- function(...) {
 #' @param recurse (logical) returns all AWS S3 objects in lower sub
 #' directories, default: `TRUE`
 #' @param ... Additional arguments passed to [s3fs::s3_dir_tree()]
+#' @family buckets
 #' @return character vector of objects/files within the bucket,
 #' printed as a tree
 #' @examples \dontrun{

R/database-rds.R

@@ -11,6 +11,7 @@
 #'
 #' If the `engine` you've chosen for your RDS instance is not supported
 #' with this function, you can likely connect to it on your own
+#' @family database
 #' @examples \dontrun{
 #' con_rds <- aws_db_rds_con("<define all params here>")
 #' con_rds
@@ -105,6 +106,7 @@ aws_db_rds_con <- function(
 #' available for returning. That wait can be around 5 - 7 minutes. You can
 #' instead set `wait = FALSE` and then check on the status of the instance
 #' yourself in the AWS dashboard.
+#' @family database
 #' @return returns `NULL`, this function called for the side effect of
 #' creating an RDS instance
 aws_db_rds_create <-
@@ -159,6 +161,7 @@ aws_db_rds_create <-
 #' Get the `paws` RDS client
 #' @export
 #' @note returns existing client if found; a new client otherwise
+#' @family database
 #' @return a list with methods for interfacing with RDS;
 #' see <https://www.paws-r-sdk.com/docs/rds/>
 aws_db_rds_client <- function() {
@@ -195,6 +198,7 @@ instance_con_info <- function(id) {
 #' Get instance status
 #' @export
 #' @inheritParams aws_db_rds_create
+#' @family database
 #' @return (character) the status of the instance, e.g., "creating",
 #' "available", "not found"
 #' @examples \dontrun{

R/database-redshift.R

@@ -15,6 +15,7 @@
 #'
 #' You can manage Redshift programatically via
 #' [paws::redshift](https://www.paws-r-sdk.com/docs/redshift/)
+#' @family database
 #' @return an object of class `RedshiftConnection`
 #' @examples \dontrun{
 #' library(DBI)
@@ -93,6 +94,7 @@ aws_db_redshift_con <- function(user, pwd, id = NULL, host = NULL, port = NULL,
 #' @note See above link to `create_cluster` docs for details on requirements
 #' for each parameter
 #' @inheritSection aws_db_rds_create Waiting
+#' @family database
 #' @return returns `NULL`, this function called for the side effect of
 #' creating an Redshift instance
 aws_db_redshift_create <-
@@ -117,6 +119,7 @@ aws_db_redshift_create <-
 
 #' Get the `paws` Redshift client
 #' @export
+#' @family database
 #' @return a list with methods for interfacing with Redshift;
 #' see <https://www.paws-r-sdk.com/docs/redshift/>
 aws_db_redshift_client <- function() {
@@ -146,6 +149,7 @@ cluster_con_info <- function(id) {
 #' Get cluster status
 #' @export
 #' @inheritParams aws_db_redshift_create
+#' @family database
 #' @return (character) the status of the cluster, e.g., "creating",
 #' "available", "not found"
 #' @examples \dontrun{

R/files.R

@@ -22,6 +22,7 @@ equal_lengths <- function(x, y) {
 #' @details
 #' - For upload: if it does exist it will be created
 #' - For download: if it does not exist, function will return an error
+#' @family files
 #' @examples \dontrun{
 #' demo_rds_file <- file.path(system.file(), "Meta/demo.rds")
 #' aws_file_upload(
@@ -66,6 +67,7 @@ aws_file_upload <- function(path, remote_path, force = FALSE, ...) {
 #' @param ... named parameters passed on to [s3fs::s3_file_download()]
 #' @return (character) a vector of local file paths
 #' @note USES A FORK OF s3fs FOR A MINOR FIX THAT MAKES LENGTH>1 INPUTS WORK
+#' @family files
 #' @examples \dontrun{
 #' tfile <- tempfile()
 #' aws_file_download(remote_path = "s3://s64-test-2/DESCRIPTION", path = tfile)
@@ -99,6 +101,7 @@ aws_file_download <- function(remote_path, path, ...) {
 #' @importFrom s3fs s3_file_delete
 #' @param remote_path (character) one or more remote S3 paths. required
 #' @param ... named parameters passed on to [s3fs::s3_file_delete()]
+#' @family files
 #' @return (character) a vector of remote file paths
 #' @examples \dontrun{
 #' # create a file
@@ -123,6 +126,7 @@ aws_file_delete <- function(remote_path, ...) {
 #' @return a tibble with many columns, with number of rows matching length
 #' of `remote_path`
 #' @note uses [s3fs::s3_file_info()] internally
+#' @family files
 #' @examples \dontrun{
 #' # files one by one
 #' aws_file_attr(s3_path("s64-test-2", "DESCRIPTION"))
@@ -143,6 +147,7 @@ aws_file_attr <- function(remote_path) {
 #' @inheritParams aws_file_attr
 #' @return vector of booleans (`TRUE` or `FALSE`), length matches
 #' `length(remote_path)`
+#' @family files
 #' @examples \dontrun{
 #' aws_file_exists(s3_path("s64-test-2", "DESCRIPTION"))
 #' aws_file_exists(s3_path("s64-test-2", "doesntexist"))
@@ -160,6 +165,7 @@ aws_file_exists <- function(remote_path) {
 #' length must match `remote_path`
 #' @param ... named parameters passed on to [s3fs::s3_file_move()]
 #' @return vector of paths, length matches `length(remote_path)`
+#' @family files
 #' @examples \dontrun{
 #' aws_file_rename(s3_path("s64-test-2", "DESCRIPTION"),
 #'   s3_path("s64-test-2", "DESC"))
@@ -189,6 +195,7 @@ aws_file_rename <- function(remote_path, new_remote_path, ...) {
 #' required for non-interactive use.
 #' @param ... named parameters passed on to [s3fs::s3_file_copy()]
 #' @return vector of paths, length matches `length(remote_path)`
+#' @family files
 #' @examples \dontrun{
 #' # create files in an existing bucket
 #' tfiles <- replicate(n = 3, tempfile())

R/groups.R

@@ -16,6 +16,7 @@ group_list_tidy <- function(x) {
 #' @param ... parameters passed on to `paws` `list_groups_for_user`
 #' if username is non-NULL, otherwise passed on to `list_users`
 #' @return A tibble with information about groups
+#' @family groups
 #' @examples \dontrun{
 #' aws_groups()
 #' aws_groups(username = aws_user_current())
@@ -41,6 +42,7 @@ aws_groups <- function(username = NULL, ...) {
 #' - attached_policies (tibble)
 #' @details see docs <https://www.paws-r-sdk.com/docs/iam_get_group/>
 #' @autoglobal
+#' @family groups
 #' @examples \dontrun{
 #' aws_group(name="users")
 #' }
@@ -61,6 +63,7 @@ aws_group <- function(name) {
 #' @return a single boolean
 #' @details uses `aws_group` internally. see docs
 #' <https://www.paws-r-sdk.com/docs/iam_get_group/>
+#' @family groups
 #' @examples \dontrun{
 #' aws_group_exists(name="users")
 #' aws_group_exists(name="apples")
@@ -79,6 +82,7 @@ aws_group_exists <- function(name) {
 #' @return A tibble with information about the group created
 #' @details See <https://www.paws-r-sdk.com/docs/iam_create_group/>
 #' docs for details on the parameters
+#' @family groups
 #' @examples \dontrun{
 #' aws_group_create("testgroup")
 #' }
@@ -94,6 +98,7 @@ aws_group_create <- function(name, path = NULL) {
 #' @return an empty list
 #' @details See <https://www.paws-r-sdk.com/docs/iam_delete_group/>
 #' docs for more details
+#' @family groups
 #' @examples \dontrun{
 #' aws_group_delete(name = "testgroup")
 #' }

R/policies.R

@@ -30,6 +30,7 @@ all_policies <- memoise::memoise(function(...) {
 #' [list_policies](https://www.paws-r-sdk.com/docs/iam_list_policies/)
 #' @details uses `memoise` internally to cache results to speed up all
 #' subsequent calls to the function
+#' @family policies
 #' @return A tibble with information about policies
 #' @examples \dontrun{
 #' aws_policies()
@@ -48,6 +49,7 @@ aws_policies <- function(refresh = FALSE, ...) {
 #' @return a tibble with policy details
 #' @details see docs <https://www.paws-r-sdk.com/docs/iam_get_policy/>
 #' @autoglobal
+#' @family policies
 #' @examples \dontrun{
 #' aws_policy("ReadOnlyAccess")
 #' aws_policy("arn:aws:iam::aws:policy/ReadOnlyAccess")
@@ -64,6 +66,7 @@ aws_policy <- function(name) {
 #' @param name (character) a policy name
 #' @return a tibble with policy details
 #' @details see docs <https://www.paws-r-sdk.com/docs/iam_get_policy/>
+#' @family policies
 #' @examples \dontrun{
 #' aws_policy_exists("ReadOnlyAccess")
 #' }
@@ -80,6 +83,7 @@ aws_policy_exists <- function(name) {
 #' beware as there is no validation is done of a user input policy arn
 #' @return a policy ARN
 #' @autoglobal
+#' @family policies
 #' @examples \dontrun{
 #' as_policy_arn("ReadOnlyAccess")
 #' as_policy_arn("arn:aws:iam::aws:policy/ReadOnlyAccess")
@@ -122,6 +126,7 @@ call_x_method <- function(x) {
 #' @param .x result of a call to create or get method for user,
 #' group, or role
 #' @param policy (character) a policy name or ARN
+#' @family policies
 #' @return A tibble with information about policies
 #' @examples \dontrun{
 #' aws_policy("AmazonRDSDataFullAccess")
@@ -143,6 +148,7 @@ aws_policy_attach <- function(.x, policy) {
 #' @param .x result of a call to create or get method for user,
 #' group, or role
 #' @param policy (character) a policy name or ARN
+#' @family policies
 #' @return A tibble with information about policies
 #' @examples \dontrun{
 #' aws_user() %>%

R/roles.R

@@ -19,6 +19,7 @@ role_list_tidy <- function(x) {
 #' @export
 #' @param ... parameters passed on to the `paws`
 #' [list_users](https://www.paws-r-sdk.com/docs/iam_list_roles/) method
+#' @family roles
 #' @return A tibble with information about roles
 #' @examples \dontrun{
 #' aws_roles()
@@ -39,6 +40,7 @@ aws_roles <- function(...) {
 #' also includes policies and attached policies by calling `list_role_policies`
 #' and `list_attached_role_policies`
 #' @autoglobal
+#' @family roles
 #' @examples \dontrun{
 #' res <- aws_role(name = "OrganizationAccountSecurityRole")
 #' res
@@ -79,6 +81,7 @@ aws_role <- function(name) {
 #' @return A tibble with information about the role created
 #' @details See <https://www.paws-r-sdk.com/docs/iam_create_role/>
 #' docs for details on the parameters
+#' @family roles
 #' @examples \dontrun{
 #' role_name <- "MyRole"
 #' trust_policy <- list(
@@ -124,6 +127,7 @@ aws_role_create <- function(
 #' @return an empty list
 #' @details See <https://www.paws-r-sdk.com/docs/iam_delete_role/>
 #' docs for more details
+#' @family roles
 #' @examples \dontrun{
 #' aws_role_delete(name = "MyRole")
 #' }

R/users.R

@@ -19,6 +19,7 @@ user_list_tidy <- function(x) {
 #' @export
 #' @param ... parameters passed on to the `paws`
 #' [list_users](https://www.paws-r-sdk.com/docs/iam_list_users/) method
+#' @family users
 #' @returns A tibble with information about user accounts
 #' @examples \dontrun{
 #' aws_users()
@@ -47,6 +48,7 @@ aws_users <- function(...) {
 #' - <https://www.paws-r-sdk.com/docs/iam_list_groups_for_user/>
 #' - <https://www.paws-r-sdk.com/docs/iam_list_attached_user_policies/>
 #' @note if username not supplied, gets logged in user
+#' @family users
 #' @examples \dontrun{
 #' # if username not supplied, gets logged in user
 #' aws_user()
@@ -76,6 +78,7 @@ aws_user <- function(username = NULL) {
 #' @return a single boolean
 #' @details uses `aws_group` internally. see docs
 #' <https://www.paws-r-sdk.com/docs/iam_get_group/>
+#' @family users
 #' @examples \dontrun{
 #' aws_user_exists(aws_user_current())
 #' aws_user_exists("blueberry")
@@ -87,6 +90,7 @@ aws_user_exists <- function(username) {
 
 #' Get the current logged-in username as a string
 #' @export
+#' @family users
 #' @return username as character
 aws_user_current <- function() {
   x <- aws_user()
@@ -106,6 +110,7 @@ aws_user_current <- function() {
 #' @return A tibble with information about the user created
 #' @details See <https://www.paws-r-sdk.com/docs/iam_create_user/>
 #' docs for details on the parameters
+#' @family users
 #' @examples \dontrun{
 #' aws_user_create("testBlueBird")
 #' }
@@ -128,6 +133,7 @@ aws_user_create <- function(
 #' @return an empty list
 #' @details See <https://www.paws-r-sdk.com/docs/iam_delete_user/>
 #' docs for more details
+#' @family users
 #' @examples \dontrun{
 #' aws_user_delete(username = "testBlueBird")
 #' }
@@ -144,6 +150,7 @@ aws_user_delete <- function(username) {
 #' @return a tibble with key details
 #' @details See <https://www.paws-r-sdk.com/docs/iam_list_access_keys/>
 #' docs for more details
+#' @family users
 #' @examples \dontrun{
 #' # aws_user_access_key()
 #' }
@@ -159,6 +166,7 @@ aws_user_access_key <- function() {
 #' @inherit aws_user return
 #' @details See <https://www.paws-r-sdk.com/docs/iam_add_user_to_group/>
 #' docs for more details
+#' @family users
 #' @examples \dontrun{
 #' if (!aws_group_exists("testgroup3")) {
 #'   aws_group_create("testgroup3")