herepath

A simpler way to find your files.

Source code: github.com/Pinto-Katende-Jonathan/herepath

herepath builds file paths relative to your project's root, no matter which folder you run your code from. It is a Python port of the R here package.

A relative path like ../../data/sales.csv breaks the moment you run a script from a different folder, a notebook, or your editor. Write this instead:

from herepath import here

here("data", "sales.csv")
# -> /home/me/my-project/data/sales.csv   (always, from anywhere)

Why herepath?

The problem it solves is small but constant. A relative path like ../data/sales.csv does not point to a file. It points to a file relative to wherever you happen to be standing, so it breaks as soon as you move.

herepath finds the root of your project once, then anchors every path to that root. The result no longer depends on your current working directory.

A few things it gives you:

• Works from anywhere. Run the same script from the project root, a subfolder, a notebook, or your IDE. here() returns the same absolute path every time.
• No dependencies. Pure standard library. herepath adds nothing to your dependency tree.
• A small API. Four core functions: here(), i_am(), set_here(), dr_here(). You can learn the essentials in a few minutes.
• A shell command too. Installing the package also gives you a herepath command for scripts and Makefiles.

Installation

pip install herepath

One name everywhere: you install herepath, you import herepath, and you get a herepath command. See Installation for more.

A short example

Suppose your project looks like this:

my-project/
├── pyproject.toml
├── data/
│   └── sales.csv
└── analysis/
    └── report.py

In analysis/report.py:

from herepath import i_am, here   # (1)!
import pandas as pd

i_am("analysis/report.py")        # (2)!

df = pd.read_csv(here("data", "sales.csv"))  # (3)!

1. Import the two functions you need.
2. Declare where this file lives, relative to the project root. herepath now knows where the root is.
3. Build a path from the root. This works whether you run the script from my-project/, from analysis/, or from a notebook three folders away.

No more ../, and no more "it works on my machine".

Where to go next

• New here? Start with the Tutorial, a step-by-step walkthrough.
• Need more control? The Advanced guide covers custom markers, tests, and deployment.
• Scripting? See the Command line page.
• Looking something up? The API reference lists every function.
• Want to help? Read Contributing.

License

MIT, Jonathan Katende Pinto. Inspired by the R here package by Kirill Müller and Jennifer Bryan.