URL Mutation Recipe

Transforms a base URL string according to a structured recipe of additive, overriding, and removal steps on its path, query string, and optional fragment. Operations run in order: append path segments, add query entries, override specific query keys, remove disallowed query keys, then optionally repeat the same add/set/remove sequence for fragment path/query while preserving any untouched components. String values for query/fragment entries count as single values; sequences of strings create repeated parameters in the given order. Unspecified URL components remain unchanged from the base URL.

Capabilities

Applies additive path and query updates

• Starting from https://example.com/base?foo=1&keep=ok, with path_segments=["dashboards","sales"], query_appends={"tag": ["north","west"], "keep": "ok"}, query_overrides={"foo": "9", "view": "summary"}, query_removals=["keep"], and no fragment recipe, the function returns https://example.com/base/dashboards/sales?foo=9&view=summary&tag=north&tag=west. @test

Merges overrides and removals in order

• Starting from https://service.test/app?mode=old&token=x&drop=1, with path_segments=["reports"], query_appends={"token": ["x","y"]}, query_overrides={"mode": "new"}, query_removals=["drop","token"], and no fragment recipe, the function returns https://service.test/app/reports?mode=new. @test

Updates fragment path and query

• Starting from https://shop.example.com/products?session=keep#filters?color=red&debug=1, with path_segments=["summer"], query_appends={"promo": "flash"}, query_overrides={"session": "stay"}, query_removals=["session"], and a fragment recipe of {"path_segments":["active"],"add_query":{"color":["blue"]},"set_query":{"sort":"price"},"remove_query":["debug"]}, the function returns https://shop.example.com/products/summer?session=stay&promo=flash#filters/active?color=red&color=blue&sort=price. @test

Implementation

@generates

API

from typing import Iterable, Mapping, Optional, Sequence, TypedDict, Union

QueryValue = Union[str, Sequence[str]]
QueryMap = Mapping[str, QueryValue]

class FragmentRecipe(TypedDict, total=False):
    path_segments: Sequence[str]
    add_query: QueryMap
    set_query: QueryMap
    remove_query: Iterable[str]

def apply_url_recipe(
    base_url: str,
    path_segments: Sequence[str],
    query_appends: QueryMap,
    query_overrides: QueryMap,
    query_removals: Iterable[str],
    fragment: Optional[FragmentRecipe] = None,
) -> str:
    """Return a URL string after applying additive, overriding, and removal steps to path, query, and fragment."""

Dependencies { .dependencies }

furl { .dependency }

Provides URL parsing and inline component mutation helpers.