Service URL Composer

Build API request URLs from a base template with safe path joining, configurable serialization, cloning for variant URLs, and component export for logging.

Capabilities

Compose endpoint paths

• Starting from base https://api.example.com/root/ with default query token=abc, joining path segments v1, users, 42 plus extra query expand=true produces https://api.example.com/root/v1/users/42?token=abc&expand=true, and the base instance remains unchanged for reuse. @test

Custom serialization

• Given base https://api.example.com/base with query note=space here and mode=raw, serializing with delimiter ; and spaces encoded as %20 returns https://api.example.com/base?note=space%20here;mode=raw. @test

Cloning for variations

• Cloning a prepared URL such as https://api.example.com/root?token=abc and then adding debug=true to only the original results in different outputs: the clone keeps https://api.example.com/root?token=abc while the original becomes https://api.example.com/root?token=abc&debug=true. @test

Component export

• Exporting the composed URL from the first scenario returns a dictionary with scheme https, host api.example.com, port 443, path segments ['root', 'v1', 'users', '42'], and ordered query pairs [('token', 'abc'), ('expand', 'true')]. @test

Implementation

@generates

API

class ServiceUrl:
    def __init__(self, base_url: str, default_query: dict[str, str] | None = None): ...
    def compose(self, *segments: str, query: dict[str, str] | None = None) -> "ServiceUrl": ...
    def as_string(self, delimiter: str = "&", quote_plus: bool = True, dont_quote: str = "") -> str: ...
    def clone(self) -> "ServiceUrl": ...
    def to_record(self) -> dict: ...

Dependencies { .dependencies }

furl { .dependency }

Python URL manipulation utility for building, joining, copying, and serializing URLs.