Merge pull request #187 from frictionlessdata/add_class

Add `datapackage` class, update `create_package()` and `check_package()`

Author: peterdesmet

NAMESPACE

@@ -1,6 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
 export(add_resource)
+export(check_package)
 export(create_package)
 export(create_schema)
 export(get_schema)

NEWS.md

@@ -2,11 +2,14 @@
 
 * `add_resource()` now supports adding additional resource properties via the `...` argument.
 * `read_resource()` now supports column selection via the `col_select` argument from `readr::read_delim()`. This can vastly improve reading speed (#123).
+* `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/check_package.R

@@ -1,34 +1,76 @@
-#' Check Data Package object
+#' Check a Data Package object
 #'
-#' Check if an object is a list describing a Data Package, i.e. it has the
-#' required properties `resources` and `directory`.
+#' Check if an object is a Data Package object with the required properties.
 #'
-#' @param package List describing a Data Package.
+#' @inheritParams read_resource
 #' @return `TRUE` or error.
 #' @family check functions
-#' @noRd
+#' @export
 check_package <- function(package) {
-  # Check package is a list with resources (list) and directory (character)
-  if (
-    !is.list(package) ||
-    !all(c("resources", "directory") %in% names(package)) ||
-    !is.list(package$resources) ||
-    !is.character(package$directory)
-  ) {
+  general_message <- "{.arg package} must be a Data Package object."
+  tip_message <- paste(
+    "Create a valid Data Package object with {.fun read_package} or ",
+    "{.fun create_package}."
+  )
+
+  # Check package is a list
+  if (!is.list(package)) {
+    cli::cli_abort(
+      c(
+        general_message,
+        "x" = "{.arg package} is not a list.",
+        "i" = tip_message
+      ),
+      class = "frictionless_error_package_invalid"
+    )
+  }
+
+  # Check package has resources (list)
+  if (!is.list(package$resources)) {
+    cli::cli_abort(
+      c(
+        general_message,
+        "x" = "{.arg package} is missing a {.field resources} property or it is
+               not a list.",
+        "i" = tip_message
+      ),
+      class = "frictionless_error_package_invalid"
+    )
+  }
+
+  # Check package has directory (character)
+  if (!is.character(package$directory)) {
     cli::cli_abort(
-      "{.arg package} must be a list describing a Data Package created with
-       {.fun read_package} or {.fun create_package}.",
+      c(
+        general_message,
+        "x" = "{.arg package} is missing a {.field directory} property or it is
+               not a character.",
+        "i" = tip_message
+      ),
       class = "frictionless_error_package_invalid"
     )
   }
 
   # Check all resources (if any) have a name
   if (purrr::some(package$resources, ~ is.null(.x$name))) {
     cli::cli_abort(
-      "All resources in {.arg package} must have a {.field name} property.",
+      "All {.field resources} in {.arg package} must have a {.field name}
+       property.",
       class = "frictionless_error_resources_without_name"
     )
   }
 
+  # Warn if class is missing
+  if (!"datapackage" %in% class(package)) {
+    cli::cli_warn(
+      c(
+        general_message,
+        "x" = "{.arg package} is missing a {.val datapackage} class.",
+        "i" = tip_message
+      ),
+      class = "frictionless_warning_package_without_class"
+    )
+  }
+
   return(TRUE)
 }

R/check_path.R

@@ -1,4 +1,4 @@
-#' Check path or URL
+#' Check a path or URL
 #'
 #' Check if a [path or
 #' URL](https://specs.frictionlessdata.io/data-resource/#url-or-path) is valid

R/check_schema.R

@@ -1,4 +1,4 @@
-#' Check Table Schema object
+#' Check a Table Schema object
 #'
 #' Check if an object is a list describing a Table Schema and (optionally)
 #' compare against a provided data frame.

R/create_package.R

@@ -1,24 +1,47 @@
-#' Create an empty Data Package
+#' Create a Data Package
 #'
-#' Initiates a list describing a [Data
-#' Package](https://specs.frictionlessdata.io/data-package/).
-#' This empty Data Package can be extended with metadata and resources (see
-#' [add_resource()]).
-#' Added resources will make the Data Package meet [Tabular Data
-#' Package](https://specs.frictionlessdata.io/tabular-data-package/)
-#' requirements, so `profile` is set to `tabular-data-package`.
+#' Initiates a [Data Package](https://specs.frictionlessdata.io/data-package/)
+#' object, either from scratch or from an existing list.
+#' This Data Package object is a list with a `datapackage` class and the
+#' following properties:
+#' - All properties of the original `descriptor`.
+#' - [`resources`](
+#'   https://specs.frictionlessdata.io/data-package/#required-properties) (an
+#'   empty list) if not present.
+#' - `directory` (set to `"."` for the current directory) if not present.
+#'   It is used as the base path to access resources with [read_resource()].
 #'
-#' @return List describing a Data Package.
+#' The function will run [check_package()] on the created package to make sure
+#' 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.
+#' @return Data Package object.
 #' @family create functions
 #' @export
 #' @examples
 #' # Create a Data Package
 #' package <- create_package()
 #' str(package)
-create_package <- function() {
-  list(
-    profile = "tabular-data-package",
-    resources = list(),
-    directory = "." # Current directory
-  )
+create_package <- function(descriptor = NULL) {
+  if (!is.null(descriptor) && !is.list(descriptor)) {
+    cli::cli_abort(
+      "{.arg descriptor} must be a list if provided.",
+      class = "frictionless_error_descriptor_invalid"
+    )
+  }
+
+  # Add properties
+  descriptor$resources <- replace_null(descriptor$resources, list())
+  descriptor$directory <- replace_null(descriptor$directory, ".") # Current dir
+
+  # Add datapackage class
+  if (!"datapackage" %in% class(descriptor)) {
+    class(descriptor) <- c("datapackage", class(descriptor))
+  }
+
+  # Check that created package is valid
+  check_package(descriptor)
+  
+  return(descriptor)
 }

R/read_package.R

@@ -5,10 +5,7 @@
 #' that describes the Data Package metadata and its Data Resources.
 #'
 #' @param file Path or URL to a `datapackage.json` file.
-#' @return List describing a Data Package.
-#'   The function will add a custom property `directory` with the directory the
-#'   descriptor was read from.
-#'   It is used as a base path to access resources.
+#' @return Data Package object, see [create_package()].
 #' @family read functions
 #' @export
 #' @examples
@@ -64,5 +61,5 @@ read_package <- function(file = "datapackage.json") {
   }
   cli::cli_inform(message, class = "frictionless_message_usage_rights")
 
-  descriptor
+  create_package(descriptor)
 }

R/read_resource.R

@@ -10,13 +10,13 @@
 #' Column names are taken from the provided Table Schema (`schema`), not from
 #' the header in the CSV file(s).
 #'
-#' @param package List describing a Data Package, created with [read_package()]
-#'   or [create_package()].
+#' @param package Data Package object, created with [read_package()] or
+#'   [create_package()].
 #' @param resource_name Name of the Data Resource.
 #' @param col_select Character vector of the columns to include in the result,
 #'   in the order provided.
 #'   Selecting columns can improve read speed.
-#' @return A [tibble()] data frame with the Data Resource's tabular data.
+#' @return [tibble()] data frame with the Data Resource's tabular data.
 #'   If there are parsing problems, a warning will alert you.
 #'   You can retrieve the full details by calling [problems()] on your data
 #'   frame.
@@ -177,7 +177,7 @@
 #'   `character`.
 #' - [any](https://specs.frictionlessdata.io/table-schema/#any) as `character`.
 #' - Any other value is not allowed.
-#' - Type is guessed when not provided.
+#' - Type is guessed if not provided.
 #' @examples
 #' # Read a datapackage.json file
 #' package <- read_package(

R/resources.R

@@ -2,7 +2,7 @@
 #'
 #' Lists the names of the Data Resources included in a Data Package.
 #'
-#' @param package List describing a Data Package.
+#' @inheritParams read_resource
 #' @return Character vector with the Data Resource names.
 #' @family read functions
 #' @export

R/write_package.R

@@ -14,8 +14,7 @@
 #'   data are written to a CSV file using [readr::write_csv()], `path` points to
 #'   location of file, `data` property is removed.
 #'   Use `compress = TRUE` to gzip those CSV files.
-#' @param package List describing a Data Package, created with [read_package()]
-#'   or [create_package()].
+#' @inheritParams read_resource
 #' @param directory Path to local directory to write files to.
 #' @param compress If `TRUE`, data of added resources will be gzip compressed
 #'   before being written to disk (e.g. `deployments.csv.gz`).