@hey-api/openapi-python 0.0.0-next-20260618224635

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Hey API
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,411 @@
+<div align="center">
+  <img alt="Hey API presents openapi-python" height="214" src="https://heyapi.dev/assets/.gen/openapi-python-hero-640w.png" width="438">
+  <h1><b>OpenAPI Python</b></h1>
+  <p><em>“The ecosystem trusted by TypeScript developers is coming to Python codebases.”</em><br/><sub>— Lubos, Founder of Hey API</sub></p>
+</div>
+
+<p align="center">
+  <!-- <a href="https://www.devtrends.dev/trends?c=v1.kZIBIg"><img src="https://api.devtrends.dev/badge/npm/%40hey-api%2Fopenapi-python?period=month&style=flat&view=value" alt="DevTrends badge for @hey-api/openapi-python" /></a> -->
+  <!-- <a href="https://www.devtrends.dev/trends?c=v1.kZIBIg&v=change"><img src="https://api.devtrends.dev/badge/npm/%40hey-api%2Fopenapi-python?period=year&style=flat&view=change" alt="DevTrends badge for @hey-api/openapi-python" /></a> -->
+  <a href="https://github.com/hey-api/hey-api/actions?query=branch%3Amain"><img src="https://github.com/hey-api/hey-api/actions/workflows/ci.yml/badge.svg?event=push&branch=main" alt="CI status" /></a>
+  <a href="https://github.com/hey-api/hey-api"><img src="https://img.shields.io/github/stars/hey-api/hey-api?style=flat&logo=github&label=GitHub&color=54C82D" alt="GitHub stars" /></a>
+  <a href="https://github.com/hey-api/hey-api/blob/main/LICENSE.md"><img src="https://img.shields.io/github/license/hey-api/hey-api" alt="MIT License"></a>
+</p>
+
+<p align="center">
+  <!-- <a href="https://stackblitz.com/edit/hey-api-example?file=openapi-ts.config.ts,src%2Fclient%2Fschemas.gen.ts,src%2Fclient%2Fsdk.gen.ts,src%2Fclient%2Ftypes.gen.ts">Demo</a>
+  <span>&nbsp;•&nbsp;</span> -->
+  <a href="https://heyapi.dev/docs/openapi/python/get-started">Manual</a>
+  <span>&nbsp;•&nbsp;</span>
+  <a href="https://github.com/hey-api/hey-api/issues">Issues</a>
+  <span>&nbsp;•&nbsp;</span>
+  <a href="https://heyapi.dev/docs/openapi/typescript/community/contributing">Contribute</a>
+</p>
+
+## About
+
+The OpenAPI to Python code generator.
+
+Generate production-grade SDKs and Pydantic models.
+
+Part of the Hey API ecosystem.
+
+## Features
+
+- production-grade code that compiles
+- runs in any Node.js 22+ environment
+- accepts any OpenAPI specification
+- core plugin for SDKs
+- HTTP client for HTTPX
+- highly customizable via plugins
+- [sync with Hey API Registry](https://heyapi.dev/docs/openapi/typescript/integrations) for spec management
+<!-- - 20+ plugins to reduce third-party boilerplate -->
+
+<!-- template-contributing-start -->
+
+## Contributing
+
+Want to see your code in products used by millions?
+
+Start with our [Contributing](https://heyapi.dev/docs/openapi/typescript/community/contributing) guide and release your first feature.
+
+<!-- template-contributing-end -->
+
+<!-- template-sponsors-start -->
+
+## Sponsors
+
+Partners behind the future of API tooling. [Become a sponsor](https://github.com/sponsors/hey-api).
+
+<h3 align="center">Gold</h3>
+
+<table align="center" style="justify-content: center;align-items: center;display: flex;">
+  <tbody>
+    <tr>
+      <td align="center" width="336px">
+        <p></p>
+        <p>
+          <a href="https://kutt.to/pkEZyc" target="_blank">
+            <picture height="50px">
+              <source media="(prefers-color-scheme: dark)" srcset="https://heyapi.dev/assets/.gen/stainless-logo-wordmark-480w.jpeg">
+              <img alt="Stainless logo" height="50px" src="https://heyapi.dev/assets/.gen/stainless-logo-wordmark-480w.jpeg">
+            </picture>
+          </a>
+          <br/>
+          Best-in-class developer interfaces for your API.
+          <br/>
+          <a href="https://kutt.to/pkEZyc" style="text-decoration:none;" target="_blank">
+            stainless.com
+          </a>
+        </p>
+        <p></p>
+      </td>
+      <td align="center" width="336px">
+        <p></p>
+        <p>
+          <a href="https://kutt.to/QM9Q2N" target="_blank">
+            <picture height="50px">
+              <source media="(prefers-color-scheme: dark)" srcset="https://heyapi.dev/assets/opencode/logo-light.svg">
+              <img alt="Opencode logo" height="50px" src="https://heyapi.dev/assets/opencode/logo-dark.svg">
+            </picture>
+          </a>
+          <br/>
+          The open source coding agent.
+          <br/>
+          <a href="https://kutt.to/QM9Q2N" style="text-decoration:none;" target="_blank">
+            opencode.ai
+          </a>
+        </p>
+        <p></p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<h3 align="center">Silver</h3>
+
+<table align="center" style="justify-content: center;align-items: center;display: flex;">
+  <tbody>
+    <tr>
+      <td align="center" width="172px">
+        <a href="https://kutt.to/skQUVd" target="_blank">
+          <picture height="40px">
+            <source media="(prefers-color-scheme: dark)" srcset="https://heyapi.dev/assets/scalar/logo-light.svg">
+            <img alt="Scalar logo" height="40px" src="https://heyapi.dev/assets/scalar/logo-dark.svg">
+          </picture>
+        </a>
+        <br/>
+        <a href="https://kutt.to/skQUVd" style="text-decoration:none;" target="_blank">
+          scalar.com
+        </a>
+      </td>
+      <td align="center" width="172px">
+        <a href="https://kutt.to/Dr9GuW" target="_blank">
+          <picture height="40px">
+            <source media="(prefers-color-scheme: dark)" srcset="https://heyapi.dev/assets/fastapi/logo-light.svg">
+            <img alt="FastAPI logo" height="40px" src="https://heyapi.dev/assets/fastapi/logo-dark.svg">
+          </picture>
+        </a>
+        <br/>
+        <a href="https://kutt.to/Dr9GuW" style="text-decoration:none;" target="_blank">
+          fastapi.tiangolo.com
+        </a>
+      </td>
+      <td align="center" width="172px">
+        <a href="https://kutt.to/yZVkdV" target="_blank">
+          <picture height="40px">
+            <source media="(prefers-color-scheme: dark)" srcset="https://heyapi.dev/assets/brands/unblocked/logo-light.svg">
+            <img alt="Unblocked logo" height="40px" src="https://heyapi.dev/assets/brands/unblocked/logo-dark.svg">
+          </picture>
+        </a>
+        <br/>
+        <a href="https://kutt.to/yZVkdV" style="text-decoration:none;" target="_blank">
+          getunblocked.com
+        </a>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<h3 align="center">Bronze</h3>
+
+<table align="center" style="justify-content: center;align-items: center;display: flex;">
+  <tbody>
+    <tr>
+      <td align="center" width="136px">
+        <a href="https://kutt.to/YpaKsX" target="_blank">
+          <picture height="34px">
+            <source media="(prefers-color-scheme: dark)" srcset="https://heyapi.dev/assets/.gen/kinde-logo-wordmark-dark-480w.webp">
+            <img alt="Kinde logo" height="34px" src="https://heyapi.dev/assets/.gen/kinde-logo-wordmark-480w.jpeg">
+          </picture>
+        </a>
+      </td>
+      <td align="center" width="136px">
+        <a href="https://kutt.to/KkqSaw" target="_blank">
+          <picture height="34px">
+            <source media="(prefers-color-scheme: dark)" srcset="https://heyapi.dev/assets/cella/logo-light.svg">
+            <img alt="Cella logo" height="34px" src="https://heyapi.dev/assets/cella/logo-dark.svg">
+          </picture>
+        </a>
+      </td>
+      <td align="center" width="136px">
+        <a href="https://kutt.to/HW4GYR" target="_blank">
+          <picture height="34px">
+            <source media="(prefers-color-scheme: dark)" srcset="https://heyapi.dev/assets/photon/logo-light.svg">
+            <img alt="Photon logo" height="34px" src="https://heyapi.dev/assets/photon/logo-dark.svg">
+          </picture>
+        </a>
+      </td>
+    </tr>
+  </tbody>
+</table>
+<!-- template-sponsors-end -->
+
+## Quick Start
+
+The fastest way to use `@hey-api/openapi-python` is via npx
+
+```sh
+npx @hey-api/openapi-python -i hey-api/backend -o src/client
+```
+
+Congratulations on creating your first client! 🎉 You can learn more about the generated files on the [Output](https://heyapi.dev/docs/openapi/python/output) page.
+
+## Installation
+
+You can download `@hey-api/openapi-python` from npm using your favorite package manager.
+
+#### npm
+
+```sh
+npm install @hey-api/openapi-python -D -E
+```
+
+#### pnpm
+
+```sh
+pnpm add @hey-api/openapi-python -D -E
+```
+
+#### yarn
+
+```sh
+yarn add @hey-api/openapi-python -D -E
+```
+
+#### bun
+
+```sh
+bun add @hey-api/openapi-python -D
+```
+
+### Versioning
+
+This package is in [initial development](https://semver.org/#spec-item-4). Please pin an exact version so you can safely upgrade when you're ready.
+
+We publish [migration notes](https://heyapi.dev/docs/openapi/python/migrating) for every breaking release. You might not be impacted by a breaking change if you don't use the affected features.
+
+## Usage
+
+### CLI
+
+Most people run `@hey-api/openapi-python` via CLI. To do that, add a script to your `package.json` file which will make `openapi-python` executable through script.
+
+```json
+"scripts": {
+  "openapi-python": "openapi-python"
+}
+```
+
+The above script can be executed by running `npm run openapi-python` or equivalent command in other package managers. Next, we will create a [configuration](https://heyapi.dev/docs/openapi/python/configuration) file and move our options from Quick Start to it.
+
+### Node.js
+
+You can also generate output programmatically by calling `createClient()` in a JavaScript/TypeScript file.
+
+#### `script.ts`
+
+```ts
+import { createClient } from '@hey-api/openapi-python';
+
+createClient({
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+});
+```
+
+<!-- ### Vite
+
+If you're using [Vite](https://vite.dev), you can integrate `@hey-api/openapi-python` directly into your build pipeline with `@hey-api/vite-plugin`. Install it alongside the main package:
+
+#### npm
+
+```sh
+npm install @hey-api/vite-plugin -D -E
+```
+
+#### pnpm
+
+```sh
+pnpm add @hey-api/vite-plugin -D -E
+```
+
+#### yarn
+
+```sh
+yarn add @hey-api/vite-plugin -D -E
+```
+
+#### bun
+
+```sh
+bun add @hey-api/vite-plugin -D
+```
+
+Then add the plugin to your Vite configuration:
+
+#### `vite.config.ts`
+
+```ts
+import { heyApiPlugin } from '@hey-api/vite-plugin';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    heyApiPlugin({
+      config: {
+        input: 'hey-api/backend', // sign up at app.heyapi.dev
+        output: 'src/client',
+      },
+    }),
+  ],
+});
+```
+
+See the [Vite](https://heyapi.dev/docs/openapi/typescript/configuration/vite) page for full configuration options. -->
+
+## Configuration
+
+`@hey-api/openapi-python` supports loading configuration from any file inside your project root folder supported by [jiti loader](https://github.com/unjs/c12?tab=readme-ov-file#-features). Below are the most common file formats.
+
+#### `openapi-python.config.ts`
+
+```js
+import { defineConfig } from '@hey-api/openapi-python';
+
+export default defineConfig({
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+});
+```
+
+#### `openapi-python.config.cjs`
+
+```js
+/** @type {import('@hey-api/openapi-python').UserConfig} */
+module.exports = {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+};
+```
+
+#### `openapi-python.config.mjs`
+
+```js
+/** @type {import('@hey-api/openapi-python').UserConfig} */
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+};
+```
+
+Alternatively, you can use `openapi-python.config.js` and configure the export statement depending on your project setup.
+
+### Input
+
+You must set the input so we can load your OpenAPI specification. It can be a path or URL, object containing a path or URL, or an object representing an OpenAPI specification. Hey API supports all valid OpenAPI versions and file formats.
+
+> If you use an HTTPS URL with a self-signed certificate in development, you will need to set [`NODE_TLS_REJECT_UNAUTHORIZED=0`](https://github.com/hey-api/hey-api/issues/276#issuecomment-2043143501) in your environment.
+
+### Output
+
+You must set the output so we know where to generate your files. It can be a path to the destination folder or an object containing the destination folder path and optional settings.
+
+> You should treat the output folder as a dependency. Do not directly modify its contents as your changes might be erased when you run `@hey-api/openapi-python` again.
+
+## Parser
+
+We parse your input before making it available to plugins. While configuring the parser is optional, it's the perfect place to modify or validate your input if needed.
+
+## Plugins
+
+Plugins are responsible for generating artifacts from your input. By default, Hey API will generate Pydantic models and SDK from your OpenAPI specification. You can add, remove, or customize any of the plugins. In fact, we highly encourage you to do so!
+
+### Client
+
+Clients are responsible for sending the actual HTTP requests. We default to HTTPX client if you're generating SDKs, but you can choose a different option from the available clients.
+
+### Available Clients
+
+- [`@hey-api/client-httpx`](https://heyapi.dev/docs/openapi/python/clients/httpx)
+
+### Proposed Clients (Vote to Prioritize)
+
+The following clients are roadmap proposals and are not started yet. You can help us prioritize them by voting on [GitHub](https://github.com/hey-api/hey-api/issues?q=state%3Aopen%20label%3A%22vote%20%F0%9F%93%A9%22).
+
+- [`@hey-api/client-aiohttp`](https://heyapi.dev/docs/openapi/python/clients/aiohttp)
+- [`@hey-api/client-requests`](https://heyapi.dev/docs/openapi/python/clients/requests)
+- [`@hey-api/client-urllib3`](https://heyapi.dev/docs/openapi/python/clients/urllib3)
+
+Don't see your client? [Build your own](https://heyapi.dev/docs/openapi/python/clients/custom) or let us know your interest by [opening an issue](https://github.com/hey-api/hey-api/issues).
+
+### Available Plugins
+
+These plugins help reduce boilerplate associated with third-party dependencies. Hey API natively supports the most popular packages. Please open an issue on [GitHub](https://github.com/hey-api/hey-api/issues) if you'd like us to support your favorite package.
+
+- [`pydantic`](https://heyapi.dev/docs/openapi/python/plugins/pydantic)
+
+### Proposed Plugins (Vote to Prioritize)
+
+The following plugins are roadmap proposals and are not started yet. You can help us prioritize them by voting on [GitHub](https://github.com/hey-api/hey-api/issues?q=state%3Aopen%20label%3A%22vote%20%F0%9F%93%A9%22).
+
+- [Attrs](https://heyapi.dev/docs/openapi/python/plugins/attrs)
+- [Dataclasses](https://heyapi.dev/docs/openapi/python/plugins/dataclasses)
+- [Factory Boy](https://heyapi.dev/docs/openapi/python/plugins/factory-boy)
+- [Faker](https://heyapi.dev/docs/openapi/python/plugins/faker)
+- [Marshmallow](https://heyapi.dev/docs/openapi/python/plugins/marshmallow)
+- [Mimesis](https://heyapi.dev/docs/openapi/python/plugins/mimesis)
+
+Don't see your plugin? [Build your own](https://heyapi.dev/docs/openapi/python/plugins/custom) or let us know your interest by [opening an issue](https://github.com/hey-api/hey-api/issues).
+
+## Migrating
+
+You can learn more on the [Migrating](https://heyapi.dev/docs/openapi/python/migrating) page.
+
+<!-- template-license-start -->
+
+## License
+
+Released under the [MIT License](https://github.com/hey-api/hey-api/blob/main/LICENSE.md).
+
+<!-- template-license-end -->

package/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+node "%~dp0\run.js" %*
+

package/bin/run.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const target = path.join(__dirname, '..', 'dist', 'run.mjs');
+
+if (!fs.existsSync(target)) {
+  console.error('openapi-python not built (expect dist/run.mjs)');
+  process.exit(1);
+}
+
+const res = spawnSync(process.execPath, [target, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+process.exit(res.status ?? 0);

package/dist/chunk-z9aeyW2b.mjs

@@ -0,0 +1,15 @@
+import { createRequire } from "node:module";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+//#endregion
+export { __require as n, __exportAll as t };

package/dist/clients/httpx/__init__.py

@@ -0,0 +1,3 @@
+from .client import Client, build_client_params, create_client
+
+__all__ = ["Client", "build_client_params", "create_client"]

package/dist/clients/httpx/client.py

@@ -0,0 +1,128 @@
+from typing import Any, Optional
+import httpx
+
+
+EXTRA_PREFIXES_MAP = {
+    "$body_": "json",
+    "$headers_": "headers",
+    "$path_": "path",
+    "$query_": "params",
+}
+
+
+def build_client_params(fields: list[dict[str, Any]], **kwargs) -> dict[str, Any]:
+    """Build client parameters from flat keyword arguments.
+
+    Args:
+        fields: List of field configurations with 'in', 'key', and optional 'map'.
+        **kwargs: Flat parameters passed to the SDK method.
+
+    Returns:
+        Dict suitable for httpx client methods: {params: {...}, headers: {...}, json: Any}
+    """
+    result: dict[str, Any] = {}
+
+    key_map = {}
+    for field in fields:
+        key = field.get("key")
+        if key:
+            key_map[key] = {
+                "in": field.get("in"),
+                "map": field.get("map", key),
+            }
+
+    for key, value in kwargs.items():
+        if value is None:
+            continue
+
+        field = key_map.get(key)
+
+        if field:
+            in_slot = field["in"]
+            map_key = field["map"]
+            slot = "json" if in_slot == "body" else in_slot
+
+            if in_slot == "body":
+                result[slot] = value
+            else:
+                if slot not in result:
+                    result[slot] = {}
+                result[slot][map_key] = value
+        else:
+            for prefix, slot in EXTRA_PREFIXES_MAP.items():
+                if key.startswith(prefix):
+                    actual_key = key[len(prefix) :]
+                    if slot not in result:
+                        result[slot] = {}
+                    result[slot][actual_key] = value
+                    break
+            else:
+                if "params" not in result:
+                    result["params"] = {}
+                result["params"][key] = value
+
+    for slot in list(result.keys()):
+        if not result[slot]:
+            del result[slot]
+
+    return result
+
+
+class BaseClient:
+    """Base HTTP client using httpx that SDK classes extend."""
+
+    def __init__(self, client: Optional[httpx.Client] = None, base_url: Optional[str] = None, **kwargs):
+        if client is not None:
+            self._client = client
+        else:
+            self._client = httpx.Client(base_url=base_url or "", **kwargs)
+
+    @property
+    def client(self) -> httpx.Client:
+        """Get the httpx client instance."""
+        return self._client
+
+    def request(self, method: str, url: str, **kwargs) -> httpx.Response:
+        """Make an HTTP request."""
+        return self._client.request(method, url, **kwargs)
+
+    def get(self, url: str, **kwargs) -> httpx.Response:
+        """Make a GET request."""
+        return self._client.get(url, **kwargs)
+
+    def post(self, url: str, **kwargs) -> httpx.Response:
+        """Make a POST request."""
+        return self._client.post(url, **kwargs)
+
+    def put(self, url: str, **kwargs) -> httpx.Response:
+        """Make a PUT request."""
+        return self._client.put(url, **kwargs)
+
+    def patch(self, url: str, **kwargs) -> httpx.Response:
+        """Make a PATCH request."""
+        return self._client.patch(url, **kwargs)
+
+    def delete(self, url: str, **kwargs) -> httpx.Response:
+        """Make a DELETE request."""
+        return self._client.delete(url, **kwargs)
+
+    def close(self):
+        """Close the client."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+class Client(BaseClient):
+    """HTTP client using httpx (alias for BaseClient)."""
+
+    pass
+
+
+def create_client(base_url: Optional[str] = None, **kwargs) -> Client:
+    """Create a new HTTP client instance."""
+    return Client(base_url=base_url, **kwargs)