Metadata-Version: 2.4
Name: vcti-path
Version: 1.2.0
Summary: Safe path handling for VCollab applications
Author: Visual Collaboration Technologies Inc.
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://github.com/vcollab/vcti-python-path
Project-URL: Changelog, https://github.com/vcollab/vcti-python-path/blob/main/CHANGELOG.md
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy; extra == "typecheck"
Dynamic: license-file

# 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

```bash
pip install vcti-path
```

### In `requirements.txt`

```
vcti-path>=1.2.0
```

### In `pyproject.toml` dependencies

```toml
dependencies = [
    "vcti-path>=1.2.0",
]
```

---

## Quick Start

### Validate filenames

```python
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](docs/design.md#filename-validation-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 `../`.

```python
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](docs/design.md#file-ids) for the full rules.

### Path resolution and access validation

```python
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](#quick-start) above |
| Understand the concepts and design decisions | [docs/design.md](docs/design.md) |
| Navigate and understand the source | [docs/source-guide.md](docs/source-guide.md) |
