Skip to content

Getting Started

Package version Static Badge GitHub Action test workflow License: MIT

An opinionated OS-path module for people who take paths too seriously. ProperPath, as a subclass of Python's popular pathlib.Path, is a drop-in replacement with some extra features. The added features/APIs are mainly aimed at improving developer experience in building CLI tools/applications. ProperPath was originally created for elAPI.

properpath on the road properpath on the road

Main Features in a Nutshell

  1. A drop-in pathlib.Path replacement with more descriptive REPL representation
  2. Built-in error logging for raised exceptions
  3. Simplified APIs for working with files and directories
  4. Better platformfirs integration
  5. Validation for file/directory write permission
  6. Support for Pydantic validation and Rich pretty-repr printing

Installation

Make sure your Python virtual environment is activated. properpath requires Python 3.12 and above. Install properpath with pip.

pip install properpath

You can install with uv as well.

uv add properpath

Quickstart

Open a Python REPL and try the following:

Python REPL
>>> from properpath import P # "P" is a shorthand for "ProperPath"

>>> P("~")
ProperPath(path=/Users/username, actual=('~',), kind=dir, exists=True, is_symlink=False, err_logger=<RootLogger root (WARNING)>)

There's also Pydantic and Rich-pretty-printing support. If you already have a script or a project where you've used from pathlib import Path, and if you're feeling adventurous (!), try the following:

1
from properpath import P as Path

Head over to the Tutorial page for more hands-on examples.