@xyd-js/opensdk-python 0.0.0-build-f0c10f6-20260703195526

package/__tests__/e2e/publish.test.ts

@@ -0,0 +1,19 @@
+import path from 'node:path';
+
+import { describe, it } from 'vitest';
+
+import { adapterReady, publishRoundTrip, pythonPublishAdapter } from '@xyd-js/opensdk-ci';
+
+import { opensdkPython, publishPython } from '../../index';
+
+// PUBLISH e2e (gated E2E_SDK_PUBLISH=1 + `python3` + PUBLISH_PYPI_URL): build +
+// twine-upload the openai SDK to the local PyPI (pypiserver), pip-install it back
+// into a scratch consumer, and import it.
+const adapter = pythonPublishAdapter();
+const FIXTURES = path.join(__dirname, '../../__fixtures__/-2.complex.openai');
+
+describe.runIf(adapterReady(adapter))('openai publish e2e (python → PyPI/pypiserver)', () => {
+  it('builds, uploads, pip-installs from the index, and imports the package', async () => {
+    await publishRoundTrip({ fixturesDir: FIXTURES, sdkName: 'openai', generate: opensdkPython, publish: publishPython, adapter });
+  }, 600000);
+});

package/__tests__/opensdk-python.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from 'vitest';
+
+import { opensdkPython } from '../index';
+import { PY_SMOKE, pyBehaviorSmoke, pyCompileSmoke, readIR, testFixture } from './utils';
+
+const fixtures = [
+  { name: '1.basic', description: 'client, resources, methods, dataclasses/enums, dep-free transport' },
+  {
+    name: '2.wire',
+    description:
+      'wire correctness: multipart/form bodies, header params, wireName + explode query arrays, cursor pagination, binary download, idempotency-key injection',
+  },
+];
+
+describe('opensdk-python', () => {
+  for (const f of fixtures) {
+    it(f.description, () => {
+      testFixture(f.name);
+    });
+  }
+
+  if (PY_SMOKE) {
+    for (const f of fixtures) {
+      it(`py_compile: ${f.name}`, () => {
+        pyCompileSmoke(f.name);
+      });
+    }
+
+    it('runtime behavior probe (retry-after, backoff, error kinds, guard, UA)', () => {
+      pyBehaviorSmoke();
+    });
+  }
+});
+
+// The runtime is policy-driven: every behavior constant in _transport.py is
+// interpolated from the IR's `sdk` block (opensdk-core's sdkBehavior(spec)),
+// so the canonical defaults — and any override — are assertable as text.
+describe('opensdk-python sdk behavior', () => {
+  it('interpolates the canonical defaults into _transport.py', () => {
+    const transport = opensdkPython(readIR('1.basic'))['petstore/_transport.py'];
+
+    // retry policy
+    expect(transport).toContain('MAX_RETRIES = 2');
+    expect(transport).toContain('RETRYABLE_STATUS_CODES = frozenset({408, 429, 500, 502, 503, 504})');
+    expect(transport).toContain('RETRY_CONNECTION_ERRORS = True');
+    expect(transport).toContain('HONOR_RETRY_AFTER_HEADER = True');
+    expect(transport).toContain('BACKOFF_INITIAL_DELAY = 0.5');
+    expect(transport).toContain('BACKOFF_MAX_DELAY = 8.0');
+    expect(transport).toContain('BACKOFF_MULTIPLIER = 2.0');
+    expect(transport).toContain('BACKOFF_JITTER = 0.25');
+    // timeout policy (60000ms -> urlopen seconds), no env override by default
+    expect(transport).toContain('DEFAULT_TIMEOUT: Optional[float] = 60.0');
+    expect(transport).toContain('urllib.request.urlopen(request, timeout=self.timeout)');
+    expect(transport).not.toContain('TIMEOUT_ENV_VAR');
+    // user-agent policy ({package}-{language}/{version} + AI-agent sniff; no runtime version by default)
+    expect(transport).toContain('USER_AGENT = "petstore-python/1.2.0"');
+    expect(transport).toContain('"CLAUDE_CODE": "claude-code"');
+    expect(transport).toContain('"COPILOT_AGENT": "copilot"');
+    expect(transport).not.toContain('import platform');
+    // error policy: per-kind exception classes + dispatch + request id; no doc URL by default
+    expect(transport).toContain('class BadRequestError(APIError):');
+    expect(transport).toContain('class NotFoundError(APIError):');
+    expect(transport).toContain('class RateLimitedError(APIError):');
+    expect(transport).toContain('class InternalError(APIError):');
+    expect(transport).toContain('404: NotFoundError,');
+    expect(transport).toContain('REQUEST_ID_HEADER = "X-Request-ID"');
+    expect(transport).not.toContain('ERROR_DOC_URL_TEMPLATE');
+    // idempotency + request guard policies
+    expect(transport).toContain('IDEMPOTENCY_HEADER = "Idempotency-Key"');
+    expect(transport).toContain(
+      'GUARDED_OPTION_KEYS = frozenset({"api_key", "apiKey", "idempotency_key", "idempotencyKey", "extra_headers", "extraHeaders", "max_retries", "maxRetries", "base_url", "baseUrl", "timeout"})',
+    );
+  });
+
+  it('interpolates sdk overrides (retry/timeout/errors/userAgent) into _transport.py', () => {
+    const ir = readIR('1.basic');
+    ir.sdk = {
+      retry: {
+        maxRetries: 5,
+        retryableStatusCodes: [429],
+        backoff: { initialDelayMs: 250, maxDelayMs: 2000, multiplier: 3, jitter: 0.5 },
+      },
+      timeout: { defaultTimeoutMs: 5000, timeoutEnvVar: 'PETSTORE_TIMEOUT_MS' },
+      errors: { errorDocUrlTemplate: 'https://docs.petstore.io/errors/{kind}' },
+      userAgent: { includeRuntimeVersion: true },
+    };
+    const transport = opensdkPython(ir)['petstore/_transport.py'];
+
+    expect(transport).toContain('MAX_RETRIES = 5');
+    expect(transport).toContain('RETRYABLE_STATUS_CODES = frozenset({429})');
+    expect(transport).toContain('BACKOFF_INITIAL_DELAY = 0.25');
+    expect(transport).toContain('BACKOFF_MAX_DELAY = 2.0');
+    expect(transport).toContain('BACKOFF_MULTIPLIER = 3.0');
+    expect(transport).toContain('BACKOFF_JITTER = 0.5');
+    expect(transport).toContain('DEFAULT_TIMEOUT: Optional[float] = 5.0');
+    expect(transport).toContain('TIMEOUT_ENV_VAR = "PETSTORE_TIMEOUT_MS"');
+    expect(transport).toContain('ERROR_DOC_URL_TEMPLATE = "https://docs.petstore.io/errors/{kind}"');
+    expect(transport).toContain('def __str__(self) -> str:');
+    expect(transport).toContain('import platform');
+    expect(transport).toContain('ua += " python/" + platform.python_version()');
+    // unmapped statusCodeMap keeps the canonical error classes
+    expect(transport).toContain('class NotFoundError(APIError):');
+  });
+
+  it('passes idempotency=True only for injectIdempotencyKey-flagged methods', () => {
+    const files = opensdkPython(readIR('2.wire'));
+    const resources = files['wire_service/resources.py'];
+    // 2.wire flags exactly one method (tokens.create).
+    expect(resources.match(/idempotency=True/g)).toHaveLength(1);
+    expect(resources).toContain('"POST", "/token"');
+    // The transport generates ONE uuid4 key per logical call, before the retry loop.
+    expect(files['wire_service/_transport.py']).toContain(
+      'request_headers.setdefault(IDEMPOTENCY_HEADER, str(uuid.uuid4()))',
+    );
+  });
+
+  it('prepends the ownership header to every generated .py file (and never to pyproject.toml)', () => {
+    const files = opensdkPython(readIR('1.basic'));
+    for (const [rel, content] of Object.entries(files)) {
+      if (rel.endsWith('.py')) {
+        expect(content.startsWith('# Code generated by opensdk. DO NOT EDIT.\n\n'), rel).toBe(true);
+      }
+    }
+    expect(files['pyproject.toml']).not.toContain('DO NOT EDIT');
+  });
+
+  it('exports the error-kind classes from the package __init__', () => {
+    const init = opensdkPython(readIR('1.basic'))['petstore/__init__.py'];
+    expect(init).toContain(
+      'from ._transport import APIError, BadRequestError, ConflictError, InternalError, NotFoundError, PermissionDeniedError, RateLimitedError, UnauthorizedError, UnprocessableEntityError',
+    );
+    expect(init).toContain('"Client"');
+  });
+});

