paths quick start guide

pip install suitkaise

Create a project-relative path

from suitkaise.paths import Skpath

path = Skpath("data/file.txt")

path.ap   # "/Users/me/project/data/file.txt" — absolute, normalized
path.rp   # "data/file.txt" — relative to project root, same on every machine
path.id   # "ZGF0YS9maWxlLnR4dA" — reversible ID for database storage
path.platform   # platform-specific absolute path

Get the current file's path

here = Skpath()  # no arguments = caller's file path
print(here.rp)   # "src/my_module.py"

Get the project root

root = Skpath().root
print(root.ap)  # "/Users/me/project"

# or directly
from suitkaise import paths
root = paths.get_project_root()

Auto-convert path types with @autopath

from suitkaise.paths import autopath, AnyPath

@autopath()
def process(path: AnyPath):
    # path is always an Skpath, no matter what was passed in
    print(path.rp)

process("data/file.txt")                  # str → Skpath
process(Path("data/file.txt"))            # Path → Skpath
process(Skpath("data/file.txt"))          # Skpath → Skpath

Use Skpath like pathlib.Path

Everything pathlib does, Skpath does too:

path = Skpath("src")

# join paths
config = path / "config" / "settings.yaml"

# read/write
config.write_text('{"debug": true}')
data = config.read_text()

# iterate
for py_file in path.rglob("*.py"):
    print(py_file.rp)

# check existence
if config.exists:
    print(config.name)

Path IDs for database storage (reversible IDs)

path = Skpath("data/reports/q1.csv")

# store a compact, reversible ID
db.execute("INSERT INTO files (path_id) VALUES (?)", (path.id,))

# reconstruct later
same_path = Skpath("ZGF0YS9yZXBvcnRzL3ExLmNzdg")
print(same_path.rp)  # "data/reports/q1.csv"

Validate and sanitize filenames

from suitkaise.paths import is_valid_filename, streamline_path_quick

is_valid_filename("report.pdf")        # True
is_valid_filename("file<name>.txt")    # False
is_valid_filename("CON")               # False (Windows reserved)

streamline_path_quick("My File (1).txt")  # "My_File__1_.txt"

Temporary root override for testing

from suitkaise.paths import CustomRoot, Skpath

with CustomRoot("/tmp/test_project"):
    path = Skpath("config/settings.yaml")
    assert path.root_str == "/tmp/test_project"

Want to learn more?