Merge pull request #401 from r-world-devs/396-397-manage-verbose-upda…

…te-docs

Next stage of necessary changes

.Rbuildignore

@@ -11,4 +11,4 @@
 ^_pkgdown\.yml$
 ^docs$
 ^pkgdown$
-^meta_data.yaml
+^project_metadata.yaml

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: GitStats
 Title: Get Statistics from GitHub and GitLab
-Version: 1.1.0.9007
+Version: 1.1.0.9008
 Authors@R: c(
     person(given = "Maciej", family = "Banas", email = "[email protected]", role = c("aut", "cre")),
     person(given = "Kamil", family = "Koziej", email = "[email protected]", role = "aut"),
@@ -17,6 +17,7 @@ RoxygenNote: 7.3.1
 Imports:
     cli,
     dplyr,
+    glue,
     httr2,
     lubridate,
     magrittr,

NAMESPACE

@@ -11,7 +11,6 @@ export(get_repos)
 export(get_users)
 export(set_github_host)
 export(set_gitlab_host)
-export(show_data)
 export(show_orgs)
 export(verbose_off)
 export(verbose_on)
@@ -28,6 +27,7 @@ importFrom(dplyr,filter)
 importFrom(dplyr,glimpse)
 importFrom(dplyr,mutate)
 importFrom(dplyr,relocate)
+importFrom(glue,glue)
 importFrom(httr2,req_headers)
 importFrom(httr2,req_perform)
 importFrom(httr2,request)

NEWS.md

@@ -6,7 +6,7 @@
 
 ## Simplifying workflow:
 
-- GitStats workflow is now simplified. To pull data on `repositories`, `commits`, `R_package_usage` you should use directly corresponding `get_*()` functions instead of `pull_*()` which are deprecated. These `get_*()` functions pull data from API, parse it into table, add some goodies (additional columns) if needed and return table instead of `GitStats` object, which in our opinion is more intuitive and user-friendly ([#345]((https://github.com/r-world-devs/GitStats/issues/345))). That means you do not need to run in pipe two or three additional function calls as before, e.g. `pull_repos(gitstats_object) %>% get_repos() %>% get_repos_stats()`, but you just run
+- GitStats workflow is now simplified. To pull data on `repositories`, `commits`, `R_package_usage` or other you should use directly corresponding `get_*()` functions instead of `pull_*()` which are deprecated. These `get_*()` functions pull data from API, parse it into table, add some goodies (additional columns) if needed and return table instead of `GitStats` object, which in our opinion is more intuitive and user-friendly ([#345]((https://github.com/r-world-devs/GitStats/issues/345))). That means you do not need to run in pipe two or three additional function calls as before, e.g. `pull_repos(gitstats_object) %>% get_repos() %>% get_repos_stats()`, but you just run
 `get_repos(gitstats_object)` to get data you need.
 - Moreover, if you run for the second time `get_*()` function GitStats will pull the data from its storage and not from API as for the first time, unless you change parameters for the function (e.g. starting date with `since` in `get_commits()`) or change directly the `use_storage` parameter in the function. ([#333](https://github.com/r-world-devs/GitStats/issues/333))
 - `pull_repos_contributors()` as a separate function is deprecated. The parameter `add_contributors` is now set by  default to `TRUE` in `get_repos()` which seems more reasonable as user gets all the data.
@@ -15,7 +15,7 @@
 ## Changes to setting parameters and pulling repositories by code:
 
 - `set_params()` function is removed. ([#386](https://github.com/r-world-devs/GitStats/issues/386)) Now the logic is moved straight to `get_*` functions. For example, if you want to pull repositories with specific `code blob`, you do not need to define anything with `set_params()` (as previously with `search_mode` and `phrase` parameter) but you just simply run `get_repos(with_code = 'your_code')`. ([#333](https://github.com/r-world-devs/GitStats/issues/333))
-- New logical parameters have been introduced for limiting messages to user when pulling data (`verbose`) - you can turn it on/off with  `verbose_on()`/`verbose_off()` functions.
+- New logical parameters have been introduced for limiting messages to user when pulling data (`verbose`) - these parameters can be set in all `get_*()` functions. You can also turn the verbose mode on/off globally with `verbose_on()`/`verbose_off()` functions.
 
 ## Deprecate:
 
@@ -27,14 +27,12 @@
 ## New features:
 
 - Added `get_release_logs()` ([#356](https://github.com/r-world-devs/GitStats/issues/356)).
-- Added `show_data()` function, where user passes the name of the object he wants to retrieve (e.g. `repos`, `commits`, `package_usage`) to the `storage` parameter.
 - `get_orgs()` is renamed to `show_orgs()` to reflect that it does not pull data from API, but only shows what is in `GitStats` object.
 
 ## Minor features:
 
 - Commits response consists now of two new columns: `author_login` and `author_name` ([#332](https://github.com/r-world-devs/GitStats/issues/332)). This is due to the mix of GitHub/GitLab handles and display names in the `author` column (the original author `name` field in commits API response).
-- Use stored repositories when pulling commits or files ([#159](https://github.com/r-world-devs/GitStats/issues/159)).
-- Improve printing `GitStats` object - now when you return `GitStats` object in console, it prints `GitStats` data divided into sections to give more readable information to user: `scanning scope` (organizations, repositories and files), `search settings` (searched phrase, language, team name) and `storage` (the output tables stored in `GitStats` with basic information on dimensions) ([#329](https://github.com/r-world-devs/GitStats/issues/329)).
+- Improve printing `GitStats` object - now when you return `GitStats` object in console, it prints `GitStats` data divided into sections to give more readable information to user: `scanning scope` (organizations and repositories), and `storage` (the output tables stored in `GitStats` with basic information on dimensions) ([#329](https://github.com/r-world-devs/GitStats/issues/329)).
 
 ## Bug fixes:
 

R/Engine.R

@@ -0,0 +1,22 @@
+#' @noRd
+#' @description A superclass for API connections.
+Engine <- R6::R6Class("Engine",
+  private = list(
+    # A token authorizing access to API.
+    token = NULL,
+
+    # Is scanning whole git platform switched on?
+    scan_all = FALSE,
+
+    # Engine type.
+    engine = NULL,
+
+    # Print messages or not.
+    verbose = TRUE,
+
+    # Set verbose mode
+    set_verbose = function(verbose) {
+      private$verbose <- verbose
+    }
+  )
+)

R/EngineGraphQL.R

@@ -1,6 +1,8 @@
 #' @noRd
 #' @description A class for methods wrapping GitHub's GraphQL API responses.
 EngineGraphQL <- R6::R6Class("EngineGraphQL",
+   inherit = Engine,
+
    public = list(
 
      #' @field gql_api_url A character, url of GraphQL API.
@@ -9,22 +11,17 @@ EngineGraphQL <- R6::R6Class("EngineGraphQL",
      #' @field gql_query An environment for GraphQL queries.
      gql_query = NULL,
 
-     #' @description Create `EngineGraphQL` object.
-     #' @param gql_api_url GraphQL API url.
-     #' @param token A token.
-     #' @param scan_all A boolean.
+     #' Create `EngineGraphQL` object.
      initialize = function(gql_api_url = NA,
                            token = NA,
                            scan_all = FALSE) {
+       private$engine <- "graphql"
        self$gql_api_url <- gql_api_url
        private$token <- token
        private$scan_all <- scan_all
      },
 
-     #' @description Wrapper of GraphQL API request and response.
-     #' @param gql_query A string with GraphQL query.
-     #' @param vars A list of named variables.
-     #' @return A list.
+     #' Wrapper of GraphQL API request and response.
      gql_response = function(gql_query, vars = "null") {
        response <- private$perform_request(
          gql_query = gql_query,
@@ -34,134 +31,32 @@ EngineGraphQL <- R6::R6Class("EngineGraphQL",
        return(response_list)
      },
 
-     #' @description Get information on users in the form of table
-     #' @param users A character vector of users
-     #' @return A table
-     pull_users = function(users) {
-       purrr::map(users, function(user) {
-         private$pull_user(username = user) %>%
-           private$prepare_user_table()
-       }) %>%
-         purrr::list_rbind()
-     },
-
-     #' @description A method to retrieve given files from all repositories for
-     #'   an organization in a table format.
-     #' @param org An organization.
-     #' @param file_path A file path.
-     #' @param pulled_repos Optional parameter to pass repository output object.
-     #' @param settings A list of  `GitStats` settings.
-     #' @return A table.
-     pull_files = function(org, file_path, pulled_repos = NULL, settings) {
-       if (!private$scan_all && settings$verbose) {
-         cli::cli_alert_info("[Engine:{cli::col_yellow('GraphQL')}][org:{org}] Pulling {file_path} files...")
-       }
-       files_table <- private$pull_file_from_org(
-         org = org,
-         file_path = file_path,
-         pulled_repos = pulled_repos
-       ) %>%
-         private$prepare_files_table(
-           org = org,
-           file_path = file_path
+     # A method to pull information on user.
+     pull_user = function(username) {
+       response <- tryCatch({
+         self$gql_response(
+           gql_query = self$gql_query$user(),
+           vars = list("user" = username)
          )
-       return(files_table)
-     },
-
-     #' @description Method to get releases.
-     #' @param org An organization.
-     #' @param repos A vector of repositories.
-     #' @param date_from A starting date of releases.
-     #' @param date_until An end date for releases.
-     #' @param settings A list of  `GitStats` settings.
-     #' @param storage A storage of `GitStats` object.
-     #' @return A table of commits.
-     pull_release_logs = function(org,
-                                  repos = NULL,
-                                  date_from,
-                                  date_until = Sys.date(),
-                                  settings,
-                                  storage = NULL) {
-       if (!private$scan_all && settings$verbose) {
-         cli::cli_alert_info("[Engine:{cli::col_yellow('GraphQL')}][org:{org}] Pulling releases...")
-       }
-       repos_names <- private$set_repositories(
-         repos = repos,
-         org = org,
-         settings = settings,
-         storage = storage
-       )
-       if (length(repos_names) > 0) {
-         releases_table <- private$pull_releases_from_org(
-           repos_names = repos_names,
-           org = org
-         ) %>%
-           private$prepare_releases_table(org, date_from, date_until)
-       } else {
-         releases_table <- NULL
-       }
-       return(releases_table)
+       }, error = function(e) {
+         NULL
+       })
+       return(response)
      }
-
    ),
    private = list(
-     # @field token A token authorizing access to API.
-     token = NULL,
-
-     # @field A boolean.
-     scan_all = FALSE,
 
+     # GraphQL method for pulling response from API
      perform_request = function(gql_query, vars) {
        response <- httr2::request(paste0(self$gql_api_url, "?")) %>%
          httr2::req_headers("Authorization" = paste0("Bearer ", private$token)) %>%
          httr2::req_body_json(list(query = gql_query, variables = vars)) %>%
          httr2::req_retry(
-           is_transient = ~ httr2::resp_status(.x) == "400|502",
+           is_transient = ~ httr2::resp_status(.x) == "400|500|502",
            max_seconds = 60
          ) %>%
          httr2::req_perform()
        return(response)
-     },
-
-     # @description A method to pull information on user.
-     # @param username A login.
-     # @return A user response.
-     pull_user = function(username) {
-       response <- NULL
-       try(
-         response <- self$gql_response(
-           gql_query = self$gql_query$user(),
-           vars = list("user" = username)
-         )
-       )
-       return(response)
-     },
-
-     # Set repositories for pulling commits or release logs
-     set_repositories = function(repos, org, settings, storage) {
-       if (is.null(repos)) {
-         if (is.null(storage$repositories)) {
-           repos_table <- self$pull_repos(
-             org = org,
-             settings = settings
-           )
-         } else {
-           if (settings$verbose) {
-             cli::cli_alert_warning(
-               cli::col_yellow("Using repositories stored in `GitStats` object.")
-             )
-           }
-           repos_table <- storage$repositories %>%
-             dplyr::filter(
-               organization == org
-             )
-         }
-         repos_names <- repos_table$repo_name
-       }
-       if (!is.null(repos)) {
-         repos_names <- repos
-       }
-       return(repos_names)
      }
    )
 )