pathbase

pathbase is a lightweight, dependency-free Python library for bidirectional filesystem path templates.

Installation

pip install -U pathbase

Quick Example

Given a real filepath, pathbase can discover the matching template from environment-provided templates and extract the tokens:

This example assumes envstack is installed so ENVPATH is resolved before pathbase runs.

ENVPATH=./examples/vfx/ pathbase parse \
'/mnt/projects/bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr'

Expected output:

{
"fields": {
"descriptor": "beauty",
"ext": "exr",
"frame": 1001,
"sequence": "seq001",
"shot": "shot010",
"show": "bigbuckbunny",
"step": "lighting",
"task": "render",
"version": 1
},
"template": "FILEPATH"
}

With envstack-managed templates, you can also emit the equivalent path for another platform:

ENVPATH=./examples/vfx/ pathbase parse --platform windows \
'/mnt/projects/bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr'

Expected output:

{
"fields": {
"descriptor": "beauty",
"ext": "exr",
"frame": 1001,
"sequence": "seq001",
"shot": "shot010",
"show": "bigbuckbunny",
"step": "lighting",
"task": "render",
"version": 1
},
"platform_path": "D:/projects/bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr",
"template": "FILEPATH"
}

If envstack is not installed, pathbase still supports direct environment variables and explicit mappings from Python.

You can also work with templates directly from Python:

frompathbaseimportTemplatetemplate=Template(
"/mnt/projects/{show}/{sequence}/{shot}/{step}/""{task}_{descriptor}_v{version:03d}.{frame:04d}.{ext}"
)
path=template.format(
show="bigbuckbunny",
sequence="seq001",
shot="shot010",
step="lighting",
task="render",
descriptor="beauty",
version=1,
frame=1001,
ext="exr",
)
fields=template.parse(
"/mnt/projects/bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr"
)

Pathbase supports:

• Template.format(...) for path construction
• Template.parse(path) for field extraction
• automatic environment-based template discovery for CLI parsing and matching
• typed numeric fields such as {version:03d} and {value:.2f}
• repeated-field validation
• mixed-separator parsing
• embedded $VAR and ${VAR} expansion from os.environ or an explicit mapping
• Template.from_env(...) as a convenience for environment-provided templates

Formatting output:

/mnt/projects/bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr

Parsing output:

{
"show": "bigbuckbunny",
"sequence": "seq001",
"shot": "shot010",
"step": "lighting",
"task": "render",
"descriptor": "beauty",
"version": 1,
"frame": 1001,
"ext": "exr",
}

CLI

pathbase also includes a lightweight CLI:

ROOT=/mnt/projects pathbase format --template '${ROOT}/{project}/{name}_v{version:03d}.txt' \
project=demo name=report version=1
ENVPATH=./examples/vfx/ pathbase parse \
'/mnt/projects/bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr'
ENVPATH=./examples/vfx/ pathbase parse --platform windows \
'/mnt/projects/bigbuckbunny/seq001/shot010/lighting/render_beauty_v001.1001.exr'
pathbase parse \
'/mnt/projects/demo/report_v001.txt'
pathbase parse --template FILEPATH \
'/mnt/projects/demo/report_v001.txt'
pathbase match '/mnt/projects/demo/report.txt'

Additional documentation lives in docs/index.md:

• Examples