psolymos / clickrup

Interacting with the ClickUp v2 API from R
https://peter.solymos.org/clickrup/
MIT License
18 stars 3 forks source link

Draft data frame interface #4

Closed krlmlr closed 3 years ago

krlmlr commented 3 years ago

How do you feel about returning tibbles instead of lists from GET calls?

Reprex follows.

krlmlr commented 3 years ago

Data frames are more idiomatic to R than deeply nested lists, and allow immediate data manipulation on the results, without complex custom extraction procedures. Using simplifyVector = TRUE together with some very generic massaging of the data returns a structure that is convenient to work with and displays nicely.

This PR also formats ID columns in a way that ensures they are never abbreviated, via the new tibble::char() . We can easily convert e.g. timestamp and duration columns to their appropriate types too.

This is with the current branch.

library(clickrup)
#> clickrup 0.0.3    2021-04-09

cu_options(
    baseurl = "https://private-anon-cfc2f69e11-clickup20.apiary-mock.com/api/v2"
)

teams <- cu_get_teams()
teams
#> # A tibble: 1 x 5
#>   id     name            color   avatar                         members         
#>   <char> <chr>           <chr>   <chr>                          <list>          
#> 1 1234   My ClickUp Team #000000 https://clickup.com/avatar.jpg <tibble [1 × 1]>
teams$members[[1]]
#> # A tibble: 1 x 1
#>   user$id $username $color  $profilePicture               
#>   <char>  <chr>     <chr>   <chr>                         
#> 1 123     John Doe  #000000 https://clickup.com/avatar.jpg

spaces <- cu_get_spaces(teams$id[[1]])
spaces
#> # A tibble: 2 x 6
#>   id     name         private statuses     multiple_assign… features$due_dates$…
#>   <char> <chr>        <lgl>   <list>       <lgl>            <lgl>               
#> 1 790    Updated Spa… FALSE   <tibble [2 … FALSE            FALSE               
#> 2 791    Second Spac… FALSE   <tibble [2 … TRUE             TRUE
spaces$statuses
#> [[1]]
#> # A tibble: 2 x 4
#>   status   type   orderindex color  
#>   <chr>    <chr>       <int> <chr>  
#> 1 to do    open            0 #d3d3d3
#> 2 complete closed          1 #6bc950
#> 
#> [[2]]
#> # A tibble: 2 x 4
#>   status type   orderindex color  
#>   <chr>  <chr>       <int> <chr>  
#> 1 Open   open            0 #d3d3d3
#> 2 Closed closed          1 #6bc950
spaces$features
#> # A tibble: 2 x 9
#>   due_dates$enabled $start_date $remap_due_dates $remap_closed_due_date
#>   <lgl>             <lgl>       <lgl>            <lgl>                 
#> 1 FALSE             FALSE       FALSE            FALSE                 
#> 2 TRUE              FALSE       FALSE            FALSE                 
#> # … with 8 more variables: time_tracking <tibble[,1]>, tags <tibble[,1]>,
#> #   time_estimates <tibble[,1]>, checklists <tibble[,1]>,
#> #   custom_fields <tibble[,1]>, remap_dependencies <tibble[,1]>,
#> #   dependency_warning <tibble[,1]>, portfolios <tibble[,1]>
spaces$features$due_dates
#> # A tibble: 2 x 4
#>   enabled start_date remap_due_dates remap_closed_due_date
#>   <lgl>   <lgl>      <lgl>           <lgl>                
#> 1 FALSE   FALSE      FALSE           FALSE                
#> 2 TRUE    FALSE      FALSE           FALSE

Created on 2021-06-06 by the reprex package (v2.0.0)

krlmlr commented 3 years ago

The jsonlite package implements this conversion out of the box. Converting those lists to data frames "after the fact" appears to be much more difficult than adding simplifyVector = TRUE . Moving forward, I see two options:

What do you think?

psolymos commented 3 years ago

Hi @krlmlr I like the idea of returning data frame / tibble as the default object type where possible. How about adding a global option for this?

krlmlr commented 3 years ago

Thanks! A global option is dangerous because then type stability depends on external factors. For that reason, I would even recommend against using a function argument that converts to a data frame.

To avoid rewriting all the documentation, should we go with a second set of functions, e.g. with a cuf_ prefix for "click-up frame"? I think this would only affect functions that read, currently it seems unclear how this applies to the writing functions.

psolymos commented 3 years ago

I like the cuf_ prefix. Yes, the writing functions would not need this yet.

krlmlr commented 3 years ago

Thanks. Happy to put a little time into it over the next few weeks.

psolymos commented 3 years ago

Thank you @krlmlr for working on this package. I am happy to add you as package author.

This is a good opportunity for me to work on it too (testing mostly) and maybe sending it to CRAN.

krlmlr commented 3 years ago

Closing in favor of #5.