connection: examples and tests

issue #27 #33

NEWS.md

@@ -13,6 +13,7 @@ Breaking change
 
 Minor
 
+* fix `max_page` with `gl_()` functions
 * Correction of api that downloaded twice the first page when `page == "all"`
 * Reduce `max_page` to retrieve content to allow to work with big GitLab servers like Gitlab.com
 * Change maintainer

R/branches.R

@@ -7,9 +7,8 @@
 #' @export
 #' 
 #' @examples \dontrun{
-#' my_gitlab <- gl_connection(gitlab_url = "https://gitlab.com",
-#'   private_token = Sys.getenv("GITLAB_COM_TOKEN")) ## fill in login parameters
-#' set_gitlab_connection(my_gitlab)
+#' set_gitlab_connection(gitlab_url = "https://gitlab.com",
+#'   private_token = Sys.getenv("GITLAB_COM_TOKEN"))
 #' project_id <- ... ## Fill in your project ID
 #' 
 #' # List branches of the project

R/ci.R

@@ -191,12 +191,10 @@ use_gitlab_ci <- function(#pipeline = gl_default_ci_pipeline(),
 #' @rdname gl_builds
 #' 
 #' @examples \dontrun{
-#' # connect as a fixed user to a gitlab instance
-#' my_gitlab <- gl_connection(
+#' # connect as a fixed user to a GitLab instance
+#' set_gitlab_connection(
 #'   gitlab_url = "https://gitlab.com",
 #'   private_token = Sys.getenv("GITLAB_COM_TOKEN"))
-#' # Set the connection for the session
-#' set_gitlab_connection(my_gitlab)
 #' 
 #' # Get pipelines and jobs information
 #' gl_pipelines(project = "test-project")

R/connect.R

@@ -17,9 +17,21 @@
 #' 
 #' @examples
 #' \dontrun{
-#' my_gitlab <- gl_connection("http://gitlab.example.com", "123####89")
-#' my_gitlab("projects")
-#' my_gitlab(gl_get_file, "test-project", "README.md", ref = "dev")
+#' # Set the connection for the session
+#' set_gitlab_connection("https://gitlab.com", private_token = Sys.getenv("GITLAB_COM_TOKEN"))
+#' # Get list of projects
+#' gl_list_projects(max_page = 1)
+#' # Unset the connection for the session
+#' unset_gitlab_connection()
+#' 
+#' # Set connection for a specific project
+#' my_project <- gl_project_connection(
+#'   gitlab_url = "https://gitlab.com",
+#'   project = 1234,
+#'   private_token = Sys.getenv("GITLAB_COM_TOKEN")
+#' )
+#' # List files of a project
+#' my_project_list_files <- my_project(gl_list_files, max_page = 1)
 #' }
 #' 
 #' @param gitlab_url URL to the GitLab instance (e.g. `https://gitlab.myserver.com`)

R/gitlab_api.R

@@ -4,9 +4,6 @@
 #' use this function directly too often, but either use {gitlabr}'s convenience wrappers or write your
 #' own. See the {gitlabr} vignette for more information on this.
 #' 
-#' Note: currently GitLab API v3 is supported. Support for GitLab API v4 (for GitLab version >= 9.0) will
-#' be added soon.
-#' 
 #' @param req vector of characters that represents the call (e.g. `c("projects", project_id, "events")`)
 #' @param api_root URL where the GitLab API to request resides (e.g. `https://gitlab.myserver.com/api/v3/`)
 #' @param verb http verb to use for request in form of one of the `httr` functions
@@ -28,19 +25,50 @@
 #' @param argname_verb name of the argument of the verb that fields and information are passed on to
 #' @param ... named parameters to pass on to GitLab API (technically: modifies query parameters of request URL),
 #' may include private_token and all other parameters as documented for the GitLab API
+#' 
 #' @importFrom utils capture.output
 #' @importFrom tibble tibble as_tibble
 #' @export
 #' 
 #' @return the response from the GitLab API, usually as a `tibble` and including all pages
 #' 
+#' @details 
+#' `gitlab()` function allows to use any request of the GitLab API [https://docs.gitlab.com/ce/api/].
+#'
+#'  For instance, the API documentation shows how to create a new project in 
+#'  [https://docs.gitlab.com/ee/api/projects.html#create-project]: 
+#'  
+#'  - The verb is `POST`
+#'  - The request is `projects`
+#'  - Required attributes are `name` or `path` (if `name` not set)
+#'  - `default_branch` is an attribute that can be set if wanted
+#'  
+#'  The corresponding use of `gitlab()` is:  
+#'  
+#'  ```
+#'  gitlab(
+#'    req = "projects",
+#'    verb = httr::POST,
+#'    name = "toto",
+#'    default_branch = "main"
+#'  )
+#'  ```
+#'  
+#' Note: currently GitLab API v4 is supported. GitLab API v3 is no longer supported, but
+#' you can give it a try.
+#' 
 #' @examples \dontrun{
-#' gitlab(req = "projects",
-#'        api_root = "https://gitlab.example.com/api/v4/",
-#'        private_token = "123####89")
-#' gitlab(req = c("projects", 21, "issues"),
-#'        state = "closed",
-#'        gitlab_con = my_gitlab)
+#' # Connect as a fixed user to a GitLab instance
+#' set_gitlab_connection(
+#'   gitlab_url = "https://gitlab.com", 
+#'   private_token = Sys.getenv("GITLAB_COM_TOKEN")
+#' )
+#' 
+#' # Use a simple request
+#' gitlab(req = "projects")
+#' # Use a combined request with extra parameters
+#' gitlab(req = c("projects", 1234, "issues"),
+#'        state = "closed")
 #' }
 gitlab <- function(req,
                    api_root,

R/global_env.R

@@ -17,7 +17,7 @@ assign(GITLAB_CON, NULL, gitlabr_env)
 #' @export
 #' 
 #' @examples \dontrun{
-#' set_gitlab_connection("http://gitlab.example.com", private_token = "123####89")
+#' set_gitlab_connection("https://gitlab.com", private_token = Sys.getenv("GITLAB_COM_TOKEN"))
 #' }
 set_gitlab_connection <- function(gitlab_con = NULL, ...) {
   stopifnot(is.null(gitlab_con) || is.function(gitlab_con))

R/projects_and_repos.R

@@ -4,8 +4,10 @@
 #' @export
 #' 
 #' @examples \dontrun{
-#' my_gitlab <- gl_connection(...) ## fill in login parameters
-#' set_gitlab_connection(my_gitlab)
+#' set_gitlab_connection(
+#'   gitlab_url = "https://gitlab.com", 
+#'   private_token = Sys.getenv("GITLAB_COM_TOKEN")
+#' )
 #' gl_list_projects(max_page = 1)
 #' }
 gl_list_projects <- function(...) {
@@ -173,10 +175,11 @@ gl_get_diff <-  function(project,
 #' @param ... passed on to [gitlab()] API call for "Create project"
 #' @export
 #' @examples \dontrun{
-#' my_gitlab <- gl_connection(
-#'   gitlab_url = "https://gitlab.com",
-#'   private_token = Sys.getenv("GITLAB_TOKEN"))
-#' gl_new_project(name = "toto", gitlab_con = my_gitlab)
+#' set_gitlab_connection(
+#'   gitlab_url = "https://gitlab.com", 
+#'   private_token = Sys.getenv("GITLAB_COM_TOKEN")
+#' )
+#' gl_new_project(name = "toto")
 #' }
 gl_new_project <- function(name,
                            path,

README.Rmd

@@ -56,15 +56,10 @@ library(gitlabr)
 # You can verify your token works
 # Sys.getenv("GITLAB_COM_TOKEN")
 
-# connect as a fixed user to a gitlab instance
-my_gitlab <- gl_connection(
+# connect as a fixed user to a GitLab instance for the session
+set_gitlab_connection(
   gitlab_url = "https://gitlab.com",
   private_token = Sys.getenv("GITLAB_COM_TOKEN"))
-# a function is returned
-# its first argument is the request (name or function), optionally followed by parameters
-
-# Set the connection for the session
-set_gitlab_connection(my_gitlab)
 ```
 
 - Find the list of projects available to you
@@ -115,7 +110,29 @@ gl_list_issues(state = "opened", my_project)
 gl_close_issue(new_feature_issue$iid, project = my_project)$state
 ```
 
-- Unset connection
+### Use additionnal requests
+
+If the API request is not already available in {gitlabr}, function `gitlab()` allows to use any request of the GitLab API [https://docs.gitlab.com/ce/api/].
+
+For instance, the API documentation shows how to create a new project in [https://docs.gitlab.com/ee/api/projects.html#create-project]:
+
+- The verb is `POST`
+- The request is `projects`
+- Required attributes are `name` or `path` (if `name` not set)
+- `default_branch` is an attribute that can be set if wanted
+
+The corresponding use of `gitlab()` is:
+
+```{r, eval=FALSE}
+gitlab(
+  req = "projects",
+    verb = httr::POST,
+    name = "toto",
+    default_branch = "main"
+  )
+```
+
+### Unset connection
 
 ```{r}
 unset_gitlab_connection()

dev/renaming_TODO.md

@@ -1,6 +1,6 @@
 - update vignette
 
-## Update tests
+## Update tests and examples to use set_gitlab_connection()
 
 - [x] branches.R // test_branches.R
   - [x] 'project' first
@@ -10,6 +10,7 @@
   - [x] 'project' first
 - [x] comments // test_comments.R
   - [x] 'project' first
-- [ ] // test_connection.R
+- [x] connect, gitlab_api, global_env // test_connection.R
+  - [x] 'project' first
 
 - [ ] NEWS: project first everywhere meaningful

tests/testthat/helper.R

@@ -19,14 +19,12 @@ test_project_name <- Sys.getenv("GITLABR_TEST_PROJECT_NAME", unset = "testor")
 test_project_id <- Sys.getenv("GITLABR_TEST_PROJECT_ID", unset = "20416969")
 
 # Set GitLab connection for all tests
-my_gitlab <- gl_connection(
+# Set the connection for the session
+set_gitlab_connection(
   gitlab_url = test_url,
   private_token = test_private_token,
   api_version = test_api_version)
 
-# Set the connection for the session
-set_gitlab_connection(my_gitlab)
-
 # Set project connection for all tests
 my_project <- gl_project_connection(
   gitlab_url = test_url,

tests/testthat/test_connection.R

@@ -186,4 +186,7 @@ test_that("set_gl_connection with dots works", {
 unset_gitlab_connection()
 
 # Set back the connection for the session as in helper.R
-set_gitlab_connection(my_gitlab)
+set_gitlab_connection(
+  gitlab_url = test_url,
+  private_token = test_private_token,
+  api_version = test_api_version)

vignettes/projects.Rmd

@@ -22,13 +22,10 @@ library(gitlabr)
 # New project
 ```{r, eval=FALSE}
 # GitLab con
-my_gitlab <- gl_connection(
+set_gitlab_connection(
   gitlab_url = "https://gitlab.com",
   private_token = Sys.getenv("GITLAB_COM_TOKEN"))
 
-# Set the connection for the session
-set_gitlab_connection(my_gitlab)
-
 #' @param name of the new project. The name of the new project.
 #' @param ... Other parameters for project creation
 

vignettes/quick-start-guide-to-gitlabr.Rmd

@@ -31,11 +31,10 @@ usethis::edit_r_environ()
 # You can verify it worked
 Sys.getenv("GITLAB_COM_TOKEN")
 
-# connect as a fixed user to a gitlab instance
-my_gitlab <- gl_connection(gitlab_url = "https://gitlab.com",
+# connect as a fixed user to a GitLab instance
+set_gitlab_connection(gitlab_url = "https://gitlab.com",
                            private_token = Sys.getenv("GITLAB_COM_TOKEN"))
-# Set the connection for the session
-set_gitlab_connection(my_gitlab)
+
 # a function is returned
 # its first argument is the request (name or function), optionally followed by parameters
 
@@ -86,7 +85,7 @@ The core function of the low level interface is `gitlab`, with the help of which
 
 ```{r eval = FALSE}
 gitlab(c("projects", 12, "issues"), 
-       api_root = "https://gitlab.points-of-interest.cc/api/v4",
+       api_root = "https://gitlab.com/api/v4",
        private_token = "XXX", # authentication for API
        verb = httr::GET,  # defaults to GET, but POST, PUT, DELETE can be used likewise
        state = "active") # additional parameters (...) for the query
@@ -95,7 +94,7 @@ gitlab(c("projects", 12, "issues"),
 translates to
 
 ```
-GET https://gitlab.points-of-interest.cc/api/v4/projects/12/issues?state=active&private_token=XXX
+GET https://gitlab.com/api/v4/projects/12/issues?state=active&private_token=XXX
 ```
 
 This way, any request documented in the [GitLab API documentation](https://doc.gitlab.com/ce/api) can be issued from {gitlabr}.
@@ -140,8 +139,8 @@ This way these more specialized functions represent and provide the connection -
 Such specialized functions can be created by the function `gitlab_connection()` and then used exactly as you would use `gitlab()`:
 
 ```{r eval = FALSE}
-my_gitlab <- gl_connection("https://test-gitlab.points-of-interest.cc",
-                           private_token = readLines("secrets/gitlab_token.txt"))
+my_gitlab <- gl_connection("https://gitlab.com",
+                           private_token = Sys.getenv("GITLAB_COM_TOKEN"))
 my_gitlab("projects")
 ```