Skip to main content

Simple package for easy project root setup

Project description

rootutils

Python Tests Codecov Build Issues License Release PyPi

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

pip install rootutils

Usage

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):

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):

[".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:

pip install autoroot autorootcwd

This adds root folder to pythonpath, sets PROJECT_ROOT env var, and loads variables from .env:

import autoroot # root setup, do not delete

This also changes working directory to root:

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rootutils-1.0.7.tar.gz (5.7 kB view details)

Uploaded Source

Built Distribution

rootutils-1.0.7-py3-none-any.whl (6.4 kB view details)

Uploaded Python 3

File details

Details for the file rootutils-1.0.7.tar.gz.

File metadata

  • Download URL: rootutils-1.0.7.tar.gz
  • Upload date:
  • Size: 5.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.16

File hashes

Hashes for rootutils-1.0.7.tar.gz
Algorithm Hash digest
SHA256 7e2444cdbf4a73a907875fb109d55a38b4ee21313cef305bf59fadbf540440bc
MD5 093c72955465a7ee3111ca878c0c69d7
BLAKE2b-256 169e62489bd92acc537ed902fc3ebc0e055e8a96c6ca3071dfdecd9c513176ec

See more details on using hashes here.

File details

Details for the file rootutils-1.0.7-py3-none-any.whl.

File metadata

  • Download URL: rootutils-1.0.7-py3-none-any.whl
  • Upload date:
  • Size: 6.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.16

File hashes

Hashes for rootutils-1.0.7-py3-none-any.whl
Algorithm Hash digest
SHA256 89f1994e6d0f499db7aca7f90edc146801cb33c8565a15c7cee4a4e4fc8c6eef
MD5 a6a9d99a6f8fa315247d7f1bc53a2d4c
BLAKE2b-256 19171e8ba0be5b52aa7a18f0df7bd6ab31345a3a4f515d6beac6a765fcacaaa3

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page