file-path-validator 3.1.0

A package for validating file paths across different operating systems and storage services.

🎉 File Path Validator (FPV) Library Documentation

Overview

The File Path Validator (FPV) library is a robust solution for validating and cleaning file paths to ensure compliance with platform-specific naming restrictions and length limits. FPV supports both operating systems and cloud storage providers, enabling seamless path validation across diverse environments.

Many cloud storage providers strive to enforce compliance with OS-specific rules, but not all do so reliably. For instance, Google Drive syncs with Windows, requiring paths to meet Windows-specific rules, yet lacks strict enforcement on its end. FPV can bridge this gap, offering cross-platform path validation ahead of time to avoid runtime failures.

---

Why Choose FPV?

(From Logan - Creator of FPV):
"At my company, we often generate file paths for clients from a mix of disjointed data sources. This can result in messy file path strings that may fail at the storage provider or OS level. FPV ensures our paths are flagged with actionable error messages early on.

For those who prefer automation, FPV's cleaning functionality can attempt to fix paths proactively. Whether you're debugging paths manually or streamlining cleanup, FPV has been a game-changer for us. I hope you find it equally helpful!"

---

🚀 Installation

Install the FPV library via pip:

pip install file-path-validator

---

Supported Platforms & Providers 🌐

🖥️ Operating Systems

• Windows
• macOS
• Linux

☁️ Cloud Storage Providers

• Dropbox
• Box
• Egnyte
• OneDrive
• SharePoint
• ShareFile

Each class inherits from FPV_Base, defining unique validation and cleaning rules tailored to the platform or provider while leveraging the library's core functionality.

---

🛠️ Key Features and Usage Examples

Core Arguments

FPV provides several configuration options for fine-grained control:

• auto_clean: Attempts to clean paths before validation. If issues remain unresolved after cleaning, an error is raised. Defaults to False.
• auto_validate: Automatically validates the path or parts upon modification. Defaults to True.
• relative: Determines if the path is treated as relative (True) or absolute (False). Some service classes enforce a specific behavior (e.g., macOS paths are always relative).
• file_added: Explicitly specify if the path includes a file. The library avoids assumptions about the last path part, requiring this flag for clarity.
• sep: Specifies the path separator (e.g., "/" for POSIX, "\\" for Windows). Service classes provide defaults but allow overrides.

---

Dynamic Path Building Example

from FPV import FPV_Windows

def dynamic_path_demo():
    # Instantiate the validator
    validator = FPV_Windows("C:\\", relative=False)

    # Add parts dynamically
    validator.add_part("NewFolder")
    validator.add_part("AnotherFolder")
    validator.add_part("file.txt", is_file=True)

    # Validate the dynamic path
    try:
        validator.validate()
        print("Path is valid:", validator.get_full_path())
    except ValueError as e:
        print("Validation Error:", e)

    # Review issues and actions
    print("Issues Log:", validator.get_logs()["issues"])
    print("Actions Log:", validator.get_logs()["actions"])

dynamic_path_demo()

---

Logs and Action Handling

• Issues Log: Tracks path non-compliance (e.g., invalid characters, excessive length). Use get_logs()["issues"] or methods like get_issues_for_part(index) for targeted inspection.
• Actions Log: Suggests fixes (e.g., truncations, character removals). Use get_logs()["actions"] or get_pending_actions_for_part(index) for a step-by-step cleaning recipe.

Example:

issues = validator.get_logs()["issues"]
actions = validator.get_logs()["actions"]

# Apply actions manually if needed
for action in actions:
    print(f"Action: {action['reason']} - Details: {action['details']}")

---

Basic Example

from FPV import FPV_Windows

example_path = "C:/ Broken/ **path/to/||file . txt"
validator = FPV_Windows(example_path, relative=True, sep='/')

try:
    # Validate the path
    validator.validate()
    print("Path is valid!")
except ValueError as e:
    print("Validation Error:", e)

# Clean the path
cleaned_path = validator.clean()
print("Cleaned Path:", cleaned_path)

---

Recommendations for Error Handling

Wrap cleaning and validation calls in a try-except block to gracefully handle exceptions:

try:
    cleaned_path = validator.clean()
    print("Cleaned Path:", cleaned_path)
except ValueError as e:
    print("Cleaning Error:", e)

---

🌐 REST API

FPV includes a high-performance REST API built with Quart (async Flask-compatible framework) for easy integration into web applications and microservices.

