Merge pull request #155 from khusmann/prettyprint

add a print function for data packages

DESCRIPTION

@@ -8,6 +8,8 @@ Authors@R: c(
            role = "aut", comment = c(ORCID = "0000-0003-3445-7562")),
     person("Pieter", "Huybrechts", email = "[email protected]",
            role = "aut", comment = c(ORCID = "0000-0002-6658-6062")),
+    person("Kyle", "Husmann", email = "[email protected]",
+           role = "ctb", comment = c(ORCID = "0000-0001-9875-8976")),
     person("Research Institute for Nature and Forest (INBO)",
            role = "cph", comment = "https://www.vlaanderen.be/inbo/en-gb/"),
     person("LifeWatch Belgium",
@@ -51,4 +53,4 @@ Encoding: UTF-8
 Language: en-GB
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.0
+RoxygenNote: 7.3.1

NAMESPACE

@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(print,datapackage)
 export(add_resource)
 export(check_package)
 export(create_package)

NEWS.md

@@ -1,15 +1,18 @@
 # frictionless (development version)
 
-* `add_resource()` now supports adding additional resource properties via the `...` argument.
+* A Data Package object (`package`) now has a `datapackage` class (#184). As a result:
+  * New function `print()` prints a a human-readable summary of the Data Package (#155).
+  * `check_package()` will warn if the class is missing.
+* `read_resource()` no longer returns a message regarding rights and credit (#121). If `package$id` is a URL (e.g. a DOI) it will be mentioned in `print()`.
 * `read_resource()` now supports column selection via the `col_select` argument from `readr::read_delim()`. This can vastly improve reading speed (#123).
+* `add_resource()` now supports adding additional resource properties via the `...` argument.
 * `create_package()` now accepts a `descriptor` argument so that a Data Package object can be created from an existing object (#184). It will always validate the created object with `create_package()`.
 * `check_package()` is now a public function, so it can be used by other packages (#185).
 * `readr::problems()` is included in NAMESPACE so users don't have to load readr to inspect parsing issues. The function is mentioned in the documentation of `read_resource()` (#129).
 * `cli::cli_abort()`, `cli::cli_warn()` and `cli::cli_inform()` are used for all errors, warnings, and messages (#163). This has several advantages:
   * Messages use semantic colours for variables, parameters, fields, etc.
   * Messages and warnings can be silenced with a global or local option, see [this blog post](https://ropensci.org/blog/2024/02/06/verbosity-control-packages/).
   * Each call has an [rlang](https://cran.r-project.org/package=rlang) class, e.g. `frictionless_error_fields_without_name`, making it easier to test for specific errors.
-* A `package` object now has a `datapackage` class (#184), `check_package()` will warn if it is missing.
 * The dependencies [glue](https://cran.r-project.org/package=glue) and [assertthat](https://cran.r-project.org/package=assertthat) are removed (#163). The functionality of glue is replaced by cli, `assertthat::assert()` calls are now `if()` functions.
 * Adhere to the requirements of [checklist](https://github.com/inbo/checklist), so that `.zenodo.json` can be created with `checklist::update_citation()`.
 * Add [Pieter Huybrechts](https://orcid.org/0000-0002-6658-6062) as author. Welcome Pieter!

R/add_resource.R

@@ -192,5 +192,5 @@ add_resource <- function(package, resource_name, data, schema = NULL,
   # Add resource (needs to be wrapped in its own list)
   package$resources <- append(package$resources, list(resource))
 
-  package
+  return(package)
 }

R/check_package.R

@@ -6,6 +6,12 @@
 #' @return `TRUE` or error.
 #' @family check functions
 #' @export
+#' @examples
+#' # Load the example Data Package
+#' package <- example_package
+#'
+#' # Check if the Data Package is valid (invisible return)
+#' check_package(package)
 check_package <- function(package) {
   general_message <- "{.arg package} must be a Data Package object."
   tip_message <- paste(

R/check_path.R

@@ -62,5 +62,6 @@ check_path <- function(path, directory = NULL, safe = FALSE) {
       )
     }
   }
+
   return(path)
 }

R/create_package.R

@@ -15,13 +15,17 @@
 #' it is valid.
 #'
 #' @param descriptor List to be made into a Data Package object.
-#'   If `NULL`, an empty Data Package object will be created from scratch.
+#'   If undefined, an empty Data Package will be created from scratch.
 #' @return Data Package object.
 #' @family create functions
 #' @export
 #' @examples
 #' # Create a Data Package
 #' package <- create_package()
+#'
+#' package
+#'
+#' # See the structure of the (empty) Data Package
 #' str(package)
 create_package <- function(descriptor = NULL) {
   if (!is.null(descriptor) && !is.list(descriptor)) {
@@ -42,6 +46,6 @@ create_package <- function(descriptor = NULL) {
 
   # Check that created package is valid
   check_package(descriptor)
-  
+
   return(descriptor)
 }

R/create_schema.R

@@ -124,5 +124,5 @@ create_schema <- function(data) {
     recursive = TRUE
   )
 
-  schema
+  return(schema)
 }

R/get_resource.R

@@ -65,5 +65,5 @@ get_resource <- function(package, resource_name) {
     resource$read_from <- "data"
   }
 
-  resource
+  return(resource)
 }

R/get_schema.R

@@ -43,5 +43,5 @@ get_schema <- function(package, resource_name) {
   # Check schema
   check_schema(schema)
 
-  schema
+  return(schema)
 }

R/print.R

@@ -0,0 +1,48 @@
+#' Print a Data Package
+#'
+#' Prints a human-readable summary of a Data Package, including its resources
+#' and a link to more information (if provided in `package$id`).
+#'
+#' @param x Data Package object, created with [read_package()] or
+#'   [create_package()].
+#' @param ... Further arguments, they are ignored by this function.
+#' @return [print()] with a summary of the Data Package object.
+#' @family datapackage functions
+#' @export
+#' @examples
+#' # Load the example Data Package
+#' package <- example_package
+#'
+#' # Print a summary of the Data Package
+#' package # Or print(package)
+print.datapackage <- function(x, ...) {
+  # All prints should use cat (= cli::cat() helpers)
+
+  # List resources
+  resources <- resources(x)
+  cli::cat_line(
+    cli::format_inline(
+      "A Data Package with {length(resources)} resource{?s}{?./:/:}"
+    )
+  )
+  if (length(resources) > 0) {
+    cli::cat_bullet(resources, bullet = "bullet")
+  }
+
+  # Include link (DOI) if available in package$id
+  if (startsWith(replace_null(x$id, ""), "http")) {
+    cli::cat_line(
+      cli::format_inline("For more information, see {.url {x$id}}.")
+    )
+  }
+
+  # Provide help
+  cli::cat_line(
+    cli::format_inline(
+      "Use {.fun unclass} to print the Data Package as a list."
+    ),
+    col = "silver"
+  )
+
+  invisible(x)
+}

R/read_package.R

@@ -14,6 +14,8 @@
 #'   system.file("extdata", "datapackage.json", package = "frictionless")
 #' )
 #'
+#' package
+#'
 #' # Access the Data Package properties
 #' package$name
 #' package$created
@@ -44,22 +46,6 @@ read_package <- function(file = "datapackage.json") {
   # Add directory
   descriptor$directory <- dirname(file) # Also works for URLs
 
-  # Inform user regarding rights and citation
-  message <- c(
-    "Please make sure you have the right to access data from this Data Package
-     for your intended use.",
-    "Follow applicable norms or requirements to credit the dataset and its
-     authors."
-  )
-  if (!is.null(descriptor$id)) {
-    if (startsWith(descriptor$id, "http")) {
-      message <- c(
-        message,
-        "i" = "For more information, see {.url {descriptor$id}}."
-      )
-    }
-  }
-  cli::cli_inform(message, class = "frictionless_message_usage_rights")
-
+  # Create package
   create_package(descriptor)
 }

R/read_resource.R

@@ -184,8 +184,7 @@
 #'   system.file("extdata", "datapackage.json", package = "frictionless")
 #' )
 #'
-#' # List resources
-#' resources(package)
+#' package
 #'
 #' # Read data from the resource "observations"
 #' read_resource(package, "observations")

R/remove_resource.R

@@ -28,5 +28,5 @@ remove_resource <- function(package, resource_name) {
     (x$name == resource_name)
   })
 
-  package
+  return(package)
 }

R/utils.R

@@ -86,5 +86,6 @@ read_descriptor <- function(x, directory = NULL, safe = FALSE) {
       x <- jsonlite::fromJSON(x, simplifyDataFrame = FALSE, simplifyVector = TRUE)
     }
   }
+
   return(x)
 }

R/write_package.R

@@ -27,8 +27,7 @@
 #'   system.file("extdata", "datapackage.json", package = "frictionless")
 #' )
 #'
-#' # List resources
-#' resources(package)
+#' package
 #'
 #' # Write the (unchanged) Data Package to disk
 #' write_package(package, directory = "my_directory")

README.Rmd

@@ -63,6 +63,8 @@ library(frictionless)
 # reading them, which is convenient and fast.
 package <- read_package("https://zenodo.org/record/5879096/files/datapackage.json")
 
+package
+
 # List resources
 resources(package)
 
@@ -80,6 +82,8 @@ my_package <-
   create_package() %>%
   add_resource(resource_name = "iris", data = iris)
 
+my_package
+
 # Write the Data Package to disk
 my_package %>%
   write_package("my_directory")

README.md

@@ -67,10 +67,14 @@ library(frictionless)
 # This gives you access to all Data Resources of the Data Package without 
 # reading them, which is convenient and fast.
 package <- read_package("https://zenodo.org/record/5879096/files/datapackage.json")
-#> Please make sure you have the right to access data from this Data Package for
-#> your intended use.
-#> Follow applicable norms or requirements to credit the dataset and its authors.
-#> ℹ For more information, see <https://doi.org/10.5281/zenodo.5879096>.
+
+package
+#> A Data Package with 3 resources:
+#> • reference-data
+#> • gps
+#> • acceleration
+#> For more information, see <https://doi.org/10.5281/zenodo.5879096>.
+#> Use `unclass()` to print the Data Package as a list.
 
 # List resources
 resources(package)
@@ -111,6 +115,11 @@ my_package <-
   create_package() %>%
   add_resource(resource_name = "iris", data = iris)
 
+my_package
+#> A Data Package with 1 resource:
+#> • iris
+#> Use `unclass()` to print the Data Package as a list.
+
 # Write the Data Package to disk
 my_package %>%
   write_package("my_directory")

_pkgdown.yml

@@ -30,4 +30,5 @@ reference:
   - has_concept("write functions")
 - title: "Miscellaneous"
   contents:
+  - has_concept("datapackage functions")
   - example_package