URL Composition Helpers

A small utility module for composing and inspecting URLs using robust URL and path helpers.

Capabilities

Resolve relative resource paths

• Given base https://example.com/api/v1/ and relative ../users?active=1, return https://example.com/users?active=1 after resolving the parent directory. @test
• Given base https://example.com/app and relative ./health, return https://example.com/health while preserving scheme and host. @test

Build paths from segments

• Joining base path /api with segments ["v2", "users", "42"] yields /api/v2/users/42. @test
• Joining base path / with segments ["blog", "", "posts", "..", "2024", "10"] produces /blog/posts/2024/10 after normalizing empty and parent segments. @test

Trim trailing segments safely

• Removing the last 2 segments from /api/v2/users/42/profile returns /api/v2/users. @test

Split URL into components

• Splitting https://demo.local:3000/base/path?q=1#frag yields scheme https, hostname demo.local, port 3000, path /base/path, query q=1, fragment frag. @test
• Splitting http://example.com yields scheme http, hostname example.com, no port, empty path, empty query, and empty fragment. @test

Implementation

@generates

API

from typing import Dict, Iterable, Optional

def resolve_relative(base_url: str, relative_path: str) -> str:
    """Return an absolute URL string after applying the relative path to the base URL."""

def join_segments(base_path: str, segments: Iterable[str]) -> str:
    """Return a normalized path string starting from base_path with provided segments appended."""

def trim_segments(path: str, drop_count: int) -> str:
    """Return a path string with the specified number of trailing segments removed (never below root)."""

def split_components(url: str) -> Dict[str, Optional[str]]:
    """Return a mapping with keys: scheme, username, password, hostname, port, path, query, fragment."""

Dependencies { .dependencies }

furl { .dependency }

Provides low-level URL joining, splitting, and path segment handling utilities.