vcti-path 1.1.0

Safe path handling for VCollab applications

Path Utilities

Overview

Safe path handling for VCollab applications -- filename validation, file identity (POSIX-style relative paths as stable IDs), and path resolution with access validation. It gives you one place to validate untrusted names and file IDs before touching the filesystem, and a stable, platform-independent way to identify files inside a base directory. FileId.resolve_path rejects absolute paths, .. traversal, and symbolic links so a resolved ID cannot escape its base directory.

This package has zero external dependencies.

---

Installation

pip install vcti-path

In requirements.txt

vcti-path>=1.1.0

In pyproject.toml dependencies

dependencies = [
    "vcti-path>=1.1.0",
]

---

Quick Start

Validate filenames

from vcti.path import FileNameValidator

FileNameValidator.is_valid("report.pdf")     # True
FileNameValidator.is_valid("bad|name")       # False
FileNameValidator.is_valid("..")             # False

FileNameValidator.validate("data.json")      # OK
FileNameValidator.validate("bad/name")       # Raises ValueError

File IDs -- stable POSIX-style identifiers

A file ID is a POSIX-format relative path that uniquely identifies a file or directory within a base directory. No leading /, ./, or ../.

from pathlib import Path
from vcti.path import FileId

# Validate
FileId.is_valid("scripts/setup.sh")     # True
FileId.is_valid("/absolute/path")       # False
FileId.is_valid("../escape")            # False

# Resolve to filesystem path
base = Path("/project")
FileId.resolve_path("src/main.py", base)
# -> Path("/project/src/main.py")

# Extract file ID from a path
src = Path("/project/src/main.py")
FileId.get_file_id(src, base)
# -> "src/main.py"

Path resolution and access validation

from vcti.path import abs_path, validate_file_access, resolve_path

# Absolute path resolution
abs_path("relative/file.txt")
# -> Path("<cwd>/relative/file.txt")

# Validate that a file exists and is readable
validate_file_access("config.yaml")
# Raises FileNotFoundError, IsADirectoryError, or PermissionError

# Resolve relative to a base directory
resolve_path("data/input.csv", "/project")
# -> Path("/project/data/input.csv")

---

Public API

Symbol	Type	Purpose
FileNameValidator.is_valid(name)	classmethod	Check if a filename is valid
FileNameValidator.validate(name)	classmethod	Validate filename, raise ValueError if invalid
FileId.is_valid(file_id)	staticmethod	Check if a POSIX file ID is valid
FileId.validate(file_id)	staticmethod	Validate file ID, raise ValueError if invalid
FileId.resolve_path(file_id, base_dir)	staticmethod	Resolve file ID to absolute path
FileId.get_file_id(file_path, base_dir)	staticmethod	Extract file ID from absolute path
abs_path(fp)	function	Convert to absolute resolved Path
validate_file_access(fp)	function	Validate file exists and is readable
validate_folder_access(fp)	function	Validate directory exists
resolve_path(path, base_dir)	function	Resolve path relative to base directory

---

Documentation

If you want to…	Read
Get started using the package	Quick Start above
Understand the concepts and design decisions	docs/design.md
Navigate and understand the source	docs/source-guide.md
Look up a specific function or type	docs/api.md