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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.