release: Release 0.7.0 (#308)

Co-authored-by: sorhawell <[email protected]>
Co-authored-by: Etienne Bacher <[email protected]>
Co-authored-by: etiennebacher <[email protected]>

.Rbuildignore

@@ -16,3 +16,6 @@
 ^\.venv$
 ^Makefile$
 ^src/\.cargo$
+^cran-comments\.md$
+^CRAN-SUBMISSION$
+^\.devcontainer$

CRAN-SUBMISSION

@@ -0,0 +1,3 @@
+Version: 0.7.0
+Date: 2023-07-15 22:14:51 UTC
+SHA: 8c2aec5466018d0c51dde9b14c1e6503590e0332

DESCRIPTION

@@ -1,14 +1,17 @@
 Package: polars
-Title: 'Polars' Ported to R
-Version: 0.6.1.9000
+Title: Lightning-Fast 'DataFrame' Library
+Version: 0.7.0
 Depends: R (>= 4.1.0)
 Imports: utils, codetools
 Authors@R:
   c(person("Ritchie", "Vink", , "[email protected]", role = c("aut")),
-    person("Soren", "Welling", , "[email protected]", role = c("aut","cre")))
-Description: 'Polars' is a lightning fast Data Frame library written in Rust.
-  This package allows converting R data to 'Polars' data and vice versa,
-  and enabling fast data processing with 'Polars'.
+    person("Soren", "Welling", , "[email protected]", role = c("aut")),
+    person("Tatsuya", "Shima", , "[email protected]", role = c("aut", "cre")),
+    person("Etienne", "Bacher", , "[email protected]", role = c("ctb")))
+Description: Lightning-fast 'DataFrame' library written in 'Rust'. Convert R data
+  to 'Polars' data and vice versa. Perform fast, lazy, larger-than-memory and
+  optimized data queries. 'Polars' is interoperable with the package 'arrow',
+  as both are based on the 'Apache Arrow' Columnar Format.
 License: MIT + file LICENSE
 Language: en-US
 Encoding: UTF-8

LICENSE

@@ -1,2 +1,2 @@
 YEAR: 2023
-COPYRIGHT HOLDER: rpolars authors
+COPYRIGHT HOLDER: polars authors (polars the R package)

LICENSE.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) 2023 rpolars authors
+Copyright (c) 2023 polars authors (polars the R package)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

NEWS.md

