Package 'paws.common'

Description

Create a list from an struct object

Usage

## S3 method for class 'struct'
as.list(x, ...)

Arguments

Description

Look up the service configuration from the service object, e.g. when calling svc$operation(), get_config() will look up svc, then get any configuration stored in it, as if the operation function were a method and the service object were a class instance.

Usage

get_config()

Details

get_config must be called directly by the operation function and assigned immediately, not provided as an argument to another function.

We look up the service object then fetch its data so we can both support documentation tooltips in RStudio and also have class-object-like behavior. Alternatives that do not support documentation tooltips in RStudio include reference classes (RC), R6 classes, and any modification of the functions at run-time, e.g. inserting the configuration into the function definition for each operation in a particular service object.

Description

Check whether an object is empty, e.g. has no sub-elements, is NA, or is the empty string.

Usage

is_empty(x)

Arguments

Examples

is_empty(NA) # TRUE
is_empty("") # TRUE
is_empty(list()) # TRUE
is_empty(list(list())) # TRUE

is_empty(1) # FALSE
is_empty(list(1)) # FALSE
is_empty(list(list(1))) # FALSE

Description

Check whether an object is empty, e.g. has no sub-elements, is NA

Usage

is_empty_xml(x)

Arguments

Examples

is_empty_xml(NA) # TRUE
is_empty_xml(list()) # TRUE
is_empty_xml(list(list())) # TRUE

is_empty_xml(1) # FALSE
is_empty_xml("") # FALSE
is_empty_xml(list(1)) # FALSE
is_empty_xml(list(list(1))) # FALSE

Description

List methods that can be paginated from a paws client.

Usage

list_paginators(svc)

Arguments

Value

character vector of functions that can be paginated.

Examples

## Not run: 
# Note: where svc is a paws client.
list_paginators(svc)

## End(Not run)

Description

Locate AWS credentials

Usage

locate_credentials(profile = "", anonymous = FALSE)

Arguments

Value

list containing AWS credentials

• access_key_id - (character) AWS access key ID

• secret_access_key - (character) AWS secret access key

• session_token - (character) AWS temporary session token

• access_token - (character) A token that gives a user permission to access certain resources

• expiration - (numeric) Indicates the Unix time when an access token will expire.

• region - (character) The AWS Region used in instantiating the client.

Description

Return request handlers for a given protocol and request signer.

Usage

new_handlers(protocol, signer)

Arguments

See Also

Other API request functions: new_operation(), new_request(), new_service(), send_request()

Examples

# Get the handlers needed for an API using REST-JSON and AWS signature V4.
handlers <- new_handlers("restjson", "v4")

Description

Return an API operation object, with information on what to request for a given API operation. For example, the S3 service's "list buckets" operation is named ListBuckets, it requires a GET request, and so on.

Usage

new_operation(
  name,
  http_method,
  http_path,
  host_prefix,
  paginator,
  stream_api = FALSE,
  before_presign_fn = NULL
)

Arguments

See Also

Other API request functions: new_handlers(), new_request(), new_service(), send_request()

Examples

# Save info about the S3 ListBuckets API operation.
op <- new_operation(
  name = "ListBuckets",
  http_method = "GET",
  http_path = "/",
  paginator = list()
)

Description

Return an API request object with everything needed to make a request.

Usage

new_request(client, operation, params, data, dest = NULL)

Arguments

See Also

Other API request functions: new_handlers(), new_operation(), new_service(), send_request()

Examples

## Not run: 
# Make a request object for the S3 ListBuckets operation.
metadata <- list(
  endpoints = list("*" = list(endpoint = "s3.{region}.amazonaws.com", global = FALSE)),
  service_name = "s3"
)
client <- new_service(metadata, new_handlers("restxml", "s3"))
op <- new_operation("ListBuckets", "GET", "/", list())
params <- list()
data <- tag_add(list(Buckets = list()), list(type = "structure"))
req <- new_request(client, op, params, data)

## End(Not run)

Description

Return an API service object with information and handlers needed to make API requests.

Usage

new_service(metadata, handlers, cfgs = NULL, operation = Operation())

Arguments

list(
  service_name = "string",
  endpoints = list("region" = list(endpoint = "endpoint", global = FALSE)),
  service_id = "string",
  api_version = "string",
  signing_name = "string"|NULL,
  json_version = "string",
  target_prefix = "string"
)