API Features

• Async Processing: Handles hundreds of concurrent requests efficiently
• Python 3.13+ Compatible: No Pydantic dependencies
• JSON Request/Response: Simple REST interface
• CORS Enabled: Works with web applications
• Health Monitoring: Built-in health check endpoint

Quick Start

1. Run the API Server

# Method 1: Using the provided script
python run_api.py

# Method 2: Direct execution
python FPV/API/api.py

The server starts on http://localhost:8000

2. API Endpoints

Base URL: http://localhost:8000/api/v1

Validate Path (POST /isValid)

Validates a file path according to the specified service's rules.

curl -X POST "http://localhost:8000/api/v1/isValid" \
     -H "Content-Type: application/json" \
     -d '{
       "service": "dropbox",
       "path": "/Documents/test.txt",
       "file_added": true
     }'

Response:

{
  "success": true,
  "is_valid": true,
  "issues": [],
  "logs": {"actions": [], "issues": []},
  "error": null
}

Clean Path (POST /clean)

Cleans a file path by applying platform-specific fixes.

curl -X POST "http://localhost:8000/api/v1/clean" \
     -H "Content-Type: application/json" \
     -d '{
       "service": "windows",
       "path": "C:\\Test<Folder>\\file*.txt",
       "relative": false,
       "file_added": true
     }'

Response:

{
  "success": true,
  "cleaned_path": "C:\\TestFolder\\file.txt",
  "logs": {
    "actions": [
      {
        "type": "action",
        "category": "INVALID_CHAR",
        "subtype": "MODIFY",
        "details": {
          "original": "Test<Folder>",
          "new_value": "TestFolder",
          "index": 1
        },
        "reason": "Removed invalid characters."
      }
    ],
    "issues": []
  },
  "error": null
}

Dynamic Path Building Endpoints

For applications like ByteWave that need to build paths incrementally with real-time validation:

Add Path Part (POST /path/add)

Adds one or more path parts to an existing path with incremental validation.

curl -X POST "http://localhost:8000/api/v1/path/add" \
     -H "Content-Type: application/json" \
     -d '{
       "service": "windows",
       "base_path": "C:\\Users\\golde",
       "parts": ["Documents"],
       "errors": [],
       "validate": true,
       "relative": false,
       "file_added": false
     }'

Response:

{
  "success": true,
  "updated_path": "C:\\Users\\golde\\Documents",
  "new_errors": [],
  "all_errors": [],
  "path_parts": ["C:", "Users", "golde", "Documents"],
  "error": null
}

Remove Path Part (POST /path/remove)

Removes a path part and updates the error state accordingly.

curl -X POST "http://localhost:8000/api/v1/path/remove" \
     -H "Content-Type: application/json" \
     -d '{
       "service": "windows",
       "base_path": "C:\\Users\\golde\\Documents",
       "part_index": 2,
       "errors": [],
       "relative": false,
       "file_added": false
     }'

Response:

{
  "success": true,
  "updated_path": "C:\\Users\\Documents",
  "remaining_errors": [],
  "removed_part": "golde",
  "path_parts": ["C:", "Users", "Documents"],
  "error": null
}

Build Path Incrementally (POST /path/build)

Builds a complete path step by step with full validation tracking.

curl -X POST "http://localhost:8000/api/v1/path/build" \
     -H "Content-Type: application/json" \
     -d '{
       "service": "dropbox",
       "root_path": "/",
       "path_parts": ["Documents", "Work", "Reports", "Q4_Report.pdf"],
       "relative": true,
       "file_added": true
     }'

Response:

{
  "success": true,
  "final_path": "/Documents/Work/Reports/Q4_Report.pdf",
  "all_errors": [],
  "step_errors": [
    {
      "step": 1,
      "part": "Documents",
      "issues": []
    },
    {
      "step": 2,
      "part": "Work",
      "issues": []
    },
    {
      "step": 3,
      "part": "Reports",
      "issues": []
    },
    {
      "step": 4,
      "part": "Q4_Report.pdf",
      "issues": []
    }
  ],
  "path_parts": ["", "Documents", "Work", "Reports", "Q4_Report.pdf"],
  "error": null
}

3. Request Parameters

Basic Endpoints (/isValid, /clean)

