URL Path Composer

Compose resource URLs from decoded path segments while controlling absoluteness and directory/file hints.

Capabilities

Normalizes decoded segments

• Accepts path parts provided as a string with separators or as a list of segment strings.
• Treats percent-encoded characters as literal segment content (e.g., reports%2F2024 remains one segment) and re-encodes reserved characters in the final URL.

Controls absolute vs relative paths

• When absolute is True, the resulting path starts with /; when False, it omits the leading slash; when None, the leading slash matches whether the base URL includes a network location.
• If the base includes a host, the final URL always has an absolute path regardless of the absolute flag being None.

Marks directories vs files

• When is_directory is True, the path ends with a trailing slash; when False, it omits the trailing slash even when the last segment contains dots.
• Preserves previously trailing slash semantics from the base URL unless explicitly overridden by is_directory.

Merges path segments with base

• Combines the base URL path with incoming parts, replacing the base path when parts start with a separator and appending otherwise.
• Collapses redundant slashes in the composed path while keeping empty trailing segment only when is_directory is True.

Implementation

@generates

API

from collections.abc import Sequence
from typing import Optional

def build_resource_url(base_url: str, parts: Sequence[str] | str, *, absolute: Optional[bool] = None, is_directory: bool = False) -> str:
    """Compose a URL using decoded path segments with optional absolute and directory/file hints."""

Dependencies { .dependencies }

furl { .dependency }

Provides URL parsing and path manipulation with decoded segments and absolute/dir/file flags.

Tests

• Joining base "https://files.example.com/root/" with parts ["reports", "Q1", "summary.txt"] yields https://files.example.com/root/reports/Q1/summary.txt with no trailing slash when is_directory is False. @test
• Combining base "/workspace" with parts "reports%2F2024/" and absolute=False returns workspace/reports%2F2024/ (relative with encoded slash) and retains a trailing slash when is_directory=True. @test
• Overriding absolute=True for base "./" and parts ["media", "clips", "final"] produces /media/clips/final/ when is_directory=True, ensuring redundant slashes are removed. @test