scalekit-sdk-python 2.21.0__tar.gz → 2.23.0__tar.gz

{scalekit_sdk_python-2.21.0/scalekit_sdk_python.egg-info → scalekit_sdk_python-2.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scalekit-sdk-python
-Version: 2.21.0
+Version: 2.23.0
 Summary: Scalekit official Python SDK
 Home-page: https://github.com/scalekit-inc/scalekit-sdk-python
 Author: Team Scalekit
@@ -15,6 +15,7 @@ Requires-Dist: grpcio<2.0,>=1.81.0
 Requires-Dist: protobuf<8.0.0,>=5.29.5
 Requires-Dist: google>=3.0
 Requires-Dist: requests>=2.34.0
+Requires-Dist: urllib3<3,>=1.26
 Requires-Dist: PyJWT>=2.13.0
 Requires-Dist: cffi>=1.15.1
 Requires-Dist: cryptography>=50.0.0
@@ -60,7 +61,7 @@ Dynamic: summary
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python versions](https://img.shields.io/pypi/pyversions/scalekit-sdk-python.svg?style=flat-square)](https://pypi.org/project/scalekit-sdk-python/)
 
-<a href="https://scalekit.com" target="_blank" rel="noopener noreferrer">Scalekit</a> provides auth and actions on behalf of users, with 500+ connectors and 20,000+ tools. Build secure AI products faster with authentication for humans (SSO, passwordless, full-stack auth) and agents (MCP/APIs, delegated actions), all unified on one platform. This Python SDK enables both traditional B2B authentication and cutting-edge agentic workflows.
+<a href="https://scalekit.com" target="_blank" rel="noopener noreferrer">Scalekit</a> provides auth and actions on behalf of users, with 600+ connectors and 35,000+ tools. Build secure AI products faster with authentication for humans (SSO, passwordless, full-stack auth) and agents (MCP/APIs, delegated actions), all unified on one platform. This Python SDK enables both traditional B2B authentication and cutting-edge agentic workflows.
 
 ## 🤖 Agent-First Features
 

{scalekit_sdk_python-2.21.0 → scalekit_sdk_python-2.23.0}/README.md

@@ -13,7 +13,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python versions](https://img.shields.io/pypi/pyversions/scalekit-sdk-python.svg?style=flat-square)](https://pypi.org/project/scalekit-sdk-python/)
 
-<a href="https://scalekit.com" target="_blank" rel="noopener noreferrer">Scalekit</a> provides auth and actions on behalf of users, with 500+ connectors and 20,000+ tools. Build secure AI products faster with authentication for humans (SSO, passwordless, full-stack auth) and agents (MCP/APIs, delegated actions), all unified on one platform. This Python SDK enables both traditional B2B authentication and cutting-edge agentic workflows.
+<a href="https://scalekit.com" target="_blank" rel="noopener noreferrer">Scalekit</a> provides auth and actions on behalf of users, with 600+ connectors and 35,000+ tools. Build secure AI products faster with authentication for humans (SSO, passwordless, full-stack auth) and agents (MCP/APIs, delegated actions), all unified on one platform. This Python SDK enables both traditional B2B authentication and cutting-edge agentic workflows.
 
 ## 🤖 Agent-First Features
 

scalekit_sdk_python-2.23.0/scalekit/__init__.py

@@ -0,0 +1,22 @@
+
+from scalekit.client import ScalekitClient
+from scalekit.common.scalekit import CodeAuthenticationOptions, AuthorizationUrlOptions
+from scalekit.actions.models.trigger_event import (
+    DeliveryScope,
+    DetectionMode,
+    PayloadState,
+    TriggerEvent,
+)
+from scalekit.actions.triggers import HeadersLike, verify_trigger_event
+
+__all__ = [
+    'ScalekitClient',
+    'AuthorizationUrlOptions',
+    'CodeAuthenticationOptions',
+    'DeliveryScope',
+    'DetectionMode',
+    'HeadersLike',
+    'PayloadState',
+    'TriggerEvent',
+    'verify_trigger_event',
+]

scalekit_sdk_python-2.23.0/scalekit/_convert.py

@@ -0,0 +1,163 @@
+"""Private converters between protobuf values and SDK types.
+
+One place for the rules every SDK-owned model follows: timestamps are read only when
+the field is present and come out as timezone-aware UTC ``datetime``; inputs must be
+timezone-aware; enum values the SDK does not know never raise; durations are
+``timedelta``. Nothing here imports the rest of the SDK, so any module can use it.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from datetime import date, datetime, timedelta, timezone
+from enum import Enum
+from typing import TypeVar
+
+from google.protobuf.internal.enum_type_wrapper import EnumTypeWrapper
+from google.protobuf.message import Message
+from google.protobuf.timestamp_pb2 import Timestamp
+
+__all__ = [
+    "date_to_str",
+    "datetime_to_timestamp",
+    "enum_from_proto",
+    "enum_to_proto",
+    "require",
+    "seconds_from_proto",
+    "str_list",
+    "timedelta_to_seconds",
+    "timestamp_from_proto",
+]
+
+_E = TypeVar("_E", bound=Enum)
+_CAMEL_BOUNDARY = re.compile(r"(?<!^)(?=[A-Z])")
+_ISO_DATE = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}")
+_ONE_SECOND = timedelta(seconds=1)
+
+
+def require(name: str, value: object) -> None:
+    """Raise ``ValueError`` when a required identifier is missing or empty."""
+    if value is None or value == "":
+        raise ValueError(f"{name} is required")
+
+
+def str_list(name: str, values: Sequence[str]) -> list[str]:
+    """Copy ``values`` into a list, refusing a bare ``str`` (which would split into characters)."""
+    if isinstance(values, (str, bytes)):
+        raise TypeError(f"{name} must be a list of strings, not a single string")
+    return list(values)
+
+
+def _enum_prefix(wrapper: EnumTypeWrapper) -> str:
+    """``TriggerDeliveryStatus`` -> ``"TRIGGER_DELIVERY_STATUS_"``."""
+    return _CAMEL_BOUNDARY.sub("_", wrapper.DESCRIPTOR.name).upper() + "_"
+
+
+def enum_from_proto(enum_cls: type[_E], wrapper: EnumTypeWrapper, value: int) -> _E | str | None:
+    """Convert a proto enum number to an SDK enum member.
+
+    ``0`` (the ``*_UNSPECIFIED`` value) becomes ``None``. A value the generated code
+    knows is looked up by its name without the ``<ENUM_NAME>_`` prefix; when the SDK
+    enum has no such member, that name is returned as a plain ``str``. A number the
+    generated code does not know is returned as ``str(value)``. Never raises.
+    """
+    if value == 0:
+        return None
+    try:
+        name: str = wrapper.Name(value)
+    except ValueError:
+        return str(value)
+    name = name.removeprefix(_enum_prefix(wrapper))
+    try:
+        return enum_cls[name]
+    except KeyError:
+        return name
+
+
+def enum_to_proto(wrapper: EnumTypeWrapper, value: Enum | str | int, field: str) -> int:
+    """Encode an enum member, a value name or a raw number as a proto enum number.
+
+    Names are accepted with or without the ``<ENUM_NAME>_`` prefix. A raw ``int`` is
+    sent as is, so values newer than this SDK can still be sent. Raises ``ValueError``
+    for a name the generated code does not know (it cannot be encoded).
+    """
+    if isinstance(value, bool):
+        raise TypeError(f"{field} must be an enum member, a name or an int, not bool")
+    if isinstance(value, Enum):
+        name = value.name
+    elif isinstance(value, str):
+        name = value
+    elif isinstance(value, int):
+        return value
+    else:
+        raise TypeError(f"{field} must be an enum member, a name or an int")
+    prefix = _enum_prefix(wrapper)
+    for candidate in (name, prefix + name):
+        try:
+            number: int = wrapper.Value(candidate)
+        except ValueError:
+            continue
+        return number
+    known = ", ".join(
+        v.name.removeprefix(prefix) for v in wrapper.DESCRIPTOR.values if v.number != 0
+    )
+    raise ValueError(f"unknown {field} {value!r}; expected one of: {known}, or an int")
+
+
+def timestamp_from_proto(message: Message, field: str) -> datetime | None:
+    """Read a ``Timestamp`` field as aware UTC ``datetime``; ``None`` when it is unset."""
+    if not message.HasField(field):
+        return None
+    result: datetime = getattr(message, field).ToDatetime(tzinfo=timezone.utc)
+    return result
+
+
+def datetime_to_timestamp(value: datetime, field: str) -> Timestamp:
+    """Encode an aware ``datetime`` as a ``Timestamp``; naive values raise ``ValueError``."""
+    if not isinstance(value, datetime):
+        raise TypeError(f"{field} must be a datetime, got {type(value).__name__}")
+    if value.tzinfo is None or value.utcoffset() is None:
+        raise ValueError(f"{field} must be timezone-aware, for example datetime.now(timezone.utc)")
+    timestamp = Timestamp()
+    timestamp.FromDatetime(value.astimezone(timezone.utc))
+    return timestamp
+
+
+def seconds_from_proto(seconds: int) -> timedelta | None:
+    """A whole-seconds proto integer as ``timedelta``; ``0`` (not set) becomes ``None``."""
+    return timedelta(seconds=seconds) if seconds else None
+
+
+def timedelta_to_seconds(value: timedelta, field: str) -> int:
+    """Encode a ``timedelta`` as whole seconds; a fractional second raises ``ValueError``."""
+    if not isinstance(value, timedelta):
+        raise TypeError(f"{field} must be a timedelta, got {type(value).__name__}")
+    if value % _ONE_SECOND:
+        raise ValueError(f"{field} must be a whole number of seconds, got {value!r}")
+    return value // _ONE_SECOND
+
+
+def date_to_str(value: date | str, field: str) -> str:
+    """Encode a calendar date as ``YYYY-MM-DD``.
+
+    A ``date`` is used as is; an aware ``datetime`` is converted to its UTC date (a
+    naive one raises ``ValueError``); a ``str`` must already be a real ``YYYY-MM-DD``
+    date.
+    """
+    if isinstance(value, datetime):
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError(f"{field} must be a date or a timezone-aware datetime")
+        return value.astimezone(timezone.utc).date().isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, str):
+        if _ISO_DATE.fullmatch(value):
+            try:
+                date.fromisoformat(value)
+            except ValueError:
+                pass
+            else:
+                return value
+        raise ValueError(f"{field} must be a YYYY-MM-DD date, got {value!r}")
+    raise TypeError(f"{field} must be a date or a YYYY-MM-DD string, got {type(value).__name__}")

{scalekit_sdk_python-2.21.0 → scalekit_sdk_python-2.23.0}/scalekit/_version.py

@@ -1,3 +1,3 @@
 # Single source of truth for the SDK version.
 # Import this in setup.py and scalekit/core.py — never hardcode the version elsewhere.
-__version__ = "2.21.0"
+__version__ = "2.23.0"

scalekit_sdk_python-2.23.0/scalekit/actions/__init__.py

@@ -0,0 +1,112 @@
+from .actions import ActionClient
+from .models.trigger_event import DeliveryScope, DetectionMode, PayloadState, TriggerEvent
+from .models.triggers import (
+    AccountHealth,
+    AccountHealthAction,
+    AccountHealthState,
+    AvailableTrigger,
+    BatchCreateTriggerSubscriptionResult,
+    BatchCreateTriggerSubscriptionsResponse,
+    BatchDeleteTriggerSubscriptionResult,
+    BatchDeleteTriggerSubscriptionsResponse,
+    BatchLookupTriggerDeliveriesResponse,
+    BatchLookupTriggerDeliveryResult,
+    BatchResendTriggerDeliveriesResponse,
+    BatchResendTriggerDeliveryResult,
+    ConfigField,
+    EligibleAccount,
+    GenerateTriggerSigningSecretResponse,
+    GetTriggerActivityResponse,
+    GetTriggerUsageResponse,
+    ListAvailableTriggersResponse,
+    ListEligibleAccountsResponse,
+    ListTriggerDeliveriesByEndpointResponse,
+    ListTriggerDeliveryAttemptsByEndpointResponse,
+    ListTriggerDeliveryAttemptsByMessageResponse,
+    ListTriggerSubscriptionsResponse,
+    LookupTriggerDeliveryResponse,
+    RecoverTriggerDeliveriesResponse,
+    RequiredScope,
+    TriggerDelivery,
+    TriggerDeliveryAttempt,
+    TriggerDeliveryAttemptStatus,
+    TriggerDeliveryAttemptTriggerType,
+    TriggerDeliveryLookupOutcome,
+    TriggerDeliveryResendOutcome,
+    TriggerDeliveryResendTarget,
+    TriggerDeliveryResendTargetParam,
+    TriggerDeliveryStatus,
+    TriggerIngressEndpoint,
+    TriggerPlatformCredentials,
+    TriggerPollErrorCode,
+    TriggerPollState,
+    TriggerRefusalCode,
+    TriggerSubscribeOutcome,
+    TriggerSubscription,
+    TriggerSubscriptionDeleteOutcome,
+    TriggerSubscriptionStatus,
+    TriggerUsageBucket,
+    TriggerUsageDay,
+    TriggerUsageHour,
+    TriggerUsagePeriod,
+)
+from .triggers import ActionTriggers, HeadersLike, verify_trigger_event
+
+__all__ = [
+    'AccountHealth',
+    'AccountHealthAction',
+    'AccountHealthState',
+    'ActionClient',
+    'ActionTriggers',
+    'AvailableTrigger',
+    'BatchCreateTriggerSubscriptionResult',
+    'BatchCreateTriggerSubscriptionsResponse',
+    'BatchDeleteTriggerSubscriptionResult',
+    'BatchDeleteTriggerSubscriptionsResponse',
+    'BatchLookupTriggerDeliveriesResponse',
+    'BatchLookupTriggerDeliveryResult',
+    'BatchResendTriggerDeliveriesResponse',
+    'BatchResendTriggerDeliveryResult',
+    'ConfigField',
+    'DeliveryScope',
+    'DetectionMode',
+    'EligibleAccount',
+    'GenerateTriggerSigningSecretResponse',
+    'GetTriggerActivityResponse',
+    'GetTriggerUsageResponse',
+    'HeadersLike',
+    'ListAvailableTriggersResponse',
+    'ListEligibleAccountsResponse',
+    'ListTriggerDeliveriesByEndpointResponse',
+    'ListTriggerDeliveryAttemptsByEndpointResponse',
+    'ListTriggerDeliveryAttemptsByMessageResponse',
+    'ListTriggerSubscriptionsResponse',
+    'LookupTriggerDeliveryResponse',
+    'PayloadState',
+    'RecoverTriggerDeliveriesResponse',
+    'RequiredScope',
+    'TriggerDelivery',
+    'TriggerDeliveryAttempt',
+    'TriggerDeliveryAttemptStatus',
+    'TriggerDeliveryAttemptTriggerType',
+    'TriggerDeliveryLookupOutcome',
+    'TriggerDeliveryResendOutcome',
+    'TriggerDeliveryResendTarget',
+    'TriggerDeliveryResendTargetParam',
+    'TriggerDeliveryStatus',
+    'TriggerEvent',
+    'TriggerIngressEndpoint',
+    'TriggerPlatformCredentials',
+    'TriggerPollErrorCode',
+    'TriggerPollState',
+    'TriggerRefusalCode',
+    'TriggerSubscribeOutcome',
+    'TriggerSubscription',
+    'TriggerSubscriptionDeleteOutcome',
+    'TriggerSubscriptionStatus',
+    'TriggerUsageBucket',
+    'TriggerUsageDay',
+    'TriggerUsageHour',
+    'TriggerUsagePeriod',
+    'verify_trigger_event',
+]

scalekit_sdk_python-2.23.0/scalekit/actions/_proxy_path.py

@@ -0,0 +1,254 @@
+"""Keep ``ActionClient.request`` and its credentials inside the Scalekit HTTP proxy.
+
+``ActionClient.request`` sends every call to ``{env_url}/proxy{path}`` with the
+client's bearer token and the connection headers. This module
+
+* verifies, before anything is sent, that the server will route the path under
+  ``<env base path>/proxy/`` (``ensure_under_proxy_prefix``), and
+* removes those credentials from any redirect hop whose target is outside that
+  prefix (``ProxySession``), while following redirects exactly as ``requests``
+  does.
+
+It never rewrites a URL: a request that passes is sent exactly as built.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import re
+from collections.abc import Callable
+from typing import cast
+from urllib.parse import unquote
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.exceptions import LocationParseError
+from urllib3.util import parse_url
+
+_PROXY_PREFIX = "/proxy/"
+
+_VALID_ESCAPE_RE = re.compile(r"%[0-9A-Fa-f]{2}")
+
+# Headers request() adds that identify the caller to Scalekit. Header names are
+# case-insensitive in requests, so "Connection_name" is covered too.
+_CREDENTIAL_HEADERS = ("Authorization", "connection_name", "identifier")
+
+# Typed handles on two requests.Session methods. Some stub distributions
+# (types-requests) declare them without annotations; calling them through these
+# keeps strict type checking without suppressions.
+_session_rebuild_auth = cast(
+    "Callable[[requests.Session, requests.PreparedRequest, requests.Response], None]",
+    requests.Session.rebuild_auth,
+)
+_session_should_strip_auth = cast(
+    "Callable[[requests.Session, str, str], bool]",
+    requests.Session.should_strip_auth,
+)
+# Only asked for request-targets (request_url); it never sends anything.
+_URL_ADAPTER = HTTPAdapter()
+
+# A proxy for every URL: request_url uses only whether one applies and its scheme.
+_ANY_FORWARD_PROXY = {"all": "http://forward-proxy.invalid"}
+
+_OUTSIDE_PROXY_MESSAGE = (
+    "path must resolve under the proxy prefix: start it with '/' and do not let '..' "
+    "segments (including percent-encoded or backslash forms) climb above it"
+)
+
+
+def ensure_under_proxy_prefix(env_url: str, url: str) -> None:
+    r"""Raise ``ValueError`` if the server would route ``url`` outside ``<base>/proxy/``.
+
+    The check starts from the path ``requests`` actually sends for ``url``
+    (``requests`` and ``urllib3`` may already have removed dot segments or
+    decoded ``%2e``). For a URL that is not ``https``, a forward proxy may be
+    used: ``requests`` then hands ``urllib3`` the absolute URL, and both
+    rebuild it (dropping an empty ``;`` parameter, removing dot segments
+    again), so that path is checked as well.
+    Each path is percent-decoded once and cleaned as Go
+    routers clean it (``clean_path``): runs of ``/`` collapse and dot
+    segments are resolved. This is done twice, as is and with ``\`` treated as
+    ``/``, and each result must equal ``<base>/proxy`` or start with
+    ``<base>/proxy/``. ``<base>`` is the path of ``env_url``, usually empty.
+
+    Args:
+        env_url: The environment URL the client was configured with, for
+            example ``"https://acme.scalekit.cloud"`` or
+            ``"https://host/base"``.
+        url: The full URL ``request()`` is about to send, built as
+            ``env_url.rstrip("/") + "/proxy" + path``.
+
+    Raises:
+        ValueError: If any server view falls outside the proxy prefix. The
+            message does not include the path.
+
+    Example:
+        >>> ensure_under_proxy_prefix("https://h", "https://h/proxy/gmail/v1/users/me")
+        >>> ensure_under_proxy_prefix("https://h", "https://h/proxy/x/../../outside")
+        Traceback (most recent call last):
+        ...
+        ValueError: path must resolve under the proxy prefix: ...
+    """
+    prepared = requests.Request(method="GET", url=url).prepare()
+    if not all(_path_is_under_prefix(env_url, sent) for sent in _sent_paths(prepared)):
+        raise ValueError(_OUTSIDE_PROXY_MESSAGE)
+
+
+class ProxySession(requests.Session):
+    """A ``requests.Session`` that keeps proxy credentials inside the proxy prefix.
+
+    Redirects are followed exactly as ``requests`` follows them. On each hop,
+    ``requests`` calls ``rebuild_auth``; before deferring to it, this removes
+    ``Authorization``, ``connection_name`` and ``identifier`` when the hop's
+    target is outside ``<env base path>/proxy/``: a different origin (as
+    ``requests.Session.should_strip_auth`` decides) or the same origin with a
+    path the server would route outside the prefix (the rule
+    ``ensure_under_proxy_prefix`` applies). Once removed, they stay
+    removed for later hops. Hops that stay under the prefix are untouched.
+
+    Example:
+        >>> with ProxySession("https://acme.scalekit.cloud") as session:
+        ...     response = session.request("GET", "https://acme.scalekit.cloud/proxy/x")
+    """
+
+    def __init__(self, env_url: str) -> None:
+        """Create a session for proxy calls to ``env_url``."""
+        super().__init__()
+        self._env_url = env_url
+        self._prefix_url = env_url.rstrip("/") + _PROXY_PREFIX
+
+    def rebuild_auth(
+        self, prepared_request: requests.PreparedRequest, response: requests.Response
+    ) -> None:
+        """Drop proxy credentials when a redirect leaves the proxy prefix, then defer."""
+        if not self._stays_in_proxy(prepared_request):
+            for name in _CREDENTIAL_HEADERS:
+                prepared_request.headers.pop(name, None)
+        _session_rebuild_auth(self, prepared_request, response)
+
+    def _stays_in_proxy(self, prepared_request: requests.PreparedRequest) -> bool:
+        url = prepared_request.url
+        if not url or _session_should_strip_auth(self, self._prefix_url, url):
+            return False
+        return all(
+            _path_is_under_prefix(self._env_url, sent) for sent in _sent_paths(prepared_request)
+        )
+
+
+def _path_is_under_prefix(env_url: str, sent: str) -> bool:
+    """Return whether the server will route ``sent`` under ``<base>/proxy/``.
+
+    ``sent`` is the path as ``requests`` puts it on the wire, so any
+    normalisation ``requests``/``urllib3`` applied is already included. Each of
+    its server views (``_server_views``) must equal ``<base>/proxy`` or start
+    with ``<base>/proxy/``. Equality admits inputs that leave the prefix and
+    come back to exactly ``<base>/proxy`` (``/..%2fproxy``): they were sent the
+    same way before this check existed, and no proxy route matches them.
+    Sibling paths such as ``<base>/proxyx`` are rejected.
+    """
+    prefix = _wire_path(env_url.rstrip("/") + _PROXY_PREFIX)
+    for prefix_view, cleaned in zip(_server_views(prefix), _server_views(sent), strict=True):
+        bare = prefix_view.rstrip("/")
+        if cleaned != bare and not cleaned.startswith(bare + "/"):
+            return False
+    return True
+
+
+def _sent_paths(prepared: requests.PreparedRequest) -> list[str]:
+    """Return the path of every request line ``prepared`` may be sent with.
+
+    ``requests`` decides the request-target (``HTTPAdapter.request_url``), and
+    this asks it for both cases: without a proxy (also a SOCKS proxy or an
+    ``https`` tunnel) and through a forward proxy, whether or not one is
+    configured. ``urllib3`` then writes the target as follows.
+
+    * A path (``/...``) is sent as is, except that ``urllib3`` may re-encode a
+      redirect hop's path (``_as_sent``); for a first request ``requests``
+      already did, and ``_as_sent`` changes nothing.
+    * An absolute URL (through a forward proxy, for any URL that is not
+      ``https``) is sent as ``urllib3.util.parse_url`` rebuilds it. That
+      removes dot segments again and treats ``%2F`` as part of a segment;
+      ``requests`` may already have dropped an empty ``;`` parameter from the
+      last segment, which can leave a ``..`` behind.
+    """
+    paths: list[str] = []
+    for proxies in (None, _ANY_FORWARD_PROXY):
+        target = _URL_ADAPTER.request_url(prepared, proxies)
+        if target.startswith("/"):
+            paths.append(_as_sent(target.split("?", 1)[0]))
+            continue
+        # Like urllib3's urlopen, parse any other target as an absolute URL.
+        # If that fails here, the send fails the same way before writing
+        # anything, so there is no further path to check.
+        with contextlib.suppress(LocationParseError):
+            paths.append(parse_url(target).path or "/")
+    return paths
+
+
+def _wire_path(url: str) -> str:
+    """Return the path (without the query) that ``requests`` sends for ``url``.
+
+    Preparing the URL runs it through ``urllib3``'s URL parser, which already
+    applies the encoding ``_as_sent`` describes, so this is the wire form.
+    """
+    path_url: str = requests.Request(method="GET", url=url).prepare().path_url
+    return path_url.split("?", 1)[0]
+
+
+def _as_sent(path: str) -> str:
+    """Return ``path`` as ``urllib3`` writes it in an origin-form request line.
+
+    When any ``%`` in the path does not start a valid ``%XX`` escape, ``urllib3``
+    encodes every ``%`` as ``%25``, so the server decodes ``%2F`` back to the
+    literal text ``%2F``, not to ``/``. ``urllib3`` escapes other characters as
+    well, but one decode restores those, so they do not change the server view.
+    """
+    if path.count("%") != len(_VALID_ESCAPE_RE.findall(path)):
+        return path.replace("%", "%25")
+    return path
+
+
+def _server_views(path: str) -> tuple[str, str]:
+    r"""Return how a server may route ``path``: decoded once, then cleaned.
+
+    The first view is what a Go router sees (``clean_path`` of the decoded
+    path). The second also treats ``\`` as ``/``, as some servers and proxies
+    do. Both are checked: neither view alone is stricter than the other.
+    """
+    decoded = unquote(path)
+    return clean_path(decoded), clean_path(decoded.replace("\\", "/"))
+
+
+def clean_path(path: str) -> str:
+    """Return ``path`` cleaned the way Go HTTP routers clean a request path.
+
+    This is Go's ``path.Clean`` on the rooted path, with a trailing slash put
+    back when ``path`` had one, which is how common Go routers clean the decoded
+    path before matching routes (and redirect to the cleaned path when it
+    differs). Empty and ``.`` segments are dropped, so runs of ``/`` collapse;
+    each ``..`` removes the segment before it, and a ``..`` at the root is
+    dropped.
+
+    Args:
+        path: A decoded URL path. A missing leading ``/`` is treated as present.
+
+    Returns:
+        The cleaned path, always starting with ``/``.
+
+    Example:
+        >>> clean_path("/proxy//../x/./y/")
+        '/x/y/'
+    """
+    segments: list[str] = []
+    for segment in path.split("/"):
+        if segment in ("", "."):
+            continue
+        if segment == "..":
+            if segments:
+                segments.pop()
+            continue
+        segments.append(segment)
+    cleaned = "/" + "/".join(segments)
+    if path.endswith("/") and cleaned != "/":
+        cleaned += "/"
+    return cleaned