Parameter	Type	Required	Default	Description
service	string	Yes	-	Service/platform name (windows, macos, linux, dropbox, box, egnyte, onedrive, sharepoint, sharefile)
path	string	Yes	-	File path to validate/clean
relative	boolean	No	true	Whether the path is relative (true) or absolute (false)
file_added	boolean	No	false	Whether the path includes a file
sep	string	No	platform default	Path separator (e.g., "/", "\")

Dynamic Path Building Endpoints

/path/add Parameters

Parameter	Type	Required	Default	Description
service	string	Yes	-	Service/platform name
base_path	string	Yes	-	Current path to add parts to
parts	array	Yes	-	Array of path parts to add
errors	array	No	[]	Current error state
validate	boolean	No	true	Whether to validate new parts
relative	boolean	No	true	Whether the path is relative
file_added	boolean	No	false	Whether the path includes a file
sep	string	No	platform default	Path separator

/path/remove Parameters

Parameter	Type	Required	Default	Description
service	string	Yes	-	Service/platform name
base_path	string	Yes	-	Current path to remove part from
part_index	integer	Yes	-	Index of part to remove (0-based)
errors	array	No	[]	Current error state
relative	boolean	No	true	Whether the path is relative
file_added	boolean	No	false	Whether the path includes a file
sep	string	No	platform default	Path separator

/path/build Parameters

Parameter	Type	Required	Default	Description
service	string	Yes	-	Service/platform name
root_path	string	Yes	-	Root path to start from
path_parts	array	Yes	-	Array of path parts to add sequentially
relative	boolean	No	true	Whether the path is relative
file_added	boolean	No	false	Whether the path includes a file
sep	string	No	platform default	Path separator

4. Python Client Example

import requests

# Validate a path
response = requests.post("http://localhost:8000/api/v1/isValid", json={
    "service": "dropbox",
    "path": "/Documents/test.txt",
    "file_added": True
})
result = response.json()
print(f"Path is valid: {result['is_valid']}")

# Clean a path
response = requests.post("http://localhost:8000/api/v1/clean", json={
    "service": "windows",
    "path": "C:\\Test<Folder>\\file*.txt",
    "relative": False,
    "file_added": True
})
result = response.json()
print(f"Cleaned path: {result['cleaned_path']}")

5. ByteWave Integration Benefits

The dynamic path building endpoints are specifically designed for applications like ByteWave that need to build paths incrementally:

🚀 Performance Advantages:

• O(1) per path part: Only validate new parts, not entire paths
• Incremental validation: Skip redundant calculations
• State management: Client maintains lightweight path state
• Async-friendly: Non-blocking operations for UI responsiveness

💡 Use Cases:

• Real-time path building: Validate as user types
• Drag-and-drop interfaces: Add/remove folders dynamically
• Batch operations: Build complex paths efficiently
• Cross-platform validation: Same API for all storage providers

🔧 Implementation Strategy:

# ByteWave can maintain minimal state:
class PathBuilder:
    def __init__(self, service="windows"):
        self.service = service
        self.path_parts = []
        self.errors = []
    
    def add_part(self, part):
        # Call /path/add API
        # Update local state
        # Return new errors only
        pass
    
    def remove_part(self, index):
        # Call /path/remove API
        # Update local state
        # Return remaining errors
        pass

6. Performance

The API is optimized for high-throughput scenarios:

• Concurrent Requests: Handles hundreds of requests per second
• Async Processing: Non-blocking I/O for better performance
• Memory Efficient: Minimal overhead for in-memory path processing
• Localhost Optimized: Fast response times for local deployments
• Incremental Validation: Only process new path parts, not entire paths

---

⚙️ Key Methods

• validate(): Validates the entire path. Raises ValueError if issues are found unless raise_error=False is explicitly set.
• clean(): Cleans the path to meet compliance rules, applying fixes from the action log. Raises errors for unresolved issues if raise_error=True.

---

Limitations and Future Plans

• Missing Features: SharePoint site URLs and encoded paths are not yet supported.
• Network Drives: Windows network drive root validation is not supported (though non-root parts are fully validated).
• User-Defined Order: Cleaning/validation order cannot yet be customized but can be manually controlled.

---

🤝 Contributing Guidelines

We welcome contributions! Please adhere to the following:

• Testing: Include unit tests for all new features or bug fixes.
• Standards: Ensure code follows PEP-8 standards or run a linter before submission.
• Pull Requests: Clearly describe your changes and their purpose.

Thank you for helping improve FPV! 🎉