package/__tests__/utils.ts

@@ -0,0 +1,117 @@
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { expect } from 'vitest';
+
+import { hasCommand, listFiles, writeTree } from '@xyd-js/opensdk-ci';
+
+import { opensdkPython } from '../index';
+import type { OpensdkPythonOptions } from '../index';
+
+const REGENERATE = process.env.REGEN === '1';
+
+// O2S_PY_SMOKE=1 (and a python3) enables a `py_compile` smoke of the generated tree.
+export const PY_SMOKE = process.env.O2S_PY_SMOKE === '1' && hasCommand('python3 --version');
+
+function fixturePath(name: string): string {
+  return path.join(__dirname, '../__fixtures__', name);
+}
+
+export function readIR(name: string) {
+  return JSON.parse(fs.readFileSync(path.join(fixturePath(name), 'input.json'), 'utf8'));
+}
+
+/** Golden test: opensdkPython(input.json) === the committed output/ file tree. */
+export function testFixture(name: string, options?: OpensdkPythonOptions) {
+  const files = opensdkPython(readIR(name), options);
+  const outDir = path.join(fixturePath(name), 'output');
+
+  if (REGENERATE) writeTree(outDir, files);
+
+  const expected = listFiles(outDir);
+  expect(Object.keys(files).sort()).toEqual(Object.keys(expected).sort());
+  for (const [rel, content] of Object.entries(files)) {
+    expect(content, `mismatch in ${name}/${rel}`).toEqual(expected[rel]);
+  }
+}
+
+/** Optional: write the project to a temp dir and `python3 -m py_compile` every module. */
+export function pyCompileSmoke(name: string, options?: OpensdkPythonOptions) {
+  const files = opensdkPython(readIR(name), options);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `o2py-${name.replace(/\W/g, '')}-`));
+  try {
+    writeTree(dir, files);
+    const modules = Object.keys(files).filter((f) => f.endsWith('.py'));
+    // The generated pytest suite (tests/*.py) is part of the compiled set, so
+    // the smoke provably covers it — not just the package modules.
+    expect(modules.some((m) => m.startsWith('tests/')), `${name}: no generated tests/*.py to compile`).toBe(true);
+    execSync(`python3 -m py_compile ${modules.map((m) => JSON.stringify(m)).join(' ')}`, { cwd: dir, stdio: 'pipe' });
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Optional: import the generated 1.basic transport in a REAL python3 and probe
+ * the behavior helpers — Retry-After parsing (both forms), the backoff+jitter
+ * envelope, the status -> exception dispatch with request_id, the request
+ * guard, and the User-Agent assembly.
+ */
+export function pyBehaviorSmoke() {
+  const files = opensdkPython(readIR('1.basic'));
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'o2py-behavior-'));
+  const script = `import datetime
+import email.utils
+
+from petstore._transport import (
+    BACKOFF_INITIAL_DELAY,
+    BACKOFF_JITTER,
+    USER_AGENT,
+    APIError,
+    InternalError,
+    NotFoundError,
+    _error_for_status,
+    _guard_options,
+    _retry_after_seconds,
+    _retry_delay,
+    _user_agent,
+)
+
+# Retry-After: integer-seconds form and HTTP-date form (case-insensitive header).
+assert _retry_after_seconds({"retry-after": "3"}) == 3.0
+future = email.utils.format_datetime(datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(seconds=5))
+http_date = _retry_after_seconds({"Retry-After": future})
+assert http_date is not None and 0.0 <= http_date <= 5.0, http_date
+
+# Backoff: first delay in the [initial, initial * (1 + jitter)] envelope; Retry-After wins.
+first = _retry_delay(0, None)
+assert BACKOFF_INITIAL_DELAY <= first <= BACKOFF_INITIAL_DELAY * (1 + BACKOFF_JITTER), first
+assert _retry_delay(1, {"Retry-After": "7"}) == 7.0
+
+# Error kinds: mapped status, 5xx catch-all, client catch-all; request_id from the policy header.
+err = _error_for_status(404, {"x-request-id": "req_123"}, b'{"error": {"message": "nope"}}')
+assert isinstance(err, NotFoundError) and err.kind == "NotFound"
+assert err.request_id == "req_123" and err.message == "nope"
+assert isinstance(_error_for_status(503, {}, b""), InternalError)
+assert type(_error_for_status(418, {}, b"")) is APIError
+
+# Request guard: option keys misplaced into params fail fast, naming the key.
+try:
+    _guard_options({"api_key": "sk-leak"})
+except ValueError as error:
+    assert "api_key" in str(error)
+else:
+    raise AssertionError("request guard did not fire")
+
+assert _user_agent().startswith(USER_AGENT)
+`;
+  try {
+    writeTree(dir, files);
+    fs.writeFileSync(path.join(dir, '_behavior_check.py'), script);
+    execSync('python3 _behavior_check.py', { cwd: dir, stdio: 'pipe' });
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}

package/biome.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.3/schema.json",
+  "files": {
+    "ignore": ["dist/**", "node_modules/**", "__fixtures__/**"]
+  },
+  "organizeImports": { "enabled": true },
+  "formatter": {
+    "enabled": true,
+    "indentWidth": 2,
+    "indentStyle": "space",
+    "lineWidth": 120
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "semicolons": "asNeeded"
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  }
+}