Merge pull request #27 from The-Strategy-Unit/francisbarton/issue18

Add usage instructions to README

Author: francisbarton

R/get_container.R

@@ -5,12 +5,12 @@
 #'
 #' @param container_name Name of the container as a string. NULL by default,
 #'  which means the function will look instead for a container name stored in
-#'  the environment variable "AZ_STORAGE_CONTAINER"
+#'  the environment variable "AZ_CONTAINER"
 #' @param ... arguments to be passed through to `get_auth_token()`
 #' @returns An Azure blob container (list object of class "blob_container")
 #' @export
 get_container <- function(container_name = NULL, ...) {
-  container_envvar_name <- "AZ_STORAGE_CONTAINER"
+  container_envvar_name <- "AZ_CONTAINER"
   cst_msg1 <- cst_error_msg("{.var container_name} must be a string")
   cst_msg2 <- cst_error_msg("{.envvar {container_envvar_name}} is not set")
   c_name <- (container_name %||% Sys.getenv(container_envvar_name, NA)) |>

R/read_azure_files.R

@@ -63,6 +63,7 @@ read_azure_json <- function(container, file, path = "/", info = NULL, ...) {
 
 
 #' Common routine for all `read_azure_*()` functions
+#'
 #' Downloads the blob with `dest = NULL`, which keeps the data in memory
 #'
 #' @inheritParams read_azure_parquet

README.md

@@ -38,12 +38,74 @@ pak::pak("The-Strategy-Unit/azkit")
 
 ## Usage
 
-_To be added._
+A primary function in `{azkit}` enables access to an Azure blob container:
+
+```r
+data_container <- azkit::get_container()
+
+```
+Authentication is handled "under the hood" by the `get_container()` function,
+but if you need to, you can explicitly return an authentication token for
+inspection or testing:
+
+```r
+my_token <- azkit::get_auth_token()
+
+```
+
+The container returned will be set by the name stored in the `AZ_CONTAINER`
+environment variable, if any, by default, but you can override this by supplying
+a container name to the function:
+
+```r
+custom_container <- azkit::get_container("custom")
+```
+
+Return a list of all available containers in your default Azure storage with:
+
+```r
+list_container_names()
+```
+
+Once you have access to a container, you can use one of a set of data reading
+functions to bring data into R from `.parquet`, `.rds`, `.json` or `.csv` files:
+
+```r
+pqt_data <- azkit::read_azure_parquet(data_container, "v_important_data")
+
+```
+
+The functions will try to match a file of the required type using the `file`
+name supplied. In the case above, "v_important_data" would match a file named
+"v_important_data.parquet", no need to supply the file extension.
+
+By default the `read_*` functions will look in the root folder of the container.
+To specify a subfolder, supply this to the `path` argument.
+The functions will _not_ search recursively into further subfolders, so the path
+needs to be full and accurate.
+
+If there is more than 1 file matching the string supplied to `file` argument,
+the functions will throw an error.
+Specifying the exact filename will avoid this of course - but shorter `file`
+arguments may be convenient in some situations.
+
+Currently these functions only read in a single file at a time.
+
+Setting the `info` argument to `TRUE` will enable the functions to give some
+confirmatory feedback on what file is being read in.
+You can also pass through arguments to for example `readr::read_csv()`:
+
+```r
+csv_data <- data_container |>
+  azkit::read_azure_csv("vital_data.csv", path = "data", col_types = "ccci")
+
+```
 
 ## Environment variables
 
-To access Azure Storage you need to add some variables to a
-[`.Renviron` file][posit_env] in your project.
+To access Azure Storage you will want to set some environment variables.
+The neatest way to do this is to include a [`.Renviron` file][posit_env] in
+your project folder.
 
 ⚠️These values are sensitive and should not be exposed to anyone outside The
 Strategy Unit.
@@ -54,12 +116,24 @@ Your `.Renviron` file should contain the variables below.
 Ask a member of [the Data Science team][suds] for the necessary values.
 
 ```
+# essential
 AZ_STORAGE_EP=
-AZ_STORAGE_CONTAINER=
+# useful but not absolutely essential:
+AZ_CONTAINER=
+
+# optional, for certain authentication scenarios:
+AZ_TENANT_ID=
+AZ_CLIENT_ID=
+AZ_APP_SECRET=
 ```
 
 These may vary depending on the specific container you’re connecting to.
 
+For one project you might want to set the default container (`AZ_CONTAINER`) to
+one value, but for a different project you might be mainly working with a
+different container so it would make sense to set the values within the
+`.Renviron` file for each project, rather than globally for your account.
+
 ## Getting help
 
 Please use the [Issues][issues] feature on GitHub to report any bugs, ideas