@@ -1,12 +1,11 @@
-# polars (development version)
+# polars 0.7.0
 
 ## BREAKING CHANGES
 
 - Replace the argument `reverse` by `descending` in all sorting functions. This
   is for consistency with the upstream Polars (#291, #293).
 - Bump rust-polars from 2023-04-20 unreleased version to version 0.30.0 released in 2023-05-30 (#289).
     - Rename `concat_lst` to `concat_list`.
-    <!-- TODO: - Rename `arr` to `list`. -->
     - Rename `$str$explode` to `$str$str_explode`.
     - Remove `tz_aware` and `utc` arguments from `str_parse`.
     - in `$date_range`'s the `lazy` argument is now `TRUE` by default.
@@ -38,7 +37,11 @@ for demonstration purposes (#240).
 - `<DataFrame>$glimpse()` is a fast `str()`-like view of a `DataFrame` (#277).
 - `$over()` now accepts a vector of column names (#287).
 - New method `<DataFrame>$describe()` (#268).
-- Cross joining is now possible with `how = "cross"` in `$join()`
+- Cross joining is now possible with `how = "cross"` in `$join()` (#310).
+- Add license info of all rust crates to `LICENSE.note` (#309).
+- With CRAN 0.7.0 release candidate (#308).
+    - New author accredited, SHIMA Tatsuya (@eitsupi).
+    - DESCRIPTION revised.
 
 # polars 0.6.1
 
@@ -139,7 +142,7 @@ Release date: 2023-02-21. Full Changelog: [v0.4.3...v0.4.5](https://github.com/p
 - Customize **extendr** to better support cross Rust-R/R-Rust error handling
   - bump extendr_api by @sorhawell in #44
   - Str even more by @sorhawell in #47
-- **rpolars** is now available for install from [rpolars.r-universe.dev](https://rpolars.r-universe.dev/rpolars#install) @eitsupi
+- **rpolars** is now available for install from [rpolars.r-universe.dev](https://rpolars.r-universe.dev/polars#install) @eitsupi
   - advertise R-universe by @sorhawell in #39
   - Includes reasonably easy pre-compiled installation for arm64-MacBooks
 - All string Expressions available

R/Field.R

@@ -32,12 +32,18 @@ pl$Field = function(name, datatype) {
 #' @examples
 #' print(pl$Field("foo", pl$List(pl$UInt64)))
 print.RField = function(x, ...) {
-  cat("")
   x$print()
   invisible(x)
 }
 
+
+#' @title auto complete $-access into a polars object
+#' @description called by the interactive R session internally
+#' @param x string name of an RField
+#' @param pattern code-stump as string to auto-complete
 #' @export
+#' @inherit .DollarNames.DataFrame return
+#' @keywords internal
 .DollarNames.RField = function(x, pattern = "") {
   get_method_usages(RField, pattern = pattern)
 }

R/after-wrappers.R

@@ -1,8 +1,18 @@
+## after-wrappers.R
+## THIS FILE IS SOURCED IMMEDIATELY AFTER extendr-wrappers.R . THIS FILE EXTENDS THE BEHAVIOUR
+## OF EXTENDR-CLASS-SYSTEM WITH:
+## 1. SEPARATE PRIVATE (.pr$) AND PUBLIC (pl$) METHODS/FUNCTIONS
+## 2. ADD INTERNAL PROFILER, pl$set_polars_options(debug_polars = TRUE)
+## 3. ADD build_debug_print TO DEBUG CLASS CONSTRUCTION DURING PACKAGE BUILDTIME (rarely used)
+## 4. ADD BETTER METHOD LOOKUP ERR MSGS macro_add_syntax_check_to_class(), HELPS END USER
+## 5. ADD OPTION TO FLAG A METHOD TO BEHAVE LIKE A PROPERTY method_as_property()
+
+
 # Build time options
 build_debug_print = FALSE
 
 #' extendr methods into pure functions
-#'
+#' @noRd
 #' @param env environment object output from extendr-wrappers.R classes
 #' @param class_name optional class string, only used for debug printing
 #' Default NULL, will infer class_name automatically
@@ -31,6 +41,7 @@ extendr_method_to_pure_functions = function(env, class_name = NULL) {
 
 #' get private method from Class
 #' @details This method if polars_optenv$debug_polars == TRUE will print what methods are called
+#' @noRd
 #' @export
 #' @keywords internal
 "$.private_polars_env" = function(self, name) {
@@ -50,15 +61,21 @@ extendr_method_to_pure_functions = function(env, class_name = NULL) {
 #' @title polars-API: private calls to rust-polars
 #' @description `.pr`
 #' Original extendr bindings converted into pure functions
+#' @details
+#' .pr gives access to all private methods of package polars. Use at own discretion.
+#' The polars package may introduce breaking changes to any private method in a patch with no
+#' deprecation warning. Most private methods takes `self` as a first argument, the object the
+#' method should be called upon.
 #' @aliases  .pr
 #' @keywords internal api_private
+#' @return not applicable
 #' @export
 #' @examples
 #' # .pr$DataFrame$print() is an external function where self is passed as arg
-#' polars:::.pr$DataFrame$print(self = pl$DataFrame(iris))
-#' @keywords internal
-#' @examples
-#' polars:::print_env(.pr, ".pr the collection of private method calls to rust-polars")
+#' .pr$DataFrame$print(self = pl$DataFrame(iris))
+#'
+#' # show all content of .pr
+#' .pr$print_env(.pr, ".pr the collection of private method calls to rust-polars")
 .pr = new.env(parent = emptyenv())
 .pr$Series = extendr_method_to_pure_functions(Series)
 .pr$DataFrame = extendr_method_to_pure_functions(DataFrame)
@@ -78,17 +95,24 @@ extendr_method_to_pure_functions = function(env, class_name = NULL) {
 .pr$RNullValues = extendr_method_to_pure_functions(RNullValues)
 .pr$RPolarsErr = extendr_method_to_pure_functions(RPolarsErr)
 
-# TODO remove export
 
 
+# add package environment to .pr, this can be used as replacement for :::, where cran does not
+# allow that. Ok use :
+#  - internal documentation (noRd) to show case inner workings of code.
+#  - unit tests, which needs to verify an internal state.
+.pr$env = getNamespace("polars")
+.pr$print_env = print_env
 
-## this macro must be defined now
 
-#' @title add syntax verification to class
+
+##### -----  MACROS used at package build time
+
+#' @title add syntax verification to a class
 #' @include utils.R
 #' @param Class_name string name of env class
 #' @rdname macro_add_syntax_check_to
-#'
+#' @noRd
 #' @keywords internal
 #' @return dollarsign method with syntax verification
 #'
@@ -139,6 +163,7 @@ if (build_debug_print) cat("\n")
 
 #' Give a class method property behavior
 #' @description Internal function, see use in source
+#' @noRd
 #' @param f a function
 #' @param setter bool, if true a property method can be modified by user
 #' @keywords internal
@@ -165,29 +190,61 @@ method_as_property = function(f, setter = FALSE) {
 #' @keywords api
 #' @details If someone do not particularly like the letter combination `pl`, they are free to
 #' bind the environment to another variable name as `simon_says = pl` or even do `attach(pl)`
-#'
+#' @return not applicable
 #' @export
 #' @examples
 #' # how to use polars via `pl`
 #' pl$col("colname")$sum() / pl$lit(42L) # expression ~ chain-method / literal-expression
 #'
-#' # pl inventory
-#' polars:::print_env(pl, "polars public functions")
-#'
-#' # all accessible classes and their public methods
-#' polars:::print_env(
-#'   polars:::pl_pub_class_env,
-#'   "polars public class methods, access via object$method()"
-#' )
+#' # show all public functions, RPolarsDataTypes, classes and methods
+#' pl$show_all_public_functions()
+#' pl$show_all_public_methods()
 pl = new.env(parent = emptyenv())
-
 class(pl) = c("pl_polars_env", "environment")
 
 
+#' show all public functions / objects
+#' @name show_all_public_functions
+#' @description print any object(function, RPolarsDataType) available via `pl$`.
+#' @return NULL
+#' @keywords functions
+#' @examples
+#' pl$show_all_public_functions()
+pl$show_all_public_functions = function() {
+  print_env(pl, "polars public functions via pl$...")
+}
+
+#' show all public methods
+#' @name show_all_public_methods
+#' @description methods are listed by their Class
+#' @param class_names character vector of polars class names to show, Default NULL is all.
+#' @return NULL
+#' @keywords functions
+#' @examples
+#' pl$show_all_public_methods()
+pl$show_all_public_methods = function(class_names = NULL) {
+
+  #subset classes to show
+  show_this_env = if(!is.null(class_names)) {
+    as.environment(mget(class_names, envir = pl_pub_class_env))
+  } else {
+    pl_pub_class_env
+  }
+
+  print_env(
+    show_this_env,
+    paste(
+      paste(class_names, collapse = ", "),
+      "class methods, access via object$method()"
+    )
+  )
+}
 
 #' get public function from pl namespace/env
 #' @details This method if polars_optenv$debug_polars == TRUE will print what methods are called
+#' @return an element from the public namespace `pl` polars. Likely a function or an RPolarsDataType
 #' @export
+#' @noRd
 #' @keywords internal
 "$.pl_polars_env" = function(self, name) {
   # print called private class in debug mode
@@ -218,18 +275,25 @@ pl_pub_class_env = as.environment(mget(pl_class_names, envir = pl_pub_env))
 
 
 #' @title Any polars class object is made of this
+#' @name polars_class_object
 #' @description One SEXP of Rtype: "externalptr" + a class attribute
 #' @keywords api_object
-#'
 #' @details
 #'  - `object$method()` calls are facilitated by a `$.ClassName`- s3method see 'R/after-wrappers.R'
 #'  - Code completion is facilitated by `.DollarNames.ClassName`-s3method see e.g. 'R/dataframe__frame.R'
 #'  - Implementation of property-methods as DataFrame_columns() and syntax checking is an extension to `$.ClassName`
 #'  See function macro_add_syntax_check_to_class().
 #'
 #' @importFrom utils .DollarNames
+#' @return not applicable
 #' @examples
-#' # all a polars object is made of:
+#' # all a polars object is only made of:
 #' some_polars_object = pl$DataFrame(iris)
 #' str(some_polars_object) # External Pointer tagged with a class attribute.
-object = "place_holder"
+#'
+#' # All state is stored on rust side.
+#'
+#' # The single exception from the rule is class "GroupBy", where objects also have
+#' # two private attributes "groupby_input" and "maintain_order".
+#' str(pl$DataFrame(iris)$groupby("Species"))
+NULL

R/autocompletion.R

@@ -1,7 +1,7 @@
 #' Extra polars auto completion
 #' @param activate bool default TRUE, enable chained auto-completion
 #' @name extra_auto_completion
-#' @return NULL
+#' @return invisible NULL
 #'
 #' @details polars always supports auto completion via .DollarNames.
 #' However chained methods like x$a()$b()$? are not supported vi .DollarNames.
@@ -32,12 +32,14 @@ pl$extra_auto_completion = function(activate = TRUE) {
       rc.options("custom.completer" = NULL)
       # function running  base auto complete.
       # It will dump suggestion into mutable .CompletionEnv$comps
-      utils:::.completeToken()
+      .completeToken = utils::getFromNamespace(".completeToken", "utils")
+      .completeToken()
 
       rc.options("custom.completer" = f)
 
       # get line buffer
-      CE = utils:::.CompletionEnv
+      .CompletionEnv = utils::getFromNamespace(".CompletionEnv", "utils")
+      CE = .CompletionEnv
       lb = CE$linebuffer
 
       # skip custom completion if token completion already yielded suggestions.
@@ -51,7 +53,7 @@ pl$extra_auto_completion = function(activate = TRUE) {
       last_char = substr(lb, nchar(lb), nchar(lb))
       if (last_char == "$" && nchar(lb) > 1L) {
         x = eval(parse(text = substr(lb, 1, nchar(lb) - 1)))
-        if (inherits(x, c(polars:::pl_class_names, "method_environment"))) {
+        if (inherits(x, c(pl_class_names, "method_environment"))) {
           your_comps = .DollarNames(x)
           # append your suggestions to the vanilla suggestions/completions
           CE$comps = c(your_comps, CE$comps)