Region and credentials

new_service requires that you've set your AWS region in one of:

1. AWS_REGION R environment variable

2. AWS_REGION OS environment variable (Linux and macOS)

3. ⁠~/.aws/config⁠ AWS configuration file

new_service also requires that you've set your AWS credentials in one of:

1. AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY R environment variables

2. AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY OS environment variables (Linux and macOS)

3. ⁠~/.aws/credentials⁠ AWS credentials file

4. IAM role

See Also

new_operation()

Other API request functions: new_handlers(), new_operation(), new_request(), send_request()

Examples

## Not run: 
# Metadata for the S3 API.
metadata <- list(
  service_name = "s3",
  endpoints = list("us-east-1" = list(endpoint = "s3.amazonaws.com", global = FALSE)),
  service_id = "S3",
  api_version = "2006-03-01",
  signing_name = NULL,
  json_version = "",
  target_prefix = ""
)

# Handlers for S3.
handlers <- new_handlers("restxml", "v4")

# Build a service object for S3, containing the information necessary to
# build, send, and receive requests.
service <- new_service(metadata, handlers)

## End(Not run)

Description

Some AWS operations return results that are incomplete and require subsequent requests in order to attain the entire result set. The process of sending subsequent requests to continue where a previous request left off is called pagination. For example, the list_objects operation of Amazon S3 returns up to 1000 objects at a time, and you must send subsequent requests with the appropriate Marker in order to retrieve the next page of results.

Usage

paginate(
  Operation,
  PageSize = NULL,
  MaxItems = NULL,
  StartingToken = NULL,
  StopOnSameToken = FALSE
)

paginate_lapply(
  Operation,
  FUN,
  ...,
  PageSize = NULL,
  MaxItems = NULL,
  StartingToken = NULL,
  StopOnSameToken = FALSE
)

paginate_sapply(
  Operation,
  FUN,
  ...,
  simplify = TRUE,
  PageSize = NULL,
  MaxItems = NULL,
  StartingToken = NULL,
  StopOnSameToken = FALSE
)

Arguments

Value

list of responses from the operation.

Examples

## Not run: 
# The following example retrieves object list. The request specifies max
# keys to limit response to include only 2 object keys.
paginate(
  svc$list_objects_v2(
    Bucket = "DOC-EXAMPLE-BUCKET"
  ),
  MaxItems = 50
)

## End(Not run)

Description

Ability to configure paws logging system, through the use of paws helper function `paws_config_log` or R:base options function. Users are able to change logging levels without calling paws.common by the use of options e.g. options("paws.log_level" = 2L).

• paws.log_level (integer): The minimum log level that should be tracked

• paws.log_file (character): path for logs to populate, default output logs to console.

• paws.log_timestamp_fmt (character): see format.POSIXct()

Usage

paws_config_log(
  level = 2L,
  file = "",
  timestamp_fmt = "%Y-%m-%d %H:%M:%OS3"
)

Arguments

Examples

# log to a file
temp_file <- tempfile()
paws_config_log(file = temp_file)
unlink(temp_file)

# change log threshold to INFO
paws_config_log(level = 3L)

# reset to default config
paws_config_log()

Description

Clears down the cache environments.

• ini_cache: an environment that stores the results from read_ini, mainly used for storing AWS config files.

• os_env_cache: an environment that stores environmental variables from Unix Operating Systems.

Usage

paws_reset_cache()

Description

Iterate over AWS Event Stream connection

Usage

paws_stream_handler(FUN, .connection = FALSE)

paws_stream_parser(con)

Arguments

Value

list of responses from the operation or a paws_connection object

Examples

## Not run: 
# Developed from:
# https://docs.aws.amazon.com/code-library/latest/ug/python_3_bedrock-runtime_code_examples.html
library(paws)

# Create a Bedrock Runtime client in the AWS Region you want to use.
client <- bedrockruntime(region = "us-east-1")

# Set the model ID, e.g., Titan Text Premier.
model_id <- "amazon.titan-text-premier-v1:0"

# Start a conversation with the user message.
user_message = "Describe the purpose of a 'hello world' program in one line."
conversation <- list(
  list(
    role = "user",
    content = list(list(text=user_message))
  )
)

