Better handling of existing properties and items

Author: antaldaniel

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: wbdataset
 Title: Making Datasets Truly Interoperable and Reusable in R with Wikibase
-Version: 0.1.1034
-Date: 2024-03-30
+Version: 0.1.1035
+Date: 2024-04-03
 Authors@R: 
     c(person(given="Daniel", family="Antal", 
            email= "daniel.antal@dataobservatory.eu", 

NEWS.md

@@ -1,12 +1,16 @@
 # wbdataset
 
+# 0.1.1035
+* `get_property_definition()` works with CSRF, `check_existing_property()` returns
+correct datatype. Improved documentation and unit tests.
+
 # 0.1.1034
 * Remove the unnecessary `log_path` parameter from the create and copy function 
 families.
 * Many corrections in the formatting and the contents of the function reference.
 
 # wbdataset 0.1.1023
-* [check_existing_item()], [check_existing_property()]
+* `check_existing_item()`, `check_existing_property()`
 
 # wbdataset 0.1.1014
 * copy_wikidata_item, copy_wikidata_property works with one or several items/properties

R/add_statement.R

@@ -28,13 +28,13 @@ add_statement <- function(
     add_item_statement(
       qid = qid, pid = pid, o = o,
       wikibase_type == "string",
-      wikibase_api_url = wikibase_api_url, csrf_token = csrf_token
+      wikibase_api_url = wikibase_api_url, csrf = csrf
     )
   } else if (wikibase_type == "item") {
     add_item_statement(
       qid = qid, pid = pid, o = o,
       wikibase_type == "item",
-      wikibase_api_url = wikibase_api_url, csrf_token = csrf_token
+      wikibase_api_url = wikibase_api_url, csrf = csrf
     )
   } else if (wikibase_type == "numeric") {
 

R/check_existing_item.R

@@ -1,27 +1,45 @@
 #' @title Check if a label already has an item.
-#' @description
-#' Avoid failed writing attempts by checking if a label already matches an item.
-#' @details
-#' A wrapper around
+#' @description Avoid failed writing attempts by checking if a label already
+#' matches an item.
+#' @details A wrapper around
 #' \href{https://www.wikidata.org/w/api.php?action=help&modules=wbsearchentities}{MediaWiki
 #' action=wbsearchentities}.
 #' @param action Defaults to \code{"create_item"}.
 #' @param search_term A label in the given language, for example, "Estonia".
+#' @param language A single language code that indicates the language of the
+#'   label and description, using BCP 47-compliant language tags (e.g., "en" for
+#'   English, "fr" for French). Defaults to \code{"en"} for English.
+#' @param wikibase_api_url The full URL of the Wikibase API, which is the
+#'   address that the \code{wbdataset} R client sends requests to when
+#'   interacting with the knowledge base. In this case it defaults to
+#'   \code{'https://www.wikidata.org/w/api.php'}, Wikidata itself, where no
+#'   CSRF is needed.
+#' @param csrf The CSRF token of your session, received with
+#'   \code{\link{get_csrf}}, not needed if
+#'   \code{wikibase_api_url="https://www.wikidata.org/w/api.php"}. Defaults
+#'   to \code{NULL}.
 #' @inheritParams create_item
 #' @return A data.frame or NULL.
+#' @examples
+#' check_existing_item(
+#'     search_term="Estonian National Museum",
+#'     language = "en",
+#'     wikibase_api_url="https://www.wikidata.org/w/api.php",
+#'     csrf=NULL)
 #' @export
 
-check_existing_item <- function(action = "create_item",
-                                search_term,
-                                language,
+check_existing_item <- function(search_term,
+                                language = "en",
                                 equivalence_property = NA_character_,
                                 equivalence_id = NA_character_,
                                 classification_property = NA_character_,
                                 classification_id = NA_character_,
+                                action = "create_item",
                                 log_file_name = NA_character_,
                                 data_curator = person("Unknown", "Person"),
-                                wikibase_api_url,
-                                csrf) {
+                                wikibase_api_url = "https://www.wikidata.org/w/api.php",
+                                csrf = NULL) {
+
   action_timestamp <- action_timestamp_create()
   action_time <- Sys.time()
 
@@ -154,7 +172,8 @@ check_existing_item <- function(action = "create_item",
     )
   )
 
-  return_ds$rowid <- defined(paste0("wbi:", as.character(return_ds$id_on_target)),
+  prefix <- ifelse(wikibase_api_url=="https://www.wikidata.org/w/api.php", "wbi:", "wd:")
+  return_ds$rowid <- defined(paste0(prefix, as.character(return_ds$id_on_target)),
     namespace = wikibase_api_url
   )
 

R/check_existing_property.R

@@ -1,32 +1,46 @@
 #' @title Check if a label already has an property.
-#' @description
-#' Avoid failed writing attempts by checking if a label already matches an item.
-#' @details
-#' A wrapper around
+#' @description Avoid failed writing attempts by checking if a label already
+#' matches an item.
+#' @details A wrapper around
 #' \href{https://www.wikidata.org/w/api.php?action=help&modules=wbsearchentities}{MediaWiki
 #' action=wbsearchentities}.
 #' @param action Defaults to \code{"create_property"}.
 #' @param classification_property The instance of, or subclass of, or superclass
 #'   of property. Defaults to \code{NA_character} when not used.
 #' @param classification_id The QID of the class. Defaults to
 #'   \code{NA_character} when not used.
+#' @param wikibase_api_url The full URL of the Wikibase API, which is the
+#'   address that the \code{wbdataset} R client sends requests to when
+#'   interacting with the knowledge base. In this case it defaults to
+#'   \code{'https://www.wikidata.org/w/api.php'}, Wikidata itself, where no
+#'   CSRF is needed.
+#' @param csrf The CSRF token of your session, received with
+#'   \code{\link{get_csrf}}, not needed if
+#'   \code{wikibase_api_url="https://www.wikidata.org/w/api.php"}. Defaults
+#'   to \code{NULL}.
 #' @param search_term A label in the given language, for example, "Estonia".
 #' @inheritParams create_property
 #' @return A data.frame or NULL.
+#' @examples
+#' # No CSRF needed for Wikidata, but you will need it for Wikibase Suit
+#' check_existing_property(
+#'     search_term="instance of",
+#'     language = "en",
+#'     wikibase_api_url="https://www.wikidata.org/w/api.php")
 #' @export
 
 check_existing_property <- function(
-    action = "create_property",
     search_term,
     language,
     equivalence_property = NA_character_,
     equivalence_id = NA_character_,
     classification_property = NA_character_,
     classification_id = NA_character_,
+    action = "create_property",
     log_file_name = NA_character_,
     data_curator = person("Unknown", "Person"),
-    wikibase_api_url,
-    csrf) {
+    wikibase_api_url="https://www.wikidata.org/w/api.php",
+    csrf=NULL) {
 
   action_timestamp <- action_timestamp_create()
   action_time <- Sys.time()
@@ -46,7 +60,9 @@ check_existing_property <- function(
     handle = csrf
   )
 
-  search_response <- httr::content(get_search, as = "parsed", type = "application/json")
+  search_response <- httr::content(get_search,
+                                   as = "parsed",
+                                   type = "application/json")
 
   if (!is.null(search_response$error)) {
     stop(paste(search_response$error$code, ": ", search_response$error$info))
@@ -79,8 +95,13 @@ check_existing_property <- function(
 
   matching_property_data <- search_response$search[[which(exact_match)]]
 
+
+
   if (action %in% c("create_property", "copy_property")) {
-    datatype <- "property"
+    datatype <- get_property_definition(matching_property_data$id, "en",
+                                        wikibase_api_url = wikibase_api_url,
+                                        return_type =  "data.frame",
+                                        csrf= csrf)$datatype
     comment_text <- glue::glue("A property with the label ", search_term, " already exists in this Wikibase.")
   }
 
@@ -163,7 +184,10 @@ check_existing_property <- function(
     )
   )
 
-  return_ds$rowid <- defined(paste0("wbi:", as.character(return_ds$id_on_target)),
+  prefix <- ifelse(wikibase_api_url=="https://www.wikidata.org/w/api.php",
+                   "wd:", "wbi:")
+
+  return_ds$rowid <- defined(paste0(prefix, as.character(return_ds$id_on_target)),
     namespace = wikibase_api_url
   )
 

R/copy_wikidata_property.R

@@ -74,6 +74,8 @@ copy_wikidata_property <- function(
     pid_equivalence_property = "P2",
     language = c("en", "hu"),
     wikibase_api_url = "https://reprexbase.eu/jekyll/api.php",
+    classification_property = NA_character_,
+    classification_id = NA_character_,
     data_curator = NULL,
     log_file_name = NULL,
     csrf,

R/data-wikidata_countries_df.R

@@ -1,8 +1,7 @@
-#' Countries on Wikidata
-#'
+#' @title Countries on Wikidata
+#' @description
 #' A small dataset of countries, including sovereign states and autonomous
 #' parts of federal states taken from Wikidata.
-#'
 #' @format ## `wikidata_countries_df`
 #' A data frame with 4 rows and 4 columns:
 #' \describe{

R/get_propety_definition.R

@@ -1,7 +1,7 @@
 #' @title Get property definition
 #' @description Receive the label and description of a property on the basis of
-#' its PID from a Wikibase instance. It will not add further statements about
-#' the property.
+#'   its PID from a Wikibase instance. It will not add further statements about
+#'   the property.
 #' @details Currently the language has a choose a default, \code{"en"}, for
 #'   cases where the user-chosen language return empty labels and descriptions.
 #'   This feature may be elaborated or changed later. The function receives
@@ -10,13 +10,24 @@
 #'   as aliases themselves can break the tidiness of the returned data.
 #' @param pid The PID of the property in the Wikibase instance (or Wikidata
 #'   itself).
-#' @param wikibase_api_url Defaults to
-#'   \code{"https://www.wikidata.org/w/api.php"}, may be replaced with a similar
-#'   API address of a Wikibase instance. Private instances may require an
-#'   authenticated session.
-#' @param return_type Defaults to \code{"data.frame"} that is suitable for receiving
-#'   the information in stand-alone use. The \code{"JSON"} passes on a JSON
-#'   string in the format that you may need it in further Wikibase API calls.
+#' @param wikibase_api_url The full URL of the Wikibase API, which is the
+#'   address that the \code{wbdataset} R client sends requests to when
+#'   interacting with the knowledge base. In this case it defaults to
+#'   \code{'https://www.wikidata.org/w/api.php'}, Wikidata itself, where no CSRF
+#'   is needed.
+#' @param csrf The CSRF token of your session, received with
+#'   \code{\link{get_csrf}}, not needed if
+#'   \code{wikibase_api_url="https://www.wikidata.org/w/api.php"}. Defaults to
+#'   \code{NULL}.
+#' @param return_type Defaults to \code{"data.frame"} that is suitable for
+#'   receiving the information in stand-alone use. The \code{"JSON"} passes on a
+#'   JSON string in the format that you may need it in further Wikibase API
+#'   calls.
+#' @param language Defaults to \code{c("en", "nl", "hu")}. A character string of
+#'   the languages in which the users wants to receive the labels and
+#'   descriptions of the property. The vector of languages must use \href{https://en.wikipedia.org/wiki/IETF_language_tag}{BCP
+#'   47}-compliant language tags (e.g., "en" for English, and "hu"
+#'   for Hungarian.)
 #' @return A data.frame of the \code{PID} with the labels and descriptions of
 #'   the property in the selected languages. Alternatively, when
 #'   \code{return_type="JSON"}, the same data prepared for use in a subsequent
@@ -30,14 +41,16 @@
 #' get_property_definition(pid = "P2047", return_type = "data.frame")
 #'
 #' # Receive JSON for copying with wbeditidentiy
-#' get_property_definition(pid = "P2047", languages = c("en", "hu"))
+#' get_property_definition(pid = "P2047", language = c("en", "hu"))
 #' @export
 
 get_property_definition <- function(
     pid,
     language = c("en", "nl", "hu"),
     wikibase_api_url = "https://www.wikidata.org/w/api.php",
-    return_type = "JSON") {
+    return_type = "JSON",
+    csrf = NULL) {
+
   ## Ensure that the pid is a character string starting with P followed by
   ## numbers.
   pid <- as.character(pid)
@@ -74,9 +87,10 @@ get_property_definition <- function(
   safely_post <- purrr::safely(httr::POST, NULL)
 
   recevied_claim <- safely_post(
-    "https://www.wikidata.org/w/api.php",
+    wikibase_api_url,
     body = claim_body,
-    encode = "form"
+    encode = "form",
+    handle = csrf
   )
 
   if (!is.null(recevied_claim$error)) {
@@ -97,12 +111,30 @@ get_property_definition <- function(
     )
   }
 
-  if (!is_response_success(response)) { # internal assertion for susccessful response
+
+  pid_is_missing <- ifelse(!is.null(response[[1]][[1]]$missing), TRUE, FALSE)
+
+
+  if (!is_response_success(response)) {
+    # internal assertion for successful response
     # Exception: retrieval of the property was not successful, even though we
     # did not get an explicit error before.
     message("Could not access ", pid)
     message(response$error$messages[[1]]) # print the error message for debugging
+    if (return_type == "data.frame") {
+      return(error_data_frame)
+    }
+    if (return_type != "data.frame") { # in any other case send JSON
+      return(error_json)
+    }
+  }
+
+  if (pid_is_missing) {
+    # No such property
+    message("Property does not exist ", pid)
+    message(response$error$messages[[1]]) # print the error message for debugging
     if (return_type == "data.frame") { # if the user needs a data.frame
+      error_data_frame$success <- TRUE
       return(error_data_frame)
     }
     if (return_type != "data.frame") { # in any other case send JSON
@@ -178,6 +210,7 @@ get_property_definition <- function(
         data.frame(
           language = names(descriptions_vector),
           description = as.character(descriptions_vector),
+          datatype = rep(response$entities[[1]]$datatype, length(descriptions_vector)),
           success = TRUE
         ),
         by = "language"
@@ -193,3 +226,4 @@ get_property_definition <- function(
     )
   }
 }
+