diff --git a/NEWS.md b/NEWS.md index e8a5335..c8cec43 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,17 @@ +HSClientR 0.3.2.9000 (2026-10-20) +================================= + +### DEPRECATIONS + + * Deprecated `hs_search()` with a warning that the method is no longer supported by this client and may return errors. + * Deprecated `hs_discover()` with a warning that the method is no longer supported by this client and may return errors. + * Deprecated the `HSClient` R6 client and updated initialization messaging to direct users to function-based APIs. + +### DOCUMENTATION + + * Updated `README` to remove detailed `HSClient` usage examples and retain only a deprecation statement. + * Updated deprecation notes for deprecated search/discover paths to reflect current support status. + HSClientR 0.3.1 (2021-03-31) ============================ diff --git a/R/HSClient.R b/R/HSClient.R index 822f57e..f77d08f 100644 --- a/R/HSClient.R +++ b/R/HSClient.R @@ -1,8 +1,11 @@ -#' @title R6 Class representing a HydroShare Client +#' @title Deprecated R6 HydroShare Client #' @description -#' `r lifecycle::badge("experimental")` +#' `r lifecycle::badge("deprecated")` #' -#' *In development* +#' `HSClient` is deprecated and retained only for backward compatibility. +#' It is no longer supported by this package and may return errors. +#' Prefer direct package functions such as [hs_resource()], [hs_files()], +#' and [hs_sysmeta()]. #' @importFrom R6 R6Class #' @importFrom urltools param_get #' @importFrom lifecycle badge @@ -14,12 +17,21 @@ HSClient <- R6::R6Class("HSClient", #' @return A new `HSClient` object. #' #' *Note: A message will be issued - #' since R6-object is still in development.* + #' since this R6 object is deprecated.* initialize = function() { + rlang::warn( + paste( + "HSClient is deprecated and no longer supported by this package.", + "It may return errors.", + "Use direct package functions such as hs_resource(), hs_files(),", + "and hs_sysmeta() instead." + ) + ) + rlang::inform( crayon::cyan(crayon::bold(paste0( - "R6-based client still in-development.\n", - "Full functionality may not exist." + "R6-based client is deprecated.\n", + "Use package functions instead." ))) ) @@ -37,10 +49,11 @@ HSClient <- R6::R6Class("HSClient", crayon::silver("=======================================\n"), "Thanks for using HSClientR! ", crayon::red("\u2665"), - "\nYou can start a query with ", - crayon::red("$query()"), - "\nMake sure to authenticate with ", - crayon::red("$authenticate()"), + "\nThis R6 client is deprecated.", + "\nPrefer package functions like ", + crayon::red("hs_resource()"), + " and ", + crayon::red("hs_files()"), "\n" ) diff --git a/R/hs_discover.R b/R/hs_discover.R index 70ec2d7..3524488 100644 --- a/R/hs_discover.R +++ b/R/hs_discover.R @@ -1,5 +1,9 @@ -#' @title HydroShare Discover API +#' @title Deprecated HydroShare Discover API helper #' @description Query the HydroShare Discover Page +#' +#' `hs_discover()` is retained for backward compatibility only. +#' This method is no longer supported by this client and may +#' return errors. #' @return A [tibble][tibble::tibble-package] of the first 40 results from #' HydroShare's [Discover Page](https://www.hydroshare.org/search/). See #' details for `tibble` description. @@ -30,6 +34,12 @@ #' @importFrom rlang .data #' @export hs_discover <- function() { + lifecycle::deprecate_warn( + when = "0.3.2", + what = "hs_discover()", + details = "The hs_discover() method is no longer supported by this client and may return errors." + ) + request <- httr::GET( handle = hsapi(), path = "discoverapi/", diff --git a/R/hs_resource.R b/R/hs_resource.R index 4a68fc1..9e6a61b 100644 --- a/R/hs_resource.R +++ b/R/hs_resource.R @@ -21,6 +21,12 @@ #' Parameters marked with an asterisk (*) are required for #' that endpoint. #' +#' ## Deprecated Search Path (`hs_search`) +#' +#' `hs_search()` is retained for backward compatibility only. +#' This method is no longer supported by this client and may +#' return errors. +#' #' ## Searching Resources (`hs_search`) #' #' ### Endpoint: @@ -227,7 +233,7 @@ hs_content_types <- function() { } # nolint start -#' @title Search HydroShare Resources using solr conventions. +#' @title Deprecated search helper for HydroShare resources. #' @param page (`integer`) A page number within the paginated result set. #' @param count (`integer`) Number of results to return per page. #' @param text (`character`) Search across all Resource Fields @@ -268,6 +274,12 @@ hs_content_types <- function() { # nolint end hs_search <- function(page = NULL, count = NULL, text = NULL, author = NULL, ...) { + lifecycle::deprecate_warn( + when = "0.3.2", + what = "hs_search()", + details = "The hs_search() method is no longer supported by this client and may return errors." + ) + # Prevents R CMD Check note about non-standard # evaluation with magrittr pipes . <- NULL diff --git a/README.md b/README.md index 39c714c..796a78a 100644 --- a/README.md +++ b/README.md @@ -13,9 +13,9 @@ HSClientR is an API wrapper for [HydroShare](https://www.hydroshare.org). Using HSClientR, you can -access resources from HydroShare directly in your R environment, either -by the package functions or the in-development -[`R6 Class`](https://r6.r-lib.org/reference/R6Class.html). +access resources from HydroShare directly in your R environment with +the package functions. The [`R6 Class`](https://r6.r-lib.org/reference/R6Class.html) +client is deprecated and retained for backward compatibility only. ## Installation @@ -42,12 +42,15 @@ as well as some additional functionality. ``` r # To set auth headers -hs_auth(set_headers = TRUE) +hs_auth(set_header = TRUE) ``` This function will begin an [OAuth 2.0](https://oauth.net/2/) dance between your R session and the -HydroShare API. This is only needed if you are utilizing `hs_user()`/`hs_userDetails()` or any of the -`DELETE`, `POST`, and `PUT` functions. Most of the `GET` functions are publicly accessible. +HydroShare API. This is only needed if you are utilizing `hs_user()`/`hs_user_details()`. Most of +the `GET` functions are publicly accessible. + +> Note: the search-based examples below call the deprecated HydroShare `/hsapi/resource/search` +> endpoint via `hs_search()` / `hs_resource(text = ...)` and will now warn or return HTTP 404. ``` r # Search for resources @@ -81,6 +84,9 @@ Another way of finding resources is via the Discover API. This is equivalent to accessing the "Discover" page directly on the HydroShare website. It returns the first 40 results. +> Note: `hs_discover()` is deprecated will may now warn or fail because the upstream Discover endpoint +> is no longer supported. + > It is preferred to use `hs_resource()` or any of the other `hs_*` functions, > as they have better support/flexibility in contrast to `hs_discover()`. @@ -151,73 +157,11 @@ hs_resource(id = "e1d4f2aff7d84f79b901595f6ea48368") For more details on using `hs_resource()`, refer to the [documentation site](https://hsclientr.justinsingh.me/reference/hs_resource.html). -## Example Using R6 HydroShare Client Class +## R6 HydroShare Client -> Note: functionality for queries and discover traversal still need to -> be implemented. The example below may change as the object matures. - -``` r -# Create new HSClient object -hs_client <- HSClient$new() - -#> R6-based client still in-development. -#> Full functionality may not exist. -#> -#> HSClientR - R6 Client -#> ======================================= -#> Thanks for using HSClientR! ♥ -#> You can start a query with $query() -#> Make sure to authenticate with $authenticate() -#> ======================================= - -hs_client$print() - -#> It looks like you haven't authenticated yet... -#> Please call $authenticate() on this object to get -#> OAuth2 authentication set up with HydroShare! :) - -# Begin authentication (hs_auth) -hs_client$authenticate() - -# OAuth2 Dance will begin and a web browser -# will open to HydroShare's login/authorization -# page. Once you login, an access token will be -# sent back to a local httpuv web server for -# your R session. - -# Search for a resource (hs_resource) -hs_client$query(text = "NHDPlus VAA") - -#> # A tibble: 2 x 18 -#> text author abstract contributor subject availability created modified -#> -#> 1 " \n ba… Rea, A… "The NHDPl… "" NHDPlus,… public 2019-0… 2019-08… -#> 2 " \n 60… Johnso… "These fil… "" roughnes… public 2020-1… 2021-02… -#> # … with 10 more variables: coverage_type , east , northlimit , -#> # eastlimit , southlimit , westlimit , start_date , -#> # end_date , resource_type , content_type - -# $query uses hs_search() to perform the query, -# and while a tibble is outputted, the object returns -# itself invisibly. Once the query is performed, we can -# print our object to see our last query and its results: - -hs_client$print() - -#> Authenticated as: -#> Justin Singh-Mohudpur -#> User: jsinghm -#> ID: 8409 -#> Org: University of California, Santa Barbara -#> ======================================= -#> Last Query ($query): text = "NHDPlus VAA" -#> Query Results: -#> -#> 6092c8a62fac45be97a09bfd0b0bf726 -#> -#> NHDPlus Value Added Attributes - no geometries -#> These files contain a curated set ... -``` +> `HSClient` is deprecated and retained for backward compatibility only. +> Prefer direct package functions such as `hs_resource()`, `hs_files()`, and +> `hs_sysmeta()`. ## Meta diff --git a/man/HSClient.Rd b/man/HSClient.Rd index b6d6111..0209acb 100644 --- a/man/HSClient.Rd +++ b/man/HSClient.Rd @@ -2,176 +2,198 @@ % Please edit documentation in R/HSClient.R \name{HSClient} \alias{HSClient} -\title{R6 Class representing a HydroShare Client} +\title{Deprecated R6 HydroShare Client} \description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -\emph{In development} +\code{HSClient} is deprecated and retained only for backward compatibility. +It is no longer supported by this package and may return errors. +Prefer direct package functions such as \code{\link[=hs_resource]{hs_resource()}}, \code{\link[=hs_files]{hs_files()}}, +and \code{\link[=hs_sysmeta]{hs_sysmeta()}}. } \section{Methods}{ \subsection{Public methods}{ -\itemize{ -\item \href{#method-new}{\code{HSClient$new()}} -\item \href{#method-print}{\code{HSClient$print()}} -\item \href{#method-authenticate}{\code{HSClient$authenticate()}} -\item \href{#method-query}{\code{HSClient$query()}} -\item \href{#method-get_res}{\code{HSClient$get_res()}} -\item \href{#method-next_res}{\code{HSClient$next_res()}} -\item \href{#method-prev_res}{\code{HSClient$prev_res()}} -\item \href{#method-next_page}{\code{HSClient$next_page()}} -\item \href{#method-prev_page}{\code{HSClient$prev_page()}} -\item \href{#method-clone}{\code{HSClient$clone()}} -} + \itemize{ + \item \href{#method-HSClient-initialize}{\code{HSClient$new()}} + \item \href{#method-HSClient-print}{\code{HSClient$print()}} + \item \href{#method-HSClient-authenticate}{\code{HSClient$authenticate()}} + \item \href{#method-HSClient-query}{\code{HSClient$query()}} + \item \href{#method-HSClient-get_res}{\code{HSClient$get_res()}} + \item \href{#method-HSClient-next_res}{\code{HSClient$next_res()}} + \item \href{#method-HSClient-prev_res}{\code{HSClient$prev_res()}} + \item \href{#method-HSClient-next_page}{\code{HSClient$next_page()}} + \item \href{#method-HSClient-prev_page}{\code{HSClient$prev_page()}} + \item \href{#method-HSClient-clone}{\code{HSClient$clone()}} + } } \if{html}{\out{
}} -\if{html}{\out{}} -\if{latex}{\out{\hypertarget{method-new}{}}} -\subsection{Method \code{new()}}{ -Initialize a HydroShare Client -\subsection{Usage}{ -\if{html}{\out{
}}\preformatted{HSClient$new()}\if{html}{\out{
}} -} - -\subsection{Returns}{ -A new \code{HSClient} object. +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-HSClient-initialize}{}}} +\subsection{\code{HSClient$new()}}{ + Initialize a HydroShare Client + \subsection{Usage}{ + \if{html}{\out{
}} + \preformatted{HSClient$new()} + \if{html}{\out{
}} + } + \subsection{Returns}{ + A new \code{HSClient} object. \emph{Note: A message will be issued -since R6-object is still in development.} -} +since this R6 object is deprecated.} + } } + \if{html}{\out{
}} -\if{html}{\out{}} -\if{latex}{\out{\hypertarget{method-print}{}}} -\subsection{Method \code{print()}}{ -Print HSClient object -\subsection{Usage}{ -\if{html}{\out{
}}\preformatted{HSClient$print()}\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-HSClient-print}{}}} +\subsection{\code{HSClient$print()}}{ + Print HSClient object + \subsection{Usage}{ + \if{html}{\out{
}} + \preformatted{HSClient$print()} + \if{html}{\out{
}} + } + \subsection{Returns}{ + \code{HSClient} output + } } -\subsection{Returns}{ -\code{HSClient} output -} -} \if{html}{\out{
}} -\if{html}{\out{}} -\if{latex}{\out{\hypertarget{method-authenticate}{}}} -\subsection{Method \code{authenticate()}}{ -Perform OAuth2 Authentication +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-HSClient-authenticate}{}}} +\subsection{\code{HSClient$authenticate()}}{ + Perform OAuth2 Authentication with HydroShare. -\subsection{Usage}{ -\if{html}{\out{
}}\preformatted{HSClient$authenticate()}\if{html}{\out{
}} -} - -\subsection{Details}{ -Note, the access token will be set + \subsection{Usage}{ + \if{html}{\out{
}} + \preformatted{HSClient$authenticate()} + \if{html}{\out{
}} + } + \subsection{Details}{ + Note, the access token will be set as a header automatically if \code{.token} is \code{NULL}. + } + \subsection{Returns}{ + self, invisibly. + } } -\subsection{Returns}{ -self, invisibly. -} -} \if{html}{\out{
}} -\if{html}{\out{}} -\if{latex}{\out{\hypertarget{method-query}{}}} -\subsection{Method \code{query()}}{ -Query/Search HydroShare -\subsection{Usage}{ -\if{html}{\out{
}}\preformatted{HSClient$query(...)}\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-HSClient-query}{}}} +\subsection{\code{HSClient$query()}}{ + Query/Search HydroShare + \subsection{Usage}{ + \if{html}{\out{
}} + \preformatted{HSClient$query(...)} + \if{html}{\out{
}} + } + \subsection{Arguments}{ + \if{html}{\out{
}} + \describe{ + \item{\code{...}}{Query parameters. See \link{hs_resource} parameters.} + } + \if{html}{\out{
}} + } + \subsection{Returns}{ + R6 object + } } -\subsection{Arguments}{ -\if{html}{\out{
}} -\describe{ -\item{\code{...}}{Query parameters. See \link{hs_resource} parameters.} -} -\if{html}{\out{
}} -} -\subsection{Returns}{ -R6 object -} -} \if{html}{\out{
}} -\if{html}{\out{}} -\if{latex}{\out{\hypertarget{method-get_res}{}}} -\subsection{Method \code{get_res()}}{ -Get current resource -\subsection{Usage}{ -\if{html}{\out{
}}\preformatted{HSClient$get_res()}\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-HSClient-get_res}{}}} +\subsection{\code{HSClient$get_res()}}{ + Get current resource + \subsection{Usage}{ + \if{html}{\out{
}} + \preformatted{HSClient$get_res()} + \if{html}{\out{
}} + } + \subsection{Returns}{ + A \link[tibble:tibble-package]{tibble} of the current resource + } } -\subsection{Returns}{ -A \link[tibble:tibble-package]{tibble} of the current resource -} -} \if{html}{\out{
}} -\if{html}{\out{}} -\if{latex}{\out{\hypertarget{method-next_res}{}}} -\subsection{Method \code{next_res()}}{ -Get next resource -\subsection{Usage}{ -\if{html}{\out{
}}\preformatted{HSClient$next_res()}\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-HSClient-next_res}{}}} +\subsection{\code{HSClient$next_res()}}{ + Get next resource + \subsection{Usage}{ + \if{html}{\out{
}} + \preformatted{HSClient$next_res()} + \if{html}{\out{
}} + } + \subsection{Returns}{ + Resource tibble. See \verb{$get_res}. + } } -\subsection{Returns}{ -Resource tibble. See \verb{$get_res}. -} -} \if{html}{\out{
}} -\if{html}{\out{}} -\if{latex}{\out{\hypertarget{method-prev_res}{}}} -\subsection{Method \code{prev_res()}}{ -Get previous resource -\subsection{Usage}{ -\if{html}{\out{
}}\preformatted{HSClient$prev_res()}\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-HSClient-prev_res}{}}} +\subsection{\code{HSClient$prev_res()}}{ + Get previous resource + \subsection{Usage}{ + \if{html}{\out{
}} + \preformatted{HSClient$prev_res()} + \if{html}{\out{
}} + } + \subsection{Returns}{ + Resource tibble. See \verb{$get_res}. + } } -\subsection{Returns}{ -Resource tibble. See \verb{$get_res}. -} -} \if{html}{\out{
}} -\if{html}{\out{}} -\if{latex}{\out{\hypertarget{method-next_page}{}}} -\subsection{Method \code{next_page()}}{ -Get next search page -\subsection{Usage}{ -\if{html}{\out{
}}\preformatted{HSClient$next_page()}\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-HSClient-next_page}{}}} +\subsection{\code{HSClient$next_page()}}{ + Get next search page + \subsection{Usage}{ + \if{html}{\out{
}} + \preformatted{HSClient$next_page()} + \if{html}{\out{
}} + } + \subsection{Returns}{ + Query tibble. See \verb{$query}. + } } -\subsection{Returns}{ -Query tibble. See \verb{$query}. -} -} \if{html}{\out{
}} -\if{html}{\out{}} -\if{latex}{\out{\hypertarget{method-prev_page}{}}} -\subsection{Method \code{prev_page()}}{ -Get previous search page -\subsection{Usage}{ -\if{html}{\out{
}}\preformatted{HSClient$prev_page()}\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-HSClient-prev_page}{}}} +\subsection{\code{HSClient$prev_page()}}{ + Get previous search page + \subsection{Usage}{ + \if{html}{\out{
}} + \preformatted{HSClient$prev_page()} + \if{html}{\out{
}} + } + \subsection{Returns}{ + Query tibble. See \verb{$query}. + } } -\subsection{Returns}{ -Query tibble. See \verb{$query}. -} -} \if{html}{\out{
}} -\if{html}{\out{}} -\if{latex}{\out{\hypertarget{method-clone}{}}} -\subsection{Method \code{clone()}}{ -The objects of this class are cloneable with this method. -\subsection{Usage}{ -\if{html}{\out{
}}\preformatted{HSClient$clone(deep = FALSE)}\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-HSClient-clone}{}}} +\subsection{\code{HSClient$clone()}}{ + The objects of this class are cloneable with this method. + \subsection{Usage}{ + \if{html}{\out{
}} + \preformatted{HSClient$clone(deep = FALSE)} + \if{html}{\out{
}} + } + \subsection{Arguments}{ + \if{html}{\out{
}} + \describe{ + \item{\code{deep}}{Whether to make a deep clone.} + } + \if{html}{\out{
}} + } } -\subsection{Arguments}{ -\if{html}{\out{
}} -\describe{ -\item{\code{deep}}{Whether to make a deep clone.} -} -\if{html}{\out{
}} -} -} } diff --git a/man/hs_discover.Rd b/man/hs_discover.Rd index ef4387d..babdf28 100644 --- a/man/hs_discover.Rd +++ b/man/hs_discover.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/hs_discover.R \name{hs_discover} \alias{hs_discover} -\title{HydroShare Discover API} +\title{Deprecated HydroShare Discover API helper} \usage{ hs_discover() } @@ -13,6 +13,10 @@ details for \code{tibble} description. } \description{ Query the HydroShare Discover Page + +\code{hs_discover()} is retained for backward compatibility only. +This method is no longer supported by this client and may +return errors. } \details{ \subsection{Main \code{tibble}}{ diff --git a/man/hs_resource.Rd b/man/hs_resource.Rd index 615ad78..b70b3cd 100644 --- a/man/hs_resource.Rd +++ b/man/hs_resource.Rd @@ -26,6 +26,13 @@ corresponding HydroShare API endpoint(s)/functions used. Parameters marked with an asterisk (*) are required for that endpoint. +\subsection{Deprecated Search Path (\code{hs_search})}{ + +\code{hs_search()} is retained for backward compatibility only. +This method is no longer supported by this client and may +return errors. +} + \subsection{Searching Resources (\code{hs_search})}{ \subsection{Endpoint:}{ \itemize{ diff --git a/man/hs_search.Rd b/man/hs_search.Rd index bc27885..918a85f 100644 --- a/man/hs_search.Rd +++ b/man/hs_search.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/hs_resource.R \name{hs_search} \alias{hs_search} -\title{Search HydroShare Resources using solr conventions.} +\title{Deprecated search helper for HydroShare resources.} \usage{ hs_search(page = NULL, count = NULL, text = NULL, author = NULL, ...) } @@ -23,7 +23,7 @@ A list with \code{.next}, \code{.prev}, and \code{results} attributes. \code{results} returns a \link[tibble:tibble-package]{tibble}. } \description{ -Search HydroShare Resources using solr conventions. +Deprecated search helper for HydroShare resources. } \details{ \subsection{Additional Parameters:}{\tabular{lll}{