# rootutils
[](https://www.python.org/downloads/release/python-370/)
[](https://github.com/ashleve/rootutils/actions/workflows/test.yml)
[](https://codecov.io/gh/ashleve/rootutils)
[](https://github.com/ashleve/rootutils/actions/workflows/publish_package.yml)
[](https://github.com/ashleve/rootutils/issues)
[](https://github.com/ashleve/rootutils/blob/main/LICENSE)
[](https://pypi.org/project/rootutils/)
[](https://pypi.org/project/rootutils/)
A simple python package to solve all your problems with pythonpath, working directory, file paths, module imports and environment variables.
## Why rootutils?
**Problem:** I would like to be able to:
- Run my python scripts from anywhere
- Always import python modules relatively to the project root directory
- Always access files relatively to the project root so I don't have to specify a series of `../` to get to the data
- Always have access to environment variables from `.env` file without having to load them manually
- Have all the above benefits in notebooks even if they're nested in subdirectories
**Solution:** The `rootutils` package provides a flexible way to setup the python project with a simple one-liner. It finds the project root based on the location of specified file name, e.g. `.project-root` or `.git`.
The package is tiny and continuosly maintained.
## Setup
```bash
pip install rootutils
```
## Usage
```python
import rootutils
# find absolute root path (searches for directory containing .project-root file)
# search starts from current file and recursively goes over parent directories
# returns pathlib object
path = rootutils.find_root(search_from=__file__, indicator=".project-root")
# find absolute root path (searches for directory containing any of the files on the list)
path = rootutils.find_root(search_from=__file__, indicator=[".git", "setup.cfg"])
# take advantage of the pathlib syntax
data_dir = path / "data"
assert data_dir.exists(), f"path doesn't exist: {data_dir}"
# set root directory
rootutils.set_root(
path=path # path to the root directory
project_root_env_var=True, # set the PROJECT_ROOT environment variable to root directory
dotenv=True, # load environment variables from .env if exists in root directory
pythonpath=True, # add root directory to the PYTHONPATH (helps with imports)
cwd=True, # change current working directory to the root directory (helps with filepaths)
)
```
Simplest usage with one-liner (combines `find_root()` and `set_root()` into one method):
```python
import rootutils
root = rootutils.setup_root(__file__, dotenv=True, pythonpath=True, cwd=False)
```
## Defaults
Default root indicators (used when you don't specify `indicator` arg):
```python
[".project-root", "setup.cfg", "setup.py", ".git", "pyproject.toml"]
```
## Autoroot
`autoroot` is an experimental package that reduces `rootutils` to single import, without the need to execute any setup calls. This means just the act of importing this dependency (`import autorootcwd`) causes execution of recurrent search for `.project-root` file.
Installation:
```bash
pip install autoroot autorootcwd
```
This adds root folder to pythonpath, sets PROJECT_ROOT env var, and loads variables from `.env`:
```python
import autoroot # root setup, do not delete
```
This also changes working directory to root:
```python
import autorootcwd # root setup, do not delete
```
Autoroot exist for convenience and speed. For example, it's faster to just add `import autorootcwd` at the beginning when creating new notebook.
Package page: https://github.com/ashleve/autoroot
## Inspirations
This package is heavily inspired by:
https://github.com/chendaniely/pyprojroot
https://github.com/pashminacameron/py-repo-root
https://github.com/EduardKononov/from-root
Raw data
{
"_id": null,
"home_page": "https://github.com/ashleve/rootutils",
"name": "rootutils",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.0",
"maintainer_email": "",
"keywords": "",
"author": "ashleve",
"author_email": "ashlevegalaxy@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/16/9e/62489bd92acc537ed902fc3ebc0e055e8a96c6ca3071dfdecd9c513176ec/rootutils-1.0.7.tar.gz",
"platform": null,
"description": "# rootutils\n\n[](https://www.python.org/downloads/release/python-370/)\n[](https://github.com/ashleve/rootutils/actions/workflows/test.yml)\n[](https://codecov.io/gh/ashleve/rootutils)\n[](https://github.com/ashleve/rootutils/actions/workflows/publish_package.yml)\n[](https://github.com/ashleve/rootutils/issues)\n[](https://github.com/ashleve/rootutils/blob/main/LICENSE)\n[](https://pypi.org/project/rootutils/)\n[](https://pypi.org/project/rootutils/)\n\nA simple python package to solve all your problems with pythonpath, working directory, file paths, module imports and environment variables.\n\n## Why rootutils?\n\n**Problem:** I would like to be able to:\n\n- Run my python scripts from anywhere\n- Always import python modules relatively to the project root directory\n- Always access files relatively to the project root so I don't have to specify a series of `../` to get to the data\n- Always have access to environment variables from `.env` file without having to load them manually\n- Have all the above benefits in notebooks even if they're nested in subdirectories\n\n**Solution:** The `rootutils` package provides a flexible way to setup the python project with a simple one-liner. It finds the project root based on the location of specified file name, e.g. `.project-root` or `.git`.\n\nThe package is tiny and continuosly maintained.\n\n## Setup\n\n```bash\npip install rootutils\n```\n\n## Usage\n\n```python\nimport rootutils\n\n# find absolute root path (searches for directory containing .project-root file)\n# search starts from current file and recursively goes over parent directories\n# returns pathlib object\npath = rootutils.find_root(search_from=__file__, indicator=\".project-root\")\n\n# find absolute root path (searches for directory containing any of the files on the list)\npath = rootutils.find_root(search_from=__file__, indicator=[\".git\", \"setup.cfg\"])\n\n# take advantage of the pathlib syntax\ndata_dir = path / \"data\"\nassert data_dir.exists(), f\"path doesn't exist: {data_dir}\"\n\n# set root directory\nrootutils.set_root(\n path=path # path to the root directory\n project_root_env_var=True, # set the PROJECT_ROOT environment variable to root directory\n dotenv=True, # load environment variables from .env if exists in root directory\n pythonpath=True, # add root directory to the PYTHONPATH (helps with imports)\n cwd=True, # change current working directory to the root directory (helps with filepaths)\n)\n```\n\nSimplest usage with one-liner (combines `find_root()` and `set_root()` into one method):\n```python\nimport rootutils\nroot = rootutils.setup_root(__file__, dotenv=True, pythonpath=True, cwd=False)\n```\n\n## Defaults\n\nDefault root indicators (used when you don't specify `indicator` arg):\n\n```python\n[\".project-root\", \"setup.cfg\", \"setup.py\", \".git\", \"pyproject.toml\"]\n```\n\n## Autoroot\n\n`autoroot` is an experimental package that reduces `rootutils` to single import, without the need to execute any setup calls. This means just the act of importing this dependency (`import autorootcwd`) causes execution of recurrent search for `.project-root` file.\n\nInstallation:\n```bash\npip install autoroot autorootcwd\n```\n\nThis adds root folder to pythonpath, sets PROJECT_ROOT env var, and loads variables from `.env`:\n```python\nimport autoroot # root setup, do not delete\n```\n\nThis also changes working directory to root:\n```python\nimport autorootcwd # root setup, do not delete\n```\n\nAutoroot exist for convenience and speed. For example, it's faster to just add `import autorootcwd` at the beginning when creating new notebook.\n\nPackage page: https://github.com/ashleve/autoroot\n\n## Inspirations\n\nThis package is heavily inspired by:\n\nhttps://github.com/chendaniely/pyprojroot\n\nhttps://github.com/pashminacameron/py-repo-root\n\nhttps://github.com/EduardKononov/from-root\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple package for easy project root setup",
"version": "1.0.7",
"project_urls": {
"Homepage": "https://github.com/ashleve/rootutils"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "19171e8ba0be5b52aa7a18f0df7bd6ab31345a3a4f515d6beac6a765fcacaaa3",
"md5": "a6a9d99a6f8fa315247d7f1bc53a2d4c",
"sha256": "89f1994e6d0f499db7aca7f90edc146801cb33c8565a15c7cee4a4e4fc8c6eef"
},
"downloads": -1,
"filename": "rootutils-1.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a6a9d99a6f8fa315247d7f1bc53a2d4c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7.0",
"size": 6403,
"upload_time": "2023-05-19T13:05:19",
"upload_time_iso_8601": "2023-05-19T13:05:19.416172Z",
"url": "https://files.pythonhosted.org/packages/19/17/1e8ba0be5b52aa7a18f0df7bd6ab31345a3a4f515d6beac6a765fcacaaa3/rootutils-1.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "169e62489bd92acc537ed902fc3ebc0e055e8a96c6ca3071dfdecd9c513176ec",
"md5": "093c72955465a7ee3111ca878c0c69d7",
"sha256": "7e2444cdbf4a73a907875fb109d55a38b4ee21313cef305bf59fadbf540440bc"
},
"downloads": -1,
"filename": "rootutils-1.0.7.tar.gz",
"has_sig": false,
"md5_digest": "093c72955465a7ee3111ca878c0c69d7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.0",
"size": 5730,
"upload_time": "2023-05-19T13:05:21",
"upload_time_iso_8601": "2023-05-19T13:05:21.837100Z",
"url": "https://files.pythonhosted.org/packages/16/9e/62489bd92acc537ed902fc3ebc0e055e8a96c6ca3071dfdecd9c513176ec/rootutils-1.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-19 13:05:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ashleve",
"github_project": "rootutils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "rootutils"
}
JSON
