From d6ec8fb5a89b1c678f2e40e15a96a994a6647ab3 Mon Sep 17 00:00:00 2001 From: Magnus Thor Torfason Date: Fri, 11 Apr 2025 15:52:48 +0000 Subject: [PATCH 01/10] Update pkgdown - Configure release/development on development branch --- _pkgdown.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/_pkgdown.yml b/_pkgdown.yml index ec0a740..32d3fa2 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -1,2 +1,7 @@ +url: https://import.rticulate.org/ + template: bootstrap: 5 + +development: + mode: auto From b95fe8a67eba3d8198701d2e142c6a62e82145aa Mon Sep 17 00:00:00 2001 From: Magnus Thor Torfason Date: Fri, 11 Apr 2025 18:14:07 +0000 Subject: [PATCH 02/10] Update README.(R)md - Add links to release/dev documentation --- README.Rmd | 11 ++++++++++- README.md | 10 +++++++++- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/README.Rmd b/README.Rmd index 2c23b6d..ce58b0a 100644 --- a/README.Rmd +++ b/README.Rmd @@ -40,7 +40,7 @@ For more on the motivation behind the package, see [vignette("import")](https://import.rticulate.org/articles/import.html) -## Installation +## Installation and Documentation Install the release version of `import` from CRAN using `pak` or `install.packages()`: @@ -51,6 +51,10 @@ pak::pak("import") install.packages("import") ``` +Documentation for the release version is available on: + +- https://import.rticulate.org/ + Install the development version of `import` from GitHub using `pak` or `devtools`: @@ -60,6 +64,11 @@ pak::pak("rticulate/import") devtools::install_github("rticulate/import") ``` +Documentation for the development version is available on: + +- https://import.rticulate.org/dev/ + + ## Usage ### Importing functions from R packages diff --git a/README.md b/README.md index c316f20..44d852a 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ import::from(Hmisc, impute, nomiss) For more on the motivation behind the package, see [vignette(“import”)](https://import.rticulate.org/articles/import.html) -## Installation +## Installation and Documentation Install the release version of `import` from CRAN using `pak` or `install.packages()`: @@ -53,6 +53,10 @@ pak::pak("import") install.packages("import") ``` +Documentation for the release version is available on: + +- + Install the development version of `import` from GitHub using `pak` or `devtools`: @@ -62,6 +66,10 @@ pak::pak("rticulate/import") devtools::install_github("rticulate/import") ``` +Documentation for the development version is available on: + +- + ## Usage ### Importing functions from R packages From 629fb04c3f2604cb9d970368c78d7305abb82467 Mon Sep 17 00:00:00 2001 From: Magnus Thor Torfason Date: Tue, 7 Oct 2025 09:11:48 +0000 Subject: [PATCH 03/10] Update tests to use full namespace in utils::install.packages() --- tests/test_import/test_from.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_import/test_from.R b/tests/test_import/test_from.R index d13b7d6..d462e62 100644 --- a/tests/test_import/test_from.R +++ b/tests/test_import/test_from.R @@ -198,7 +198,7 @@ test_that("Imports from libraries NOT defined in .libPaths work", { if (!file.exists("packageToTest_0.1.0.tar.gz")) { system("R CMD build packageToTest") } - install.packages("packageToTest_0.1.0.tar.gz", + utils::install.packages("packageToTest_0.1.0.tar.gz", lib = tmp_install_dir, repos = NULL, type = "source", From f9bf6a4da90b62b72b49258e47939d5dbe8d7edf Mon Sep 17 00:00:00 2001 From: Magnus Thor Torfason Date: Tue, 14 Oct 2025 22:07:27 +0000 Subject: [PATCH 04/10] Bump version to 1.3.3.9001 --- DESCRIPTION | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DESCRIPTION b/DESCRIPTION index 15b4f2a..c7e30e9 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: import Type: Package Title: An Import Mechanism for R -Version: 1.3.3 +Version: 1.3.3.9001 Authors@R: c(person(given = "Stefan Milton", family = "Bache", From 177f1d737872aa66a5d0a855775a49ccf0e5c3cc Mon Sep 17 00:00:00 2001 From: Magnus Thor Torfason Date: Tue, 14 Oct 2025 22:07:50 +0000 Subject: [PATCH 05/10] Add tests for import::what() --- tests/test_import/test_from.R | 9 ++++ tests/test_import/test_what.R | 97 +++++++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+) create mode 100644 tests/test_import/test_what.R diff --git a/tests/test_import/test_from.R b/tests/test_import/test_from.R index d462e62..f0990ac 100644 --- a/tests/test_import/test_from.R +++ b/tests/test_import/test_from.R @@ -207,6 +207,15 @@ test_that("Imports from libraries NOT defined in .libPaths work", { expect_true("packageToTest" %in% list.files(tmp_install_dir)) expect_silent(import::from(.from = packageToTest, .library = tmp_install_dir, hello)) expect_equal(hello(), "Hello, world!") + + # We test import::what() from custom path here, to avoid installing the package twice + import::what(packageToTest, .library = tmp_install_dir) |> + expect_contains("hello") + import::what(.from = packageToTest, .library = tmp_install_dir) |> + expect_contains("hello") + + # And then we clean up + cleanup_environment() }) test_that("Functions named `get` in the calling environment do not mask base::get", { diff --git a/tests/test_import/test_what.R b/tests/test_import/test_what.R new file mode 100644 index 0000000..3160b85 --- /dev/null +++ b/tests/test_import/test_what.R @@ -0,0 +1,97 @@ + +# We use the testthat library to evaluate expectations. +# Tests must nevertheless be run outside the standard testthat +# test harness, because import::from changes environments that +# are protected when run inside the harness. See the contents +# of the testthat directory to examine the custom test harness +# that is used instead. These tests can also be run manually. +library(testthat) + +# Printing the directory helps with fixing any problems if tests fail +print(getwd()) + +# Source cleanup script +# (we do not use import::from because then the script would clean itself up) +source("cleanup_environment.R") + +## IMPORTANT: +## Remember to run the cleanup script after each test sequence with: +## > cleanup_environment() + + +## Tests begin + + +test_that("Listing imports from libraries works", { + # (also verifies that nothing is actually imported) + normal_print("OK") |> expect_error() + import::what(knitr) |> expect_contains("normal_print") + normal_print("OK") |> expect_error() +}) + +test_that("Listing imports from modules works", { + # (also verifies that nothing is actually imported) + fun1() |> expect_error() + import::what(module_base.R) |> expect_contains("fun1") + fun1() |> expect_error() +}) + +test_that("Listing imports from subsequent modules works", { + import::what(module_base.R) |> expect_contains("fun1") + import::what(module_subsequent.R) |> expect_contains("fun7") +}) + +test_that("Passing values as characters works", { + char_package <- "knitr" + import::what(char_package, .character_only=TRUE) |> + expect_contains("normal_print") |> + expect_contains("knit_print") +}) + +test_that("Specifying modules by absolute path works", { + abs_module <- file.path(tempdir(),"module_base.R") + file.copy("module_base.R",abs_module) + import::what(abs_module, .character_only=TRUE) |> + expect_contains("fun1") +}) + +test_that("import:::what() throws an error", { + # import::what() relies on `.all`, which is not implemented for private functions + import::what(knitr) |> expect_contains("normal_print") + import:::what(knitr) |> expect_error() +}) + +test_that("Specifying .into/.all/.except throws an error", { + import::what(knitr, .into = "custom_env") |> + expect_error("Unexpected arguments") + import::what(knitr, .into={environment()}) |> + expect_error("Unexpected arguments") + import::what(knitr, .all = TRUE) |> + expect_error("Unexpected arguments") + import::what(knitr, .except = "normal_print") |> + expect_error("Unexpected arguments") +}) + +test_that("Listing imports from libraries NOT defined in .libPaths works", { + # This is tested in test_from.R to avoid installing the package twice, + # since installation takes over a second +}) + +test_that("Script errors are caught and allow manual retry", { + Sys.getenv("SOMECONFIG", NA) |> is.na() |> expect_true() + import::what(module_script_error.R) |> + expect_error("Failed to import") + Sys.setenv("SOMECONFIG"="any") + import::what(module_script_error.R) |> + expect_contains("foo") + Sys.unsetenv("SOMECONFIG") + cleanup_environment() +}) + +## Tests end + + +## IMPORTANT: +## The following line must be printed exactly as is, +## it is used by the custom harness to check if the tests worked: +print("Import tests completed successfully ...") From d1b47a94bd355324b27defba47530dae36acc882 Mon Sep 17 00:00:00 2001 From: Magnus Thor Torfason Date: Tue, 14 Oct 2025 22:09:06 +0000 Subject: [PATCH 06/10] Implement import::what() --- NAMESPACE | 1 + R/what.R | 41 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 R/what.R diff --git a/NAMESPACE b/NAMESPACE index 220751e..74a8382 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -3,3 +3,4 @@ export(from) export(here) export(into) +export(what) diff --git a/R/what.R b/R/what.R new file mode 100644 index 0000000..9c3e2e9 --- /dev/null +++ b/R/what.R @@ -0,0 +1,41 @@ +#' @rdname importfunctions +#' @export +what <- function(.from, ..., + .library = .libPaths()[1L], .directory=".", + .chdir = TRUE, .character_only = FALSE, .S3 = FALSE) +{ + # Capture the call and check that it is valid. + cl <- match.call() + if (!identical(cl[[1L]], call( "::", quote(import), quote(what)))) + stop("Use `import::what()`when listing objects available for import", + call. = FALSE) + + # Ensure the needed arguments are provided. + if (missing(.from)) + stop("Argument `.from` must be specified.", call. = FALSE) + + # ... is included to prevent unnamed arguments apart from `.from`, + # but including anything there is an error. + dots <- as.list(substitute(list(...)))[-1L] + if (length(dots) > 0L) { + stop("Unexpected arguments passed via `...`") + } + + # Create cl which captures the call + cl <- match.call() + + # If no symbols were supplied in `...`, list everything + dots <- as.list(substitute(list(...)))[-1L] + if (length(dots) == 0L) cl[[".all"]] <- TRUE + + # Rewrite the call to import::from syntax and evaluate in new frame. + tmp_env <- new.env(parent = emptyenv()) + cl[[1L]][[3L]] <- quote(from) + cl[[".into"]] <- quote(tmp_env) # import into our temporary env + + # Evaluate in an environment where `tmp_env` is bound, with the parent frame + # as enclosure. This preserves parent lookup while exposing `tmp_env`. + eval(cl, envir = list2env(list(tmp_env = tmp_env), parent = parent.frame())) + + ls(tmp_env) +} From 9a22495d099bfb7d428eff1da07f6d72da940632 Mon Sep 17 00:00:00 2001 From: Magnus Thor Torfason Date: Tue, 14 Oct 2025 22:09:53 +0000 Subject: [PATCH 07/10] Document import::what() --- NEWS.md | 10 ++++++++++ R/from.R | 29 +++++++++++++++++++---------- README.Rmd | 32 +++++++++++++++++++++----------- README.md | 34 ++++++++++++++++++++++------------ man/importfunctions.Rd | 40 +++++++++++++++++++++++++++++----------- 5 files changed, 101 insertions(+), 44 deletions(-) diff --git a/NEWS.md b/NEWS.md index 8791e03..8e8ed0b 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,14 @@ +Version 1.3.3.9001 +============= + +* New function, import::what(), which lists objects available for import from + a given package or module. + +* Documentation links now point both to release and dev documentation. + + + Version 1.3.3 ============= diff --git a/R/from.R b/R/from.R index 577d974..effd78c 100644 --- a/R/from.R +++ b/R/from.R @@ -1,16 +1,23 @@ #' Import Objects From a Package. #' -#' The `import::from` and `import::into` functions provide an alternative way to -#' import objects (e.g. functions) from packages. It is sometimes preferred over -#' using `library` (or `require`) which will import all objects exported by the -#' package. The benefit over `obj <- pkg::obj` is that the imported objects will -#' (by default) be placed in a separate entry in the search path (which can be -#' specified), rather in the global/current environment. Also, it is a more -#' succinct way of importing several objects. Note that the two functions are -#' symmetric, and usage is a matter of preference and whether specifying the -#' `.into` argument is desired. The function `import::here` imports into the -#' current environment. +#' @description +#' The `import::from()`, `import::into()`, and `import::here()` functions +#' provide an alternative way to import objects (e.g. functions) from packages +#' or modules (see below). It is sometimes preferred over using `library` (or +#' `require`) which will import all objects exported by the package. The benefit +#' over `obj <- pkg::obj` is that the imported objects will (by default) be +#' placed in a separate entry in the search path (which can be specified), +#' rather in the global/current environment. Also, it is a more succinct way of +#' importing several objects. #' +#' `import::from()` and `import::into()` are symmetric, and usage is a matter of +#' preference and whether specifying the `.into` argument is desired. +#' `import::here()` is a shorthand that always imports into the current +#' environment, and `import::what()` provides a way to quickly list +#' all objects in a package or module that are available for import by the other +#' functions. +#' +#' @details #' The function arguments can be quoted or unquoted as with e.g. `library`. In #' any case, the character representation is used when unquoted arguments are #' provided (and not the value of objects with matching names). The period in @@ -89,6 +96,8 @@ #' @examples #' import::from(parallel, makeCluster, parLapply) #' import::into("imports:parallel", makeCluster, parLapply, .from = parallel) +#' import::here(parallel, detectCores) +#' import::what(parallel) #' #' @seealso #' Helpful links: diff --git a/README.Rmd b/README.Rmd index c32a7d7..b9ff07b 100644 --- a/README.Rmd +++ b/README.Rmd @@ -36,9 +36,6 @@ import those functions only: import::from(Hmisc, impute, nomiss) ``` -For more on the motivation behind the package, see -[vignette("import")](https://rticulate.github.io/import/articles/import.html) - ## Installation and Documentation @@ -50,23 +47,32 @@ pak::pak("import") # or install.packages("import") ``` +Documentation (for the main branch, which should match the CRAN release) +is available on: + +- https://rticulate.github.io/import/ -Documentation for the release version is available on: -- https://import.rticulate.org/ +### Development Versions -Install the development version of `import` from GitHub using `pak` or -`devtools`: +Install the development version of `import` from GitHub using `pak` (or +`devtools` if you prefer: ```R +# The main branch typically matches the CRAN release pak::pak("rticulate/import") - # or + +# New features are developed on the dev branch +pak::pak("rticulate/import@dev") + +# Or you can use devtools ... devtools::install_github("rticulate/import") +devtools::install_github("rticulate/import@dev") ``` Documentation for the development version is available on: -- https://import.rticulate.org/dev/ +- https://rticulate.github.io/import/dev/ ## Usage @@ -74,9 +80,11 @@ Documentation for the development version is available on: ### Importing functions from R packages The most basic use case is to import a few functions from package (here the -`psych` package): +`psych` package). We start by using `import::what()` to list available +functions. ```R +import::what(psych) |> head() import::from(psych, geometric.mean, harmonic.mean) geometric.mean(trees$Volume) ``` @@ -118,9 +126,11 @@ The `import` package allows R files to be used as "modules" from which functions are loaded. For example, the file [sequence_module.R](https://raw.githubusercontent.com/rticulate/import/master/man/examples/sequence_module.R) contains several functions calculating terms of mathematical sequences. It is -possible to import from such files, just as one imports from packages: +possible to import from such files, just as one imports from packages. Again, +we start by using `import::what()` to check what is available in the module: ```R +import::what(sequence_module.R) import::from(sequence_module.R, fibonacci, square, triangular) ``` diff --git a/README.md b/README.md index 7151b04..dca9267 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![CRAN status](https://www.r-pkg.org/badges/version/import)](https://CRAN.R-project.org/package=import) [![CRAN status -shields](https://img.shields.io/badge/Git-1.3.3-success)](https://github.com/rticulate/import) +shields](https://img.shields.io/badge/Git-1.3.3.9001-success)](https://github.com/rticulate/import) [![R build status](https://github.com/rticulate/import/workflows/R-CMD-check/badge.svg)](https://github.com/rticulate/import/actions) @@ -39,9 +39,6 @@ and the `nomiss()` functions, can import those functions only: import::from(Hmisc, impute, nomiss) ``` -For more on the motivation behind the package, see -[vignette(“import”)](https://rticulate.github.io/import/articles/import.html) - ## Installation and Documentation Install the release version of `import` from CRAN using `pak` or @@ -53,31 +50,42 @@ pak::pak("import") install.packages("import") ``` -Documentation for the release version is available on: +Documentation (for the main branch, which should match the CRAN release) +is available on: + +- -- +### Development Versions -Install the development version of `import` from GitHub using `pak` or -`devtools`: +Install the development version of `import` from GitHub using `pak` (or +`devtools` if you prefer: ``` r +# The main branch typically matches the CRAN release pak::pak("rticulate/import") - # or + +# New features are developed on the dev branch +pak::pak("rticulate/import@dev") + +# Or you can use devtools ... devtools::install_github("rticulate/import") +devtools::install_github("rticulate/import@dev") ``` Documentation for the development version is available on: -- +- ## Usage ### Importing functions from R packages The most basic use case is to import a few functions from package (here -the `psych` package): +the `psych` package). We start by using `import::what()` to list +available functions. ``` r +import::what(psych) |> head() import::from(psych, geometric.mean, harmonic.mean) geometric.mean(trees$Volume) ``` @@ -122,9 +130,11 @@ functions are loaded. For example, the file [sequence_module.R](https://raw.githubusercontent.com/rticulate/import/master/man/examples/sequence_module.R) contains several functions calculating terms of mathematical sequences. It is possible to import from such files, just as one imports from -packages: +packages. Again, we start by using `import::what()` to check what is +available in the module: ``` r +import::what(sequence_module.R) import::from(sequence_module.R, fibonacci, square, triangular) ``` diff --git a/man/importfunctions.Rd b/man/importfunctions.Rd index 7eeb678..132d4d9 100644 --- a/man/importfunctions.Rd +++ b/man/importfunctions.Rd @@ -1,9 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/from.R, R/here.R, R/into.R +% Please edit documentation in R/from.R, R/here.R, R/into.R, R/what.R \name{from} \alias{from} \alias{here} \alias{into} +\alias{what} \title{Import Objects From a Package.} \usage{ from( @@ -43,6 +44,16 @@ into( .character_only = FALSE, .S3 = FALSE ) + +what( + .from, + ..., + .library = .libPaths()[1L], + .directory = ".", + .chdir = TRUE, + .character_only = FALSE, + .S3 = FALSE +) } \arguments{ \item{.from}{The package from which to import.} @@ -94,16 +105,21 @@ future to improve the feature.}} a reference to the environment containing the imported objects. } \description{ -The \code{import::from} and \code{import::into} functions provide an alternative way to -import objects (e.g. functions) from packages. It is sometimes preferred over -using \code{library} (or \code{require}) which will import all objects exported by the -package. The benefit over \code{obj <- pkg::obj} is that the imported objects will -(by default) be placed in a separate entry in the search path (which can be -specified), rather in the global/current environment. Also, it is a more -succinct way of importing several objects. Note that the two functions are -symmetric, and usage is a matter of preference and whether specifying the -\code{.into} argument is desired. The function \code{import::here} imports into the -current environment. +The \code{import::from()}, \code{import::into()}, and \code{import::here()} functions +provide an alternative way to import objects (e.g. functions) from packages +or modules (see below). It is sometimes preferred over using \code{library} (or +\code{require}) which will import all objects exported by the package. The benefit +over \code{obj <- pkg::obj} is that the imported objects will (by default) be +placed in a separate entry in the search path (which can be specified), +rather in the global/current environment. Also, it is a more succinct way of +importing several objects. + +\code{import::from()} and \code{import::into()} are symmetric, and usage is a matter of +preference and whether specifying the \code{.into} argument is desired. +\code{import::here()} is a shorthand that always imports into the current +environment, and \code{import::what()} provides a way to quickly list +all objects in a package or module that are available for import by the other +functions. } \details{ The function arguments can be quoted or unquoted as with e.g. \code{library}. In @@ -147,6 +163,8 @@ is irrelevant. \examples{ import::from(parallel, makeCluster, parLapply) import::into("imports:parallel", makeCluster, parLapply, .from = parallel) +import::here(parallel, detectCores) +import::what(parallel) } \seealso{ From 8fe31103d5a962749e74fe19fdafa805448e548a Mon Sep 17 00:00:00 2001 From: Magnus Thor Torfason Date: Tue, 14 Oct 2025 22:15:23 +0000 Subject: [PATCH 08/10] Bump version and configure pkgdown.yaml to build on dev push --- .github/workflows/pkgdown.yaml | 2 +- DESCRIPTION | 2 +- README.Rmd | 7 +------ README.md | 9 ++------- 4 files changed, 5 insertions(+), 15 deletions(-) diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 921e962..7a159c4 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -1,6 +1,6 @@ on: push: - branches: [main, docs, x/docs] + branches: [main, dev, docs, x/docs] name: pkgdown diff --git a/DESCRIPTION b/DESCRIPTION index c7e30e9..f9cc34a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: import Type: Package Title: An Import Mechanism for R -Version: 1.3.3.9001 +Version: 1.3.3.9002 Authors@R: c(person(given = "Stefan Milton", family = "Bache", diff --git a/README.Rmd b/README.Rmd index b9ff07b..67926d6 100644 --- a/README.Rmd +++ b/README.Rmd @@ -55,8 +55,7 @@ is available on: ### Development Versions -Install the development version of `import` from GitHub using `pak` (or -`devtools` if you prefer: +Install the development version of `import` from GitHub using `pak`: ```R # The main branch typically matches the CRAN release @@ -64,10 +63,6 @@ pak::pak("rticulate/import") # New features are developed on the dev branch pak::pak("rticulate/import@dev") - -# Or you can use devtools ... -devtools::install_github("rticulate/import") -devtools::install_github("rticulate/import@dev") ``` Documentation for the development version is available on: diff --git a/README.md b/README.md index dca9267..7cce89e 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![CRAN status](https://www.r-pkg.org/badges/version/import)](https://CRAN.R-project.org/package=import) [![CRAN status -shields](https://img.shields.io/badge/Git-1.3.3.9001-success)](https://github.com/rticulate/import) +shields](https://img.shields.io/badge/Git-1.3.3.9002-success)](https://github.com/rticulate/import) [![R build status](https://github.com/rticulate/import/workflows/R-CMD-check/badge.svg)](https://github.com/rticulate/import/actions) @@ -57,8 +57,7 @@ is available on: ### Development Versions -Install the development version of `import` from GitHub using `pak` (or -`devtools` if you prefer: +Install the development version of `import` from GitHub using `pak`: ``` r # The main branch typically matches the CRAN release @@ -66,10 +65,6 @@ pak::pak("rticulate/import") # New features are developed on the dev branch pak::pak("rticulate/import@dev") - -# Or you can use devtools ... -devtools::install_github("rticulate/import") -devtools::install_github("rticulate/import@dev") ``` Documentation for the development version is available on: From b0138b6438cfddbd5cb950a4964017b2f2cd3366 Mon Sep 17 00:00:00 2001 From: Magnus Thor Torfason Date: Sun, 19 Oct 2025 10:42:58 +0000 Subject: [PATCH 09/10] Add import::what() to vignette and review overall documentation --- NEWS.md | 4 +- README.Rmd | 24 ++-- README.md | 25 ++-- vignettes/import.Rmd | 267 ++++++++++++++++++++++++++----------------- 4 files changed, 193 insertions(+), 127 deletions(-) diff --git a/NEWS.md b/NEWS.md index 8e8ed0b..2795d4f 100644 --- a/NEWS.md +++ b/NEWS.md @@ -5,7 +5,9 @@ Version 1.3.3.9001 * New function, import::what(), which lists objects available for import from a given package or module. -* Documentation links now point both to release and dev documentation. +* Documentation links now point both to release and development documentation. + +* Other minor documentation improvements. diff --git a/README.Rmd b/README.Rmd index 67926d6..8d0f5d3 100644 --- a/README.Rmd +++ b/README.Rmd @@ -22,8 +22,8 @@ using the help (`?import::from`). The typical way of using functionality exposed by a package in R scripts is to load (and attach) the entire package with `library()` (or `require()`). This can -have the **undesirable effect of masking objects** in the user's search path and -can also make it difficult and **confusing to identify** what functionality +have the undesirable effect of masking objects in the user's search path and +can also make it difficult and confusing to identify what functionality comes from which package when using several `library` statements. The `import` package provides a simple alternative, allowing the user specify in @@ -36,7 +36,6 @@ import those functions only: import::from(Hmisc, impute, nomiss) ``` - ## Installation and Documentation Install the release version of `import` from CRAN using `pak` or @@ -47,15 +46,17 @@ pak::pak("import") # or install.packages("import") ``` -Documentation (for the main branch, which should match the CRAN release) -is available on: + +A documentation site is available on GitHub. For the `main` branch, which +usually matches the CRAN release, the link is: - https://rticulate.github.io/import/ -### Development Versions +### Installing from GitHub -Install the development version of `import` from GitHub using `pak`: +Install the either the `main` (release) or the `dev` (development) branch of +`import` from GitHub using `pak`: ```R # The main branch typically matches the CRAN release @@ -65,7 +66,7 @@ pak::pak("rticulate/import") pak::pak("rticulate/import@dev") ``` -Documentation for the development version is available on: +Documentation for the `dev` branch is available on: - https://rticulate.github.io/import/dev/ @@ -74,9 +75,9 @@ Documentation for the development version is available on: ### Importing functions from R packages -The most basic use case is to import a few functions from package (here the -`psych` package). We start by using `import::what()` to list available -functions. +The most basic use case is to import a few functions from package using +`import::from()`. Here we import from the `psych` package. We start by using +`import::what()` to list available functions. ```R import::what(psych) |> head() @@ -115,6 +116,7 @@ These and other examples are discussed in more detail in the [Importing from Packages](https://rticulate.github.io/import/articles/import.html#importing-from-packages) section of the package vignette. + ### Importing Functions from "Module" Scripts The `import` package allows R files to be used as "modules" from which functions diff --git a/README.md b/README.md index 7cce89e..a1ae70f 100644 --- a/README.md +++ b/README.md @@ -24,10 +24,10 @@ or using the help (`?import::from`). The typical way of using functionality exposed by a package in R scripts is to load (and attach) the entire package with `library()` (or -`require()`). This can have the **undesirable effect of masking -objects** in the user’s search path and can also make it difficult and -**confusing to identify** what functionality comes from which package -when using several `library` statements. +`require()`). This can have the undesirable effect of masking objects in +the user’s search path and can also make it difficult and confusing to +identify what functionality comes from which package when using several +`library` statements. The `import` package provides a simple alternative, allowing the user specify in a concise way exactly which objects. For example, the `Hmisc` @@ -50,14 +50,15 @@ pak::pak("import") install.packages("import") ``` -Documentation (for the main branch, which should match the CRAN release) -is available on: +A documentation site is available on GitHub. For the `main` branch, +which usually matches the CRAN release, the link is: - -### Development Versions +### Installing from GitHub -Install the development version of `import` from GitHub using `pak`: +Install the either the `main` (release) or the `dev` (development) +branch of `import` from GitHub using `pak`: ``` r # The main branch typically matches the CRAN release @@ -67,7 +68,7 @@ pak::pak("rticulate/import") pak::pak("rticulate/import@dev") ``` -Documentation for the development version is available on: +Documentation for the `dev` branch is available on: - @@ -75,9 +76,9 @@ Documentation for the development version is available on: ### Importing functions from R packages -The most basic use case is to import a few functions from package (here -the `psych` package). We start by using `import::what()` to list -available functions. +The most basic use case is to import a few functions from package using +`import::from()`. Here we import from the `psych` package. We start by +using `import::what()` to list available functions. ``` r import::what(psych) |> head() diff --git a/vignettes/import.Rmd b/vignettes/import.Rmd index c1adcaf..613adb1 100644 --- a/vignettes/import.Rmd +++ b/vignettes/import.Rmd @@ -1,32 +1,32 @@ --- title: "The import package" -output: +output: rmarkdown::html_vignette: toc: true vignette: > %\VignetteIndexEntry{The import package} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} -editor_options: +editor_options: chunk_output_type: console --- -* This version: May, 2022 +* This version: October, 2025 * Latest version at: https://rticulate.github.io/import/articles/import.html * A briefer intro at: https://rticulate.github.io/import/ -# Introduction +# Introduction {#intro} One of the most important aspects of the R ecosystem is the ease with which extensions and new features can be developed and distributed in the form of *packages.* The main distribution channel is the *Comprehensive R Archive Network*, from which packages can be installed directly from R. Another popular option is using GitHub repositories from which packages can -also be painlessly installed, e.g. using `install_github` from the -`devtools` package. +also be painlessly installed, e.g. using `install_github` from the +`devtools` package. -The `import` package provides an alternative approach to using external -functionality in R scripts; first however, it is useful to describe the standard +The `import` package provides an alternative approach to using external +functionality in R scripts; first however, it is useful to describe the standard approach to clarify how `import` may serve as improvement. The most common way to include the functionality provided by a package is to use the `library` function: @@ -35,7 +35,7 @@ the `library` function: library(PackageA) library(PackageB) -value1 <- function_a(...) # Supposedly this comes from PackageA, +value1 <- function_a(...) # Supposedly this comes from PackageA, value2 <- function_b(...) # and this from PackageB, but who knows?! ... ``` @@ -43,31 +43,31 @@ value2 <- function_b(...) # and this from PackageB, but who knows?! In some situations this is fine; however there are some subtle shortcomings: 1. Packages are *attached* and *all* of their exported objects are exposed, -2. When using more packages this way, the *order* in which they are attached +2. When using more packages this way, the *order* in which they are attached can be important, 3. It quickly becomes *unclear* to the reader of a script which package certain functionality comes from, and -4. the terms "library" and "package" are often used incorrectly +4. the terms "library" and "package" are often used incorrectly (although a minor point, it seems to confuse somewhat). The problem with (1) is that the search path is populated with more objects than are needed and it is not immediately clear whether name clashes will occur. Problem (2) refers to the case where packages export different objects with the same names, say if `function_b` is exported in both -`PackageA` and `PackageB` above. In this case the name will -point to the object from the package attached *last*. The earlier exposed +`PackageA` and `PackageB` above. In this case the name will +point to the object from the package attached *last*. The earlier exposed objects are said to *masked*. Even if this is not a problem when *writing* the script, an update of packages may cause this problem -later on when *executing* the script; and tracking down the resulting -errors may be tough and time consuming. Problem (3) may appear unimportant, +later on when *executing* the script; and tracking down the resulting +errors may be tough and time consuming. Problem (3) may appear unimportant, but it is not to be underestimated. Code snippets are very commonly shared -and spending time figuring out where functionality comes from is not +and spending time figuring out where functionality comes from is not a very satisfying nor value-adding activity. -It is possible to unambiguously specify where a function comes from by -prefixing it with `::` every time it used, but this is often +It is possible to unambiguously specify where a function comes from by +prefixing it with `::` every time it used, but this is often overly verbose and does not provide an easily accessible overview of what -external functionality is used in a script. One may also import single +external functionality is used in a script. One may also import single exported objects, one at a time, using the (double) "colon syntax", ```{r, eval = FALSE} @@ -75,23 +75,23 @@ function_a <- PackageA::function_a function_b <- PackageB::function_b ``` -The downside of this approach is that the object is **placed +The downside of this approach is that the object is **placed in the user's global work space**, rather than being encapsulated somewhere else -in the search path (when using `library` to load `pkg`, a namespace `package:pkg` -will be attached in the search path which will contain the exported functions -from `pkg`). Another minor point is that one can **only import one object at a +in the search path (when using `library` to load `pkg`, a namespace `package:pkg` +will be attached in the search path which will contain the exported functions +from `pkg`). Another minor point is that one can **only import one object at a time** using this approach. While packages form the backbone of code distribution, another option comes in the form of *scripts*, but these are usually task specific and not -commonly used to "bundle" functionality for use in *other* scripts. In -particular, when `source` is used to include contents from one script in +commonly used to "bundle" functionality for use in *other* scripts. In +particular, when `source` is used to include contents from one script in another, once again *all* objects produced by the script will be "exposed" -and may "over populate" the working environment, masking other objects, -if not only producing some mental clutter. Scope management is therefore not too +and may "over populate" the working environment, masking other objects, +if not only producing some mental clutter. Scope management is therefore not too comfortable when splitting functionality across files in a modular way. -The `import` package sets out to improve the way external functionality +The `import` package sets out to improve the way external functionality is included in your code by alleviating some of the concerns raised above by providing an expressive way of importing object from both packages and scripts. The latter provides a bridge between the *package* approach to @@ -99,59 +99,68 @@ distribution and simple stand-alone script files. This allows for the use of scr as *modules*, a collection of related object definitions, each of which may be used at different places without exposing more than necessary. -The package is inspired in part by Python's +The package is inspired in part by Python's `from some_module import some_function` syntax, and solves -the two issues raised above. It is also similar to `roxygen2`s -`@importFrom package function1 function2` for packages. While `import` will +the two issues raised above. It is also similar to `roxygen2`s +`@importFrom package function1 function2` for packages. While `import` will also work for package development, the intended use case is when using external functions `R` scripts. In addition to being able to import objects from packages, `import` also allows you to import objects from other *scripts* (i.e. a kind of *module*). This allows a simple way to distribute and use functionality without the need to write -a full package. One example is a Shiny app, where one can place definitions -in a script and import only the needed objects where they are used. This +a full package. One example is a Shiny app, where one can place definitions +in a script and import only the needed objects where they are used. This avoids workspace clutter and name clashes. For more details see below. -# Basic Usage +# Basic usage {#basic} -## Importing from Packages +## Importing from packages {#package} -The most basic use case is to import a few functions from package +The most basic use case is to import a few functions from package (here the `psych` package): ```{r, eval=FALSE} +import::what(psych) |> grepv(pattern = "mean") +#> [1] "circadian.mean" "circular.mean" "geometric.mean" "harmonic.mean" +#> [5] "winsor.mean" "winsor.means" import::from(psych, geometric.mean, harmonic.mean) geometric.mean(trees$Volume) +#> [1] 26.38331 +harmonic.mean(trees$Volume) +#> [1] 23.15689 ``` -The imported objects are placed in a separate entity in the search path which by -default is named "imports". It is therefore also easy to get rid of them again -with `detach("imports")`. The main point is that it is **clear which functions -will be used and where they come from**. It's noteworthy that there is nothing -special going on: the `import::from` function is only a convenient wrapper -around `getExportedValue` (as is `::` itself) and `assign`. +The imported objects are placed in a separate entity in the search path which by +default is named "imports". It is therefore also easy to get rid of them again +with `detach("imports")`. The main point is that it is **clear which functions +will be used and where they come from**. It's noteworthy that there is nothing +special going on: the `import::from` function is only a convenient wrapper +around `getExportedValue` (as is `::` itself) and `assign`. -The `import` package itself should not to be attached +The `import` package itself should not to be attached (don't include it via `library`, you will get a warning). Rather, it is designed -to be expressive when using the colon syntax. To import non-exported objects +to be expressive when using the colon syntax. To import non-exported objects one must use triple-colon syntax: `import:::from(pkg, obj)`. If any of the `import` functions are called regularly, i.e. without preceding -`import::` or `import:::`, an error is raised. If `import` is attached, a +`import::` or `import:::`, an error is raised. If `import` is attached, a startup message will inform that `import` *should not* be attached. -If one of the function names conflicts with an existing function (such as `filter` +If one of the function names conflicts with an existing function (such as `filter` from the `dplyr` package) it is simple to rename it: ```{r, eval=FALSE} import::from(dplyr, select, arrange, keep_when = filter) keep_when(mtcars, hp>250) +#> mpg cyl disp hp drat wt qsec vs am gear carb +#> Ford Pantera L 15.8 8 351 264 4.22 3.17 14.5 0 1 5 4 +#> Maserati Bora 15.0 8 301 335 3.54 3.57 14.6 0 1 5 8 ``` This does pretty much what it says: three functions are imported from `dplyr`, two of which will keep their original name, and one which is renamed, e.g. to -avoid name clash with `stats::filter`. +avoid name clash with `stats::filter`. You can use `.all=TRUE` to import all functions from a package, but rename one of them: @@ -165,7 +174,7 @@ To omit a function from the import, use `.except` (which takes a character vecto import::from(dplyr, .except=c("filter", "lag")) ``` -Note that `import` tries to be smart about this and assumes that if you are using the +Note that `import` tries to be smart about this and assumes that if you are using the `.except` parameter, you probably want to import everything you are _not_ explicitly omitting, and sets the `.all` parameter to `TRUE`. You can override this in exceptional cases, but you seldom need to. @@ -179,14 +188,14 @@ import::from(tidyr, unnest) import::from(broom, tidy) ready_data <- - starwars %>% - keep_when(mass < 100) %>% + starwars %>% + keep_when(mass < 100) %>% select(name, height, mass, films) %>% unnest(films) %>% mutate( log_mass = log(mass), films=factor(films)) -linear_model <- - lm(log_mass ~ height + films, data = ready_data) %>% +linear_model <- + lm(log_mass ~ height + films, data = ready_data) %>% tidy ``` @@ -197,37 +206,40 @@ exposes a function `tidy` after an update, as `import` is *explicit* about importing. It also shows that one can import multiple objects in a single -statement, and even rename objects if desired; for example, in the above +statement, and even rename objects if desired; for example, in the above one can imagine that `filter` from `stats` is needed later on, and so -`dplyr`'s `filter` is renamed to avoid confusion. Sometimes, it is +`dplyr`'s `filter` is renamed to avoid confusion. Sometimes, it is not at all clear what purpose a package has; e.g. the name `magrittr` does -not immediately reveal that it's main purpose is to provide the pipe +not immediately reveal that it's main purpose is to provide the pipe operator, `%>%`. -### Importing Functions from "Module" Scripts {#module} - +## Importing from "module" scripts {#module} The `import` package allows for importing objects defined in script files, which we will here refer to as "modules". -The module will be fully evaluated by `import` when an import is requested, -after which objects such as functions or data can be imported. +The module will be fully evaluated by `import` when an import is requested, +after which objects such as functions or data can be imported. Such modules should be side-effect free, but this is -not enforced. +not enforced. Attachments are detached (e.g. packages attached by `library`) -but loaded namespaces remain loaded. This means that *values* created -by functions in an attached namespace will work with `import`, but +but loaded namespaces remain loaded. This means that *values* created +by functions in an attached namespace will work with `import`, but functions to be exported *should not* rely on such functions (use function importing in the modules instead). -For example, the file -[sequence_module.R](https://raw.githubusercontent.com/rticulate/import/master/man/examples/sequence_module.R) -contains several functions calculating terms of mathematical sequences. +For example, the file +[sequence_module.R](https://raw.githubusercontent.com/rticulate/import/master/man/examples/sequence_module.R) +contains several functions calculating terms of mathematical sequences. It is possible to import from such files, just as one imports from packages: ```{r, eval=FALSE} +import::what(sequence_module.R) +#> [1] "fibonacci" "square" "triangular" import::from(sequence_module.R, fibonacci, square, triangular) +fibonacci(7) +#> [1] 13 ``` Renaming, the `.all`, and the `.except` parameters work in the same way as for packages: @@ -237,24 +249,24 @@ import::from(sequence_module.R, fib=fibonacci, .except="square") ``` If a module is modified, `import` will -realize this and reload the script if further imports are executed or -re-executed; otherwise additional imports will not cause the script to be -reloaded for efficiency. As the script is loaded in its own environment +realize this and reload the script if further imports are executed or +re-executed; otherwise additional imports will not cause the script to be +reloaded for efficiency. As the script is loaded in its own environment (maintained by `import`) dependencies are kept (except those exposed through attachment), as the following small example shows. **Contents of "[some_module.R](https://raw.githubusercontent.com/rticulate/import/master/man/examples/some_module.R)":** ```{r, eval=FALSE} -## Do not use library() inside a module. This results in a warning, +## Do not use library() inside a module. This results in a warning, ## and functions relying on ggplot2 will not work. #library(ggplot2) -## This is also not recommended, because it is not clear wether recursively +## This is also not recommended, because it is not clear wether recursively ## imported functions should be available after the module is imported -#import::here(qplot, .from = ggplot2) +#import::from(qplot, .from = ggplot2) ## This is the recommended way to recursively import functions on which -## module functions depend. The qplot function will be available to +## module functions depend. The qplot function will be available to ## module functions, but will not itself be available after import import::here(qplot, .from = ggplot2) @@ -294,8 +306,8 @@ plot_it() ``` Suppose that you have some related functionality that you wish to bundle, and -that authoring a full package seems excessive or inappropriate -for the specific task, for example bundling related user interface components for a `shiny` +that authoring a full package seems excessive or inappropriate +for the specific task, for example bundling related user interface components for a `shiny` application. One option with `import` is to author a module (script), say as outlined below: @@ -303,14 +315,14 @@ below: # File: foo.R # Desc: Functionality related to foos. # Imports from other_resources.R -# When recursively importing from another module or package for use by -# your module functions, you should always use import::here() rather +# When recursively importing from another module or package for use by +# your module functions, you should always use import::here() rather # than import::from() or library() import::here(fun_a, fun_b, .from = "other_resources.R") internal_fun <- function(...) ... -fun_c <- function(...) +fun_c <- function(...) { ... a <- fun_a(...) @@ -325,31 +337,80 @@ Then in another file we need `fun_c`: ```{r, eval = FALSE} # File: bar.R -# Desc: Functionality related to bars. +# Desc: Functionality related to bars. # Imports from foo.R import::here(fun_c, .from = "foo.R") ... ``` -In the above, *only* `fun_c` is visible inside `bar.R`. The -functions on which it depends exist, but are not exposed. -Also, note that imported scripts may themselves import. +In the above, *only* `fun_c` is visible inside `bar.R`. The +functions on which it depends exist, but are not exposed. +Also, note that imported scripts may themselves import. Since the desired effect of `import::from` inside a module script -is ambiguous, this results in a warning (but the functions will +is ambiguous, this results in a warning (but the functions will still be imported into the local environment of the script, just -as with `import::here` which only imports are only exposed to +as with `import::here` which only imports are only exposed to the module itself. When importing from a module, it is sourced into an environment -managed by `import`, and will not be sourced again upon subsequent -imports (unless the file has changed). For example, in a `shiny` +managed by `import`, and will not be sourced again upon subsequent +imports (unless the file has changed). For example, in a `shiny` application, importing some objects in `server.R` and others in `ui.R` from the same module will not cause it to be sourced twice. +## Checking what is available + +When working with a new package or module, it is often useful to see which +objects are available before deciding what to import. For this purpose, +`import::what()` (which you may have already noticed in some of the examples +above) provides a convenient way of listing all candidate objects. It works in +the same spirit as `import::from()`, but instead of actually importing objects +into your working environment, it creates a temporary environment, loads all +available objects there, and then returns their names as a character vector, +without affecting the working environment above. + +This makes it easy to explore without cluttering the search path, especially +when working interactively on preparing data analysis tasks. For example: + +``` r +import::what(psych) |> head(4) +#> [1] "%+%" "acs" "alpha" "alpha.ci" +``` + +Objects can then be imported selectively: + +``` r +import::from(psych, alpha, alpha.ci) +``` + +The same works for modules (script files), which can be even more useful +as modules don't have a help file with an index of available functions: + +``` r +import::what("sequence_module.R") +#> [1] "fibonacci" "square" "triangular" +``` +In this way, what() provides a quick overview of available functions, data, +or other objects in a package or script module, letting you decide what to +bring into your code while keeping your workspace uncluttered. It is +particularly useful when exploring large packages or new modules whose +contents you are not yet familiar with. + +Note that all relevant options from `import::from()`, such as those for +specifying the source directory or library, including specifying specifying the +package/module as a `character` variable: + +``` r +some_packages <- paste0(c("read", "string", "tidy"), "r") +import::what(some_packages[1], .character_only = TRUE) |> tail(4) +#> [1] "write_file" "write_lines" "write_rds" "write_tsv" +``` + +More on that in the section on [advanced usage](#advanced) below. -### Choosing where import looks for packages or modules +## Where import looks for packages or modules The `import` package will by default use the current set of library paths, i.e. the result of `.libPaths()`. It is, however, possible to specify a different set @@ -363,10 +424,10 @@ the new default is applicable in a broader set of circumstances, but if this change causes any issues, we would very much appreciate hearing about it. When importing from a module (.R file), the directory where `import` looks for -the module script can be specified with the with `.directory` parameter. +the module script can be specified with the with `.directory` parameter. The default is `.` (the current working directory). -### Choosing where the imported functions are placed +## Choosing where the imported functions are placed One can also specify which names to use in the search path and use several to group imports. Names can be specified either as character literals or as @@ -379,7 +440,7 @@ import::from(dplyr, arrange, .into = "datatools") import::from(psych, describe, .into=month.name[1]) # Uses env: "January" ``` -The `import::into` and `import::from` accept the same parameters and achieve the +`import::into()` and `import::from()` accept the same parameters and achieve the same result. The the choice between them a matter of preference). If using custom search path entities actively, one might prefer the alternative syntax (which does the same but reverses the argument order): @@ -394,8 +455,8 @@ Be aware that beginning in version `1.3.0` hidden objects (those with names prefixed by a period) are supported. Take care to avoid name clashes with argument names. -If it is desired to import objects directly into the current environment, -this can be accomplished by `import::here`. This is particularly +If it is desired to import objects directly into the current environment, +this can be accomplished by `import::here`. This is particularly useful when importing inside a function definition, or module scripts as described [here](#module). @@ -430,7 +491,7 @@ x = import::into(new.env(), "%<>%", .from = magrittr) ``` -# Advanced usage +# Advanced usage {#advanced} ## Advanced usage and the .character_only parameter @@ -455,7 +516,7 @@ can be helpful. ## Programmatic selection of objects to import It is not always know in advance which objects to import from a given -package. For example, assume we have a list of objects from the +package. For example, assume we have a list of objects from the `broom` package that we need to import, we can do it as follows: ```{r, eval = FALSE} @@ -468,7 +529,7 @@ It is worth noting that because `.character_only` disables non-standard evaluation on *all* parameters, the name of the package must now be quoted. One common use case is when one wants to import all objects except one -or a few, because of conflicts with other packages. Should one, for +or a few, because of conflicts with other packages. Should one, for example, want to use the `stats` versions of the `filter()` and `lag()` functions, but import all the other functions in the `dplyr` package, one could do it like this: @@ -484,7 +545,7 @@ import::from("dplyr", objects, .character_only=TRUE) The same approach can be used when the directory of the source file for a module is not known in advance. This can be useful when the original source file is not always run with the original -working directory, but one still does not want to specify a +working directory, but one still does not want to specify a hard-coded absolute path, but to determine it at run time: ```{r, eval = FALSE} @@ -495,9 +556,9 @@ import::from(mymodule, "myfunction", .character_only=TRUE) Again, note that now the name of the function must be quoted because non-standard evaluation is disabled on all parameters. -The `here` package is useful in many circumstances like this; it +The `here` package is useful in many circumstances like this; it allows the setting of a "root" directory for a project and by using -the `here::here()` function to figure out the correct directory, +the `here::here()` function to figure out the correct directory, regardless of the working directory. ```{r, eval = FALSE} @@ -519,13 +580,13 @@ the similarity in names. ## Importing from a URL Another case where `.character_only` comes in handy is when one -wants to import some functions from a URL. While `import` does -not allow direct importing from a URL (because of difficult -questions about when a URL target has changes, whether to +wants to import some functions from a URL. While `import` does +not allow direct importing from a URL (because of difficult +questions about when a URL target has changes, whether to download a file and other things), it easy to achieve the desired -result by using the `pins` package (whose main purpose is to -resolve such difficult questions). A simple example follows, which -directly imports the `myfunc()` function, which is defined in the +result by using the `pins` package (whose main purpose is to +resolve such difficult questions). A simple example follows, which +directly imports the `myfunc()` function, which is defined in the [`plusone_module.R`](https://raw.githubusercontent.com/rticulate/import/master/man/examples/plusone_module.R): ```{r, eval = FALSE} From 531ee812bf39bdb5182d95777f683670b8f0504a Mon Sep 17 00:00:00 2001 From: Magnus Thor Torfason Date: Sun, 19 Oct 2025 10:50:22 +0000 Subject: [PATCH 10/10] Bump version to 1.3.4 for release --- DESCRIPTION | 2 +- NEWS.md | 2 +- README.md | 2 +- cran-comments.md | 9 ++++++--- 4 files changed, 9 insertions(+), 6 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index f9cc34a..36bb47e 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: import Type: Package Title: An Import Mechanism for R -Version: 1.3.3.9002 +Version: 1.3.4 Authors@R: c(person(given = "Stefan Milton", family = "Bache", diff --git a/NEWS.md b/NEWS.md index 2795d4f..f3d6de5 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,5 @@ -Version 1.3.3.9001 +Version 1.3.4 ============= * New function, import::what(), which lists objects available for import from diff --git a/README.md b/README.md index a1ae70f..d5fcbfb 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![CRAN status](https://www.r-pkg.org/badges/version/import)](https://CRAN.R-project.org/package=import) [![CRAN status -shields](https://img.shields.io/badge/Git-1.3.3.9002-success)](https://github.com/rticulate/import) +shields](https://img.shields.io/badge/Git-1.3.4-success)](https://github.com/rticulate/import) [![R build status](https://github.com/rticulate/import/workflows/R-CMD-check/badge.svg)](https://github.com/rticulate/import/actions) diff --git a/cran-comments.md b/cran-comments.md index 92e930c..b0d84f5 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,9 +1,12 @@ ## General -Version 1.3.3 is a bug fix release with the following fixes: +Version 1.3.4 adds `import::what()` to list available objects for import, +and provides some documentation improvements: -* When imports conflict, include name of the conflicting object in error message -* Update docs to point to rticulate.github.io/import (old doc domain is defunct) +* New function, import::what(), which lists objects available for import from + a given package or module. +* Documentation links now point both to release and development documentation. +* Other minor documentation improvements. More info in `NEWS.md`