Skip to main content

Path Utilities

Overview

Safe path handling for VCollab applications. Its core is the file ID: a relative path such as reports/2026/summary.pdf that a web service hands to its clients to name a file or folder under the service's base directory. File IDs are safe to carry in URLs, mirror the folder structure, and mean the same file on Windows, Linux and macOS. FileId.resolve_path turns a client's ID back into a path, and rejects absolute paths, .. traversal, and symbolic links or junctions below the base directory, so a resolved ID cannot escape a base directory you trust. The package also validates file names and checks file and folder access.

This package has zero external dependencies.


Installation

pip install vcti-path

In requirements.txt

vcti-path>=1.2.0

In pyproject.toml dependencies

dependencies = [
    "vcti-path>=1.2.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.is_valid("aux.txt")        # False -- Windows device name
FileNameValidator.is_valid("report.")        # False -- trailing dot

FileNameValidator.validate("data.json")      # OK
try:
    FileNameValidator.validate("bad/name")
except ValueError as exc:
    print(exc)                               # Invalid file or directory name: 'bad/name'

The same rules apply on every platform, so a valid name works on both Windows and Linux. Every file or folder you address by file ID must follow them; see File name rules for the full list.

File IDs -- portable, URL-safe names for files under a base directory

A file ID is a relative path that names a file or directory within a base directory. Its canonical form uses / as the separator; \ is accepted as input and converted. No leading /, ./, or ../.

from pathlib import Path
from vcti.path import FileId

# Validate
FileId.is_valid("scripts/setup.sh")     # True
FileId.is_valid("scripts\\setup.sh")    # True -- "\" is a separator too
FileId.is_valid("/absolute/path")       # False
FileId.is_valid("../escape")            # False

# Convert a client-supplied path to the canonical ID before storing it
FileId.from_path("scripts\\setup.sh")
# -> "scripts/setup.sh"

# 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"

A client that puts a file ID in a URL must percent-encode each part, since names may contain #, %, spaces and similar characters. See File IDs for the full rules.

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, which must exist
resolve_path("data/input.csv", project_root)
# -> project_root / "data/input.csv", absolute

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 file ID is valid (/ or \ separators, or a PurePath)
FileId.validate(file_id) staticmethod Validate file ID, raise ValueError if invalid
FileId.from_path(file_id) staticmethod Convert a relative path to the canonical / file ID
FileId.resolve_path(file_id, base_dir) staticmethod Join file ID to base_dir (absolute if base_dir is)
FileId.get_file_id(file_path, base_dir) staticmethod Extract the canonical file ID of a path under base_dir
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

Dependencies

None. Standard library only.


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

Metadata

Release files for vcti-path 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vcti-path 1.2.0
File Size Uploaded Provenance Actions
vcti_path-1.2.0.tar.gz 22.5 kB With provenance Details for vcti_path-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vcti-path 1.2.0
File Interpreter ABI Platform Actions
vcti_path-1.2.0-py3-none-any.whl Python 3 none any Details for vcti_path-1.2.0-py3-none-any.whl

Total release size: 33.1 kB

Release files / vcti_path-1.2.0.tar.gz

Download URL vcti_path-1.2.0.tar.gz
Size 22.5 kB
Tags Source
SHA-256 checksum
How to use checksums
fd8158829243976d94038ffb9fb26d4ada8bda8c3a6c1046fac0069d5e865e22
BLAKE2b-256 checksum
How to use checksums
645d62bb25bce7d2bf05e0dc195b811a60250333325eebd1299ed8704d0de28a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / vcti_path-1.2.0-py3-none-any.whl

Download URL vcti_path-1.2.0-py3-none-any.whl
Size 10.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9ab4a5a2187e41550f30081034ba9f6e5a5a4111a3f17b9587ae22e95f0a5b30
BLAKE2b-256 checksum
How to use checksums
03829f126c861f58d54737f227726bc982e6055560fe69a3ce25aea9f9e71907
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for vcti-path 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for vcti_path-1.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page