pyprojroot

Common errors

• FileNotFoundError: [Errno 2] No such file or directory: 'data/my_file.csv'

  cause The `here()` function could not find a project root indicator (e.g., .git, setup.py) in the current directory or its parent directories, or the path relative to the root was incorrect.
  fix Ensure a project root indicator exists in a parent directory. If running a script, make sure the current working directory or one of its parents contains a recognized marker. Double-check the path passed to `here()` is correct relative to your actual project root.

• ModuleNotFoundError: No module named 'pyprojroot.here'

  cause The `pyprojroot` library is either not installed, or there's a typo in the import statement.
  fix Install the library using `pip install pyprojroot`. Verify the import statement: `from pyprojroot.here import here` is for the common `here` function, while `import pyprojroot` is for the top-level module.

Warnings

• gotcha pyprojroot relies on specific 'root indicators' (e.g., `.git`, `setup.py`, `requirements.txt`, `.here`) to identify the project root. If your project lacks these common markers, or if the current working directory is not within a project containing such a marker, it may fail to find the root or find an unexpected root.
  Fix: Ensure your project's root directory contains at least one of the default root indicators (e.g., initialize a Git repository with `.git`, or add a `requirements.txt` file). For custom markers, use `pyprojroot.find_root` with a `pyprojroot.criterion`.
• gotcha While `pyprojroot` returns `pathlib.Path` objects, its primary value is in robustly *finding* the project root, a task `pathlib` alone doesn't directly solve across varied execution contexts (e.g., scripts vs. notebooks). New users sometimes overlook this distinction.
  Fix: Understand that `pyprojroot` complements `pathlib` by providing a reliable starting point for relative paths within a project, regardless of the current working directory. `pathlib` then provides the elegant API for path manipulation.

Install

• pip install pyprojroot PyPI
• conda install -c conda-forge pyprojroot Conda

Imports

• here

  from pyprojroot.here import here

• find_root

  import pyprojroot
  root_path = pyprojroot.find_root(pyprojroot.has_dir('.git'))

  For programmatic root finding, often combined with a criterion from pyprojroot.criterion.

Quickstart

This quickstart demonstrates how to use `here()` to find the project root and then construct paths to files or directories relative to it. It assumes a project structure with a root marker (like `.git`) and uses `pathlib.Path` objects for robust path manipulation. The example creates temporary files to be runnable.

import os
from pyprojroot.here import here
from pathlib import Path

# Simulate a project structure for demonstration
# In a real project, you would have a .git or other marker in the root.
# And your data/notebooks would be actual directories.

# Create a dummy project root indicator (e.g., .git directory)
project_root_indicator = Path.cwd() / ".git"
project_root_indicator.mkdir(exist_ok=True)

# Create a dummy data directory and file
data_dir = here() / "data"
data_dir.mkdir(parents=True, exist_ok=True)
data_file = data_dir / "my_data.csv"
data_file.write_text("column1,column2\n1,A\n2,B")

print(f"Project root (found by pyprojroot): {here()}")
print(f"Absolute path to my_data.csv: {here('data/my_data.csv')}")

# Example of reading the data using a common library (e.g., pandas)
try:
    import pandas as pd
    df = pd.read_csv(here('data/my_data.csv'))
    print("\nData loaded successfully with pandas:")
    print(df)
except ImportError:
    print("\nInstall pandas (pip install pandas) to run the DataFrame example.")

# Clean up dummy project indicator and data
project_root_indicator.rmdir()
data_file.unlink()
data_dir.rmdir()