resp <- client$converse_stream(
  modelId = model_id,
  messages = conversation,
  inferenceConfig = list(maxTokens=512, temperature=0.5, topP=0.9)
)
resp$stream(\(chunk) chunk$contentBlockDelta$delta$text)

# Or handle stream utilising paws_stream_parser
while(!is.null(event <- paws_stream_parser(con))) {
   print(chunk$contentBlockDelta$delta$text)
}

# or return httr2 resp_perform_connection
con <- resp$stream(.connection = T)

while (!is.null(event <- resp_stream_aws(con))) {
  str(event)
}
close(con)


## End(Not run)

Description

populate copies data from a list (e.g. input by a user) to another list with a similar shape. The second list, called the interface, will generally also contain extra metadata for making API requests, such as names or types.

Usage

populate(input, interface)

Arguments

Examples

# Make an interface with metadata, e.g. type.
interface <- tag_add(list(foo = c(), bar = c()), list(type = "structure"))

# Combine data and the metadata from the interface.
populate(list(foo = 1, bar = 2), interface)

Description

Send a request and handle the response. Build the HTTP request, send it to AWS, interpret the response, and throw an error if the response is not ok.

Usage

send_request(request)

Arguments

See Also

Other API request functions: new_handlers(), new_operation(), new_request(), new_service()

Examples

## Not run: 
# Send a request and handle the response.
resp <- send_request(req)

## End(Not run)

Description

set_config adds a given set of configuration settings in cfgs to a service object, i.e. the service object for S3. Configuration settings can include credentials, region, endpoint, etc. These configuration settings will be used whenever an operation is called from that service object.

Usage

set_config(svc, cfgs = list())

Arguments

Details

set_config explicitly makes the credentials property mutable, such that when the SDK retrieves credentials later on, it will save them in the service object. This means that credentials don't need to be fetched on each operation, only if and when the saved credentials expire.

The optional configuration settings can include the following:

list(
  credentials = list(
    creds = list(
      access_key_id = "string",
      secret_access_key = "string",
      session_token = "string"
    ),
    profile = "string"
  ),
  endpoint = "string",
  region = "string"
)

Examples

# Create a config object with custom credentials and endpoint.
config <- set_config(
  svc = list(),
  cfgs = list(
    credentials = list(
      creds = list(
        access_key_id = "abc",
        secret_access_key = "123"
      )
    ),
    endpoint = "https://foo.com"
  )
)

Description

Help functions for setting the parameters for services

Usage

config(
  credentials = list(creds = list(access_key_id = "", secret_access_key = "",
    session_token = "", access_token = "", expiration = Inf), profile = "", anonymous =
    FALSE),
  endpoint = "",
  region = "",
  close_connection = FALSE,
  max_retries = 3,
  connect_timeout = 60,
  s3_force_path_style = FALSE,
  sts_regional_endpoint = "",
  signature_version = ""
)

credentials(
  creds = list(access_key_id = "", secret_access_key = "", session_token = "",
    access_token = "", expiration = Inf),
  profile = "",
  anonymous = FALSE
)

creds(
  access_key_id = "",
  secret_access_key = "",
  session_token = "",
  access_token = "",
  expiration = Inf
)

Arguments

Value

list set of parameter variables for paws services.

Examples

# set service parameter access_key_id and secret_access_key

config(credentials(creds("dummy", "secret")))

# set service parameter access_key_id and secret_access_key using using lists
config(
    credentials = list(
        creds = list(
            access_key_id = "dummy",
            secret_access_key = "secret"
        )
    )
)

Description

Tags are metadata stored in an object's attributes, used to store types and names needed to make AWS API requests.

tag_get returns the value of the given tag, or "" if the tag doesn't exist.

tag_has returns whether the object has the given tag.

tag_add returns the object after adding the given list of tags and values.

tag_del returns the object after recursively deleting tags in tags, or all tags if NULL.

type returns broadly what type an object is, based on its type tag.

Usage

tag_get(object, tag)

tag_get_all(object)

tag_has(object, tag)

tag_add(object, tags)

tag_del(object, tags = NULL)

type(object)

Arguments

Examples

foo <- list()
foo <- tag_add(foo, list(tag_name = "tag_value"))
tag_has(foo, "tag_name") # TRUE
tag_get(foo, "tag_name") # "tag_value"
tag_get(foo, "not_exist") # ""
foo <- tag_del(foo)
tag_has(foo, "tag_name") # FALSE