Fix Python SDK type issues with ty type checker (#1122)

## Summary
- Resolved 43 type diagnostics reported by ty (Astral's Python type
checker)
- Fixed Self type issues on class singletons
- Added explicit type annotations for shadowed attributes
- Replaced None with UNSET for auto-generated API parameters
- Fixed method signature alignment for protocol matching
- Added targeted type: ignore suppressions for pattern-based limitations

All checks pass: ty check, ruff format, ruff check.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Mostly typing/CI changes, but some adjustments affect sandbox
connect/pause overload dispatch and API response/parameter handling
(`UNSET` vs `None`), which could alter edge-case runtime behavior.
> 
> **Overview**
> Fixes Python SDK static typing issues for Astral’s `ty` checker and
wires typechecking into CI.
> 
> Adds a new `Typecheck` GitHub Action plus workspace `typecheck`
scripts (TS packages via `tsc`, Python SDK via `make typecheck` running
`ty`), and publishes a patch changeset for `@e2b/python-sdk`.
> 
> Across the Python SDK, adjusts type annotations and overloads (e.g.,
`Self`/singleton typing, `connect` overloads, optional
`user`/token/domain handling), tightens API model parsing with
`cast`/`Optional` checks and `UNSET` usage, and adds a few targeted `ty`
ignore comments in tests/protocols to silence checker limitations.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
f664028. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Author: 3 people

.changeset/tangy-kiwis-repeat.md

@@ -0,0 +1,5 @@
+---
+'@e2b/python-sdk': patch
+---
+
+fixes type errors when using with ty

.github/workflows/typecheck.yml

@@ -0,0 +1,62 @@
+name: Typecheck
+
+on:
+  pull_request:
+
+jobs:
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+
+      - name: Parse .tool-versions
+        uses: wistia/parse-tool-versions@v2.1.1
+        with:
+          filename: '.tool-versions'
+          uppercase: 'true'
+          prefix: 'tool_version_'
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: '${{ env.TOOL_VERSION_PNPM }}'
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '${{ env.TOOL_VERSION_NODEJS }}'
+          cache: pnpm
+
+      - name: Configure pnpm
+        run: |
+          pnpm config set auto-install-peers true
+          pnpm config set exclude-links-from-lockfile true
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '${{ env.TOOL_VERSION_PYTHON }}'
+
+      - name: Install and configure Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: '${{ env.TOOL_VERSION_POETRY }}'
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          installer-parallel: true
+
+      - name: Install Python dependencies
+        working-directory: packages/python-sdk
+        run: |
+          poetry install --with dev
+
+      - name: Run typecheck
+        run: |
+          pnpm run typecheck

package.json

@@ -12,6 +12,7 @@
     "pnpm-install-hack": "cd packages/js-sdk && sed -i '' 's/\"version\": \".*\"/\"version\": \"9.9.9\"/g' package.json && cd ../.. && pnpm i && git checkout -- packages/js-sdk/package.json",
     "generate-sdk-reference": "pnpm --if-present --recursive run generate-sdk-reference",
     "lint": "pnpm --if-present --recursive run lint",
+    "typecheck": "pnpm --if-present --recursive run typecheck",
     "format": "pnpm --if-present --recursive run format",
     "changeset": "pnpx @changesets/cli"
   },

packages/cli/package.json

@@ -38,6 +38,7 @@
     "prepublishOnly": "pnpm build",
     "build": "tsc --noEmit --skipLibCheck && tsup --minify",
     "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit --skipLibCheck",
     "lint": "eslint src",
     "format": "prettier --write src",
     "test:interactive": "pnpm build && ./dist/index.js",

packages/js-sdk/package.json

@@ -41,6 +41,7 @@
     "test:bun": "bun test tests/runtimes/bun --env-file=.env",
     "test:deno": "deno test tests/runtimes/deno/ --allow-net --allow-read --allow-env --unstable-sloppy-imports --trace-leaks",
     "test:integration": "E2B_INTEGRATION_TEST=1 vitest run tests/integration/**",
+    "typecheck": "tsc --noEmit",
     "lint": "eslint src/ tests/",
     "format": "prettier --write src/ tests/ example.mts"
   },

packages/python-sdk/Makefile

@@ -23,6 +23,9 @@ generate: generate-api generate-envd generate-mcp
 init:
 	pip install openapi-python-client datamodel-code-generator
 
+typecheck:
+	ty check
+
 lint:
 	ruff check .
 	ruff format --check .

packages/python-sdk/e2b/api/__init__.py

@@ -31,7 +31,7 @@ class SandboxCreateResponse:
     sandbox_id: str
     sandbox_domain: Optional[str]
     envd_version: str
-    envd_access_token: str
+    envd_access_token: Optional[str]
     traffic_access_token: Optional[str]
 
 
@@ -135,7 +135,7 @@ def __init__(
                 "transport": transport,
             },
             headers=headers,
-            token=token,
+            token=token or "",
             auth_header_name=auth_header_name,
             prefix=prefix,
             *args,

packages/python-sdk/e2b/api/client_async/__init__.py

@@ -3,8 +3,6 @@
 
 from typing import Optional
 
-from typing_extensions import Self
-
 from e2b.connection_config import ConnectionConfig
 from e2b.api import limits, AsyncApiClient
 
@@ -21,7 +19,7 @@ def get_api_client(config: ConnectionConfig, **kwargs) -> AsyncApiClient:
 
 
 class AsyncTransportWithLogger(httpx.AsyncHTTPTransport):
-    singleton: Optional[Self] = None
+    singleton: Optional["AsyncTransportWithLogger"] = None
 
     async def handle_async_request(self, request):
         url = f"{request.url.scheme}://{request.url.host}{request.url.path}"

packages/python-sdk/e2b/api/client_sync/__init__.py

@@ -3,8 +3,6 @@
 import httpx
 import logging
 
-from typing_extensions import Self
-
 from e2b.api import ApiClient, limits
 from e2b.connection_config import ConnectionConfig
 
@@ -20,7 +18,7 @@ def get_api_client(config: ConnectionConfig, **kwargs) -> ApiClient:
 
 
 class TransportWithLogger(httpx.HTTPTransport):
-    singleton: Optional[Self] = None
+    singleton: Optional["TransportWithLogger"] = None
 
     def handle_request(self, request):
         url = f"{request.url.scheme}://{request.url.host}{request.url.path}"

packages/python-sdk/e2b/connection_config.py

@@ -117,7 +117,9 @@ def __init__(
             or ("http://localhost:3000" if self.debug else f"https://api.{self.domain}")
         )
 
-        self._sandbox_url = sandbox_url or ConnectionConfig._sandbox_url()
+        self._sandbox_url: Optional[str] = (
+            sandbox_url or ConnectionConfig._sandbox_url()
+        )
 
     @staticmethod
     def _get_request_timeout(
@@ -136,7 +138,7 @@ def get_request_timeout(self, request_timeout: Optional[float] = None):
 
     def get_sandbox_url(self, sandbox_id: str, sandbox_domain: str) -> str:
         if self._sandbox_url:
-            return self._sandbox_url
+            return self._sandbox_url  # type: ignore[return-value]
 
         return f"{'http' if self.debug else 'https'}://{self.get_host(sandbox_id, sandbox_domain, self.envd_port)}"