rootpath

library0.1.1pypypi✓ verified 87d ago

The `rootpath` library for Python offers automatic detection of a project's or package's root directory. It identifies the root by searching for common files and folders like `.git` or `requirements.txt` in parent directories. This is particularly useful for resolving Python's module import challenges by optionally adding the detected root path to `sys.path`. The current version is 0.1.1, and the library appears to be in a maintenance mode with its last PyPI update in 2019.

devops

pip install rootpath

github ↗package ↗

INSTALL

IMPORT

SIG · ROOTPATH

rootpath

devopspythonv0.1.1

Install

5.5s avg

Import

12ms

Disk

49MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.1.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.012s · 50.5MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 5.5s · import 0.010s · 50MB

49MB installed

● package 49MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

detect

✓ import rootpath root_dir = rootpath.detect()

The primary function to detect the project root path.

append_to_sys_path

✓ import rootpath rootpath.append_to_sys_path()

Call after detection to add the root to sys.path for easier imports.

This quickstart demonstrates how to use `rootpath.detect()` to find the project's root directory and `rootpath.append_to_sys_path()` to add it to `sys.path`, enabling simpler absolute imports within your project.

import os import rootpath # Example project structure for demonstration: # /tmp/my_project/ # ├── .git (or requirements.txt, setup.py, etc.) # └── src/ # └── my_module.py # Simulate running from a submodule (e.g., /tmp/my_project/src/my_module.py) # In a real scenario, you'd run this from within your project directory. # Detect the project root from the current file's location # It will traverse up until it finds a common project marker. project_root = rootpath.detect() print(f"Detected project root: {project_root}") # Optionally, add the project root to sys.path for simplified imports rootpath.append_to_sys_path(project_root) print(f"sys.path now includes: {project_root}") # You can also override the detection pattern # For example, if your root is marked by a specific file 'my_custom_root.txt' # custom_root = rootpath.detect(pattern='my_custom_root.txt') # print(f"Detected custom root: {custom_root}")

Debug

Known issues

gotchaThe `rootpath.detect()` function relies on a set of common files and folders (e.g., `.git`, `requirements.txt`, `setup.py`) to identify the project root. If your project uses a non-standard marker or lacks these common files in the expected location, `rootpath` might not detect the intended root.

fix

Override the default detection pattern by passing the `pattern` argument to `rootpath.detect()`, specifying a unique file or directory that marks your project's root (e.g., `rootpath.detect(pattern='my_project_root_marker.txt')`).

affects: 0.1.1

gotcha`rootpath` primarily focuses on detecting the root path and offers a basic `sys.path` modification helper. For more advanced path management, environment variable loading, or deeper integration with project setup across various scenarios (like notebooks or containerized environments), consider more comprehensive libraries such as `rootutils` or `pyrootutils`.

fix

Evaluate your project's specific needs. If complex path resolution, `.env` file loading, or robust cross-environment configuration is required, explore alternatives like `rootutils` or `pyrootutils`.

affects: 0.1.1

deprecatedThe library's last update was in March 2019 (version 0.1.1). While the core functionality is simple and likely stable, users should be aware of its age, which implies less active maintenance or updates for newer Python versions or edge cases that might arise with evolving project structures or Python features.

fix

Ensure thorough testing within your specific environment and Python version. If you encounter issues not addressed by the current version, consider contributing to the project or exploring more actively maintained alternatives if the problem is critical.

affects: <=0.1.1

gotchaRelying on `__file__` (which `rootpath` uses implicitly to start its search) might lead to `NameError` in environments where `__file__` is not defined, such as the Python REPL, some interactive Jupyter Notebook cells, or certain frozen executables.

fix

For interactive sessions, consider explicitly providing a starting path using `rootpath.detect(start_path=os.getcwd())`. For packaged applications, ensure the execution environment correctly defines `__file__` or provide a fallback mechanism for the `start_path` argument.

affects: 0.1.1

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'my_project.my_submodule'

Python's default import mechanism may struggle with relative imports when scripts are run from subdirectories, leading to internal project modules not being found, especially if the project root isn't on `sys.path`.

fix

After detecting the root path, ensure it is added to Python's system path: `import rootpath; project_root = rootpath.detect(); rootpath.append_to_sys_path(project_root)`. This allows absolute imports from the project root.

AssertionError: '/some/unexpected/path' == '/expected/project/root' (or similar incorrect path returned)

`rootpath.detect()` was unable to identify the intended project root, likely because its default marker files (e.g., `.git`, `requirements.txt`, `setup.py`) were not present or found in an unexpected location, or your project's root marker differs.

fix

Specify a custom marker file for root detection: `project_root = rootpath.detect(pattern='my_custom_root_file.txt')` where `my_custom_root_file.txt` is a unique file at your project's root.

NameError: name '__file__' is not defined

The `rootpath` library, like many path utilities, often relies on the `__file__` global variable to determine the current script's location and traverse parent directories. In certain interactive environments (e.g., direct Python REPL, specific Jupyter notebook setups, or some frozen executables), `__file__` may not be defined.

fix

If `__file__` is not defined, you can explicitly provide a starting path to `rootpath.detect()`, for example, `rootpath.detect(start_path=os.getcwd())` or `rootpath.detect(start_path='/path/to/your/project/start_point')`. Be mindful of the current working directory in interactive sessions.

Upgrade

Version history

0.1.1latest on PyPI · released Mar 10, 2019

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/grimen/python-rootpath ↗

packagehttps://pypi.org/project/rootpath/ ↗