File Path to URI Converter

Build a utility that converts between filesystem paths and file URIs, with intelligent detection of input format.

Capabilities

Convert filesystem paths to file URIs

• Given an absolute path /home/user/documents/file.txt, convert it to a file URI file:///home/user/documents/file.txt @test
• Given a Windows path C:\Users\Documents\file.txt, convert it to a file URI with proper encoding @test

Convert file URIs to filesystem paths

• Given a file URI file:///home/user/documents/file.txt, convert it back to the filesystem path /home/user/documents/file.txt @test
• Given a file URI with encoded characters file:///home/user/my%20document.txt, convert it to the decoded path /home/user/my document.txt @test

Smart conversion with automatic format detection

• Given a filesystem path /home/user/file.txt, detect it's a path and convert to file URI @test
• Given a file URI file:///home/user/file.txt, detect it's already a URI and return the corresponding path @test
• Given an http URL http://example.com/file, detect it's not a file path or file URI and raise an appropriate error @test

Implementation

@generates

API

def path_to_file_uri(path: str) -> str:
    """
    Convert a filesystem path to a file:// URI.

    Args:
        path: The filesystem path to convert

    Returns:
        A file:// URI string
    """
    pass

def file_uri_to_path(uri: str) -> str:
    """
    Convert a file:// URI to a filesystem path.

    Args:
        uri: The file:// URI to convert

    Returns:
        A filesystem path string
    """
    pass

def smart_convert(uri_or_path: str) -> str:
    """
    Intelligently detect whether input is a path or URI and convert appropriately.
    If input is a path, convert to URI. If input is a file URI, convert to path.

    Args:
        uri_or_path: Either a filesystem path or a file:// URI

    Returns:
        The converted string (URI if given path, path if given URI)

    Raises:
        ValueError: If input is not a filesystem path or file:// URI
    """
    pass

Dependencies { .dependencies }

w3lib { .dependency }

Provides web-related utility functions for URL and path handling.

@satisfied-by