DOCSEARCHbyAlgolia
Submit Docs

rootutils

repository·main·Indexed 41 days ago

https://github.com/ashleve/rootutils

A lightweight Python utility to locate the project root, manage PYTHONPATH for imports, load .env files, and control the current working directory. Features include find_root(), set_root(), and setup_root() for automating project environment configuration.

Tokens
981
Snippets
6
Records
6
Agent score
2%

What's inside rootutils

  1. Quickstart: Setup the project root in one line

    main

    The simplest way to initialize your project environment is using rootutils.setup_root(). This method combines finding the root and configuring the environment into a single call.

    import rootutils

# This finds the root and applies settings in one step
root = rootutils.setup_root(__file__, dotenv=True, pythonpath=True, cwd=False)
    import rootutils
root = rootutils.setup_root(__file__, dotenv=True, pythonpath=True, cwd=False)

  3. Use autoroot for zero-config setup

    main

    The autoroot package is an experimental companion to rootutils that allows you to set up your project environment simply by importing a module. This is particularly useful in Jupyter notebooks.

    • import autoroot: Automatically finds the root, adds it to PYTHONPATH, sets the PROJECT_ROOT environment variable, and loads .env variables.
    • import autorootcwd: Does everything in autoroot AND changes the current working directory to the project root.

    Installation:

    pip install autoroot autorootcwd
    import autoroot # root setup, do not delete

# OR

import autorootcwd # root setup, do not delete

  4. Configure the project environment with set_root()

    main

    Use rootutils.set_root() to apply project-wide configurations once the root path is found. This allows you to automate imports, environment variable loading, and directory management.

    Arguments:

    • path: The pathlib.Path object representing the root directory.
    • project_root_env_var (bool): If True, sets the PROJECT_ROOT environment variable to the root directory.
    • dotenv (bool): If True, loads environment variables from a .env file located in the root directory.
    • pythonpath (bool): If True, adds the root directory to sys.path (PYTHONPATH) to enable relative module imports.
    • cwd (bool): If True, changes the current working directory to the root directory.
    import rootutils

path = rootutils.find_root(search_from=__file__, indicator=".project-root")

rootutils.set_root(
    path=path,
    project_root_env_var=True,
    dotenv=True,
    pythonpath=True,
    cwd=True,
)

  5. Find the project root directory

    main

    Use rootutils.find_root() to locate the absolute path of your project root. The search starts from the directory of the provided search_from file and recursively traverses parent directories looking for an indicator.

    • search_from: The starting point for the search (e.g., __file__).
    • indicator: A string or a list of strings representing files that mark the project root. If not provided, it defaults to a predefined list of common markers.

    Returns a pathlib.Path object.

    import rootutils

# Search for a specific indicator file
path = rootutils.find_root(search_from=__file__, indicator=".project-root")

# Search for any file in a provided list
path = rootutils.find_root(search_from=__file__, indicator=".git", "setup.cfg")

  6. Default root indicators in rootutils

    main

    If you do not provide an indicator argument to find_root(), the package searches for the following files in order to identify the project root:

    [".project-root", "setup.cfg", "setup.py", ".git", "pyproject.toml"]
    [".project-root", "setup.cfg", "setup.py", ".git", "pyproject.toml"]