From 61bc0ab0d5f4de01aca031f307cfcae96c21bf22 Mon Sep 17 00:00:00 2001
From: John Benninghoff <jbenninghoff@mac.com>
Date: Wed, 5 Jun 2024 16:49:32 -0500
Subject: [PATCH] Add package_downloads() utility function

---
 DESCRIPTION                 |  1 +
 NAMESPACE                   |  1 +
 NEWS.md                     |  4 ++++
 R/utils.R                   | 26 ++++++++++++++++++++++++++
 _pkgdown.yml                |  1 +
 man/package_downloads.Rd    | 25 +++++++++++++++++++++++++
 renv.lock                   | 11 +++++++++++
 tests/testthat/test-utils.R | 12 ++++++++++++
 8 files changed, 81 insertions(+)
 create mode 100644 man/package_downloads.Rd

diff --git a/DESCRIPTION b/DESCRIPTION
index 66770f16..a1be830a 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -13,6 +13,7 @@ BugReports: https://github.com/jabenninghoff/rdev/issues
 Imports:
     checkmate,
     cli,
+    cranlogs,
     curl,
     desc,
     devtools,
diff --git a/NAMESPACE b/NAMESPACE
index 7828ccd4..9260c6c8 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -17,6 +17,7 @@ export(merge_release)
 export(missing_deps)
 export(new_branch)
 export(open_files)
+export(package_downloads)
 export(rmd_metadata)
 export(setup_analysis)
 export(setup_rdev)
diff --git a/NEWS.md b/NEWS.md
index e3f74790..ee79b85a 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,3 +1,7 @@
+# rdev 1.11.0
+
+* Added function `package_downloads()`: A wrapper for `cranlogs::cran_downloads()` that summarizes the number of package downloads from the RStudio CRAN mirror
+
 # rdev 1.10.11
 
 * Minor updates
diff --git a/R/utils.R b/R/utils.R
index 695bf0b6..f9405891 100644
--- a/R/utils.R
+++ b/R/utils.R
@@ -216,3 +216,29 @@ open_files <- function(files = c("TODO.md", "NEWS.md", "README.Rmd", "DESCRIPTIO
   writeLines(paste0("Opening files: ", toString(files)))
   invisible(vapply(files, rstudioapi::navigateToFile, character(1)))
 }
+
+#' Summarize package downloads
+#'
+#' A wrapper for [cranlogs::cran_downloads()] that summarizes the number of package downloads from
+#'   the RStudio CRAN mirror.
+#'
+#' By default, the summary is for the last month.
+#'
+#' @param packages A character vector of the packages to query.
+#' @param when The period to summarize, one of `last-day`, `last-week` or `last-month`
+#'   (the default).
+#'
+#' @return A data frame containing the total number of downloads by package for the specified
+#'   period, sorted by popularity.
+#' @export
+package_downloads <- function(packages, when = "last-month") {
+  checkmate::assert_character(packages, min.chars = 1)
+  if ("R" %in% packages) {
+    stop("Querying downloads of R is not supported!")
+  }
+
+  df <- cranlogs::cran_downloads(packages = packages, when = when) |>
+    stats::aggregate(by = count ~ package, FUN = sum)
+
+  df[order(df$count, decreasing = TRUE), ]
+}
diff --git a/_pkgdown.yml b/_pkgdown.yml
index f136b610..67a0ba60 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -58,6 +58,7 @@ reference:
     - extra_deps
     - urlchecker-reexports
     - html_url_check
+    - package_downloads
   - title: rdev Package
     desc: >
       rdev package documentation
diff --git a/man/package_downloads.Rd b/man/package_downloads.Rd
new file mode 100644
index 00000000..7f36e446
--- /dev/null
+++ b/man/package_downloads.Rd
@@ -0,0 +1,25 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/utils.R
+\name{package_downloads}
+\alias{package_downloads}
+\title{Summarize package downloads}
+\usage{
+package_downloads(packages, when = "last-month")
+}
+\arguments{
+\item{packages}{A character vector of the packages to query.}
+
+\item{when}{The period to summarize, one of \code{last-day}, \code{last-week} or \code{last-month}
+(the default).}
+}
+\value{
+A data frame containing the total number of downloads by package for the specified
+period, sorted by popularity.
+}
+\description{
+A wrapper for \code{\link[cranlogs:cran_downloads]{cranlogs::cran_downloads()}} that summarizes the number of package downloads from
+the RStudio CRAN mirror.
+}
+\details{
+By default, the summary is for the last month.
+}
diff --git a/renv.lock b/renv.lock
index 475f3f14..835dc689 100644
--- a/renv.lock
+++ b/renv.lock
@@ -274,6 +274,17 @@
       ],
       "Hash": "5a295d7d963cc5035284dcdbaf334f4e"
     },
+    "cranlogs": {
+      "Package": "cranlogs",
+      "Version": "2.1.1",
+      "Source": "Repository",
+      "Repository": "CRAN",
+      "Requirements": [
+        "httr",
+        "jsonlite"
+      ],
+      "Hash": "cfa4eec97df94fd69cb8652368966020"
+    },
     "crayon": {
       "Package": "crayon",
       "Version": "1.5.2",
diff --git a/tests/testthat/test-utils.R b/tests/testthat/test-utils.R
index 7fa04537..43a1a6ce 100644
--- a/tests/testthat/test-utils.R
+++ b/tests/testthat/test-utils.R
@@ -215,3 +215,15 @@ test_that("open_files opens all files", {
   )
   expect_named(ret, files)
 })
+
+# package_downloads
+
+test_that("package_downloads validates arguments", {
+  mockery::stub(package_downloads, "cranlogs::cran_downloads", NULL)
+
+  expect_error(package_downloads(NULL), "'packages'")
+  expect_error(package_downloads(""), "'packages'")
+  expect_error(package_downloads(c("checkmate", "")), "'packages'")
+  expect_error(package_downloads("R"), "Querying downloads of R is not supported!")
+  expect_error(package_downloads(c("checkmate", "R")), "Querying downloads of R is not supported!")
+})