release: 0.2.0

.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/**'
@@ -17,14 +19,14 @@ jobs:
     timeout-minutes: 10
     name: lint
     runs-on: ${{ github.repository == 'stainless-sdks/docstrange-python' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
     steps:
       - uses: actions/checkout@v6
 
       - name: Install uv
         uses: astral-sh/setup-uv@v5
         with:
-          version: '0.9.13'
+          version: '0.10.2'
 
       - name: Install dependencies
         run: uv sync --all-extras
@@ -33,7 +35,7 @@ jobs:
         run: ./scripts/lint
 
   build:
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
+    if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
     timeout-minutes: 10
     name: build
     permissions:
@@ -46,7 +48,7 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v5
         with:
-          version: '0.9.13'
+          version: '0.10.2'
 
       - name: Install dependencies
         run: uv sync --all-extras
@@ -55,14 +57,18 @@ jobs:
         run: uv build
 
       - name: Get GitHub OIDC Token
-        if: github.repository == 'stainless-sdks/docstrange-python'
+        if: |-
+          github.repository == 'stainless-sdks/docstrange-python' &&
+          !startsWith(github.ref, 'refs/heads/stl/')
         id: github-oidc
         uses: actions/github-script@v8
         with:
           script: core.setOutput('github_token', await core.getIDToken());
 
       - name: Upload tarball
-        if: github.repository == 'stainless-sdks/docstrange-python'
+        if: |-
+          github.repository == 'stainless-sdks/docstrange-python' &&
+          !startsWith(github.ref, 'refs/heads/stl/')
         env:
           URL: https://pkg.stainless.com/s
           AUTH: ${{ steps.github-oidc.outputs.github_token }}
@@ -80,7 +86,7 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v5
         with:
-          version: '0.9.13'
+          version: '0.10.2'
 
       - name: Bootstrap
         run: ./scripts/bootstrap

.github/workflows/publish-pypi.yml

@@ -13,9 +13,8 @@ jobs:
     name: publish
     runs-on: ubuntu-latest
     permissions:
-
-      id-token: write
       contents: read
+      id-token: write
 
     steps:
       - uses: actions/checkout@v6

.gitignore

@@ -1,4 +1,5 @@
 .prism.log
+.stdy.log
 _dev
 
 __pycache__

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.1"
+  ".": "0.2.0"
 }

CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.2.0 (2026-03-27)
+
+Full Changelog: [v0.1.1...v0.2.0](https://github.com/NanoNets/docstrange-python/compare/v0.1.1...v0.2.0)
+
+### Features
+
+* **internal:** implement indices array format for query and form serialization ([2790680](https://github.com/NanoNets/docstrange-python/commit/279068029d8c1533c1058b6daf50415c96a7d793))
+
+
+### Bug Fixes
+
+* **deps:** bump minimum typing-extensions version ([3293c84](https://github.com/NanoNets/docstrange-python/commit/3293c8459d7cd5831d9497fe222d5b2479ceba6a))
+* **pydantic:** do not pass `by_alias` unless set ([8281a9a](https://github.com/NanoNets/docstrange-python/commit/8281a9a9ca7f2b2e97a11eccbb27c26445f8b741))
+* sanitize endpoint path params ([2529403](https://github.com/NanoNets/docstrange-python/commit/2529403cdb31e5f4591924947c9c9f281f3cf7de))
+
+
+### Chores
+
+* **ci:** bump uv version ([c323a36](https://github.com/NanoNets/docstrange-python/commit/c323a36839f55b7a9d64749b57c109cdfac3242d))
+* **ci:** skip lint on metadata-only changes ([aa1f737](https://github.com/NanoNets/docstrange-python/commit/aa1f737af893ccd0ff6b86e39f3273fc4d01eff5))
+* **ci:** skip uploading artifacts on stainless-internal branches ([c4ae12c](https://github.com/NanoNets/docstrange-python/commit/c4ae12c45ae60c005b25136b1fe1a1357966b7cf))
+* format all `api.md` files ([181d23f](https://github.com/NanoNets/docstrange-python/commit/181d23f1cb3ba49a4f9e1b15904b6f554d45c47e))
+* **internal:** add request options to SSE classes ([db43c2d](https://github.com/NanoNets/docstrange-python/commit/db43c2d91944f4dbfa4c10a29ae9710d72ac354d))
+* **internal:** make `test_proxy_environment_variables` more resilient ([813e69d](https://github.com/NanoNets/docstrange-python/commit/813e69df0940d2528b14f076b9583d90edffd2a2))
+* **internal:** make `test_proxy_environment_variables` more resilient to env ([135f28b](https://github.com/NanoNets/docstrange-python/commit/135f28ba8d42802aeaf25a2a0e4b04189390c0b8))
+* **internal:** refactor authentication internals ([d91fcfa](https://github.com/NanoNets/docstrange-python/commit/d91fcfa6b17d19771a43c30af59d1eff3b484931))
+* **internal:** remove mock server code ([7ca1623](https://github.com/NanoNets/docstrange-python/commit/7ca1623eaa59ff51c76aa66a948052487416f767))
+* **internal:** tweak CI branches ([cb69cd0](https://github.com/NanoNets/docstrange-python/commit/cb69cd0526fbc4a37ea880f06729681921589a1f))
+* **internal:** update gitignore ([d1375ed](https://github.com/NanoNets/docstrange-python/commit/d1375ede29d45d13aba9f38066e35f61433c0641))
+* **internal:** version bump ([bccc6c4](https://github.com/NanoNets/docstrange-python/commit/bccc6c4c4c5784dfd388395ff5e429ed8348ddf3))
+* **test:** update skip reason message ([abd2c81](https://github.com/NanoNets/docstrange-python/commit/abd2c81bcd43080e8bf606af12e8d4b9889e62a1))
+* update mock server docs ([4b3083c](https://github.com/NanoNets/docstrange-python/commit/4b3083c18f27cede567c9ee00186c4c69723dc92))
+* update placeholder string ([c15515a](https://github.com/NanoNets/docstrange-python/commit/c15515aa7218d4d07c85543c0438539e339c5d44))
+* update SDK settings ([1dafac3](https://github.com/NanoNets/docstrange-python/commit/1dafac38b9d0a26e55a15e6ca90954ae3ac186e1))
+* update SDK settings ([7c6f5e0](https://github.com/NanoNets/docstrange-python/commit/7c6f5e0d4eede9a88ec92a25071922644f473433))
+* update SDK settings ([c87d8ae](https://github.com/NanoNets/docstrange-python/commit/c87d8aede4de4ba2865222011cd7b28202d0d2d1))
+
 ## 0.1.1 (2026-02-13)
 
 Full Changelog: [v0.1.0...v0.1.1](https://github.com/NanoNets/docstrange-python/compare/v0.1.0...v0.1.1)

CONTRIBUTING.md

@@ -85,13 +85,6 @@ $ pip install ./path-to-wheel-file.whl
 
 ## Running tests
 
-Most tests require you to [set up a mock server](https://github.com/stoplightio/prism) against the OpenAPI spec to run the tests.
-
-```sh
-# you will need npm installed
-$ npx prism mock path/to/your/openapi.yml
-```
-
 ```sh
 $ ./scripts/test
 ```

bin/publish-pypi

@@ -4,4 +4,8 @@ set -eux
 rm -rf dist
 mkdir -p dist
 uv build
-uv publish
+if [ -n "${PYPI_TOKEN:-}" ]; then
+  uv publish --token=$PYPI_TOKEN
+else
+  uv publish
+fi

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstrange-api"
-version = "0.1.1"
+version = "0.2.0"
 description = "The official Python library for the docstrange 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",

scripts/format

@@ -11,4 +11,4 @@ uv run ruff check --fix .
 uv run ruff format
 
 echo "==> Formatting docs"
-uv run python scripts/utils/ruffen-docs.py README.md api.md
+uv run python scripts/utils/ruffen-docs.py README.md $(find . -type f -name api.md)

scripts/test

@@ -4,53 +4,7 @@ set -e
 
 cd "$(dirname "$0")/.."
 
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[0;33m'
-NC='\033[0m' # No Color
 
-function prism_is_running() {
-  curl --silent "http://localhost:4010" >/dev/null 2>&1
-}
-
-kill_server_on_port() {
-  pids=$(lsof -t -i tcp:"$1" || echo "")
-  if [ "$pids" != "" ]; then
-    kill "$pids"
-    echo "Stopped $pids."
-  fi
-}
-
-function is_overriding_api_base_url() {
-  [ -n "$TEST_API_BASE_URL" ]
-}
-
-if ! is_overriding_api_base_url && ! prism_is_running ; then
-  # When we exit this script, make sure to kill the background mock server process
-  trap 'kill_server_on_port 4010' EXIT
-
-  # Start the dev server
-  ./scripts/mock --daemon
-fi
-
-if is_overriding_api_base_url ; then
-  echo -e "${GREEN}✔ Running tests against ${TEST_API_BASE_URL}${NC}"
-  echo
-elif ! prism_is_running ; then
-  echo -e "${RED}ERROR:${NC} The test suite will not run without a mock Prism server"
-  echo -e "running against your OpenAPI spec."
-  echo
-  echo -e "To run the server, pass in the path or url of your OpenAPI"
-  echo -e "spec to the prism command:"
-  echo
-  echo -e "  \$ ${YELLOW}npm exec --package=@stainless-api/prism-cli@5.15.0 -- prism mock path/to/your.openapi.yml${NC}"
-  echo
-
-  exit 1
-else
-  echo -e "${GREEN}✔ Mock prism server is running with your OpenAPI spec${NC}"
-  echo
-fi
 
 export DEFER_PYDANTIC_BUILD=false
 

src/docstrange/_base_client.py

@@ -63,7 +63,7 @@
 )
 from ._utils import is_dict, is_list, asyncify, is_given, lru_cache, is_mapping
 from ._compat import PYDANTIC_V1, model_copy, model_dump
-from ._models import GenericModel, FinalRequestOptions, validate_type, construct_type
+from ._models import GenericModel, SecurityOptions, FinalRequestOptions, validate_type, construct_type
 from ._response import (
     APIResponse,
     BaseAPIResponse,
@@ -432,9 +432,27 @@ def _make_status_error(
     ) -> _exceptions.APIStatusError:
         raise NotImplementedError()
 
+    def _auth_headers(
+        self,
+        security: SecurityOptions,  # noqa: ARG002
+    ) -> dict[str, str]:
+        return {}
+
+    def _auth_query(
+        self,
+        security: SecurityOptions,  # noqa: ARG002
+    ) -> dict[str, str]:
+        return {}
+
+    def _custom_auth(
+        self,
+        security: SecurityOptions,  # noqa: ARG002
+    ) -> httpx.Auth | None:
+        return None
+
     def _build_headers(self, options: FinalRequestOptions, *, retries_taken: int = 0) -> httpx.Headers:
         custom_headers = options.headers or {}
-        headers_dict = _merge_mappings(self.default_headers, custom_headers)
+        headers_dict = _merge_mappings({**self._auth_headers(options.security), **self.default_headers}, custom_headers)
         self._validate_headers(headers_dict, custom_headers)
 
         # headers are case-insensitive while dictionaries are not.
@@ -506,7 +524,7 @@ def _build_request(
                 raise RuntimeError(f"Unexpected JSON data type, {type(json_data)}, cannot merge with `extra_body`")
 
         headers = self._build_headers(options, retries_taken=retries_taken)
-        params = _merge_mappings(self.default_query, options.params)
+        params = _merge_mappings({**self._auth_query(options.security), **self.default_query}, options.params)
         content_type = headers.get("Content-Type")
         files = options.files
 
@@ -671,7 +689,6 @@ def default_headers(self) -> dict[str, str | Omit]:
             "Content-Type": "application/json",
             "User-Agent": self.user_agent,
             **self.platform_headers(),
-            **self.auth_headers,
             **self._custom_headers,
         }
 
@@ -990,8 +1007,9 @@ def request(
             self._prepare_request(request)
 
             kwargs: HttpxSendArgs = {}
-            if self.custom_auth is not None:
-                kwargs["auth"] = self.custom_auth
+            custom_auth = self._custom_auth(options.security)
+            if custom_auth is not None:
+                kwargs["auth"] = custom_auth
 
             if options.follow_redirects is not None:
                 kwargs["follow_redirects"] = options.follow_redirects
@@ -1952,6 +1970,7 @@ def make_request_options(
     idempotency_key: str | None = None,
     timeout: float | httpx.Timeout | None | NotGiven = not_given,
     post_parser: PostParser | NotGiven = not_given,
+    security: SecurityOptions | None = None,
 ) -> RequestOptions:
     """Create a dict of type RequestOptions without keys of NotGiven values."""
     options: RequestOptions = {}
@@ -1977,6 +1996,9 @@ def make_request_options(
         # internal
         options["post_parser"] = post_parser  # type: ignore
 
+    if security is not None:
+        options["security"] = security
+
     return options