release: 0.20.1

.github/workflows/ci.yml

@@ -1,12 +1,14 @@
 name: CI
 on:
   push:
-    branches-ignore:
-      - 'generated'
-      - 'codegen/**'
-      - 'integrated/**'
-      - 'stl-preview-head/**'
-      - 'stl-preview-base/**'
+    branches:
+      - '**'
+      - '!integrated/**'
+      - '!stl-preview-head/**'
+      - '!stl-preview-base/**'
+      - '!generated'
+      - '!codegen/**'
+      - 'codegen/stl/**'
   pull_request:
     branches-ignore:
       - 'stl-preview-head/**'

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.20.0"
+  ".": "0.20.1"
 }

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.20.1 (2026-03-20)
+
+Full Changelog: [v0.20.0...v0.20.1](https://github.com/isaacus-dev/isaacus-python/compare/v0.20.0...v0.20.1)
+
+### Bug Fixes
+
+* **deps:** bump minimum typing-extensions version ([394751d](https://github.com/isaacus-dev/isaacus-python/commit/394751d769909d21410f96e62e93bb312d94c3e2))
+* **pydantic:** do not pass `by_alias` unless set ([7f72945](https://github.com/isaacus-dev/isaacus-python/commit/7f729458707c86cc6f6fa1a9d02089d37438ab49))
+* sanitize endpoint path params ([0d18b42](https://github.com/isaacus-dev/isaacus-python/commit/0d18b42ebef0a59339ebae15f27c92ea4b8c4d34))
+
+
+### Chores
+
+* **internal:** tweak CI branches ([6fa92c9](https://github.com/isaacus-dev/isaacus-python/commit/6fa92c9234a575001af5511e372acccce4cc201c))
+
 ## 0.20.0 (2026-03-11)
 
 Full Changelog: [v0.19.3...v0.20.0](https://github.com/isaacus-dev/isaacus-python/compare/v0.19.3...v0.20.0)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "isaacus"
-version = "0.20.0"
+version = "0.20.1"
 description = "The official Python library for the isaacus API"
 dynamic = ["readme"]
 license = "Apache-2.0"
@@ -11,7 +11,7 @@ authors = [
 dependencies = [
   "httpx>=0.23.0, <1",
   "pydantic>=1.9.0, <3",
-  "typing-extensions>=4.10, <5",
+  "typing-extensions>=4.14, <5",
   "anyio>=3.5.0, <5",
   "distro>=1.7.0, <2",
   "sniffio",

src/isaacus/_compat.py

@@ -2,7 +2,7 @@
 
 from typing import TYPE_CHECKING, Any, Union, Generic, TypeVar, Callable, cast, overload
 from datetime import date, datetime
-from typing_extensions import Self, Literal
+from typing_extensions import Self, Literal, TypedDict
 
 import pydantic
 from pydantic.fields import FieldInfo
@@ -131,6 +131,10 @@ def model_json(model: pydantic.BaseModel, *, indent: int | None = None) -> str:
     return model.model_dump_json(indent=indent)
 
 
+class _ModelDumpKwargs(TypedDict, total=False):
+    by_alias: bool
+
+
 def model_dump(
     model: pydantic.BaseModel,
     *,
@@ -142,14 +146,17 @@ def model_dump(
     by_alias: bool | None = None,
 ) -> dict[str, Any]:
     if (not PYDANTIC_V1) or hasattr(model, "model_dump"):
+        kwargs: _ModelDumpKwargs = {}
+        if by_alias is not None:
+            kwargs["by_alias"] = by_alias
         return model.model_dump(
             mode=mode,
             exclude=exclude,
             exclude_unset=exclude_unset,
             exclude_defaults=exclude_defaults,
             # warnings are not supported in Pydantic v1
             warnings=True if PYDANTIC_V1 else warnings,
-            by_alias=by_alias,
+            **kwargs,
         )
     return cast(
         "dict[str, Any]",

src/isaacus/_utils/__init__.py

@@ -1,3 +1,4 @@
+from ._path import path_template as path_template
 from ._sync import asyncify as asyncify
 from ._proxy import LazyProxy as LazyProxy
 from ._utils import (

src/isaacus/_utils/_path.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import re
+from typing import (
+    Any,
+    Mapping,
+    Callable,
+)
+from urllib.parse import quote
+
+# Matches '.' or '..' where each dot is either literal or percent-encoded (%2e / %2E).
+_DOT_SEGMENT_RE = re.compile(r"^(?:\.|%2[eE]){1,2}$")
+
+_PLACEHOLDER_RE = re.compile(r"\{(\w+)\}")
+
+
+def _quote_path_segment_part(value: str) -> str:
+    """Percent-encode `value` for use in a URI path segment.
+
+    Considers characters not in `pchar` set from RFC 3986 §3.3 to be unsafe.
+    https://datatracker.ietf.org/doc/html/rfc3986#section-3.3
+    """
+    # quote() already treats unreserved characters (letters, digits, and -._~)
+    # as safe, so we only need to add sub-delims, ':', and '@'.
+    # Notably, unlike the default `safe` for quote(), / is unsafe and must be quoted.
+    return quote(value, safe="!$&'()*+,;=:@")
+
+
+def _quote_query_part(value: str) -> str:
+    """Percent-encode `value` for use in a URI query string.
+
+    Considers &, = and characters not in `query` set from RFC 3986 §3.4 to be unsafe.
+    https://datatracker.ietf.org/doc/html/rfc3986#section-3.4
+    """
+    return quote(value, safe="!$'()*+,;:@/?")
+
+
+def _quote_fragment_part(value: str) -> str:
+    """Percent-encode `value` for use in a URI fragment.
+
+    Considers characters not in `fragment` set from RFC 3986 §3.5 to be unsafe.
+    https://datatracker.ietf.org/doc/html/rfc3986#section-3.5
+    """
+    return quote(value, safe="!$&'()*+,;=:@/?")
+
+
+def _interpolate(
+    template: str,
+    values: Mapping[str, Any],
+    quoter: Callable[[str], str],
+) -> str:
+    """Replace {name} placeholders in `template`, quoting each value with `quoter`.
+
+    Placeholder names are looked up in `values`.
+
+    Raises:
+        KeyError: If a placeholder is not found in `values`.
+    """
+    # re.split with a capturing group returns alternating
+    # [text, name, text, name, ..., text] elements.
+    parts = _PLACEHOLDER_RE.split(template)
+
+    for i in range(1, len(parts), 2):
+        name = parts[i]
+        if name not in values:
+            raise KeyError(f"a value for placeholder {{{name}}} was not provided")
+        val = values[name]
+        if val is None:
+            parts[i] = "null"
+        elif isinstance(val, bool):
+            parts[i] = "true" if val else "false"
+        else:
+            parts[i] = quoter(str(values[name]))
+
+    return "".join(parts)
+
+
+def path_template(template: str, /, **kwargs: Any) -> str:
+    """Interpolate {name} placeholders in `template` from keyword arguments.
+
+    Args:
+        template: The template string containing {name} placeholders.
+        **kwargs: Keyword arguments to interpolate into the template.
+
+    Returns:
+        The template with placeholders interpolated and percent-encoded.
+
+        Safe characters for percent-encoding are dependent on the URI component.
+        Placeholders in path and fragment portions are percent-encoded where the `segment`
+        and `fragment` sets from RFC 3986 respectively are considered safe.
+        Placeholders in the query portion are percent-encoded where the `query` set from
+        RFC 3986 §3.3 is considered safe except for = and & characters.
+
+    Raises:
+        KeyError: If a placeholder is not found in `kwargs`.
+        ValueError: If resulting path contains /./ or /../ segments (including percent-encoded dot-segments).
+    """
+    # Split the template into path, query, and fragment portions.
+    fragment_template: str | None = None
+    query_template: str | None = None
+
+    rest = template
+    if "#" in rest:
+        rest, fragment_template = rest.split("#", 1)
+    if "?" in rest:
+        rest, query_template = rest.split("?", 1)
+    path_template = rest
+
+    # Interpolate each portion with the appropriate quoting rules.
+    path_result = _interpolate(path_template, kwargs, _quote_path_segment_part)
+
+    # Reject dot-segments (. and ..) in the final assembled path.  The check
+    # runs after interpolation so that adjacent placeholders or a mix of static
+    # text and placeholders that together form a dot-segment are caught.
+    # Also reject percent-encoded dot-segments to protect against incorrectly
+    # implemented normalization in servers/proxies.
+    for segment in path_result.split("/"):
+        if _DOT_SEGMENT_RE.match(segment):
+            raise ValueError(f"Constructed path {path_result!r} contains dot-segment {segment!r} which is not allowed")
+
+    result = path_result
+    if query_template is not None:
+        result += "?" + _interpolate(query_template, kwargs, _quote_query_part)
+    if fragment_template is not None:
+        result += "#" + _interpolate(fragment_template, kwargs, _quote_fragment_part)
+
+    return result

src/isaacus/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "isaacus"
-__version__ = "0.20.0"  # x-release-please-version
+__version__ = "0.20.1"  # x-release-please-version

tests/test_utils/test_path.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from isaacus._utils._path import path_template
+
+
+@pytest.mark.parametrize(
+    "template, kwargs, expected",
+    [
+        ("/v1/{id}", dict(id="abc"), "/v1/abc"),
+        ("/v1/{a}/{b}", dict(a="x", b="y"), "/v1/x/y"),
+        ("/v1/{a}{b}/path/{c}?val={d}#{e}", dict(a="x", b="y", c="z", d="u", e="v"), "/v1/xy/path/z?val=u#v"),
+        ("/{w}/{w}", dict(w="echo"), "/echo/echo"),
+        ("/v1/static", {}, "/v1/static"),
+        ("", {}, ""),
+        ("/v1/?q={n}&count=10", dict(n=42), "/v1/?q=42&count=10"),
+        ("/v1/{v}", dict(v=None), "/v1/null"),
+        ("/v1/{v}", dict(v=True), "/v1/true"),
+        ("/v1/{v}", dict(v=False), "/v1/false"),
+        ("/v1/{v}", dict(v=".hidden"), "/v1/.hidden"),  # dot prefix ok
+        ("/v1/{v}", dict(v="file.txt"), "/v1/file.txt"),  # dot in middle ok
+        ("/v1/{v}", dict(v="..."), "/v1/..."),  # triple dot ok
+        ("/v1/{a}{b}", dict(a=".", b="txt"), "/v1/.txt"),  # dot var combining with adjacent to be ok
+        ("/items?q={v}#{f}", dict(v=".", f=".."), "/items?q=.#.."),  # dots in query/fragment are fine
+        (
+            "/v1/{a}?query={b}",
+            dict(a="../../other/endpoint", b="a&bad=true"),
+            "/v1/..%2F..%2Fother%2Fendpoint?query=a%26bad%3Dtrue",
+        ),
+        ("/v1/{val}", dict(val="a/b/c"), "/v1/a%2Fb%2Fc"),
+        ("/v1/{val}", dict(val="a/b/c?query=value"), "/v1/a%2Fb%2Fc%3Fquery=value"),
+        ("/v1/{val}", dict(val="a/b/c?query=value&bad=true"), "/v1/a%2Fb%2Fc%3Fquery=value&bad=true"),
+        ("/v1/{val}", dict(val="%20"), "/v1/%2520"),  # escapes escape sequences in input
+        # Query: slash and ? are safe, # is not
+        ("/items?q={v}", dict(v="a/b"), "/items?q=a/b"),
+        ("/items?q={v}", dict(v="a?b"), "/items?q=a?b"),
+        ("/items?q={v}", dict(v="a#b"), "/items?q=a%23b"),
+        ("/items?q={v}", dict(v="a b"), "/items?q=a%20b"),
+        # Fragment: slash and ? are safe
+        ("/docs#{v}", dict(v="a/b"), "/docs#a/b"),
+        ("/docs#{v}", dict(v="a?b"), "/docs#a?b"),
+        # Path: slash, ? and # are all encoded
+        ("/v1/{v}", dict(v="a/b"), "/v1/a%2Fb"),
+        ("/v1/{v}", dict(v="a?b"), "/v1/a%3Fb"),
+        ("/v1/{v}", dict(v="a#b"), "/v1/a%23b"),
+        # same var encoded differently by component
+        (
+            "/v1/{v}?q={v}#{v}",
+            dict(v="a/b?c#d"),
+            "/v1/a%2Fb%3Fc%23d?q=a/b?c%23d#a/b?c%23d",
+        ),
+        ("/v1/{val}", dict(val="x?admin=true"), "/v1/x%3Fadmin=true"),  # query injection
+        ("/v1/{val}", dict(val="x#admin"), "/v1/x%23admin"),  # fragment injection
+    ],
+)
+def test_interpolation(template: str, kwargs: dict[str, Any], expected: str) -> None:
+    assert path_template(template, **kwargs) == expected
+
+
+def test_missing_kwarg_raises_key_error() -> None:
+    with pytest.raises(KeyError, match="org_id"):
+        path_template("/v1/{org_id}")
+
+
+@pytest.mark.parametrize(
+    "template, kwargs",
+    [
+        ("{a}/path", dict(a=".")),
+        ("{a}/path", dict(a="..")),
+        ("/v1/{a}", dict(a=".")),
+        ("/v1/{a}", dict(a="..")),
+        ("/v1/{a}/path", dict(a=".")),
+        ("/v1/{a}/path", dict(a="..")),
+        ("/v1/{a}{b}", dict(a=".", b=".")),  # adjacent vars → ".."
+        ("/v1/{a}.", dict(a=".")),  # var + static → ".."
+        ("/v1/{a}{b}", dict(a="", b=".")),  # empty + dot → "."
+        ("/v1/%2e/{x}", dict(x="ok")),  # encoded dot in static text
+        ("/v1/%2e./{x}", dict(x="ok")),  # mixed encoded ".." in static
+        ("/v1/.%2E/{x}", dict(x="ok")),  # mixed encoded ".." in static
+        ("/v1/{v}?q=1", dict(v="..")),
+        ("/v1/{v}#frag", dict(v="..")),
+    ],
+)
+def test_dot_segment_rejected(template: str, kwargs: dict[str, Any]) -> None:
+    with pytest.raises(ValueError, match="dot-segment"):
+        path_template(template, **kwargs)