{"id":14068780,"url":"https://github.com/rticulate/import","last_synced_at":"2025-12-12T01:02:14.245Z","repository":{"id":28254175,"uuid":"31763299","full_name":"rticulate/import","owner":"rticulate","description":"An Import Mechanism For R","archived":false,"fork":false,"pushed_at":"2024-01-23T17:22:56.000Z","size":4452,"stargazers_count":220,"open_issues_count":4,"forks_count":14,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-05-22T16:13:51.913Z","etag":null,"topics":["cran","r"],"latest_commit_sha":null,"homepage":"https://import.rticulate.org","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rticulate.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-03-06T09:56:16.000Z","updated_at":"2024-02-13T16:45:34.000Z","dependencies_parsed_at":"2024-01-22T11:54:16.131Z","dependency_job_id":null,"html_url":"https://github.com/rticulate/import","commit_stats":{"total_commits":96,"total_committers":9,"mean_commits":"10.666666666666666","dds":0.6041666666666667,"last_synced_commit":"720a4c928bfda257fb2d7e794f31270860db5571"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rticulate%2Fimport","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rticulate%2Fimport/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rticulate%2Fimport/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rticulate%2Fimport/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rticulate","download_url":"https://codeload.github.com/rticulate/import/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228082372,"owners_count":17866607,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cran","r"],"created_at":"2024-08-13T07:06:24.057Z","updated_at":"2025-10-22T06:22:59.339Z","avatar_url":"https://github.com/rticulate.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n# import \u003ca href=\"https://rticulate.github.io/import\"\u003e\u003cimg src=\"man/figures/logo.png\" align=\"right\" height=\"138\" /\u003e\u003c/a\u003e\n\n\u003c!-- badges: start --\u003e\n[![CRAN status](https://www.r-pkg.org/badges/version/import)](https://CRAN.R-project.org/package=import)\n[![CRAN status shields](https://img.shields.io/badge/Git-`r desc::desc_get_version() `-success)](https://github.com/rticulate/import)\n[![R build status](https://github.com/rticulate/import/workflows/R-CMD-check/badge.svg)](https://github.com/rticulate/import/actions)\n\u003c!-- badges: end --\u003e\n\n# An Import Mechanism For R\n\nThe import package is intended to simplify the way in which functions from\nexternal packages or modules are made available for use in R scripts. Learn more\non the [package website](https://rticulate.github.io/import/), by reading\n[`vignette(\"import\")`](https://rticulate.github.io/import/articles/import.html), or\nusing the help (`?import::from`).\n\n## Introduction\n\nThe typical way of using functionality exposed by a package in R scripts is to\nload (and attach) the entire package with `library()` (or `require()`). This can\nhave the undesirable effect of masking objects in the user's search path and\ncan also make it difficult and confusing to identify what functionality\ncomes from which package when using several `library` statements.\n\nThe `import` package provides a simple alternative, allowing the user specify in\na concise way exactly which objects. For example, the `Hmisc` package exposes\nover four hundred functions. Instead of exposing all of those functions, someone\nwho only needs access to, say the `impute()` and the `nomiss()` functions, can\nimport those functions only:\n\n```R\nimport::from(Hmisc, impute, nomiss)\n```\n\n## Installation and Documentation\n\nInstall the release version of `import` from CRAN using `pak` or\n`install.packages()`:\n\n```R\npak::pak(\"import\")\n  # or\ninstall.packages(\"import\")\n```\n\nA documentation site is available on GitHub. For the `main` branch, which\nusually matches the CRAN release, the link is:\n\n- https://rticulate.github.io/import/\n\n\n### Installing from GitHub\n\nInstall the either the `main` (release) or the `dev` (development) branch of\n`import` from GitHub using `pak`:\n\n```R\n# The main branch typically matches the CRAN release\npak::pak(\"rticulate/import\")\n\n# New features are developed on the dev branch\npak::pak(\"rticulate/import@dev\")\n```\n\nDocumentation for the `dev` branch is available on:\n\n- https://rticulate.github.io/import/dev/\n\n\n## Usage\n\n### Importing functions from R packages\n\nThe most basic use case is to import a few functions from package using\n`import::from()`. Here we import from the `psych` package. We start by using\n`import::what()` to list available functions.\n\n```R\nimport::what(psych) |\u003e head()\nimport::from(psych, geometric.mean, harmonic.mean)\ngeometric.mean(trees$Volume)\n```\n\nIf one of the function names conflicts with an existing function (such as\n`filter` from the `dplyr` package) it is simple to rename it:\n\n```R\nimport::from(dplyr, select, arrange, keep_when = filter)\nkeep_when(mtcars, hp\u003e250)\n```\n\nUse `.all=TRUE` to import all functions from a package. If you want to rename\none of them, you can still do that:\n\n```R\nimport::from(dplyr, keep_when = filter, .all=TRUE)\n```\n\nTo omit a function from the import, use `.except` (which takes a character\nvector):\n\n```R\nimport::from(dplyr, .except=c(\"filter\", \"lag\"))\n```\n\nNote that `import` tries to be smart about this and assumes that if you are\nusing the `.except` parameter, you probably want to import everything you are\n_not_ explicitly omitting, and sets the `.all` parameter to `TRUE`. You can\nstill override this in exceptional cases, but you seldom need to.\n\nThese and other examples are discussed in more detail in the \n[Importing from Packages](https://rticulate.github.io/import/articles/import.html#importing-from-packages)\nsection of the package vignette.\n\n\n### Importing Functions from \"Module\" Scripts\n\nThe `import` package allows R files to be used as \"modules\" from which functions\nare loaded. For example, the file\n[sequence_module.R](https://raw.githubusercontent.com/rticulate/import/master/man/examples/sequence_module.R) \ncontains several functions calculating terms of mathematical sequences. It is\npossible to import from such files, just as one imports from packages. Again,\nwe start by using `import::what()` to check what is available in the module:\n\n```R\nimport::what(sequence_module.R)\nimport::from(sequence_module.R, fibonacci, square, triangular)\n```\n\nRenaming, as well as the `.all` and `.except` parameters, work in the same way\nas for packages:\n\n```R\nimport::from(sequence_module.R, fib=fibonacci, .except=\"square\")\n```\n\nThese and other examples are discussed in more detail in the \n[Importing from Modules](https://rticulate.github.io/import/articles/import.html#importing-functions-from-module-scripts) \nsection of the package vignette.\n\n### Choosing where import looks for packages or modules\n\nThe `import` package will by default use the current set of library paths, i.e.\nthe result of `.libPaths()`. It is, however, possible to specify a different set\nof library paths using the `.library` argument in any of the `import` functions,\nfor example to import packages installed in a custom location, or to remove any\nambiguity as to where imports come from.\n\nNote that in versions up to and including `1.3.0` this defaulted to use only the\n*first* entry in the library paths, i.e. `.library=.libPaths()[1L]`. We believe\nthe new default is applicable in a broader set of circumstances, but if this\nchange causes any issues, we would very much appreciate hearing about it.\n\nWhen importing from a module (.R file), the directory where `import` looks for\nthe module script can be specified with the with `.directory` parameter. The\ndefault is `.` (the current working directory).\n\n### Choosing where the imported functions are placed\n\nBy default, imported objects are placed in a separate entity in the search path\ncalled \"imports\". One can also specify which names to use in the search path and\nuse several to group imports:\n\n```R\nimport::from(magrittr, \"%\u003e%\", \"%$%\", .into = \"operators\") \nimport::from(dplyr, arrange, .into = \"datatools\")\n```\n\nIf using custom search path entities actively, one might prefer the alternative\nsyntax (which does the same but reverses the argument order):\n\n```R\nimport::into(\"operators\", \"%\u003e%\", \"%$%\", .from = magrittr)\nimport::into(\"datatools\", arrange, .from = dplyr)\n```\n\nIf it is desired to place imported objects in the current environment, use\n`import::here()`:\n\n### More advanced usage\n\nThe `import` package is designed to be simple to use for basic cases, so it uses\nsymbolic evaluation to allow the names of packages, modules and functions to be\nentered without quotes (except for operators, such as `\"%\u003e%\"` which must be\nquoted). However, this means that it calling a variable containing the name of a\nmodule, or a vector of functions to import, will not work. For this use case,\nyou can use the `.character_only` parameter:\n\n```R\nmodule_name \u003c- \"../utils/my_module.R\"\n\n# Will not work (import will look for a package called \"module_name\")\nimport::from(module_name, foo, bar)\n\n# This will correctly import the foo() and bar() functions from \"../utils/my_module.R\"\nimport::from(module_name, foo, bar, .character_only=TRUE)\n```\n\nThe `.character_only` parameter is covered in more detail in the \n[Advanced Usage](https://rticulate.github.io/import/articles/import.html#advanced-usage) \nsection of the package vignette, which also describes how you can import from\nmodule scripts stored online with the help of the `pins` package, or achieve\npython-like imports with the help of `{}` notation for environments in the\n`.into` parameter.\n\n# Contributing\n\nContributions to this project are welcome. Please start by opening an issue or\ndiscussion thread. New features are added conservatively based on supply (is\nanyone willing to contribute an implementation of the feature?), demand (how\nmany people seem to need a new feature?), and last, but not least, by whether a\nfeature can be implemented without breaking backwards compatibility.\n\n- Created and authored by [@smbache](https://github.com/smbache)\n- Currently maintained by [@torfason](https://github.com/torfason)\n- Code contributions by \n  [@awong234](https://github.com/awong234), \n  [@brshallo](https://github.com/brshallo), \n  [@flying-sheep](https://github.com/flying-sheep), \n  [@hutch3232](https://github.com/hutch3232),\n  [@J-Moravec](https://github.com/J-Moravec), \n  [@klmr](https://github.com/klmr),\n  [@mschilli87](https://github.com/mschilli87),\n  [@olivroy](https://github.com/olivroy)\n  [@aramirezreyes](https://github.com/aramirezreyes)\n  \n*(Did we forget to add you? If so, please let us know!)*\n\n# See also:\n\n- Some of the use cases for `import` can now be handled directly in base R using\n  the new `exclude` and `include.only` arguments of `library()` and `require()`\n- For an interesting but slightly different idea of Python-like modules for R, \n  see the [box](https://klmr.me/box/) package by\n  [@klmr](https://github.com/klmr) (previously called\n  [modules](https://github.com/klmr/modules)).\n- Another approach, focused on treating the use of functions with naming \n  conflicts as explicit errors is the\n  [conflicted](https://github.com/r-lib/conflicted) package by\n  [@hadley](https://github.com/hadley).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frticulate%2Fimport","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frticulate%2Fimport","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frticulate%2Fimport/lists"}